Session management

This page covers all configuration modes, custom HTTP clients and connection lifecycle details.

Configuration modes

pypaperless can be configured in three ways:

1. Explicit parameters

Pass url and token directly to the constructor:

from pypaperless import PaperlessClient

paperless = PaperlessClient("localhost:8000", "your-api-token")

2. PaperlessSettings object

Build a PaperlessSettings instance and pass it to PaperlessClient.from_config(). Useful when you want to construct or validate settings separately:

from pypaperless import PaperlessClient, PaperlessSettings

cfg = PaperlessSettings(
    url="https://paperless.example.com",
    token="your-api-token",
)

async with PaperlessClient.from_config(cfg) as paperless:
    ...

3. Environment variables

Set the PYPAPERLESS_* environment variables and call PaperlessClient.from_env(). Ideal for containers, CI pipelines and twelve-factor apps:

export PYPAPERLESS_URL=https://paperless.example.com
export PYPAPERLESS_TOKEN=your-api-token

from pypaperless import PaperlessClient

async with PaperlessClient.from_env() as paperless:
    ...

The PaperlessClient constructor reference

PaperlessClient(
    url: str,
    token: str | None = None,
    *,
    client: httpx.AsyncClient | None = None,
)

For config-object or environment-variable based initialization use the factory class methods:

Lifecycle

Context manager

The recommended approach - initialize() and close() are called automatically:

from pypaperless import PaperlessClient

async with PaperlessClient("localhost:8000", "your-api-token") as paperless:
    # fully initialised here
    ...
# connection closed here

Manual

paperless = PaperlessClient("localhost:8000", "your-api-token")
await paperless.initialize()

try:
    # use paperless
    pass
finally:
    await paperless.close()

What initialize() does

1. Sends a GET request to /api/schema/ to verify connectivity and authentication.
2. Reads the x-api-version and x-version response headers.
3. Sets is_initialized = True.

Any connectivity or authentication problem raises an exception before is_initialized becomes True. See Exceptions for details.

Custom HTTP client

You can supply your own httpx.AsyncClient. This is useful when you need to:

• Configure timeouts, retries or proxy settings
• Reuse an existing client for connection pooling
• Inject custom headers or SSL certificates

import httpx
from pypaperless import PaperlessClient

custom_client = httpx.AsyncClient(
    timeout=httpx.Timeout(30.0),
    verify="/path/to/ca-bundle.pem",
    headers={"X-Custom-Header": "value"},
)

async with PaperlessClient("localhost:8000", "your-api-token", client=custom_client) as paperless:
    ...

Logging

pypaperless uses the standard Python logging module under the logger name pypaperless.

import logging
logging.basicConfig(level=logging.DEBUG)

The library logs INFO-level messages for initialize() and close() events.

Available resources

After initialisation, the following services are available on the PaperlessClient instance:

See Resources for the full feature matrix.