paperap.resources.documents module

METADATA:

File: documents.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.resources.documents.DocumentResource(client)[source]

Bases: StandardResource[Document, DocumentQuerySet]

Resource for managing documents.

Parameters:

client (PaperlessClient)

model_class

alias of Document

queryset_class

alias of DocumentQuerySet

name: str = 'documents'
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>}
download(document_id, *, original=False)[source]
Parameters:

  • document_id (int)

  • original (bool)

Return type:

bytes

preview(document_id)[source]
Parameters:

document_id (int)

Return type:

bytes

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_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.

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

next_asn()[source]
Return type:

int

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_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_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_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_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

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_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_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_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_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_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_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_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

empty_trash()[source]

Empty the trash.

Return type:

dict[str, Any]

Returns:

The API response.

Raises:

APIError – If the empty trash request fails.

client: PaperlessClient
class paperap.resources.documents.DocumentNoteResource(client)[source]

Bases: StandardResource[DocumentNote, DocumentNoteQuerySet]

Resource for managing document notes.

Parameters:

client (PaperlessClient)

model_class

alias of DocumentNote

queryset_class

alias of DocumentNoteQuerySet

name: str = 'notes'
endpoints: ClassVar[Endpoints] = {'list': <string.Template object>}
client: PaperlessClient