paperap.resources package


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

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

class paperap.resources.DocumentResource(client)[source]

Bases: StandardResource[Document, DocumentQuerySet]

Resource for managing documents.

Parameters:

client (PaperlessClient)

bulk_action(action, ids, **kwargs)[source]

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

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

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

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

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:
bulk_modify_custom_fields(ids, add_custom_fields=None, remove_custom_fields=None)[source]

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

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

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

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

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

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

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

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

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

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)[source]
Parameters:
  • document_id (int)

  • original (bool)

Return type:

bytes

empty_trash()[source]

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

int

preview(document_id)[source]
Parameters:

document_id (int)

Return type:

bytes

queryset_class

alias of DocumentQuerySet

thumbnail(document_id)[source]
Parameters:

document_id (int)

Return type:

bytes

upload_async(filepath, **metadata)[source]

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:
upload_content(file_content, filename, **metadata)[source]

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

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.

class paperap.resources.CorrespondentResource(client)[source]

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

class paperap.resources.TagResource(client)[source]

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

class paperap.resources.DocumentTypeResource(client)[source]

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

class paperap.resources.DocumentMetadataResource(client)[source]

Bases: StandardResource[DocumentMetadata, DocumentMetadataQuerySet]

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'detail': <string.Template object>}
get_metadata(document_id)[source]
Parameters:

document_id (int)

Return type:

DocumentMetadata

model_class

alias of DocumentMetadata

name: str = 'document_metadata'
queryset_class

alias of DocumentMetadataQuerySet

class paperap.resources.DocumentSuggestionsResource(client)[source]

Bases: StandardResource[DocumentSuggestions, DocumentSuggestionsQuerySet]

Parameters:

client (PaperlessClient)

endpoints: ClassVar[Endpoints] = {'detail': <string.Template object>}
get_suggestions(document_id)[source]
Parameters:

document_id (int)

Return type:

DocumentSuggestions

model_class

alias of DocumentSuggestions

name: str = 'document_suggestions'
queryset_class

alias of DocumentSuggestionsQuerySet

class paperap.resources.DownloadedDocumentResource(client)[source]

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

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

class paperap.resources.ProfileResource(client)[source]

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

class paperap.resources.ShareLinksResource(client)[source]

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

class paperap.resources.StoragePathResource(client)[source]

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

class paperap.resources.CustomFieldResource(client)[source]

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

class paperap.resources.UserResource(client)[source]

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

Get the current authenticated user.

Return type:

User

Returns:

The current user.

model_class

alias of User

queryset_class

alias of UserQuerySet

class paperap.resources.GroupResource(client)[source]

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

class paperap.resources.TaskResource(client)[source]

Bases: StandardResource[Task, TaskQuerySet]

Resource for managing tasks.

Parameters:

client (PaperlessClient)

acknowledge(task_id)[source]

Acknowledge a task.

Parameters:

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

Return type:

None

bulk_acknowledge(task_ids)[source]

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

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

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

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:
wait_for_tasks(task_ids, max_wait=300, poll_interval=1.0)[source]

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.

class paperap.resources.SavedViewResource(client)[source]

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

class paperap.resources.UISettingsResource(client)[source]

Bases: StandardResource[UISettings, UISettingsQuerySet]

Resource for managing UI settings.

Parameters:

client (PaperlessClient)

delete(model_id)[source]

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

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

Update the current user’s UI settings.

Parameters:

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

Return type:

UISettings

Returns:

The updated UI settings.

class paperap.resources.WorkflowResource(client)[source]

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

class paperap.resources.WorkflowTriggerResource(client)[source]

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

class paperap.resources.WorkflowActionResource(client)[source]

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

Submodules