paperap 0.0.12

Python library for interacting with the Paperless NGX REST API

Paperap

Python library for interacting with the Paperless NGX REST API

Overview

Paperap (pronounced like "paperwrap") is a Python client library for interacting with the Paperless-NGX REST API. It provides an object-oriented interface for managing documents, tags, correspondents, and other resources within Paperless-NGX.

Status

The library is in active development, and is not ready for production use.

Features

• Authentication via API token or username/password
• Object-oriented interface with lazy-loaded querysets
• Pagination and filtering support
• Strongly typed models with Pydantic
• Intended to be easily integrated with existing Python applications

Installation

pip install paperap

Quick Start

Documentation: https://paperap.readthedocs.io

Creating a Client

Using API Token:

from paperap import PaperlessClient

client = PaperlessClient(
    base_url="https://paperless.example.com",
    token="your-token"
)

Using Username and Password:

client = PaperlessClient(
    base_url="https://paperless.example.com",
    username="user",
    password="pass"
)

Loading Settings from Environment Variables:

Set the following environment variables:

• PAPERLESS_BASE_URL
• PAPERLESS_TOKEN or both PAPERLESS_USERNAME and PAPERLESS_PASSWORD

Then create a client without arguments:

client = PaperlessClient()

Working with Documents

Listing Documents:

for doc in client.documents.all():
    print(doc.title)

Filtering Documents:

docs = client.documents.filter(title__contains="invoice")
for doc in docs:
    print(doc.title)

Getting a Single Document:

doc = client.documents.get(123)
print(doc.title)

Tags, Correspondents, and Other Resources

The same interface applies to other resources like tags, correspondents, and document types:

for tag in client.tags.all():
    print(tag.name)

Error Handling

Paperap raises exceptions for API errors:

• PaperlessError - Base exception
• APIError - Error when contacting the Paperless NGX API
• AuthenticationError - Error when authentication fails
• ObjectNotFoundError - Error when a single object is requested but not found
• MultipleObjectsFoundError - Error when a single object is requested but multiple objects are found

from paperap.exceptions import ObjectNotFoundError

try:
    doc = client.documents.get(9999)  # Nonexistent document
except ObjectNotFoundError as e:
    print(f"Error: {e}")

Contributing

I welcome contributions! Please open an issue or submit a pull request on GitHub.

Run tests with either of the following cli commands:

bun run test
uv run python -m unittest discover -s tests

Setup dev environment:

uv venv
source .venv/bin/activate
uv sync --all-groups

Setup env vars:

cp env-sample .env

Run pre-commit:

pre-commit run --all-files

TODO

• increase test coverage (currently around 85%)
• Make integration tests easier to setup for other users (wip)
• Deleting tags, custom fields, etc via document.tags = None
• devcontainer (wip)
• cli tools (1 done)
• updating permissions, ownership, sharing, etc
• changing settings
• local queryset filtering on fields not supported by api
• unit tests for additional edge cases
• immutability (resources, response dicts, (optionally) for models)
• hypothesis testing (additional models)
• factories create relationships in db
• Lazy Document Evaluation after upload/download async
• Remove validators that pydantic handles natively
• factories create unique names
• git action to distribute to pypi
• batch editing
• Empty trash
• publish sphinx docs
• Compile sphinx documentation
• async model updates
• uploading documents
• raise errors for intuitive features unsupported by api (partially done)
• enforce read-only fields
• migrate to pytest
• Replace yarl with pydantic urls
• fetch each model synchronously and validate data types
• lazy loading querysets
• relationships between models using querysets
• saving data to paperless
• vscode tasks

Known Bugs

• Looping over a queryset and deleting items will not modify the next page of the queryset
• Running unit tests and integration tests together causes errors, meaning something is not being cleaned up properly

License

Paperap is released under the MIT License.

Author

Jess Mann - [e-mail]

Related Projects

• Paperless-NGX
• pypaperless - async client that is more mature