Metadata-Version: 2.5
Name: easypaperless
Version: 0.7.1
Summary: A Python API wrapper for paperless-ngx
Project-URL: Homepage, https://github.com/MoritzGrenke/easypaperless
Project-URL: Repository, https://github.com/MoritzGrenke/easypaperless
Project-URL: Issues, https://github.com/MoritzGrenke/easypaperless/issues
Author-email: Moritz Grenke <info@360mix.de>
License: MIT
License-File: LICENSE
Keywords: api,document management,paperless,paperless-ngx,wrapper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.19; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: python-dotenv>=1.0; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff<0.16,>=0.15; extra == 'dev'
Requires-Dist: tenacity>=8.2; extra == 'dev'
Provides-Extra: docs
Requires-Dist: pdoc>=14; extra == 'docs'
Provides-Extra: scripts
Requires-Dist: python-dotenv>=1.0; extra == 'scripts'
Description-Content-Type: text/markdown

# easypaperless 

[![PyPI version](https://img.shields.io/pypi/v/easypaperless.svg)](https://pypi.org/project/easypaperless/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<div style="border: 2px solid #f39c12; padding: 12px; border-radius: 6px;">

**⚠️ Alpha Release**
This project is under active development. Breaking changes might occur, but will be documented in the changelog.
</div>
<br />


**easypaperless** is a high-level easy-to-use Python API wrapper for [Paperless-ngx](https://github.com/paperless-ngx/paperless-ngx). 

Unlike other wrappers that simply mirror REST endpoints, **easypaperless** is designed for humans. It provides a true abstraction layer, allowing you to interact with your document management system using intuitive Python methods and objects. You don't need to understand the underlying REST API to be productive.



---

## ✨ Key Features

* **True Abstraction:** Focus on your logic, not on HTTP methods or JSON payloads.
* **Developer Experience (DX):** Full Type Hinting support. Your IDE (VS Code, PyCharm, etc.) will provide perfect autocompletion and documentation as you type.
* **Extensive Coverage:** Currently covers a lot of essential workflows from document management to complex bulk operations.
* **Async-First with Sync Support:** Built on top of httpx, easypaperless is fully asynchronous by default for high-performance applications. But it also offers a synchronous wrapper for a classic blocking workflow.
* **Built-in Bulk Tools:** Easily manage hundreds of tags, correspondents, or documents with single-method calls.
* **Structured Logging:** The library emits structured log records under the `easypaperless` logger hierarchy. Attach any standard Python logging handler to capture API calls, responses, and errors.
* **Intuitive Error Hierarchy:** easypaperless provides descriptive, custom exceptions that tell you exactly what went wrong.

---

## 📋 Requirements

* Python: 3.11 or higher
* Paperless-ngx: 2.18 or higher (only tested with 2.18 so far)

### Core Dependencies: 

* httpx>=0.27 
* Pydantic>=2.0 

---

## 🚀 Installation

Install the package via pip:

```bash

pip install easypaperless

```

---

## 🛠 Quickstart

Get up and running in seconds. No API deep-dive required.

Create a API Authentification token in your paperless-ngx user profile and replace "YOUR_TOKEN" in following code examples by your actual token. Replace url with your actual url. Consider to create a dedicated paperless-ngx user for the api usage and limit the permissions to your needs.

### async Client

``` Python

import asyncio
from easypaperless import PaperlessClient

async def main():

    # create a paperless client
    # we encourage you to use .env files to store your credentials
    url = "http://localhost:8000"
    api_token = "YOUR_TOKEN"
    async with PaperlessClient(url=url, api_token=api_token) as client:
        # List documents — full-text search across title and OCR content, return the last 3 docs
        # list() returns a PagedResult; use .results for the items and .count for the total
        docs = await client.documents.list(
            search="test", max_results=3, ordering="added", descending=True
        )
        print(f"Total matching: {docs.count}")
        for doc in docs.results:
            print(f"Id: {doc.id} \nTitle: {doc.title} \nadded: {doc.added}\n")

        # Fetch a single document
        doc = await client.documents.get(id=1)
        print(doc.title, doc.created)

        # check if a "API_edited" tag already exists - otherwise create it.
        tags = await client.tags.list(name_exact="API_edited")
        if not tags.results:
            await client.tags.create(name="API_edited", color="#40bfb7")

        # Update metadata — string names are resolved to IDs automatically
        await client.documents.update(id=1, tags=["API_edited"])

        # Upload and wait for processing to complete
        # doc = await client.documents.upload("path/scan.pdf", title="your title here", wait=True)
        # print("Processed:", doc.id)


asyncio.run(main())

```

### sync Client

``` Python

from easypaperless import SyncPaperlessClient

# same example with the sync client:
# we encourage you to use .env files to store your credentials
url = "http://localhost:8000"
api_token = "YOUR_TOKEN"
with SyncPaperlessClient(url=url, api_token=api_token) as client:
    # List documents — full-text search across title and OCR content, return the last 3 docs
    # list() returns a PagedResult; use .results for the items and .count for the total
    docs = client.documents.list(search="test", max_results=3, ordering="added", descending=True)
    print(f"Total matching: {docs.count}")
    for doc in docs.results:
        print(f"Id: {doc.id} \nTitle: {doc.title} \nadded: {doc.added}\n")

    # Fetch a single document
    doc1 = client.documents.get(id=1)
    print(doc1.title, doc1.created)

    # check if a "API_edited" tag already exists - otherwise create it.
    tags = client.tags.list(name_exact="API_edited")
    if not tags.results:
        client.tags.create(name="API_edited", color="#40bfb7")

    # Update metadata — string names are resolved to IDs automatically
    doc_after_update = client.documents.update(id=1, tags=["API_edited"])
    print(doc_after_update.title, doc_after_update.created, doc_after_update.tags)

```

`SyncPaperlessClient` runs its own private event loop thread, so it can be used from a worker thread while another event loop (e.g. FastAPI/uvicorn) runs in the main thread. `close()` (or leaving the `with` block) stops and joins that thread and is safe to call twice. Do not call it directly from inside a running event loop (e.g. Jupyter) — use `PaperlessClient` there.

### Testing with an injected transport

Both clients accept a `transport` keyword (`httpx.AsyncBaseTransport`). It is handed to the internal `httpx.AsyncClient`, while easypaperless still controls the auth header, base URL, timeout and retries. This lets you test code that uses easypaperless with an `httpx.MockTransport`, without global patching:

``` Python
import httpx
from easypaperless import SyncPaperlessClient

def handler(request: httpx.Request) -> httpx.Response:
    assert request.url.path == "/api/tags/"
    return httpx.Response(200, json={"count": 0, "next": None, "previous": None, "results": []})

with SyncPaperlessClient(url="http://paperless.test", api_token="t",
                         transport=httpx.MockTransport(handler)) as client:
    assert client.tags.list().count == 0
```

With `SyncPaperlessClient` the handler runs on the client's internal loop thread. A custom `httpx.AsyncHTTPTransport(proxy=..., local_address=..., verify=...)` works the same way.

## ⚠️ Error Handling

Every exception raised by easypaperless derives from `PaperlessError` and is importable from `easypaperless`. Each one has a non-empty message and a `status_code` attribute (the HTTP status, or `None` when no response was received).

```
PaperlessError
├── AuthError
│   ├── AuthenticationError     401 – token missing or invalid
│   └── PermissionDeniedError   403 – token valid, permission missing
├── BadRequestError             400 – .field_errors, .non_field_errors
├── NotFoundError               404, or a name that could not be resolved
├── ValidationError             422
├── NotPaperlessError           server_version(): URL is not a paperless-ngx instance
├── ServerError
│   ├── ServerResponseError     5xx response (status_code set)
│   └── TransportError          no response: connection refused, DNS, TLS, protocol error
│       └── TransportTimeoutError   connect/read/write/pool timeout
├── UploadError                 document processing task failed (.task)
├── TaskTimeoutError            task polling exceeded poll_timeout (.task_id, .timeout)
└── RetryExhaustedError         all retry attempts failed (last error chained as __cause__)
```

| Exception | Raised when | `status_code` |
|-----------|-------------|---------------|
| `AuthenticationError` | HTTP 401: the API token is missing or invalid | `401` |
| `PermissionDeniedError` | HTTP 403: the token is valid but lacks a permission; the message is paperless's `detail` text verbatim | `403` |
| `BadRequestError` | HTTP 400: paperless rejected the request data. `field_errors` maps field name → list of messages, `non_field_errors` holds the rest | `400` |
| `NotFoundError` | HTTP 404, or a tag/correspondent/... name could not be resolved | `404` / `None` |
| `ValidationError` | HTTP 422 | `422` |
| `NotPaperlessError` | `server_version()`: the API root answered with 404, or with a response (e.g. an HTML page) without the `X-Version` header | the HTTP status |
| `ServerResponseError` | HTTP 5xx, or a download returned an HTML page instead of the file | the HTTP status |
| `TransportError` | paperless could not be reached: connection refused, DNS or TLS failure, broken connection. The original `httpx` exception is chained as `__cause__` | `None` |
| `TransportTimeoutError` | the request timed out (the operation may still have completed on the server) | `None` |
| `UploadError` | the processing task of an upload reports `FAILURE`/`REVOKED`, or succeeds without a document ID. `.task` holds the `Task` with paperless's `status` and `result` unaltered | `None` |
| `TaskTimeoutError` | `tasks.wait()` / `upload(wait=True)` did not finish within `poll_timeout`. `.task_id` and `.timeout` are set so you can call `tasks.wait()` again | `None` |
| `RetryExhaustedError` | all `retry_attempts` failed; `.attempts`, `.url`, last error as `__cause__` | `None` |
| `PaperlessError` | any other HTTP error status (e.g. 409, 429) | the HTTP status |

The classes are subclasses of the earlier ones, so existing `except AuthError` / `except ServerError` clauses keep working. Catching a more specific class lets you react differently:

```python
from easypaperless import (
    BadRequestError, PermissionDeniedError, AuthenticationError,
    ServerResponseError, TransportError,
)

try:
    await client.tags.create(name="")
except BadRequestError as err:
    print(err.field_errors)          # {"name": ["This field may not be blank."]}
except PermissionDeniedError as err:
    print(f"grant permission: {err}")
except AuthenticationError:
    print("check your API token")
except TransportError:
    print("paperless unreachable — retry later")
except ServerResponseError as err:
    print(f"paperless returned {err.status_code}")
```

### Retries

The default `retry_on` contains `ServerError` and therefore retries both transport errors and 5xx responses; pass `retry_on=(TransportError,)` to retry only when paperless was unreachable.

When all retries are exhausted you get a `RetryExhaustedError`; the original classifiable error of the last attempt (e.g. `TransportError` or `ServerResponseError`) is available as its `__cause__`, so `isinstance(err.__cause__, TransportError)` tells you what went wrong.

Requests that create something are **never retried**, whatever `retry_attempts` or `tenacity_retrying` say: `documents.upload()`, every resource's `create()` and `documents.notes.create()`. If the response is lost after paperless has already accepted the request (e.g. a timeout), a retry would create a duplicate. These calls send exactly one request and raise the error (e.g. `TransportTimeoutError`), so you can decide yourself whether to check and try again. All other requests (GET, PATCH, DELETE and the bulk/trash/task-acknowledge POSTs) keep retrying.

## 🔒 Security: Secrets in Logs and Errors

easypaperless never puts your API token into exception messages, `repr()` of clients/resources, or its own log records (at any level, including `DEBUG`). The `Authorization` header is never logged, and when request bodies are logged at `DEBUG`, `password` values (e.g. from `users.create()` / `users.update()`) are replaced by `"***"`.

Not covered: secrets you put into URLs, query parameters or free-text fields (e.g. note text) yourself, and logging done by `httpx`/`httpcore`. Those libraries log at `DEBUG` under the `httpx` and `httpcore` loggers; keep them at `WARNING` or above in production:

```python
import logging
logging.getLogger("httpx").setLevel(logging.WARNING)
logging.getLogger("httpcore").setLevel(logging.WARNING)
```

## 📖 Functional Overview

All functionality is accessed through resource attributes on the client (e.g. `client.documents`, `client.tags`). Both `PaperlessClient` (async) and `SyncPaperlessClient` (sync) expose the same resources and methods.

All `list()` methods return a `PagedResult[T]` containing `.results` (the items), `.count` (total matches from the server), `.next` / `.previous` (raw page URLs when requesting a single page), and `.all` (all matching IDs when provided by the API).

The `UNSET` sentinel (importable from `easypaperless`) allows you to distinguish "not provided" from explicit `None` in optional parameters. Omitting a parameter or passing `UNSET` leaves the field unchanged; passing `None` explicitly clears a nullable field.

### Client

* **PaperlessClient / SyncPaperlessClient** Token-based authentication. Configurable timeout, poll interval, and poll timeout for slow instances. Optional built-in retry-with-exponential-backoff for transient errors (`retry_attempts`, `retry_backoff`, `retry_on`); also accepts a pre-configured `tenacity.AsyncRetrying` instance for advanced retry strategies. Optional injectable `httpx` transport (`transport=`) for mock-based testing or custom proxy/TLS settings.
* **server_version()** One cheap authenticated request (`GET /api/`) that returns the paperless-ngx version from the `X-Version` header, e.g. `"2.18.4"`. Use it as a "test connection" check: a refused token raises `AuthenticationError`, an unreachable server raises `TransportError`, and a URL that is not a paperless-ngx instance (404, or an HTML page without `X-Version`) raises `NotPaperlessError`.
* **system_status()** Returns a `SystemStatus` model from `GET /api/status/`: version, install type, server OS, storage, database and migrations, plus the health of Redis, Celery, the search index and the classifier. All fields are optional. Requires an admin token (otherwise `PermissionDeniedError`).

```python
from easypaperless import NotPaperlessError

try:
    print(await client.server_version())     # "2.18.4"
except NotPaperlessError:
    print("this URL is not a paperless-ngx instance")

status = await client.system_status()
print(status.database.status, status.tasks.celery_status)
```

#### Checking the service user's permissions

paperless-ngx's 403 responses never say which permission is missing. **ui_settings()** (`GET /api/ui_settings/`) returns a `UiSettings` model with the token's `user` (`id`, `username`, `is_staff`, `is_superuser`, `groups`), its effective `permissions` (bare codenames such as `"add_document"`, including permissions granted via groups) and some server `settings` (`version`, `app_title`, `trash_delay`, ...). `missing_permissions(required)` names the codenames the user lacks (always empty for a superuser); `has_permission(codename)` checks a single one.

The endpoint itself needs the `view_uisettings` permission (directly or via a group); without it `ui_settings()` raises `PermissionDeniedError`. Grant it to service users you want to check.

```python
from easypaperless import PermissionDeniedError

DELIVERY_PERMISSIONS = {
    "add_document", "view_document", "change_document",
    "add_note", "delete_note", "view_user", "view_paperlesstask",
}

try:
    settings = await client.ui_settings()
except PermissionDeniedError:
    print("service user lacks view_uisettings, cannot check its permissions")
else:
    missing = settings.missing_permissions(DELIVERY_PERMISSIONS)
    if missing:
        print(f"user {settings.user.username!r} is missing: {', '.join(sorted(missing))}")
```

### `client.documents` — Documents

* **list()** Search and filter documents by title, content, tags, dates, correspondent, and more. The workhorse of the wrapper.
  `list(checksum="<md5>")` finds a document by the MD5 of its original file (case-insensitive exact match). Documents in the trash are **not** found, but paperless still rejects a re-upload of the same file as a duplicate: the upload's `UploadError` then has `err.task.result` ending in `"Note: existing document is in the trash."` and `err.task.related_document` set to `None`. Use `client.trash.list()` / `client.trash.restore()` to find or recover it.
* **get()** Fetch a single document's data; optionally includes extended file metadata.
* **get_metadata()** Retrieve file-level technical metadata (checksums, sizes, MIME types) for a specific document.
* **update()** Partially update document fields like title, tags, or dates using PATCH semantics. Supports `UNSET` to distinguish "not provided" from explicit `None`.
* **delete()** Permanently remove a document from your Paperless-ngx instance.
* **download()** Download the binary content of a document — either the archived PDF or the original file.
* **thumbnail()** Download the thumbnail image of a document as raw bytes.
* **upload()** Upload a new file to Paperless-ngx and optionally wait for the processing task to complete. Accepts a path or in-memory `bytes` (then `filename` is required; no temporary file is written), plus optional `filename`, `content_type` and a per-call `request_timeout` for the upload request. The upload request is never retried automatically (see [Retries](#retries)).

```python
task_id = await client.documents.upload(
    pdf_bytes, filename="capture.pdf", content_type="application/pdf", request_timeout=120
)
```
* **history()** Retrieve the full audit log for a document as a `PagedResult[AuditLogEntry]`, showing who changed what and when.

#### Document Bulk Operations

* **bulk_add_tag()** Add a single tag to a collection of documents in one request.
* **bulk_remove_tag()** Strip a specific tag from multiple documents simultaneously.
* **bulk_modify_tags()** Atomically add and remove multiple tags across a set of documents.
* **bulk_delete()** Permanently delete a list of documents in a single batch.
* **bulk_set_correspondent()** Assign or clear the correspondent for multiple documents at once.
* **bulk_set_document_type()** Change the document type for a group of documents in one go.
* **bulk_set_storage_path()** Update the storage path for multiple documents simultaneously.
* **bulk_modify_custom_fields()** Batch update or remove custom field values across multiple documents.
* **bulk_set_permissions()** Manage ownership and access permissions for a list of documents.
* **bulk_download()** Download multiple documents as a single ZIP archive. Supports choosing the file variant (`archive`, `originals`, or `both`), compression algorithm, and optional filename formatting.

### `client.documents.notes` — Document Notes

* **list()** Retrieve all text notes attached to a specific document.
* **create()** Add a new text note to an existing document.
* **delete()** Remove a specific note from a document.

### `client.tags` — Tags

* **list() / get() / create() / update() / delete()** Full CRUD for document tags, supporting colors and matching algorithms.
* **bulk_delete()** Batch delete tags.
* **bulk_set_permissions()** Batch update access control and ownership for tags.

### `client.correspondents` — Correspondents

* **list() / get() / create() / update() / delete()** Full CRUD for document authors, senders, or recipients.
* **bulk_delete()** Batch delete correspondents.
* **bulk_set_permissions()** Batch update access control and ownership for correspondents.

### `client.document_types` — Document Types

* **list() / get() / create() / update() / delete()** Full CRUD for categories like "Invoice," "Letter," or "Contract."
* **bulk_delete()** Batch delete document types.
* **bulk_set_permissions()** Batch update access control and ownership for document types.

### `client.storage_paths` — Storage Paths

* **list() / get() / create() / update() / delete()** Full CRUD for the physical directory structure where files are stored.
* **bulk_delete()** Batch delete storage paths.
* **bulk_set_permissions()** Batch update access control and ownership for storage paths.

### Reading Object Permissions (`full_perms`)

`get()` and `list()` of `documents`, `tags`, `correspondents`, `document_types` and `storage_paths` accept `full_perms=True`. The view/change users and groups (IDs) are then available as `.permissions`, a `SetPermissions` model with the same shape you pass to `set_permissions`. Without `full_perms` the field is `None`. Note that with `full_perms=True` paperless-ngx leaves out `user_can_change` (and for documents `is_shared_by_requester`), so those fields are `None`.

```python
from easypaperless import PermissionSet, SetPermissions

perms = SetPermissions(view=PermissionSet(users=[7]), change=PermissionSet(users=[7]))
await client.documents.update(42, owner=3, set_permissions=perms)

doc = await client.documents.get(42, full_perms=True)
assert doc.owner == 3 and doc.permissions == perms

tags = await client.tags.list(full_perms=True)
for tag in tags.results:
    print(tag.name, tag.owner, tag.permissions.view.groups)
```

### `client.custom_fields` — Custom Fields

* **list() / get() / create() / update() / delete()** Full CRUD for user-defined metadata fields for advanced document tracking.

### `client.users` — Users

* **list() / get() / create() / update() / delete()** Full CRUD for Paperless-ngx user accounts. Supports filtering by username and paginated results.
* Use `PaperlessPermission` (a typed `Literal` alias of the app-labelled strings, e.g. `"documents.view_document"`) for type-safe checks against `user.inherited_permissions`. `user.user_permissions` and `group.permissions` use bare codenames (`"view_document"`), both on read and on write; paperless-ngx rejects the app-labelled form there.

### `client.groups` — Groups

* **list() / get() / create() / update() / delete()** Full CRUD for Paperless-ngx user groups. Supports filtering by name and paginated results. Use group IDs in `set_permissions` to grant object permissions to a whole group.

### `client.trash` — Trash

* **list()** List all documents currently in the Paperless-ngx trash bin. Returns `PagedResult[Document]`.
* **restore()** Recover one or more trashed documents back to active status.
* **empty()** Permanently and irreversibly delete trashed documents. **This operation cannot be undone.**

### `client.tasks` — Background Tasks

* **list()** List paperless-ngx background tasks, filtered by `task_id`, `status`, `task_name`, `type` or `acknowledged`. Returns `PagedResult[Task]`.
* **get()** Fetch one task by its UUID (e.g. the ID returned by `upload(wait=False)`); raises `NotFoundError` for an unknown ID.
* **wait()** Poll a task until it finishes and return the final `Task`. Accepts `poll_interval` / `poll_timeout` (falling back to the client defaults). `upload(wait=True)` uses it internally.
* **acknowledge()** Mark tasks as acknowledged (by numeric `Task.id`), like "Dismiss" in the paperless UI. Returns the number of acknowledged tasks.

```python
task_id = await client.documents.upload("scan.pdf")      # returns at once; persist task_id
try:
    task = await client.tasks.wait(task_id, poll_timeout=120)
    doc = await client.documents.get(int(task.related_document))
except UploadError as err:
    if err.task and ": It is a duplicate of " in (err.task.result or ""):
        # "scan.pdf: Not consuming scan.pdf: It is a duplicate of Invoice (#12)."
        existing_id = err.task.related_document          # "12", or None if #12 is in the trash
except TaskTimeoutError as err:
    ...                                                   # still running: wait again later with err.task_id
```


## 📚 Documentation

See the 👉 [Full API Reference (pdoc)](https://moritzgrenke.github.io/easypaperless/)

## 🤝 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue. 

## 📄 License

This project is licensed under the MIT License.


