paperap.client module

METADATA:

File: client.py
Project: paperap

Created: 2025-03-04
Version: 0.0.10

Author: Jess Mann Email: jess@jmann.me

Copyright (c) 2025 Jess Mann

LAST MODIFIED:

2025-03-04 By Jess Mann

class paperap.client.PaperlessClient(settings=None, **kwargs)[source]

Bases: object

Client for interacting with the Paperless-NgX API.

Parameters:: settings (Settings | None) – Settings object containing client configuration.

Examples

```python # Using token authentication client = PaperlessClient(

Settings(
base_url=”https://paperless.example.com”, token=”40characterslong40characterslong40charac”

)

)

# Using basic authentication client = PaperlessClient(

Settings(
base_url=”https://paperless.example.com”, username=”user”, password=”pass”

)

)

# Loading all settings from environment variables (e.g. PAPERLESS_TOKEN) client = PaperlessClient()

# With context manager with PaperlessClient(…) as client:

docs = client.documents.list()

```

Parameters:: kwargs (Unpack[SettingsArgs])

plugins: dict[str, Plugin]

correspondents: CorrespondentResource

custom_fields: CustomFieldResource

document_types: DocumentTypeResource

document_metadata: DocumentMetadataResource

document_suggestions: DocumentSuggestionsResource

downloaded_documents: DownloadedDocumentResource

documents: DocumentResource

document_notes: DocumentNoteResource

groups: GroupResource

profile: ProfileResource

saved_views: SavedViewResource

share_links: ShareLinksResource

storage_paths: StoragePathResource

tags: TagResource

tasks: TaskResource

ui_settings: UISettingsResource

users: UserResource

workflow_actions: WorkflowActionResource

workflow_triggers: WorkflowTriggerResource

workflows: WorkflowResource

__init__(settings=None, **kwargs)[source]

Parameters:

settings (Settings | None)
kwargs (Unpack[SettingsArgs])

settings: Settings

auth: AuthBase

session: Session

property base_url: HttpUrl: Get the base URL.

get_headers()[source]

Get headers for requests.

Return type:: dict[str, str]

close()[source]

Close the client and release resources.

Return type:: None

request_raw(method, endpoint, *, params=None, data=None, files=None)[source]

Make a request to the Paperless-NgX API.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE).
endpoint (str | HttpUrl) – API endpoint relative to base URL.
params (dict[str, Any] | None) – Query parameters for the request.
data (dict[str, Any] | None) – Request body data.
files (dict[str, Any] | None) – Files to upload.
json_response – Whether to parse the response as JSON.

Return type:

Response | None

Returns:

Response object or None if no content.

Raises:

AuthenticationError – If authentication fails.
ResourceNotFoundError – If the requested resource doesn’t exist.
APIError – If the API returns an error.
PaperapError – For other errors.

request(method, endpoint, *, params=None, data=None, files=None, json_response=True)[source]

Make a request to the Paperless-NgX API.

Generally, this should be done using resources, not by calling this method directly.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE).
endpoint (str | HttpUrl) – API endpoint relative to base URL.
params (dict[str, Any] | None) – Query parameters for the request.
data (dict[str, Any] | None) – Request body data.
files (dict[str, Any] | None) – Files to upload.
json_response (bool) – Whether to parse the response as JSON.

Return type:

dict[str, Any] | bytes | None

Returns:

Parsed response data.

generate_token(base_url, username, password, timeout=None)[source]

Generate an API token using username and password.

Parameters:

base_url (str) – The base URL of the Paperless-NgX instance.
username (str) – Username for authentication.
password (str) – Password for authentication.
timeout (int | None) – Request timeout in seconds.

Return type:

str

Returns:

Generated API token.

Raises:

AuthenticationError – If authentication fails.
PaperapError – For other errors.

get_statistics()[source]

Get system statistics.

Return type:: dict[str, Any]
Returns:: Dictionary containing system statistics.

get_system_status()[source]

Get system status.

Return type:: dict[str, Any]
Returns:: Dictionary containing system status information.

get_config()[source]

Get system configuration.

Return type:: dict[str, Any]
Returns:: Dictionary containing system configuration.