paperap.models.document.queryset module

METADATA:

File: queryset.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.queryset.CustomFieldQuery(field, operation, value)[source]

Bases: NamedTuple

field: str: Alias for field number 0

operation: Union[str, CustomFieldQuery, tuple[str, Union[str, _QueryParam], Any]]: Alias for field number 1

value: Any: Alias for field number 2

class paperap.models.document.queryset.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.queryset.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)

resource: DocumentResource

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

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)

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)

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

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

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

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

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

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

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

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

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

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

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

has_custom_fields()[source]

Filter documents that have custom fields.

Return type:: Self

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

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

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()

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()

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)

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)

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

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]
... )

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)

filters: dict[str, Any]

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)

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)