paperap package

METADATA:

File: __init__.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.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])

__init__(settings=None, **kwargs)[source]
Parameters:
property base_url: HttpUrl

Get the base URL.

close()[source]

Close the client and release resources.

Return type:

None

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:
get_config()[source]

Get system configuration.

Return type:

dict[str, Any]

Returns:

Dictionary containing system configuration.

get_headers()[source]

Get headers for requests.

Return type:

dict[str, str]

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.

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.

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:
settings: Settings
auth: AuthBase
session: Session
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
storage_paths: StoragePathResource
tags: TagResource
tasks: TaskResource
ui_settings: UISettingsResource
users: UserResource
workflow_actions: WorkflowActionResource
workflow_triggers: WorkflowTriggerResource
workflows: WorkflowResource

Subpackages

Submodules