paperap.models.document 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.models.document.Document(**data)[source]

Bases: StandardModel

Represents a Paperless-NgX document.

added: The timestamp when the document was added to the system.

archive_serial_number: The serial number of the archive.

archived_file_name: The name of the archived file.

content: The content of the document.

correspondent: The correspondent associated with the document.

created: The timestamp when the document was created.

created_date: The date when the document was created.

updated: The timestamp when the document was last updated.

custom_fields: Custom fields associated with the document.

deleted_at: The timestamp when the document was deleted.

document_type: The document type associated with the document.

is_shared_by_requester: Whether the document is shared by the requester.

notes: Notes associated with the document.

original_filename: The original file name of the document.

owner: The owner of the document.

page_count: The number of pages in the document.

storage_path: The storage path of the document.

tags: The tags associated with the document.

title: The title of the document.

user_can_change: Whether the user can change the document.

checksum: The checksum of the document.

Examples

>>> document = client.documents().get(pk=1)
>>> document.title = 'Example Document'
>>> document.save()
>>> document.title
'Example Document'

# Get document metadata >>> metadata = document.get_metadata() >>> print(metadata.original_mime_type)

# Download document >>> download = document.download() >>> with open(download.disposition_filename, ‘wb’) as f: … f.write(download.content)

# Get document suggestions >>> suggestions = document.get_suggestions() >>> print(suggestions.tags)

Parameters:: data (Any)

class Meta(model)[source]

Bases: Meta

Parameters:: model (type[_Self])

blacklist_filtering_params: ClassVar[set[str]] = {}

field_map: dict[str, str] = {'correspondent': 'correspondent_id', 'custom_fields': 'custom_field_dicts', 'document_type': 'document_type_id', 'storage_path': 'storage_path_id', 'tags': 'tag_ids'}

filtering_disabled: ClassVar[set[str]] = {'deleted_at', 'is_shared_by_requester', 'page_count'}

filtering_fields: ClassVar[set[str]] = {'__search_hit__', '_correspondent', '_document_type', '_resource', '_storage_path', 'added', 'archive_checksum', 'archive_filename', 'archive_serial_number', 'archived_file_name', 'checksum', 'content', 'correspondent_id', 'created', 'created_date', 'custom_field_dicts', 'document_type_id', 'filename', 'id', 'notes', 'original_filename', 'owner', 'storage_path_id', 'storage_type', 'tag_ids', 'title', 'user_can_change'}

filtering_strategies: ClassVar[set[FilteringStrategies]] = {FilteringStrategies.WHITELIST}

read_only_fields: ClassVar[set[str]] = {'archived_file_name', 'deleted_at', 'id', 'is_shared_by_requester', 'page_count'}

supported_filtering_params: ClassVar[set[str]] = {'added__date__gt', 'added__date__lt', 'added__day', 'added__gt', 'added__lt', 'added__month', 'added__year', 'archive_serial_number', 'archive_serial_number__gt', 'archive_serial_number__gte', 'archive_serial_number__isnull', 'archive_serial_number__lt', 'archive_serial_number__lte', 'checksum__icontains', 'checksum__iendswith', 'checksum__iexact', 'checksum__istartswith', 'content__contains', 'content__icontains', 'content__iendswith', 'content__iexact', 'content__istartswith', 'correspondent__id', 'correspondent__id__in', 'correspondent__id__none', 'correspondent__isnull', 'correspondent__name__icontains', 'correspondent__name__iendswith', 'correspondent__name__iexact', 'correspondent__name__istartswith', 'correspondent__slug__iexact', 'created__date__gt', 'created__date__lt', 'created__day', 'created__gt', 'created__lt', 'created__month', 'created__year', 'custom_field_query', 'custom_fields__icontains', 'custom_fields__id__all', 'custom_fields__id__in', 'custom_fields__id__none', 'document_type__id', 'document_type__id__in', 'document_type__id__none', 'document_type__isnull', 'document_type__name__icontains', 'document_type__name__iendswith', 'document_type__name__iexact', 'document_type__name__istartswith', 'has_custom_fields', 'id', 'id__in', 'is_in_inbox', 'is_tagged', 'limit', 'original_filename__icontains', 'original_filename__iendswith', 'original_filename__iexact', 'original_filename__istartswith', 'owner__id', 'owner__id__in', 'owner__id__none', 'owner__isnull', 'shared_by__id', 'shared_by__id__in', 'storage_path__id', 'storage_path__id__in', 'storage_path__id__none', 'storage_path__isnull', 'storage_path__name__icontains', 'storage_path__name__iendswith', 'storage_path__name__iexact', 'storage_path__name__istartswith', 'tags__id', 'tags__id__all', 'tags__id__in', 'tags__id__none', 'tags__name__icontains', 'tags__name__iendswith', 'tags__name__iexact', 'tags__name__istartswith', 'title__icontains', 'title__iendswith', 'title__iexact', 'title__istartswith', 'title_content'}

model: type[_Self]

name: str

add_tag(tag)[source]

Add a tag to the document.

Parameters:: tag (Tag | int | str) – The tag to add.
Return type:: None

append_content(value)[source]

Append content to the document.

Parameters:: value (str) – The content to append.
Return type:: None

property correspondent: Correspondent | None

Get the correspondent for this document.

Returns:: The correspondent or None if not set.

Examples

>>> document = client.documents().get(pk=1)
>>> document.correspondent.name
'Example Correspondent'

property custom_field_ids: list[int]: Get the IDs of the custom fields for this document.

custom_field_value(field_id, default=None, *, raise_errors=False)[source]

Get the value of a custom field by ID.

Parameters:

field_id (int) – The ID of the custom field.
default (Any) – The value to return if the field is not found.
raise_errors (bool) – Whether to raise an error if the field is not found.

Return type:

Any

Returns:

The value of the custom field or the default value if not found.

property custom_field_values: list[Any]: Get the values of the custom fields for this document.

property custom_fields: CustomFieldQuerySet

Get the custom fields for this document.

Returns:: List of custom fields associated with this document.

property document_type: DocumentType | None

Get the document type for this document.

Returns:: The document type or None if not set.

Examples

>>> document = client.documents().get(pk=1)
>>> document.document_type.name
'Example Document Type

download(original=False)[source]

Download the document file.

Parameters:: original (bool) – Whether to download the original file instead of the archived version.
Return type:: DownloadedDocument
Returns:: The downloaded document.

Examples

>>> download = document.download()
>>> with open(download.disposition_filename, 'wb') as f:
...     f.write(download.content)

get_metadata()[source]

Get the metadata for this document.

Return type:: DocumentMetadata
Returns:: The document metadata.

Examples

>>> metadata = document.get_metadata()
>>> print(metadata.original_mime_type)

get_suggestions()[source]

Get suggestions for this document.

Return type:: DocumentSuggestions
Returns:: The document suggestions.

Examples

>>> suggestions = document.get_suggestions()
>>> print(suggestions.tags)

property has_search_hit: bool

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:

self (BaseModel)
context (Any)

Return type:

None

preview(original=False)[source]

Get a preview of the document.

Parameters:: original (bool) – Whether to preview the original file instead of the archived version.
Return type:: DownloadedDocument
Returns:: The document preview.

remove_tag(tag)[source]

Remove a tag from the document.

Parameters:: tag (Tag | int | str) – The tag to remove.
Return type:: None

property search_hit: dict[str, Any] | None

serialize_datetime(value)[source]

Serialize datetime fields to ISO format.

Parameters:: value (datetime | None) – The datetime value to serialize.
Return type:: str | None
Returns:: The serialized datetime value.

serialize_notes(value)[source]

Serialize notes to a list of dictionaries.

Parameters:: value (list[DocumentNote]) – The list of DocumentNote objects to serialize.
Return type:: list[dict[str, Any]]
Returns:: A list of dictionaries representing the notes.

property storage_path: StoragePath | None

Get the storage path for this document.

Returns:: The storage path or None if not set.

Examples

>>> document = client.documents().get(pk=1)
>>> document.storage_path.name
'Example Storage Path'

property tag_names: list[str]: Get the names of the tags for this document.

property tags: TagQuerySet

Get the tags for this document.

Returns:: List of tags associated with this document.

Examples

>>> document = client.documents().get(pk=1)
>>> for tag in document.tags:
...     print(f'{tag.name} # {tag.id}')
'Tag 1 # 1'
'Tag 2 # 2'
'Tag 3 # 3'

>>> if 5 in document.tags:
...     print('Tag ID #5 is associated with this document')

>>> tag = client.tags().get(pk=1)
>>> if tag in document.tags:
...     print('Tag ID #1 is associated with this document')

>>> filtered_tags = document.tags.filter(name__icontains='example')
>>> for tag in filtered_tags:
...     print(f'{tag.name} # {tag.id}')

thumbnail(original=False)[source]

Get the document thumbnail.

Parameters:: original (bool) – Whether to get the thumbnail of the original file.
Return type:: DownloadedDocument
Returns:: The document thumbnail.

update_locally(from_db=None, **kwargs)[source]

Update the document locally with the provided data.

Parameters:

from_db (bool | None) – Whether to update from the database.
**kwargs (Any) – Additional data to update the document with.

Raises:

NotImplementedError – If attempting to set notes or tags to None when they are not already None.

Return type:

None

classmethod validate_custom_fields(value)[source]

Validate and return custom field dictionaries.

Parameters:: value (Any) – The list of custom field dictionaries to validate.
Return type:: list[CustomFieldValues]
Returns:: A list of validated custom field dictionaries.

classmethod validate_is_shared_by_requester(value)[source]

Validate and return the is_shared_by_requester flag.

Parameters:: value (Any) – The flag to validate.
Return type:: bool
Returns:: The validated flag.

classmethod validate_notes(value)[source]

Validate and return the list of notes.

Parameters:: value (Any) – The list of notes to validate.
Return type:: list[Any]
Returns:: The validated list of notes.

classmethod validate_tags(value)[source]

Validate and convert tag IDs to a list of integers.

Parameters:: value (Any) – The list of tag IDs to validate.
Return type:: list[int]
Returns:: A list of validated tag IDs.

classmethod validate_text(value)[source]

Validate and return a text field.

Parameters:: value (Any) – The value of the text field to validate.
Return type:: str
Returns:: The validated text value.

added: datetime | None

archive_checksum: str | None

archive_filename: str | None

archive_serial_number: int | None

archived_file_name: str | None

checksum: str | None

content: str

correspondent_id: int | None

created: datetime | None

created_date: str | None

custom_field_dicts: Annotated[list[CustomFieldValues], Field(default_factory=list)]

deleted_at: datetime | None

document_type_id: int | None

filename: str | None

is_shared_by_requester: bool

notes: list[DocumentNote]

original_filename: str | None

owner: int | None

page_count: int | None

storage_path_id: int | None

storage_type: DocumentStorageType | None

tag_ids: Annotated[list[int], Field(default_factory=list)]

title: str

user_can_change: bool | None

id: int

class paperap.models.document.DocumentNote(**data)[source]

Bases: StandardModel

Represents a note on a Paperless-NgX document.

Parameters:: data (Any)

class Meta(model)[source]

Bases: Meta

Parameters:: model (type[_Self])

blacklist_filtering_params: ClassVar[set[str]] = {}

field_map: dict[str, str] = {}

filtering_disabled: ClassVar[set[str]] = {}

filtering_fields: ClassVar[set[str]] = {'_resource', 'created', 'deleted_at', 'document', 'id', 'note', 'restored_at', 'transaction_id', 'user'}

read_only_fields: ClassVar[set[str]] = {'created', 'deleted_at', 'id', 'restored_at', 'transaction_id'}

supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}

model: type[_Self]

name: str

get_document()[source]

Get the document associated with this note.

Return type:: Document
Returns:: The document associated with this note.

get_user()[source]

Get the user who created this note.

Return type:: User
Returns:: The user who created this note.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:

self (BaseModel)
context (Any)

Return type:

None

serialize_datetime(value)[source]

Serialize datetime fields to ISO format.

Parameters:: value (datetime | None) – The datetime value to serialize.
Return type:: str | None
Returns:: The serialized datetime value or None if the value is None.

deleted_at: datetime | None

restored_at: datetime | None

transaction_id: int | None

note: str

created: datetime

document: int

user: int

id: int

class paperap.models.document.DocumentQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: StandardQuerySet[Document], HasOwner

QuerySet for Paperless-ngx documents with specialized filtering methods.

Examples

>>> # Search for documents
>>> docs = client.documents().search("invoice")
>>> for doc in docs:
...     print(doc.title)

>>> # Find documents similar to a specific document
>>> similar_docs = client.documents().more_like(42)
>>> for doc in similar_docs:
...     print(doc.title)

Parameters:

resource (BaseResource[_Model, Self])
filters (dict[str, Any] | None)
_cache (list[_Model] | None)
_fetch_all (bool)
_next_url (str | None)
_last_response (ClientResponse)
_iter (Iterator[_Model] | None)
_urls_fetched (list[str] | None)

add_tag(tag_id)[source]

Add a tag to all documents in the current queryset.

Parameters:: tag_id (int) – Tag ID to add
Return type:: Self
Returns:: Self for method chaining

Examples

>>> # Add tag 3 to all documents with "invoice" in title
>>> client.documents().title("invoice", exact=False).add_tag(3)

added_after(date_str)[source]

Filter documents added after the specified date.

Parameters:: date_str (str) – ISO format date string (YYYY-MM-DD)
Return type:: Self
Returns:: Filtered DocumentQuerySet

added_before(date_str)[source]

Filter documents added before the specified date.

Parameters:: date_str (str) – ISO format date string (YYYY-MM-DD)
Return type:: Self
Returns:: Filtered DocumentQuerySet

asn(value, *, exact=True, case_insensitive=True)[source]

Filter documents by archive serial number.

Parameters:

value (str) – The archive serial number to filter by
exact (bool) – If True, match the exact value, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

content(text)[source]

Filter documents whose content contains the specified text.

Parameters:: text (str) – The text to search for in document content
Return type:: Self
Returns:: Filtered DocumentQuerySet

correspondent(value=None, *, exact=True, case_insensitive=True, **kwargs)[source]

Filter documents by correspondent.

Any number of filter arguments can be provided, but at least one must be specified.

Parameters:

value (int | str | None) – The correspondent ID or name to filter by
exact (bool) – If True, match the exact value, otherwise use contains
**kwargs (Any) – Additional filters (slug, id, name)

Return type:

Self

Returns:

Filtered DocumentQuerySet

Raises:

ValueError – If no valid filters are provided

Examples

# Filter by ID client.documents().all().correspondent(1) client.documents().all().correspondent(id=1)

# Filter by name client.documents().all().correspondent(“John Doe”) client.documents().all().correspondent(name=”John Doe”)

# Filter by name (exact match) client.documents().all().correspondent(“John Doe”, exact=True) client.documents().all().correspondent(name=”John Doe”, exact=True)

# Filter by slug client.documents().all().correspondent(slug=”john-doe”)

# Filter by ID and name client.documents().all().correspondent(1, name=”John Doe”) client.documents().all().correspondent(id=1, name=”John Doe”) client.documents().all().correspondent(“John Doe”, id=1)

Parameters:: case_insensitive (bool)

correspondent_id(correspondent_id)[source]

Filter documents by correspondent ID.

Parameters:: correspondent_id (int) – The correspondent ID to filter by
Return type:: Self
Returns:: Filtered DocumentQuerySet

correspondent_name(name, *, exact=True, case_insensitive=True)[source]

Filter documents by correspondent name.

Parameters:

name (str) – The correspondent name to filter by
exact (bool) – If True, match the exact name, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

correspondent_slug(slug, *, exact=True, case_insensitive=True)[source]

Filter documents by correspondent slug.

Parameters:

slug (str) – The correspondent slug to filter by
exact (bool) – If True, match the exact slug, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

created_after(date)[source]

Filter models created after a given date.

Parameters:: date (datetime | str) – The date to filter by
Return type:: Self
Returns:: Filtered QuerySet

created_before(date)[source]

Filter models created before a given date.

Parameters:: date (datetime | str) – The date to filter by
Return type:: Self
Returns:: Filtered QuerySet

created_between(start, end)[source]

Filter models created between two dates.

Parameters:

start (datetime | str) – The start date to filter by
end (datetime | str) – The end date to filter by

Return type:

Self

Returns:

Filtered QuerySet

custom_field(field, value, *, exact=False, case_insensitive=True)[source]

Filter documents by custom field.

Parameters:

field (str) – The name of the custom field
value (Any) – The value to filter by
exact (bool) – If True, match the exact value, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

custom_field_contains(field, values)[source]

Filter documents with a custom field that contains all specified values.

Parameters:

field (str) – The name of the custom field
values (list[Any]) – The list of values that the field should contain

Return type:

Self

Returns:

Filtered DocumentQuerySet

custom_field_exact(field, value)[source]

Filter documents with a custom field value that matches exactly.

Parameters:

field (str) – The name of the custom field
value (Any) – The exact value to match

Return type:

Self

Returns:

Filtered DocumentQuerySet

custom_field_exists(field, exists=True)[source]

Filter documents based on the existence of a custom field.

Parameters:

field (str) – The name of the custom field
exists (bool) – True to filter documents where the field exists, False otherwise

Return type:

Self

Returns:

Filtered DocumentQuerySet

custom_field_fullsearch(value, *, case_insensitive=True)[source]

Filter documents by searching through both custom field name and value.

Parameters:

value (str) – The search string
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

custom_field_in(field, values)[source]

Filter documents with a custom field value in a list of values.

Parameters:

field (str) – The name of the custom field
values (list[Any]) – The list of values to match

Return type:

Self

Returns:

Filtered DocumentQuerySet

custom_field_isnull(field)[source]

Filter documents with a custom field that is null or empty.

Parameters:: field (str) – The name of the custom field
Return type:: Self
Returns:: Filtered DocumentQuerySet

custom_field_query(*args, **kwargs)[source]

Filter documents by custom field query.

Parameters:

args (Any)
kwargs (Any)

Return type:

Self

custom_field_range(field, start, end)[source]

Filter documents with a custom field value within a specified range.

Parameters:

field (str) – The name of the custom field
start (str) – The start value of the range
end (str) – The end value of the range

Return type:

Self

Returns:

Filtered DocumentQuerySet

delete()[source]

Delete all documents in the current queryset.

Return type:: TypeAliasType
Returns:: Self for method chaining

Examples

>>> # Delete all documents with "invoice" in title
>>> client.documents().title("invoice", exact=False).delete()

document_type(value=None, *, exact=True, case_insensitive=True, **kwargs)[source]

Filter documents by document type.

Any number of filter arguments can be provided, but at least one must be specified.

Parameters:

value (int | str | None) – The document type ID or name to filter by
exact (bool) – If True, match the exact value, otherwise use contains
**kwargs (Any) – Additional filters (id, name)

Return type:

Self

Returns:

Filtered DocumentQuerySet

Raises:

ValueError – If no valid filters are provided

Examples

# Filter by ID client.documents().all().document_type(1) client.documents().all().document_type(id=1)

# Filter by name client.documents().all().document_type(“Invoice”) client.documents().all().document_type(name=”Invoice”)

# Filter by name (exact match) client.documents().all().document_type(“Invoice”, exact=True) client.documents().all().document_type(name=”Invoice”, exact=True)

# Filter by ID and name client.documents().all().document_type(1, name=”Invoice”) client.documents().all().document_type(id=1, name=”Invoice”) client.documents().all().document_type(“Invoice”, id=1)

Parameters:: case_insensitive (bool)

document_type_id(document_type_id)[source]

Filter documents by document type ID.

Parameters:: document_type_id (int) – The document type ID to filter by
Return type:: Self
Returns:: Filtered DocumentQuerySet

document_type_name(name, *, exact=True, case_insensitive=True)[source]

Filter documents by document type name.

Parameters:

name (str) – The document type name to filter by
exact (bool) – If True, match the exact name, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

has_custom_field_id(pk, *, exact=False)[source]

Filter documents that have a custom field with the specified ID(s).

Parameters:

pk (int | list[int]) – A single custom field ID or list of custom field IDs
exact (bool) – If True, return results that have exactly these ids and no others

Return type:

Self

Returns:

Filtered DocumentQuerySet

has_custom_fields()[source]

Filter documents that have custom fields.

Return type:: Self

merge(metadata_document_id=None, delete_originals=False)[source]

Merge all documents in the current queryset.

Parameters:

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 succeeded, False if there are no ids to merge

Raises:

BadResponseError – If the merge action returns an unexpected response
APIError – If the merge action fails

Examples

>>> # Merge all documents with tag "merge_me"
>>> client.documents().tag_name("merge_me").merge(delete_originals=True)

modify_custom_fields(add_custom_fields=None, remove_custom_fields=None)[source]

Modify custom fields on all documents in the current queryset.

Parameters:

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:

Self

Returns:

Self for method chaining

Examples

>>> # Add a custom field to documents with "invoice" in title
>>> client.documents().title("invoice", exact=False).modify_custom_fields(
...     add_custom_fields={5: "Processed"}
... )

modify_tags(add_tags=None, remove_tags=None)[source]

Modify tags on all documents in the current queryset.

Parameters:

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

Return type:

Self

Returns:

Self for method chaining

Examples

>>> # Add tag 3 and remove tag 4 from all documents with "invoice" in title
>>> client.documents().title("invoice", exact=False).modify_tags(
...     add_tags=[3], remove_tags=[4]
... )

more_like(document_id)[source]

Find documents similar to the specified document.

Parameters:: document_id (int) – The ID of the document to find similar documents for.
Return type:: DocumentQuerySet
Returns:: A queryset with similar documents.

Examples

>>> similar_docs = client.documents().more_like(42)
>>> for doc in similar_docs:
...     print(doc.title)

no_custom_fields()[source]

Filter documents that do not have custom fields.

Return type:: Self

notes(text)[source]

Filter documents whose notes contain the specified text.

Parameters:: text (str) – The text to search for in document notes
Return type:: Self
Returns:: Filtered DocumentQuerySet

original_filename(name, *, exact=True, case_insensitive=True)[source]

Filter documents by original file name.

Parameters:

name (str) – The original file name to filter by
exact (bool) – If True, match the exact name, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

remove_tag(tag_id)[source]

Remove a tag from all documents in the current queryset.

Parameters:: tag_id (int) – Tag ID to remove
Return type:: Self
Returns:: Self for method chaining

Examples

>>> # Remove tag 4 from all documents with "invoice" in title
>>> client.documents().title("invoice", exact=False).remove_tag(4)

reprocess()[source]

Reprocess all documents in the current queryset.

Return type:: TypeAliasType
Returns:: Self for method chaining

Examples

>>> # Reprocess documents added in the last week
>>> from datetime import datetime, timedelta
>>> week_ago = datetime.now() - timedelta(days=7)
>>> client.documents().added_after(week_ago.strftime("%Y-%m-%d")).reprocess()

rotate(degrees)[source]

Rotate all documents in the current queryset.

Parameters:: degrees (int) – Degrees to rotate (must be 90, 180, or 270)
Return type:: TypeAliasType
Returns:: Self for method chaining

Examples

>>> # Rotate all documents with "sideways" in title by 90 degrees
>>> client.documents().title("sideways", exact=False).rotate(90)

search(query)[source]

Search for documents using a query string.

Parameters:: query (str) – The search query.
Return type:: DocumentQuerySet
Returns:: A queryset with the search results.

Examples

>>> docs = client.documents().search("invoice")
>>> for doc in docs:
...     print(doc.title)

set_permissions(permissions=None, owner_id=None, merge=False)[source]

Set permissions for all documents in the current queryset.

Parameters:

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:

Self

Returns:

Self for method chaining

Examples

>>> # Set owner to user 2 for all documents with "invoice" in title
>>> client.documents().title("invoice", exact=False).set_permissions(owner_id=2)

storage_path(value=None, *, exact=True, case_insensitive=True, **kwargs)[source]

Filter documents by storage path.

Any number of filter arguments can be provided, but at least one must be specified.

Parameters:

value (int | str | None) – The storage path ID or name to filter by
exact (bool) – If True, match the exact value, otherwise use contains
**kwargs (Any) – Additional filters (id, name)

Return type:

Self

Returns:

Filtered DocumentQuerySet

Raises:

ValueError – If no valid filters are provided

Examples

# Filter by ID client.documents().all().storage_path(1) client.documents().all().storage_path(id=1)

# Filter by name client.documents().all().storage_path(“Invoices”) client.documents().all().storage_path(name=”Invoices”)

# Filter by name (exact match) client.documents().all().storage_path(“Invoices”, exact=True) client.documents().all().storage_path(name=”Invoices”, exact=True)

# Filter by ID and name client.documents().all().storage_path(1, name=”Invoices”) client.documents().all().storage_path(id=1, name=”Invoices”) client.documents().all().storage_path(“Invoices”, id=1)

Parameters:: case_insensitive (bool)

storage_path_id(storage_path_id)[source]

Filter documents by storage path ID.

Parameters:: storage_path_id (int) – The storage path ID to filter by
Return type:: Self
Returns:: Filtered DocumentQuerySet

storage_path_name(name, *, exact=True, case_insensitive=True)[source]

Filter documents by storage path name.

Parameters:

name (str) – The storage path name to filter by
exact (bool) – If True, match the exact name, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

tag_id(tag_id)[source]

Filter documents that have the specified tag ID(s).

Parameters:: tag_id (int | list[int]) – A single tag ID or list of tag IDs
Return type:: Self
Returns:: Filtered DocumentQuerySet

tag_name(tag_name, *, exact=True, case_insensitive=True)[source]

Filter documents that have a tag with the specified name.

Parameters:

tag_name (str) – The name of the tag
exact (bool) – If True, match the exact tag name, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

title(title, *, exact=True, case_insensitive=True)[source]

Filter documents by title.

Parameters:

title (str) – The document title to filter by
exact (bool) – If True, match the exact title, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentQuerySet

update(*, correspondent=None, document_type=None, storage_path=None, owner=None)[source]

Perform bulk updates on all documents in the current queryset.

This method allows for multiple update operations in a single call.

Parameters:

correspondent (Correspondent | int | None) – Set correspondent for all documents
document_type (DocumentType | int | None) – Set document type for all documents
storage_path (StoragePath | int | None) – Set storage path for all documents
owner (int | None) – Owner ID to assign

Return type:

Self

Returns:

Self for method chaining

user_can_change(value)[source]

Filter documents by user change permission.

Parameters:: value (bool) – True to filter documents the user can change
Return type:: Self
Returns:: Filtered DocumentQuerySet

resource: DocumentResource

filters: dict[str, Any]

class paperap.models.document.DocumentNoteQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: StandardQuerySet[DocumentNote]

Parameters:

resource (BaseResource[_Model, Self])
filters (dict[str, Any] | None)
_cache (list[_Model] | None)
_fetch_all (bool)
_next_url (str | None)
_last_response (ClientResponse)
_iter (Iterator[_Model] | None)
_urls_fetched (list[str] | None)

class paperap.models.document.DownloadedDocument(**data)[source]

Bases: StandardModel

Represents a downloaded Paperless-NgX document file.

mode: The retrieval mode (download, preview, thumbnail).

original: Whether to retrieve the original file.

content: The binary content of the file.

content_type: The MIME type of the file.

disposition_filename: The filename from the Content-Disposition header.

disposition_type: The type from the Content-Disposition header.

Parameters:: data (Any)

class Meta(model)[source]

Bases: Meta

Parameters:: model (type[_Self])

blacklist_filtering_params: ClassVar[set[str]] = {}

field_map: dict[str, str] = {}

filtering_disabled: ClassVar[set[str]] = {}

filtering_fields: ClassVar[set[str]] = {'_resource', 'content', 'content_type', 'disposition_filename', 'disposition_type', 'id', 'mode', 'original'}

read_only_fields: ClassVar[set[str]] = {'content', 'content_type', 'disposition_filename', 'disposition_type', 'id'}

supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:

self (BaseModel)
context (Any)

Return type:

None

mode: RetrieveFileMode | None

original: bool

content: bytes | None

content_type: str | None

disposition_filename: str | None

disposition_type: str | None

class paperap.models.document.DownloadedDocumentQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: StandardQuerySet[DownloadedDocument]

Parameters:

resource (BaseResource[_Model, Self])
filters (dict[str, Any] | None)
_cache (list[_Model] | None)
_fetch_all (bool)
_next_url (str | None)
_last_response (ClientResponse)
_iter (Iterator[_Model] | None)
_urls_fetched (list[str] | None)

class paperap.models.document.DocumentMetadata(**data)[source]

Bases: StandardModel

Represents a Paperless-NgX document’s metadata.

original_checksum: The checksum of the original document.

original_size: The size of the original document in bytes.

original_mime_type: The MIME type of the original document.

media_filename: The filename of the media file.

has_archive_version: Whether the document has an archive version.

original_metadata: Metadata of the original document.

archive_checksum: The checksum of the archived document.

archive_media_filename: The filename of the archived media file.

original_filename: The original filename of the document.

lang: The language of the document.

archive_size: The size of the archived document in bytes.

archive_metadata: Metadata of the archived document.

Parameters:: data (Any)

class Meta(model)[source]

Bases: Meta

Parameters:: model (type[_Self])

blacklist_filtering_params: ClassVar[set[str]] = {}

field_map: dict[str, str] = {}

filtering_disabled: ClassVar[set[str]] = {}

filtering_fields: ClassVar[set[str]] = {'_resource', 'archive_checksum', 'archive_media_filename', 'archive_metadata', 'archive_size', 'has_archive_version', 'id', 'lang', 'media_filename', 'original_checksum', 'original_filename', 'original_metadata', 'original_mime_type', 'original_size'}

read_only_fields: ClassVar[set[str]] = {'archive_checksum', 'archive_media_filename', 'archive_metadata', 'archive_size', 'has_archive_version', 'id', 'lang', 'media_filename', 'original_checksum', 'original_filename', 'original_metadata', 'original_mime_type', 'original_size'}

supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:

self (BaseModel)
context (Any)

Return type:

None

original_checksum: str | None

original_size: int | None

original_mime_type: str | None

media_filename: str | None

has_archive_version: bool | None

original_metadata: list[MetadataElement]

archive_checksum: str | None

archive_media_filename: str | None

original_filename: str | None

lang: str | None

archive_size: int | None

archive_metadata: list[MetadataElement]

class paperap.models.document.DocumentMetadataQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: StandardQuerySet[DocumentMetadata]

Parameters:

resource (BaseResource[_Model, Self])
filters (dict[str, Any] | None)
_cache (list[_Model] | None)
_fetch_all (bool)
_next_url (str | None)
_last_response (ClientResponse)
_iter (Iterator[_Model] | None)
_urls_fetched (list[str] | None)

class paperap.models.document.MetadataElement(**data)[source]

Bases: BaseModel

Represents metadata for a document in Paperless-NgX.

This is a key-value pair of metadata information.

Parameters:: data (Any)

model_config: ClassVar[ConfigDict] = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

key: str

value: str

class paperap.models.document.CustomFieldValues(**data)[source]

Bases: ConstModel

Parameters:: data (Any)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

field: int

value: Any

class paperap.models.document.DocumentSuggestions(**data)[source]

Bases: StandardModel

Represents suggestions for a Paperless-NgX document.

correspondents: List of suggested correspondent IDs.

tags: List of suggested tag IDs.

document_types: List of suggested document type IDs.

storage_paths: List of suggested storage path IDs.

dates: List of suggested dates.

Parameters:: data (Any)

class Meta(model)[source]

Bases: Meta

Parameters:: model (type[_Self])

blacklist_filtering_params: ClassVar[set[str]] = {}

field_map: dict[str, str] = {}

filtering_disabled: ClassVar[set[str]] = {}

filtering_fields: ClassVar[set[str]] = {'_resource', 'correspondents', 'dates', 'document_types', 'id', 'storage_paths', 'tags'}

read_only_fields: ClassVar[set[str]] = {'correspondents', 'dates', 'document_types', 'id', 'storage_paths', 'tags'}

supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:

self (BaseModel)
context (Any)

Return type:

None

correspondents: list[int]

tags: list[int]

document_types: list[int]

storage_paths: list[int]

dates: list[date]

class paperap.models.document.DocumentSuggestionsQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: StandardQuerySet[DocumentSuggestions]

Parameters:

resource (BaseResource[_Model, Self])
filters (dict[str, Any] | None)
_cache (list[_Model] | None)
_fetch_all (bool)
_next_url (str | None)
_last_response (ClientResponse)
_iter (Iterator[_Model] | None)
_urls_fetched (list[str] | None)

paperap.models.document package

Subpackages

Submodules