# Nutrient DWS Python Client
[](https://badge.fury.io/py/nutrient-dws)
[](https://github.com/PSPDFKit/nutrient-dws-client-python/actions/workflows/ci.yml)
[](https://github.com/PSPDFKit/nutrient-dws-client-python/actions/workflows/integration-tests.yml)
[](https://opensource.org/licenses/MIT)
A Python client library for [Nutrient Document Web Services (DWS) API](https://nutrient.io/). This library provides a fully async, type-safe, and ergonomic interface for document processing operations including conversion, merging, compression, watermarking, OCR, and text extraction.
> **Note**: This package is published as `nutrient-dws` on PyPI. The package provides full type support and is designed for async Python environments (Python 3.10+).
## Features
- 📄 **Powerful document processing**: Convert, OCR, edit, compress, watermark, redact, and digitally sign documents
- 🤖 **LLM friendly**: Built-in support for popular Coding Agents (Claude Code, GitHub Copilot, JetBrains Junie, Cursor, Windsurf) with auto-generated rules
- 🔄 **100% mapping with DWS Processor API**: Complete coverage of all Nutrient DWS Processor API capabilities
- 🛠️ **Convenient functions with sane defaults**: Simple interfaces for common operations with smart default settings
- ⛓️ **Chainable operations**: Build complex document workflows with intuitive method chaining
- 🚀 **Fully async**: Built from the ground up with async/await support for optimal performance
- 🔐 **Flexible authentication and security**: Support for API keys and async token providers with secure handling
- ✅ **Highly tested**: Comprehensive test suite ensuring reliability and stability
- 🔒 **Type-safe**: Full type annotations with comprehensive type definitions
- 🐍 **Pythonic**: Follows Python conventions and best practices
## Installation
```bash
pip install nutrient-dws
```
## Integration with Coding Agents
This package has built-in support with popular coding agents like Claude Code, GitHub Copilot, Cursor, and Windsurf by exposing scripts that will inject rules instructing the coding agents on how to use the package. This ensures that the coding agent doesn't hallucinate documentation, as well as making full use of all the features offered in Nutrient DWS Python Client.
```bash
# Adding code rule to Claude Code
dws-add-claude-code-rule
# Adding code rule to GitHub Copilot
dws-add-github-copilot-rule
# Adding code rule to Junie (Jetbrains)
dws-add-junie-rule
# Adding code rule to Cursor
dws-add-cursor-rule
# Adding code rule to Windsurf
dws-add-windsurf-rule
```
The documentation for Nutrient DWS Python Client is also available on [Context7](https://context7.com/pspdfkit/nutrient-dws-client-python)
## Quick Start
```python
from nutrient_dws import NutrientClient
client = NutrientClient(api_key='your_api_key')
```
## Direct Methods
The client provides numerous async methods for document processing:
```python
import asyncio
from nutrient_dws import NutrientClient
async def main():
client = NutrientClient(api_key='your_api_key')
# Convert a document
pdf_result = await client.convert('document.docx', 'pdf')
# Extract text
text_result = await client.extract_text('document.pdf')
# Add a watermark
watermarked_doc = await client.watermark_text('document.pdf', 'CONFIDENTIAL')
# Merge multiple documents
merged_pdf = await client.merge(['doc1.pdf', 'doc2.pdf', 'doc3.pdf'])
asyncio.run(main())
```
For a complete list of available methods with examples, see the [Methods Documentation](docs/METHODS.md).
## Workflow System
The client also provides a fluent builder pattern with staged interfaces to create document processing workflows:
```python
from nutrient_dws.builder.constant import BuildActions
async def main():
client = NutrientClient(api_key='your_api_key')
result = await (client
.workflow()
.add_file_part('document.pdf')
.add_file_part('appendix.pdf')
.apply_action(BuildActions.watermark_text('CONFIDENTIAL', {
'opacity': 0.5,
'fontSize': 48
}))
.output_pdf({
'optimize': {
'mrcCompression': True,
'imageOptimizationQuality': 2
}
})
.execute())
asyncio.run(main())
```
The workflow system follows a staged approach:
1. Add document parts (files, HTML, pages)
2. Apply actions (optional)
3. Set output format
4. Execute or perform a dry run
For detailed information about the workflow system, including examples and best practices, see the [Workflow Documentation](docs/WORKFLOW.md).
## Error Handling
The library provides a comprehensive error hierarchy:
```python
from nutrient_dws import (
NutrientClient,
NutrientError,
ValidationError,
APIError,
AuthenticationError,
NetworkError
)
async def main():
client = NutrientClient(api_key='your_api_key')
try:
result = await client.convert('file.docx', 'pdf')
except ValidationError as error:
# Invalid input parameters
print(f'Invalid input: {error.message} - Details: {error.details}')
except AuthenticationError as error:
# Authentication failed
print(f'Auth error: {error.message} - Status: {error.status_code}')
except APIError as error:
# API returned an error
print(f'API error: {error.message} - Status: {error.status_code} - Details: {error.details}')
except NetworkError as error:
# Network request failed
print(f'Network error: {error.message} - Details: {error.details}')
asyncio.run(main())
```
## Testing
The library includes comprehensive unit and integration tests:
```bash
# Run all tests
python -m pytest
# Run with coverage report
python -m pytest --cov=nutrient_dws --cov-report=html
# Run only unit tests
python -m pytest tests/unit/
# Run integration tests (requires API key)
NUTRIENT_API_KEY=your_key python -m pytest tests/test_integration.py
```
The library maintains high test coverage across all API methods, including:
- Unit tests for all public methods
- Integration tests for real API interactions
- Type checking with mypy
## Development
For development, install the package in development mode:
```bash
# Clone the repository
git clone https://github.com/PSPDFKit/nutrient-dws-client-python.git
cd nutrient-dws-client-python
# Install in development mode
pip install -e ".[dev]"
# Run type checking
mypy src/
# Run linting
ruff check src/
# Run formatting
ruff format src/
```
## Contributing
We welcome contributions to improve the library! Please follow our development standards to ensure code quality and maintainability.
Quick start for contributors:
1. Clone and setup the repository
2. Make changes following atomic commit practices
3. Use conventional commits for clear change history
4. Include appropriate tests for new features
5. Ensure type checking passes with mypy
6. Follow Python code style with ruff
For detailed contribution guidelines, see the [Contributing Guide](docs/CONTRIBUTING.md).
## Project Structure
```
src/
├── nutrient_dws/
│ ├── builder/ # Builder classes and constants
│ ├── generated/ # Generated type definitions
│ ├── types/ # Type definitions
│ ├── client.py # Main NutrientClient class
│ ├── errors.py # Error classes
│ ├── http.py # HTTP layer
│ ├── inputs.py # Input handling
│ ├── workflow.py # Workflow factory
│ └── __init__.py # Public exports
├── nutrient_dws_scripts/ # CLI scripts for coding agents
└── tests/ # Test files
```
## Python Version Support
This library supports Python 3.10 and higher. The async-first design requires modern Python features for optimal performance and type safety.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
For issues and feature requests, please use the [GitHub issue tracker](https://github.com/PSPDFKit/nutrient-dws-client-python/issues).
For questions about the Nutrient DWS Processor API, refer to the [official documentation](https://nutrient.io/docs/).
Raw data
{
"_id": null,
"home_page": null,
"name": "nutrient-dws",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "nutrient, pdf, document, processing, api, client",
"author": null,
"author_email": "Nutrient <support@nutrient.io>",
"download_url": "https://files.pythonhosted.org/packages/47/5e/e0b34d51db3beac955d9442c757e6b0c23aa92cceb80f5596f24ef04453a/nutrient_dws-2.0.0.tar.gz",
"platform": null,
"description": "# Nutrient DWS Python Client\n\n[](https://badge.fury.io/py/nutrient-dws)\n[](https://github.com/PSPDFKit/nutrient-dws-client-python/actions/workflows/ci.yml)\n[](https://github.com/PSPDFKit/nutrient-dws-client-python/actions/workflows/integration-tests.yml)\n[](https://opensource.org/licenses/MIT)\n\nA Python client library for [Nutrient Document Web Services (DWS) API](https://nutrient.io/). This library provides a fully async, type-safe, and ergonomic interface for document processing operations including conversion, merging, compression, watermarking, OCR, and text extraction.\n\n> **Note**: This package is published as `nutrient-dws` on PyPI. The package provides full type support and is designed for async Python environments (Python 3.10+).\n\n## Features\n\n- \ud83d\udcc4 **Powerful document processing**: Convert, OCR, edit, compress, watermark, redact, and digitally sign documents\n- \ud83e\udd16 **LLM friendly**: Built-in support for popular Coding Agents (Claude Code, GitHub Copilot, JetBrains Junie, Cursor, Windsurf) with auto-generated rules\n- \ud83d\udd04 **100% mapping with DWS Processor API**: Complete coverage of all Nutrient DWS Processor API capabilities\n- \ud83d\udee0\ufe0f **Convenient functions with sane defaults**: Simple interfaces for common operations with smart default settings\n- \u26d3\ufe0f **Chainable operations**: Build complex document workflows with intuitive method chaining\n- \ud83d\ude80 **Fully async**: Built from the ground up with async/await support for optimal performance\n- \ud83d\udd10 **Flexible authentication and security**: Support for API keys and async token providers with secure handling\n- \u2705 **Highly tested**: Comprehensive test suite ensuring reliability and stability\n- \ud83d\udd12 **Type-safe**: Full type annotations with comprehensive type definitions\n- \ud83d\udc0d **Pythonic**: Follows Python conventions and best practices\n\n## Installation\n\n```bash\npip install nutrient-dws\n```\n\n\n## Integration with Coding Agents\n\nThis package has built-in support with popular coding agents like Claude Code, GitHub Copilot, Cursor, and Windsurf by exposing scripts that will inject rules instructing the coding agents on how to use the package. This ensures that the coding agent doesn't hallucinate documentation, as well as making full use of all the features offered in Nutrient DWS Python Client.\n\n```bash\n# Adding code rule to Claude Code\ndws-add-claude-code-rule\n\n# Adding code rule to GitHub Copilot\ndws-add-github-copilot-rule\n\n# Adding code rule to Junie (Jetbrains)\ndws-add-junie-rule\n\n# Adding code rule to Cursor\ndws-add-cursor-rule\n\n# Adding code rule to Windsurf\ndws-add-windsurf-rule\n```\n\nThe documentation for Nutrient DWS Python Client is also available on [Context7](https://context7.com/pspdfkit/nutrient-dws-client-python)\n\n## Quick Start\n\n```python\nfrom nutrient_dws import NutrientClient\n\nclient = NutrientClient(api_key='your_api_key')\n```\n\n## Direct Methods\n\nThe client provides numerous async methods for document processing:\n\n```python\nimport asyncio\nfrom nutrient_dws import NutrientClient\n\nasync def main():\n client = NutrientClient(api_key='your_api_key')\n\n # Convert a document\n pdf_result = await client.convert('document.docx', 'pdf')\n\n # Extract text\n text_result = await client.extract_text('document.pdf')\n\n # Add a watermark\n watermarked_doc = await client.watermark_text('document.pdf', 'CONFIDENTIAL')\n\n # Merge multiple documents\n merged_pdf = await client.merge(['doc1.pdf', 'doc2.pdf', 'doc3.pdf'])\n\nasyncio.run(main())\n```\n\nFor a complete list of available methods with examples, see the [Methods Documentation](docs/METHODS.md).\n\n## Workflow System\n\nThe client also provides a fluent builder pattern with staged interfaces to create document processing workflows:\n\n```python\nfrom nutrient_dws.builder.constant import BuildActions\n\nasync def main():\n client = NutrientClient(api_key='your_api_key')\n\n result = await (client\n .workflow()\n .add_file_part('document.pdf')\n .add_file_part('appendix.pdf')\n .apply_action(BuildActions.watermark_text('CONFIDENTIAL', {\n 'opacity': 0.5,\n 'fontSize': 48\n }))\n .output_pdf({\n 'optimize': {\n 'mrcCompression': True,\n 'imageOptimizationQuality': 2\n }\n })\n .execute())\n\nasyncio.run(main())\n```\n\nThe workflow system follows a staged approach:\n1. Add document parts (files, HTML, pages)\n2. Apply actions (optional)\n3. Set output format\n4. Execute or perform a dry run\n\nFor detailed information about the workflow system, including examples and best practices, see the [Workflow Documentation](docs/WORKFLOW.md).\n\n## Error Handling\n\nThe library provides a comprehensive error hierarchy:\n\n```python\nfrom nutrient_dws import (\n NutrientClient,\n NutrientError,\n ValidationError,\n APIError,\n AuthenticationError,\n NetworkError\n)\n\nasync def main():\n client = NutrientClient(api_key='your_api_key')\n\n try:\n result = await client.convert('file.docx', 'pdf')\n except ValidationError as error:\n # Invalid input parameters\n print(f'Invalid input: {error.message} - Details: {error.details}')\n except AuthenticationError as error:\n # Authentication failed\n print(f'Auth error: {error.message} - Status: {error.status_code}')\n except APIError as error:\n # API returned an error\n print(f'API error: {error.message} - Status: {error.status_code} - Details: {error.details}')\n except NetworkError as error:\n # Network request failed\n print(f'Network error: {error.message} - Details: {error.details}')\n\nasyncio.run(main())\n```\n\n## Testing\n\nThe library includes comprehensive unit and integration tests:\n\n```bash\n# Run all tests\npython -m pytest\n\n# Run with coverage report\npython -m pytest --cov=nutrient_dws --cov-report=html\n\n# Run only unit tests\npython -m pytest tests/unit/\n\n# Run integration tests (requires API key)\nNUTRIENT_API_KEY=your_key python -m pytest tests/test_integration.py\n```\n\nThe library maintains high test coverage across all API methods, including:\n- Unit tests for all public methods\n- Integration tests for real API interactions\n- Type checking with mypy\n\n## Development\n\nFor development, install the package in development mode:\n\n```bash\n# Clone the repository\ngit clone https://github.com/PSPDFKit/nutrient-dws-client-python.git\ncd nutrient-dws-client-python\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Run type checking\nmypy src/\n\n# Run linting\nruff check src/\n\n# Run formatting\nruff format src/\n```\n\n## Contributing\n\nWe welcome contributions to improve the library! Please follow our development standards to ensure code quality and maintainability.\n\nQuick start for contributors:\n\n1. Clone and setup the repository\n2. Make changes following atomic commit practices\n3. Use conventional commits for clear change history\n4. Include appropriate tests for new features\n5. Ensure type checking passes with mypy\n6. Follow Python code style with ruff\n\nFor detailed contribution guidelines, see the [Contributing Guide](docs/CONTRIBUTING.md).\n\n## Project Structure\n\n```\nsrc/\n\u251c\u2500\u2500 nutrient_dws/\n\u2502 \u251c\u2500\u2500 builder/ # Builder classes and constants\n\u2502 \u251c\u2500\u2500 generated/ # Generated type definitions\n\u2502 \u251c\u2500\u2500 types/ # Type definitions\n\u2502 \u251c\u2500\u2500 client.py # Main NutrientClient class\n\u2502 \u251c\u2500\u2500 errors.py # Error classes\n\u2502 \u251c\u2500\u2500 http.py # HTTP layer\n\u2502 \u251c\u2500\u2500 inputs.py # Input handling\n\u2502 \u251c\u2500\u2500 workflow.py # Workflow factory\n\u2502 \u2514\u2500\u2500 __init__.py # Public exports\n\u251c\u2500\u2500 nutrient_dws_scripts/ # CLI scripts for coding agents\n\u2514\u2500\u2500 tests/ # Test files\n```\n\n## Python Version Support\n\nThis library supports Python 3.10 and higher. The async-first design requires modern Python features for optimal performance and type safety.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\nFor issues and feature requests, please use the [GitHub issue tracker](https://github.com/PSPDFKit/nutrient-dws-client-python/issues).\n\nFor questions about the Nutrient DWS Processor API, refer to the [official documentation](https://nutrient.io/docs/).\n",
"bugtrack_url": null,
"license": null,
"summary": "Python client library for Nutrient Document Web Services API",
"version": "2.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/PSPDFKit/nutrient-dws-client-python/issues",
"Documentation": "https://github.com/PSPDFKit/nutrient-dws-client-python/blob/main/README.md",
"Homepage": "https://github.com/PSPDFKit/nutrient-dws-client-python",
"Repository": "https://github.com/PSPDFKit/nutrient-dws-client-python"
},
"split_keywords": [
"nutrient",
" pdf",
" document",
" processing",
" api",
" client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cef1e7167f5b341894790569c3228fc46768aaf0d3ec5f72b2bb69e2922655d7",
"md5": "7e124673b341bd9f9b4587172f2dc4b9",
"sha256": "2579f06403d32328bfbd6b82d9b34e2c3034529eaa818ff1d5f3cdb7f2421ab3"
},
"downloads": -1,
"filename": "nutrient_dws-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7e124673b341bd9f9b4587172f2dc4b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 74195,
"upload_time": "2025-08-23T12:43:02",
"upload_time_iso_8601": "2025-08-23T12:43:02.079241Z",
"url": "https://files.pythonhosted.org/packages/ce/f1/e7167f5b341894790569c3228fc46768aaf0d3ec5f72b2bb69e2922655d7/nutrient_dws-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "475ee0b34d51db3beac955d9442c757e6b0c23aa92cceb80f5596f24ef04453a",
"md5": "fb7b2872b5efd56d3ff5a5dd2545e118",
"sha256": "515c83462818fed3bdff624b5173f10c3e997b89fb9e497443a535443678b5fb"
},
"downloads": -1,
"filename": "nutrient_dws-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "fb7b2872b5efd56d3ff5a5dd2545e118",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 64607,
"upload_time": "2025-08-23T12:43:03",
"upload_time_iso_8601": "2025-08-23T12:43:03.600985Z",
"url": "https://files.pythonhosted.org/packages/47/5e/e0b34d51db3beac955d9442c757e6b0c23aa92cceb80f5596f24ef04453a/nutrient_dws-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 12:43:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "PSPDFKit",
"github_project": "nutrient-dws-client-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nutrient-dws"
}
JSON
