Resources

This section contains documentation for the resources module.

---

METADATA:

File: __init__.py

Project: paperap

Created: 2025-03-04

Version: 0.0.9

Author: Jess Mann Email: jess@jmann.me

Copyright (c) 2025 Jess Mann

---

LAST MODIFIED:

2025-03-04 By Jess Mann

class paperap.resources.DocumentNoteResource(client)

Bases: StandardResource[DocumentNote, DocumentNoteQuerySet]

Resource for managing document notes.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'list': <string.Template object>}

model_class

alias of DocumentNote

name: str = 'notes'

queryset_class

alias of DocumentNoteQuerySet

client: PaperlessClient

class paperap.resources.DocumentResource(client)

Bases: StandardResource[Document, DocumentQuerySet]

Resource for managing documents.

Parameters:

client (PaperlessClient)

bulk_action(action, ids, **kwargs)

Perform a bulk action on multiple documents.

Parameters:

• action (str) – The action to perform (e.g., “delete”, “set_correspondent”, etc.)

• ids (list[int]) – List of document IDs to perform the action on

• **kwargs (Any) – Additional parameters for the action

Return type:

dict[str, Any]

Returns:

The API response

Raises:

ConfigurationError – If the bulk edit endpoint is not defined

bulk_add_tag(ids, tag_id)

Add a tag to multiple documents.

Parameters:

• ids (list[int]) – List of document IDs to update

• tag_id (int) – Tag ID to add

Return type:

dict[str, Any]

Returns:

The API response

bulk_delete(ids)

Delete multiple documents at once.

Parameters:

ids (list[int]) – List of document IDs to delete

Return type:

dict[str, Any]

Returns:

The API response

bulk_delete_pages(document_id, pages)

Delete pages from a document.

Parameters:

• document_id (int) – Document ID

• pages (list[int]) – List of page numbers to delete

Return type:

dict[str, Any]

Returns:

The API response

bulk_merge(ids, metadata_document_id=None, delete_originals=False)

Merge multiple documents.

Parameters:

• ids (list[int]) – List of document IDs to merge

• metadata_document_id (int | None) – Apply metadata from this document to the merged document

• delete_originals (bool) – Whether to delete the original documents after merging

Return type:

bool

Returns:

True if submitting the merge was successful

Raises:

• BadResponseError – If the merge action returns an unexpected response

• APIError – If the merge action fails

bulk_modify_custom_fields(ids, add_custom_fields=None, remove_custom_fields=None)

Modify custom fields on multiple documents.

Parameters:

• ids (list[int]) – List of document IDs to update

• add_custom_fields (dict[int, Any] | None) – Dictionary of custom field ID to value pairs to add

• remove_custom_fields (list[int] | None) – List of custom field IDs to remove

Return type:

dict[str, Any]

Returns:

The API response

bulk_modify_tags(ids, add_tags=None, remove_tags=None)

Modify tags on multiple documents.

Parameters:

• ids (list[int]) – List of document IDs to update

• add_tags (list[int] | None) – List of tag IDs to add

• remove_tags (list[int] | None) – List of tag IDs to remove

Return type:

dict[str, Any]

Returns:

The API response

bulk_remove_tag(ids, tag_id)

Remove a tag from multiple documents.

Parameters:

• ids (list[int]) – List of document IDs to update

• tag_id (int) – Tag ID to remove

Return type:

dict[str, Any]

Returns:

The API response

bulk_reprocess(ids)

Reprocess multiple documents.

Parameters:

ids (list[int]) – List of document IDs to reprocess

Return type:

dict[str, Any]

Returns:

The API response

bulk_rotate(ids, degrees)

Rotate documents.

Parameters:

• ids (list[int]) – List of document IDs to rotate

• degrees (int) – Degrees to rotate (must be 90, 180, or 270)

Return type:

dict[str, Any]

Returns:

The API response

bulk_set_correspondent(ids, correspondent)

Set correspondent for multiple documents.

Parameters:

• ids (list[int]) – List of document IDs to update

• correspondent (Correspondent | int) – Correspondent ID to assign

Return type:

dict[str, Any]

Returns:

The API response

bulk_set_document_type(ids, document_type)

Set document type for multiple documents.

Parameters:

• ids (list[int]) – List of document IDs to update

• document_type_id – Document type ID to assign

• document_type (DocumentType | int)

Return type:

dict[str, Any]

Returns:

The API response

bulk_set_permissions(ids, permissions=None, owner_id=None, merge=False)

Set permissions for multiple documents.

Parameters:

• ids (list[int]) – List of document IDs to update

• permissions (dict[str, Any] | None) – Permissions object

• owner_id (int | None) – Owner ID to assign

• merge (bool) – Whether to merge with existing permissions (True) or replace them (False)

Return type:

dict[str, Any]

Returns:

The API response

bulk_set_storage_path(ids, storage_path)

Set storage path for multiple documents.

Parameters:

• ids (list[int]) – List of document IDs to update

• storage_path_id – Storage path ID to assign

• storage_path (StoragePath | int)

Return type:

dict[str, Any]

Returns:

The API response

bulk_split(document_id, pages, delete_originals=False)

Split a document.

Parameters:

• document_id (int) – Document ID to split

• pages (list) – List of pages to split (can include ranges, e.g. “[1,2-3,4,5-7]”)

• delete_originals (bool) – Whether to delete the original document after splitting

Return type:

dict[str, Any]

Returns:

The API response

download(document_id, *, original=False)

Parameters:

• document_id (int)

• original (bool)

Return type:

bytes

empty_trash()

Empty the trash.

Return type:

dict[str, Any]

Returns:

The API response.

Raises:

APIError – If the empty trash request fails.

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'download': <string.Template object>, 'empty_trash': <string.Template object>, 'list': <string.Template object>, 'next_asn': <string.Template object>, 'preview': <string.Template object>, 'thumbnail': <string.Template object>, 'update': <string.Template object>, 'upload': <string.Template object>}

model_class

alias of Document

name: str = 'documents'

next_asn()

Return type:

int

preview(document_id)

Parameters:

document_id (int)

Return type:

bytes

queryset_class

alias of DocumentQuerySet

thumbnail(document_id)

Parameters:

document_id (int)

Return type:

bytes

upload_async(filepath, **metadata)

Upload a document from a file to paperless ngx.

Parameters:

filepath (Path | str) – The path to the file to upload.

Return type:

str

Returns:

A UUID string (task identifier) as returned by Paperless ngx. e.g. ca6a6dc8-b434-4fcd-8436-8b2546465622

Raises:

• FileNotFoundError – If the file does not exist.

• ResourceNotFoundError – If the upload fails.

upload_content(file_content, filename, **metadata)

Upload a document with optional metadata.

Parameters:

• file_content (bytes) – The binary content of the file to upload

• filename (str) – The name of the file

• **metadata – Additional metadata to include with the upload

Returns:

ca6a6dc8-b434-4fcd-8436-8b2546465622 This is likely a task id, or similar.

Return type:

A string that looks like this

Raises:

ResourceNotFoundError – If the upload fails

upload_sync(filepath, max_wait=300, poll_interval=1.0, **metadata)

Upload a document and wait until it has been processed.

Parameters:

• filepath (Path | str) – Path to the file to upload.

• max_wait (int) – Maximum time (in seconds) to wait for processing.

• poll_interval (float) – Seconds between polling attempts.

• **metadata – Additional metadata for the upload.

Return type:

Document

Returns:

A Document instance once available.

Raises:

• APIError – If the document is not processed within the max_wait.

• BadResponseError – If document processing succeeds but no document ID is returned.

client: PaperlessClient

class paperap.resources.CorrespondentResource(client)

Bases: StandardResource[Correspondent, CorrespondentQuerySet], BulkEditing

Resource for managing correspondents.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of Correspondent

name: str = 'correspondents'

queryset_class

alias of CorrespondentQuerySet

client: PaperlessClient

class paperap.resources.TagResource(client)

Bases: StandardResource[Tag, TagQuerySet], BulkEditing

Resource for managing tags.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of Tag

name: str = 'tags'

queryset_class

alias of TagQuerySet

client: PaperlessClient

class paperap.resources.DocumentTypeResource(client)

Bases: StandardResource[DocumentType, DocumentTypeQuerySet], BulkEditing

Resource for managing document types.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of DocumentType

name: str = 'document_types'

queryset_class

alias of DocumentTypeQuerySet

client: PaperlessClient

class paperap.resources.DocumentMetadataResource(client)

Bases: StandardResource[DocumentMetadata, DocumentMetadataQuerySet]

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'detail': <string.Template object>}

get_metadata(document_id)

Parameters:

document_id (int)

Return type:

DocumentMetadata

model_class

alias of DocumentMetadata

name: str = 'document_metadata'

queryset_class

alias of DocumentMetadataQuerySet

client: PaperlessClient

class paperap.resources.DocumentSuggestionsResource(client)

Bases: StandardResource[DocumentSuggestions, DocumentSuggestionsQuerySet]

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'detail': <string.Template object>}

get_suggestions(document_id)

Parameters:

document_id (int)

Return type:

DocumentSuggestions

model_class

alias of DocumentSuggestions

name: str = 'document_suggestions'

queryset_class

alias of DocumentSuggestionsQuerySet

client: PaperlessClient

class paperap.resources.DownloadedDocumentResource(client)

Bases: StandardResource[DownloadedDocument, DownloadedDocumentQuerySet]

Resource for managing downloaded document content.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {RetrieveFileMode.DOWNLOAD: <string.Template object>, RetrieveFileMode.PREVIEW: <string.Template object>, RetrieveFileMode.THUMBNAIL: <string.Template object>}

load(downloaded_document)

Load the document file content from the API.

This method fetches the binary content of the document file and updates the model with the response data.

Parameters:

downloaded_document (DownloadedDocument)

Return type:

None

model_class

alias of DownloadedDocument

name: str = 'document'

queryset_class

alias of DownloadedDocumentQuerySet

client: PaperlessClient

class paperap.resources.ProfileResource(client)

Bases: StandardResource[Profile, ProfileQuerySet]

Resource for managing profiles.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of Profile

name: str = 'profile'

queryset_class

alias of ProfileQuerySet

client: PaperlessClient

class paperap.resources.ShareLinksResource(client)

Bases: StandardResource[ShareLinks, ShareLinksQuerySet]

Resource for managing share links.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of ShareLinks

name: str = 'share_links'

queryset_class

alias of ShareLinksQuerySet

client: PaperlessClient

class paperap.resources.StoragePathResource(client)

Bases: StandardResource[StoragePath, StoragePathQuerySet], BulkEditing

Resource for managing storage paths.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of StoragePath

name: str = 'storage_paths'

queryset_class

alias of StoragePathQuerySet

client: PaperlessClient

class paperap.resources.CustomFieldResource(client)

Bases: StandardResource[CustomField, CustomFieldQuerySet]

Resource for managing custom fields.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of CustomField

name: str = 'custom_fields'

queryset_class

alias of CustomFieldQuerySet

client: PaperlessClient

class paperap.resources.UserResource(client)

Bases: StandardResource[User, UserQuerySet]

Resource for managing users.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

get_current()

Get the current authenticated user.

Return type:

User

Returns:

The current user.

model_class

alias of User

queryset_class

alias of UserQuerySet

client: PaperlessClient

name: str

class paperap.resources.GroupResource(client)

Bases: StandardResource[Group, GroupQuerySet]

Resource for managing groups.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of Group

queryset_class

alias of GroupQuerySet

client: PaperlessClient

name: str

class paperap.resources.TaskResource(client)

Bases: StandardResource[Task, TaskQuerySet]

Resource for managing tasks.

Parameters:

client (PaperlessClient)

acknowledge(task_id)

Acknowledge a task.

Parameters:

task_id (int) – ID of the task to acknowledge.

Return type:

None

bulk_acknowledge(task_ids)

Acknowledge multiple tasks.

Parameters:

task_ids (list[int]) – list of task IDs to acknowledge.

Return type:

None

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

execute_task(method, endpoint, data=None, max_wait=300)

Execute a task synchronously.

This is a helper method that executes a task and waits for its completion.

Parameters:

• method (str) – HTTP method (GET, POST, etc.)

• endpoint (str) – API endpoint to call

• data (dict[str, Any] | None) – Optional data to send with the request

• max_wait (int) – Maximum time to wait for task completion

Return type:

Task

Returns:

The task object, once completed.

Raises:

APIError – If the task fails or times out

get_task_result(task_id, wait=True, max_wait=300)

Get the result of a task.

Parameters:

• task_id (str) – The task ID.

• wait (bool) – Whether to wait for the task to complete if it’s not already.

• max_wait (int) – Maximum time (in seconds) to wait if wait=True.

Return type:

str | None

Returns:

The result of the task.

Raises:

• APIError – If the task fails or times out.

• ResourceNotFoundError – If the task cannot be found.

model_class

alias of Task

queryset_class

alias of TaskQuerySet

wait_for_task(task_id, max_wait=300, poll_interval=1.0, success_callback=None, failure_callback=None)

Wait for a task to complete.

Parameters:

• task_id (str) – The task ID to wait for.

• max_wait (int) – Maximum time (in seconds) to wait for completion.

• poll_interval (float) – Seconds between polling attempts.

• success_callback (Optional[Callable[[Task], None]]) – Optional callback to execute when task succeeds.

• failure_callback (Optional[Callable[[Task], None]]) – Optional callback to execute when task fails.

Return type:

Task

Returns:

The completed Task instance.

Raises:

• APIError – If the task fails or times out.

• ResourceNotFoundError – If the task cannot be found.

wait_for_tasks(task_ids, max_wait=300, poll_interval=1.0)

Wait for multiple tasks to complete.

Parameters:

• task_ids (list[str]) – List of task IDs to wait for.

• max_wait (int) – Maximum time (in seconds) to wait for all tasks.

• poll_interval (float) – Seconds between polling attempts.

Return type:

dict[str, Task]

Returns:

Dictionary mapping task IDs to completed Task instances.

Raises:

APIError – If any task fails or times out.

client: PaperlessClient

name: str

class paperap.resources.SavedViewResource(client)

Bases: StandardResource[SavedView, SavedViewQuerySet]

Resource for managing saved views.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of SavedView

name: str = 'saved_views'

queryset_class

alias of SavedViewQuerySet

client: PaperlessClient

class paperap.resources.UISettingsResource(client)

Bases: StandardResource[UISettings, UISettingsQuerySet]

Resource for managing UI settings.

Parameters:

client (PaperlessClient)

delete(model_id)

Delete a resource.

Parameters:

model_id (int | UISettings) – ID of the resource.

Return type:

None

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

get_current()

Get the current user’s UI settings.

Return type:

UISettings | None

Returns:

The current user’s UI settings.

model_class

alias of UISettings

name: str = 'ui_settings'

queryset_class

alias of UISettingsQuerySet

update_current(settings)

Update the current user’s UI settings.

Parameters:

settings (dict[str, Any]) – The settings to update.

Return type:

UISettings

Returns:

The updated UI settings.

client: PaperlessClient

class paperap.resources.WorkflowResource(client)

Bases: StandardResource[Workflow, WorkflowQuerySet]

Resource for managing workflows.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of Workflow

name: str = 'workflows'

queryset_class

alias of WorkflowQuerySet

client: PaperlessClient

class paperap.resources.WorkflowTriggerResource(client)

Bases: StandardResource[WorkflowTrigger, WorkflowTriggerQuerySet]

Resource for managing workflow triggers.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of WorkflowTrigger

name: str = 'workflow_triggers'

queryset_class

alias of WorkflowTriggerQuerySet

client: PaperlessClient

class paperap.resources.WorkflowActionResource(client)

Bases: StandardResource[WorkflowAction, WorkflowActionQuerySet]

Resource for managing workflow actions.

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'create': <string.Template object>, 'delete': <string.Template object>, 'detail': <string.Template object>, 'list': <string.Template object>, 'update': <string.Template object>}

model_class

alias of WorkflowAction

name: str = 'workflow_actions'

queryset_class

alias of WorkflowActionQuerySet

client: PaperlessClient