Little api client for paperless(-ngx): pypaperless
pypaperless
[![GitHub Release][release-badge]][release-url] [![Python Version][python-badge]][python-url] [![GitHub License][license-badge]][license-url]
[![Tests][tests-badge]][tests-url] [![Codecov][codecov-badge]][codecov-url] [![Linting][linting-badge]][linting-url] [![Typing][typing-badge]][typing-url]
pypaperless is a modern, fully async Python client library for the Paperless-ngx REST API.
Features
| Feature | Details | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Fully async | Built on asyncio + httpx.AsyncClient; drop-in for any async framework | | Type-safe models | All resources are validated Pydantic models | | Complete resource coverage | Documents, Correspondents, Tags, Document Types, Storage Paths, Custom Fields, Saved Views, Share Links, Workflows, Mail Accounts/Rules, Tasks, Trash, and more | | CRUD + permissions | Create, read, update, delete and manage object-level permissions per resource | | Async iteration & paging | Iterate over all items or page-by-page; server-side filtering via filter() | | Document operations | Upload, download, search (full-text & advanced), notes, suggestions, metadata | | Custom field system | Rich typed access to custom field values — read, write, remove with caching | | Token generation | Static helper to exchange username + password for an API token | | Custom HTTP client | Bring your own httpx.AsyncClient for full control over timeouts, proxies, TLS, … |
Quick example
import asyncio
from pypaperless import PaperlessClient
async def main(): async with PaperlessClient("localhost:8000", "your-api-token") as paperless: # iterate all documents - pagination is handled automatically async for document in paperless.documents: print(document.id, document.title)
# fetch a single item doc = await paperless.documents(42)
# filter with server-side parameters async with paperless.tags.filter(name__ic) as filtered: async for tag in filtered: print(tag.id, tag.name)
asyncio.run(main())
Installation
Requires Python 3.13+.
pip install pypaperlessDocumentation
Full documentation is available [here][docs-url].
Compatibility matrix
| pypaperless | Paperless-ngx | Python | Notes | | --------------- | --------------- | ------ | --------------------------------------- | | >= v6.0 | >= 3.0 | 3.13 | Current release | | >= v5.2 | >= 2.19 | 3.12 | | | >= v5.0 | >= 2.17 | 3.12 | | | >= v4.x | >= 2.15 | 3.12 | | | < v4.0 | < 2.15 | 3.11 | Incompatible with Paperless-ngx >= 2.15 |
Recommendation: Keep both Paperless-ngx and pypaperless up to date to benefit from the latest API features and bug fixes.
Authors & contributors
pypaperless is written and maintained by [Tobias Schulz][contributors-tbsch]. Feedback and contributions are always welcome.
Check out all [contributors][contributors-url].
[codecov-badge]: https://codecov.io/gh/tb1337/paperless-api/graph/badge.svg?token=IMXRBK3HRE [codecov-url]: https://app.codecov.io/gh/tb1337/paperless-api/tree/main [contributors-tbsch]: https://tbsch.de [contributors-url]: https://github.com/tb1337/paperless-api/graphs/contributors [docs-url]: https://pypaperless.docs.tbsch.de [license-badge]: https://img.shields.io/github/license/tb1337/paperless-api [license-url]: /LICENSE.md [python-badge]: https://img.shields.io/pypi/pyversions/pypaperless [python-url]: https://pypi.org/project/pypaperless/ [tests-badge]: https://github.com/tb1337/paperless-api/actions/workflows/tests.yml/badge.svg [tests-url]: https://github.com/tb1337/paperless-api/actions [release-badge]: https://img.shields.io/github/v/release/tb1337/paperless-api [release-url]: https://github.com/tb1337/paperless-api/releases [linting-badge]: https://github.com/tb1337/paperless-api/actions/workflows/linting.yml/badge.svg [linting-url]: https://github.com/tb1337/paperless-api/actions [typing-badge]: https://github.com/tb1337/paperless-api/actions/workflows/typing.yml/badge.svg [typing-url]: https://github.com/tb1337/paperless-api/actions
