Models 

property resource: BaseResource[Self, BaseQuerySet]

property save_executor: ThreadPoolExecutor

should_save_on_write()[source]

Check if the model should save on attribute write, factoring in the client settings.

Return type:: bool

to_dict(*, include_read_only=True, exclude_none=False, exclude_unset=True)[source]

Convert the model to a dictionary for API requests.

Parameters:

include_read_only (bool) – Whether to include read-only fields.
exclude_none (bool) – Whether to exclude fields with None values.
exclude_unset (bool) – Whether to exclude fields that are not set.

Return type:

dict[str, Any]

Returns:

A dictionary with model data ready for API submission.

Examples

# Convert a Document instance to a dictionary data = doc.to_dict()

update(**kwargs)[source]

Update this model with new values.

Subclasses implement this with auto-saving features. However, base BaseModel instances simply call update_locally.

Parameters:: **kwargs (Any) – New field values.
Return type:: None

Examples

# Update a Document instance doc.update(filename=”new_example.pdf”)

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

Update model attributes without triggering automatic save.

Parameters:

**kwargs (Any) – Field values to update
from_db (bool | None)
skip_changed_fields (bool)

Return type:

Returns:

Self with updated values

class paperap.models.StandardModel(**data)[source]

Bases: BaseModel, ABC

Standard model for Paperless-ngx API objects with an ID field.

id: Unique identifier for the model.

Parameters:: data (Any)

class Meta(model)[source]

Bases: Meta

Metadata for the StandardModel.

read_only_fields: Fields that should not be modified.

supported_filtering_params: Params allowed during queryset filtering.

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', 'id'}

read_only_fields: ClassVar[set[str]] = {'id'}

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

model: type[_Self]

name: str

__setattr__(name, value)[source]

Override attribute setting to automatically trigger async save.

Parameters:

name (str) – Attribute name
value (Any) – New attribute value

Return type:

__str__()[source]

Human-readable string representation.

Return type:: str
Returns:: A string representation of the model.

is_new()[source]

Check if this model represents a new (unsaved) object.

Return type:: bool
Returns:: True if the model is new, False otherwise.

Examples

# Check if a Document instance is new is_new = doc.is_new()

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:

refresh()[source]

Refresh the model with the latest data from the server.

Return type:: bool
Returns:: True if the model data changes, False on failure or if the data does not change.
Raises:: ResourceNotFoundError – If the model is not found on Paperless. (e.g. it was deleted remotely)

property resource: StandardResource[Self, StandardQuerySet]

save(*, force=False)[source]

Parameters:: force (bool)
Return type:: bool

save_async(*, force=False)[source]

Save this model instance asynchronously.

Changes are sent to the server in a background thread, and the model is updated when the server responds.

Return type:: bool
Returns:: True if the save was successfully submitted async, False otherwise.
Parameters:: force (bool)

save_sync(*, force=False)[source]

Save this model instance synchronously.

Changes are sent to the server immediately, and the model is updated when the server responds.

Return type:

bool

Returns:

True if the save was successful, False otherwise.

Raises:

ResourceNotFoundError – If the resource doesn’t exist on the server
RequestError – If there’s a communication error with the server
PermissionError – If the user doesn’t have permission to update the resource

Parameters:

force (bool)

update(**kwargs)[source]

Update this model with new values and save changes.

NOTE: new instances will not be saved automatically. (I’m not sure if that’s the right design decision or not)

Parameters:: **kwargs (Any) – New field values.
Return type:: None

id: int

class paperap.models.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:

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

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:

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.Correspondent(**data)[source]

Represents a correspondent in Paperless-NgX.

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', 'document_count', 'id', 'name', 'owner', 'slug', 'user_can_change'}

queryset: alias of CorrespondentQuerySet

read_only_fields: ClassVar[set[str]] = {'document_count', 'id', 'slug'}

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

model: type[_Self]

name: str

property documents: DocumentQuerySet: Get documents for this correspondent.

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:

slug: str | None

name: str | None

document_count: int

owner: int | None

user_can_change: bool | None

id: int

class paperap.models.Tag(**data)[source]

Represents a tag in Paperless-NgX.

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', 'colour', 'document_count', 'id', 'is_inbox_tag', 'name', 'owner', 'slug', 'user_can_change'}

queryset: alias of TagQuerySet

read_only_fields: ClassVar[set[str]] = {'document_count', 'id', 'slug'}

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

model: type[_Self]

name: str

property color: str | int | None: Alias for colour field.

property documents: DocumentQuerySet

Get documents with this tag.

Returns:: List of documents.

classmethod handle_text_color_alias(data)[source]

Handle ‘text_color’ as an alias for ‘colour’.

Parameters:: data (dict[str, Any])
Return type:: dict[str, Any]

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:

name: str | None

slug: str | None

colour: str | int | None

is_inbox_tag: bool | None

document_count: int

owner: int | None

user_can_change: bool | None

id: int

class paperap.models.DocumentType(**data)[source]

Represents a document type in Paperless-NgX.

name: The name of the document type.

slug: A unique identifier for the document type.

match: The pattern used for matching documents.

matching_algorithm: The algorithm used for matching.

is_insensitive: Whether the matching is case insensitive.

document_count: The number of documents of this type.

owner: The owner of the document type.

user_can_change: Whether the user can change the document type.

Returns:: A new instance of DocumentType.

Examples

# Create a new DocumentType instance doc_type = DocumentType(name=”Invoice”, slug=”invoice”, match=”INV-*”)

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', 'document_count', 'id', 'name', 'owner', 'slug', 'user_can_change'}

queryset: alias of DocumentTypeQuerySet

read_only_fields: ClassVar[set[str]] = {'document_count', 'id', 'slug'}

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

model: type[_Self]

name: str

property documents: DocumentQuerySet

Get documents with this document type.

Returns:: A DocumentQuerySet containing documents of this type.

Examples

# Get all documents of this type documents = doc_type.documents

Get documents with this document type.

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:

name: str

slug: str | None

document_count: int

owner: int | None

user_can_change: bool | None

id: int

class paperap.models.StoragePath(**data)[source]

Represents a storage path in Paperless-NgX.

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', 'document_count', 'id', 'name', 'owner', 'path', 'slug', 'user_can_change'}

queryset: alias of StoragePathQuerySet

read_only_fields: ClassVar[set[str]] = {'document_count', 'id', 'slug'}

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

model: type[_Self]

name: str

property documents: DocumentQuerySet: Get documents in this storage path.

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:

name: str

slug: str | None

path: str | None

document_count: int

owner: int | None

user_can_change: bool | None

id: int

class paperap.models.CustomField(**data)[source]

Bases: StandardModel

Represents a custom field in Paperless-NgX.

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', 'data_type', 'document_count', 'extra_data', 'id', 'name'}

read_only_fields: ClassVar[set[str]] = {'id', 'slug'}

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

model: type[_Self]

name: str

property documents: DocumentQuerySet: Get documents with this custom field.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'allow', '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:

classmethod validate_data_type(v)[source]

Validate the data_type field.

Parameters:: v (Any) – The value to validate.
Return type:: CustomFieldTypes | None
Returns:: The validated value.
Raises:: ValueError – If the value is not a valid data type.

name: str

data_type: CustomFieldTypes | None

extra_data: dict[str, Any]

document_count: int

id: int

class paperap.models.User(**data)[source]

Bases: StandardModel

Represents a user in Paperless-NgX.

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', 'date_joined', 'email', 'first_name', 'groups', 'id', 'inherited_permissions', 'is_active', 'is_staff', 'is_superuser', 'last_name', 'password', 'user_permissions', 'username'}

queryset: alias of UserQuerySet

read_only_fields: ClassVar[set[str]] = {'id'}

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

model: type[_Self]

name: str

get_groups()[source]

Get the groups this user is a member of.

Returns:: The groups this user is a member
Return type:: GroupQuerySet

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:

username: str | None

email: str | None

password: str | None

first_name: str | None

last_name: str | None

date_joined: str | None

is_staff: bool | None

is_active: bool | None

is_superuser: bool | None

groups: list[int]

user_permissions: list[str]

inherited_permissions: list[str]

id: int

class paperap.models.Group(**data)[source]

Bases: StandardModel

Represents a user group in Paperless-NgX.

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', 'id', 'name', 'permissions'}

queryset: alias of GroupQuerySet

read_only_fields: ClassVar[set[str]] = {'id'}

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

model: type[_Self]

name: str

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:

property users: UserQuerySet

Get the users in this group.

Returns:: The users in this group
Return type:: UserQuerySet

name: str | None

permissions: list[str]

id: int

class paperap.models.Task(**data)[source]

Bases: StandardModel

Represents a task in Paperless-NgX.

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', 'acknowledged', 'date_created', 'date_done', 'date_started', 'id', 'related_document', 'result', 'status', 'task_file_name', 'task_id', 'task_name', 'type'}

queryset: alias of TaskQuerySet

read_only_fields: ClassVar[set[str]] = {'id'}

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

model: type[_Self]

name: str

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:

task_id: str

task_file_name: str | None

task_name: TaskNameType | None

date_created: datetime | None

date_started: datetime | None

date_done: datetime | None

type: TaskTypeType | None

status: TaskStatusType | None

result: str | None

acknowledged: bool

related_document: int | None

id: int

class paperap.models.SavedView(**data)[source]

Bases: StandardModel

Represents a saved view in Paperless-NgX.

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', 'display_fields', 'display_mode', 'filter_rules', 'id', 'name', 'owner', 'page_size', 'show_in_sidebar', 'show_on_dashboard', 'sort_field', 'sort_reverse', 'user_can_change'}

queryset: alias of SavedViewQuerySet

read_only_fields: ClassVar[set[str]] = {'id', 'owner', 'user_can_change'}

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

model: type[_Self]

name: str

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:

name: str

show_on_dashboard: bool | None

show_in_sidebar: bool | None

sort_field: str | None

sort_reverse: bool | None

filter_rules: list[SavedViewFilterRuleType]

page_size: int | None

display_mode: SavedViewDisplayModeType | None

display_fields: list[SavedViewDisplayFieldType]

owner: int | None

user_can_change: bool | None

id: int

class paperap.models.UISettings(**data)[source]

Bases: StandardModel

Represents UI settings in Paperless-NgX.

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', 'id', 'permissions', 'settings', 'user'}

queryset: alias of UISettingsQuerySet

read_only_fields: ClassVar[set[str]] = {'id'}

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

model: type[_Self]

name: str

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:

user: dict[str, Any]

settings: dict[str, Any]

permissions: list[str]

id: int

class paperap.models.Workflow(**data)[source]

Bases: StandardModel

Represents a workflow in Paperless-NgX.

Parameters:: data (Any)

class Meta(model)[source]

Bases: Meta

Metadata for the Workflow model.

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', 'actions', 'enabled', 'id', 'name', 'order', 'triggers'}

queryset: alias of WorkflowQuerySet

read_only_fields: ClassVar[set[str]] = {'id'}

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

model: type[_Self]

name: str

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:

name: str

order: int | None

enabled: bool | None

triggers: list[dict[str, Any]]

actions: list[dict[str, Any]]

id: int

class paperap.models.WorkflowTrigger(**data)[source]

Represents a workflow trigger in Paperless-NgX.

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', 'filter_filename', 'filter_has_correspondent', 'filter_has_document_type', 'filter_has_tags', 'filter_mailrule', 'filter_path', 'id', 'schedule_date_custom_field', 'schedule_date_field', 'schedule_is_recurring', 'schedule_offset_days', 'schedule_recurring_interval_days', 'sources', 'type'}

queryset: alias of WorkflowTriggerQuerySet

read_only_fields: ClassVar[set[str]] = {'id'}

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

model: type[_Self]

name: str

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:

sources: list[WorkflowTriggerSourceType]

type: WorkflowTriggerType | None

filter_path: str | None

filter_filename: str | None

filter_mailrule: str | None

filter_has_tags: list[int]

filter_has_correspondent: int | None

filter_has_document_type: int | None

schedule_date_field: ScheduleDateFieldType | None

schedule_date_custom_field: int | None

schedule_offset_days: int

schedule_is_recurring: bool

schedule_recurring_interval_days: int

id: int

class paperap.models.WorkflowAction(**data)[source]

Bases: StandardModel

Represents a workflow action in Paperless-NgX.

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', 'assign_change_groups', 'assign_change_users', 'assign_correspondent', 'assign_custom_fields', 'assign_custom_fields_values', 'assign_document_type', 'assign_owner', 'assign_storage_path', 'assign_tags', 'assign_title', 'assign_view_groups', 'assign_view_users', 'email', 'id', 'remove_all_correspondents', 'remove_all_custom_fields', 'remove_all_document_types', 'remove_all_owners', 'remove_all_permissions', 'remove_all_storage_paths', 'remove_all_tags', 'remove_change_groups', 'remove_change_users', 'remove_correspondents', 'remove_custom_fields', 'remove_document_types', 'remove_owners', 'remove_storage_paths', 'remove_tags', 'remove_view_groups', 'remove_view_users', 'type', 'webhook'}

queryset: alias of WorkflowActionQuerySet

read_only_fields: ClassVar[set[str]] = {'id'}

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

model: type[_Self]

name: str

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:

type: WorkflowActionType | None

assign_title: str | None

assign_tags: list[int]

assign_correspondent: int | None

assign_document_type: int | None

assign_storage_path: int | None

assign_owner: int | None

assign_view_users: list[int]

assign_view_groups: list[int]

assign_change_users: list[int]

assign_change_groups: list[int]

assign_custom_fields: list[int]

assign_custom_fields_values: dict[str, Any]

remove_all_tags: bool | None

remove_tags: list[int]

remove_all_correspondents: bool | None

remove_correspondents: list[int]

remove_all_document_types: bool | None

remove_document_types: list[int]

remove_all_storage_paths: bool | None

remove_storage_paths: list[int]

remove_custom_fields: list[int]

remove_all_custom_fields: bool | None

remove_all_owners: bool | None

remove_owners: list[int]

remove_all_permissions: bool | None

remove_view_users: list[int]

remove_view_groups: list[int]

remove_change_users: list[int]

remove_change_groups: list[int]

email: dict[str, Any] | None

webhook: dict[str, Any] | None

id: int

class paperap.models.Profile(**data)[source]

Bases: StandardModel

Represents a user profile in the Paperless NGX system.

email: The email address of the user.

password: The password for the user.

first_name: The first name of the user.

last_name: The last name of the user.

auth_token: The authentication token for the user.

social_accounts: A list of social accounts associated with the user.

has_usable_password: Indicates if the user has a usable password.

Examples

>>> profile = Profile(email="a@google.com", password="abc", first_name="John", last_name="Doe")
>>> print(profile.email)

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', 'auth_token', 'email', 'first_name', 'has_usable_password', 'id', 'last_name', 'password', 'social_accounts'}

queryset: alias of ProfileQuerySet

read_only_fields: ClassVar[set[str]] = {'id'}

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

model: type[_Self]

name: str

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:

email: str | None

password: str | None

first_name: str | None

last_name: str | None

auth_token: str | None

social_accounts: list[Any]

has_usable_password: bool

id: int

class paperap.models.ShareLinks(**data)[source]

Bases: StandardModel

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', 'document', 'expiration', 'file_version', 'id', 'owner', 'slug'}

queryset: alias of ShareLinksQuerySet

read_only_fields: ClassVar[set[str]] = {'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 share link

Returns:: The document object
Return type:: Document

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:

serialize_datetime(value)[source]

Serialize a datetime object to an ISO 8601 formatted string

Parameters:: value (datetime) – The datetime object to serialize
Returns:: The serialized datetime
Return type:: str

expiration: datetime | None

slug: str | None

document: int | None

created: datetime | None

file_version: ShareLinkFileVersionType | None

owner: int | None

id: int

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

Bases: Iterable, Generic

A lazy-loaded, chainable query interface for Paperless NGX resources.

BaseQuerySet provides pagination, filtering, and caching functionality similar to Django’s QuerySet. It’s designed to be lazy - only fetching data when it’s actually needed.

Parameters:

resource (BaseResource[_Model, Self]) – The BaseResource instance.
filters (dict[str, Any] | None) – Initial filter parameters.
_cache (list[_Model] | None) – Optional internal result cache.
_fetch_all (bool) – Whether all results have been fetched.
_next_url (str | None) – URL for the next page of results.
_last_response (ClientResponse) – Optional last response from the API.
_iter (Iterator[_Model] | None) – Optional iterator for the results.

Returns:

A new instance of BaseQuerySet.

Examples

# Create a QuerySet for documents >>> docs = client.documents() >>> for doc in docs: … print(doc.id) 1 2 3

Parameters:: _urls_fetched (list[str] | None)

__bool__()[source]

Return True if the QuerySet has any results.

Return type:: bool
Returns:: True if there are any objects matching the filters

__contains__(item)[source]

Return True if the QuerySet contains the given object.

Parameters:: item (Any) – The object to check for
Return type:: bool
Returns:: True if the object is in the QuerySet

__getitem__(key)[source]

Retrieve an item or slice of items from the QuerySet.

Parameters:: key (int | slice) – An integer index or slice
Return type:: _Model | list[_Model]
Returns:: A single object or list of objects
Raises:: IndexError – If the index is out of range

__init__(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

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)

__iter__()[source]

Iterate over the objects in the QuerySet.

Return type:: Iterator[_Model]
Returns:: An iterator over the objects

__len__()[source]

Return the number of objects in the QuerySet.

Return type:: int
Returns:: The count of objects

all()[source]

Return a new QuerySet that copies the current one.

Return type:: Self
Returns:: A copy of the current BaseQuerySet

count()[source]

Return the total number of objects in the queryset.

Return type:: int
Returns:: The total count of objects matching the filters
Raises:: NotImplementedError – If the response does not have a count attribute

count_this_page()[source]

Return the number of objects on the current page.

Return type:: int
Returns:: The count of objects on the current page
Raises:: NotImplementedError – If _last_response is not set

exclude(**kwargs)[source]

Return a new QuerySet excluding objects with the given filters.

Parameters:: **kwargs (Any) – Filters to exclude, where keys are field names and values are excluded values
Return type:: Self
Returns:: A new QuerySet excluding objects that match the filters

Examples

# Get documents with any correspondent except ID 1 docs = client.documents.exclude(correspondent=1)

exists()[source]

Return True if the QuerySet contains any results.

Return type:: bool
Returns:: True if there are any objects matching the filters

filter(**kwargs)[source]

Return a new QuerySet with the given filters applied.

Parameters:: **kwargs (Any) – Filters to apply, where keys are field names and values are desired values. Supports Django-style lookups like field__contains, field__in, etc.
Return type:: Self
Returns:: A new QuerySet with the additional filters applied

Examples

# Get documents with specific correspondent docs = client.documents.filter(correspondent=1)

# Get documents with specific correspondent and document type docs = client.documents.filter(correspondent=1, document_type=2)

# Get documents with title containing “invoice” docs = client.documents.filter(title__contains=”invoice”)

# Get documents with IDs in a list docs = client.documents.filter(id__in=[1, 2, 3])

filter_field_by_str(field, value, *, exact=True, case_insensitive=True)[source]

Filter a queryset based on a given field.

This allows subclasses to easily implement custom filter methods.

Parameters:

field (str) – The field name to filter by.
value (str) – The value to filter against.
exact (bool) – Whether to filter by an exact match.
case_insensitive (bool) – Whether the filter should be case-insensitive.

Return type:

Self

Returns:

A new QuerySet instance with the filter applied.

first()[source]

Return the first object in the QuerySet, or None if empty.

Return type:: _Model | None
Returns:: The first object or None if no objects match

get(pk)[source]

Retrieve a single object from the API.

Raises NotImplementedError. Subclasses may implement this.

Parameters:

pk (Any) – The primary key (e.g. the id) of the object to retrieve

Return type:

_Model

Returns:

A single object matching the query

Raises:

ObjectNotFoundError – If no object or multiple objects are found
NotImplementedError – If the method is not implemented by the subclass

Examples

# Get document with ID 123 doc = client.documents.get(123)

last()[source]

Return the last object in the QuerySet, or None if empty.

Note: This requires fetching all results to determine the last one.

Return type:: _Model | None
Returns:: The last object or None if no objects match

none()[source]

Return an empty QuerySet.

Return type:: Self
Returns:: An empty QuerySet

order_by(*fields)[source]

Return a new QuerySet ordered by the specified fields.

Parameters:: *fields (str) – Field names to order by. Prefix with ‘-’ for descending order.
Return type:: Self
Returns:: A new QuerySet with the ordering applied

Examples

# Order documents by title ascending docs = client.documents.order_by(‘title’)

# Order documents by added date descending docs = client.documents.order_by(‘-added’)

resource: BaseResource[TypeVar(_Model, bound= BaseModel), Self]

filters: dict[str, Any]

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

Bases: BaseQuerySet, Generic

A queryset for StandardModel instances (i.e. BaseModels with standard fields, like id).

Returns:: A new instance of StandardModel.
Raises:: ValueError – If resource is not provided.

Examples

# Create a StandardModel instance model = StandardModel(id=1)

Parameters:

resource (BaseResource[_Model, Self]) – The BaseResource instance.
filters (dict[str, Any] | None) – Initial filter parameters.

Returns:

A new instance of StandardQuerySet.

Raises:

ObjectNotFoundError – If no object or multiple objects are found.

Examples

# Create a StandardQuerySet for documents docs = StandardQuerySet(resource=client.documents)

Parameters:

_cache (list[_Model] | None)
_fetch_all (bool)
_next_url (str | None)
_last_response (ClientResponse)
_iter (Iterator[_Model] | None)
_urls_fetched (list[str] | None)

__contains__(item)[source]

Return True if the QuerySet contains the given object.

NOTE: This method only ensures a match by ID, not by full object equality. This is intentional, as the object may be outdated or not fully populated.

Parameters:: item (Any) – The object or ID to check for
Return type:: bool
Returns:: True if the object is in the QuerySet

bulk_action(action, **kwargs)[source]

Perform a bulk action on all objects in the queryset.

This method fetches all IDs in the queryset and passes them to the resource’s bulk_action method.

Parameters:

action (str) – The action to perform
**kwargs (Any) – Additional parameters for the action

Return type:

TypeAliasType

Returns:

The API response

Raises:

NotImplementedError – If the resource doesn’t support bulk actions

bulk_assign_correspondent(correspondent_id)[source]

Assign a correspondent to all objects in the queryset.

Parameters:: correspondent_id (int) – Correspondent ID to assign
Return type:: TypeAliasType
Returns:: The API response

bulk_assign_document_type(document_type_id)[source]

Assign a document type to all objects in the queryset.

Parameters:: document_type_id (int) – Document type ID to assign
Return type:: TypeAliasType
Returns:: The API response

bulk_assign_owner(owner_id)[source]

Assign an owner to all objects in the queryset.

Parameters:: owner_id (int) – Owner ID to assign
Return type:: TypeAliasType
Returns:: The API response

bulk_assign_storage_path(storage_path_id)[source]

Assign a storage path to all objects in the queryset.

Parameters:: storage_path_id (int) – Storage path ID to assign
Return type:: TypeAliasType
Returns:: The API response

bulk_assign_tags(tag_ids, remove_existing=False)[source]

Assign tags to all objects in the queryset.

Parameters:

tag_ids (list[int]) – List of tag IDs to assign
remove_existing (bool) – If True, remove existing tags before assigning new ones

Return type:

TypeAliasType

Returns:

The API response

bulk_update(**kwargs)[source]

Update all objects in the queryset with the given values.

Parameters:: **kwargs (Any) – Fields to update
Return type:: TypeAliasType
Returns:: The API response

delete()[source]

Delete all objects in the queryset.

Return type:: TypeAliasType
Returns:: The API response

get(pk)[source]

Retrieve a single object from the API.

Parameters:: pk (int) – The ID of the object to retrieve
Return type:: _Model
Returns:: A single object matching the query
Raises:: ObjectNotFoundError – If no object or multiple objects are found

Examples

# Get document with ID 123 doc = client.documents.get(123)

id(value)[source]

Filter models by ID.

Parameters:: value (int | list[int]) – The ID or list of IDs to filter by
Return type:: Self
Returns:: Filtered QuerySet

resource: StandardResource[TypeVar(_Model, bound= StandardModel), Self]

filters: dict[str, Any]

class paperap.models.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.CorrespondentQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: StandardQuerySet[Correspondent], HasOwner, HasDocumentCount

QuerySet for Paperless-ngx correspondents with specialized filtering methods.

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)

case_insensitive(insensitive=True)[source]

Filter correspondents by case sensitivity setting.

Parameters:: insensitive (bool) – If True, get correspondents with case insensitive matching
Return type:: Self
Returns:: Filtered CorrespondentQuerySet

match(match, *, exact=True, case_insensitive=True)[source]

Filter correspondents by match.

Parameters:

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

Return type:

Self

Returns:

Filtered CorrespondentQuerySet

matching_algorithm(value)[source]

Filter correspondents by their matching algorithm.

Parameters:: value (int) – The matching algorithm ID to filter by
Return type:: Self
Returns:: Filtered CorrespondentQuerySet

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

Filter correspondents by name.

Parameters:

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

Return type:

Self

Returns:

Filtered CorrespondentQuerySet

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

Filter correspondents by slug.

Parameters:

value (str) – The slug to filter by
exact (bool) – If True, match the exact slug, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered CorrespondentQuerySet

user_can_change(value=True)[source]

Filter correspondents by user change permission.

Parameters:: value (bool) – If True, get correspondents that can be changed by user
Return type:: Self
Returns:: Filtered CorrespondentQuerySet

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

Bases: StandardQuerySet[Tag], HasStandard

QuerySet for Paperless-ngx tags with specialized filtering methods.

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)

case_insensitive(value=True)[source]

Filter tags by case insensitivity.

Parameters:: value (bool) – If True, filter tags that are case insensitive
Return type:: Self
Returns:: Filtered TagQuerySet

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

Filter tags by color.

Parameters:

value (str | int) – The color to filter by (string or integer)
exact (bool) – If True, match the exact color, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching (for string values)

Return type:

Self

Returns:

Filtered TagQuerySet

is_inbox_tag(value=True)[source]

Filter tags by inbox status.

Parameters:: value (bool) – If True, get inbox tags, otherwise non-inbox tags
Return type:: Self
Returns:: Filtered TagQuerySet

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

Filter tags by match value.

Parameters:

value (str) – The value to filter by
exact (bool) – If True, match the exact value, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered TagQuerySet

matching_algorithm(value)[source]

Filter tags by matching algorithm.

Parameters:: value (int) – The matching algorithm to filter by
Return type:: Self
Returns:: Filtered TagQuerySet

user_can_change(value=True)[source]

Filter tags by user change permission.

Parameters:: value (bool) – If True, get tags that can be changed by user
Return type:: Self
Returns:: Filtered TagQuerySet

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

Bases: StandardQuerySet[DocumentType], HasOwner, HasDocumentCount

QuerySet for Paperless-ngx document types with specialized filtering methods.

Returns:: A new instance of DocumentTypeQuerySet.

Examples

# Create a DocumentTypeQuerySet instance queryset = DocumentTypeQuerySet()

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)

case_insensitive(value=True)[source]

Filter document types by case sensitivity setting.

Parameters:

insensitive – If True, get document types with case insensitive matching
value (bool)

Return type:

Self

Returns:

Filtered DocumentTypeQuerySet

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

Filter document types by match pattern.

Parameters:

value (str) – The pattern to search for in match
exact (bool) – If True, match the exact pattern, otherwise use contains
case_insensitive (bool)

Return type:

Self

Returns:

Filtered DocumentTypeQuerySet

matching_algorithm(value)[source]

Filter document types by matching algorithm.

Parameters:: value (int) – The matching algorithm ID
Return type:: Self
Returns:: Filtered DocumentTypeQuerySet

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

Filter document types by name.

Parameters:

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

Return type:

Self

Returns:

Filtered DocumentTypeQuerySet

Examples

# Filter document types by name filtered = queryset.name(“Invoice”)

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

Filter document types by slug.

Parameters:

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

Return type:

Self

Returns:

Filtered DocumentTypeQuerySet

user_can_change(value=True)[source]

Filter document types by user change permission.

Parameters:: value (bool) – If True, get document types where users can change
Return type:: Self
Returns:: Filtered DocumentTypeQuerySet

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

Bases: StandardQuerySet[StoragePath], HasStandard

QuerySet for Paperless-ngx storage paths with specialized filtering methods.

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)

case_insensitive(insensitive=True)[source]

Filter storage paths by case sensitivity setting.

Parameters:: insensitive (bool) – If True, get storage paths with case insensitive matching
Return type:: Self
Returns:: Filtered StoragePathQuerySet

match(value, *, exact=True)[source]

Filter storage paths by match value.

Parameters:

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

Return type:

Self

Returns:

Filtered StoragePathQuerySet

matching_algorithm(value)[source]

Filter storage paths by matching algorithm.

Parameters:: value (int) – The matching algorithm to filter by
Return type:: Self
Returns:: Filtered StoragePathQuerySet

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

Filter storage paths by their actual path value.

Parameters:

value (str) – The path to filter by
exact (bool) – If True, match the exact path, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered StoragePathQuerySet

user_can_change(can_change=True)[source]

Filter storage paths by user change permission.

Parameters:: can_change (bool) – If True, get storage paths that can be changed by user
Return type:: Self
Returns:: Filtered StoragePathQuerySet

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

Bases: StandardQuerySet[CustomField], HasDocumentCount

QuerySet for Paperless-ngx custom fields with specialized filtering methods.

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)

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

Filter custom fields by data type.

Parameters:

value (str) – The data type to filter by (e.g., “string”, “integer”, “boolean”, “date”)
exact (bool) – If True, match the exact data type, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered CustomFieldQuerySet

extra_data(key, value)[source]

Filter custom fields by a key-value pair in extra_data.

Parameters:

key (str) – The key in extra_data to filter by
value (Any) – The value to filter by

Return type:

Self

Returns:

Filtered CustomFieldQuerySet

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

Filter custom fields by name.

Parameters:

value (str) – The custom field name to filter by
exact (bool) – If True, match the exact name, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered CustomFieldQuerySet

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

Bases: StandardQuerySet[User]

A lazy-loaded, chainable query interface for Paperless NGX resources.

BaseQuerySet provides pagination, filtering, and caching functionality similar to Django’s BaseQuerySet. It’s designed to be lazy - only fetching data when it’s actually needed.

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)

active(value=True)[source]

Filter users by active status.

Parameters:: value (bool) – If True, filter users that are active
Return type:: Self
Returns:: Filtered UserQuerySet

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

Filter users by email.

Parameters:

value (str) – The email to filter by
exact (bool) – If True, match the exact email, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered UserQuerySet

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

Filter users by first name.

Parameters:

value (str) – The first name to filter by
exact (bool) – If True, match the exact first name, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered UserQuerySet

has_inherited_permission(value)[source]

Filter users by inherited permission.

Parameters:: value (str) – The inherited permission to filter by
Return type:: Self
Returns:: Filtered UserQuerySet

has_permission(value)[source]

Filter users by permission.

Parameters:: value (str) – The permission to filter by
Return type:: Self
Returns:: Filtered UserQuerySet

in_group(value)[source]

Filter users by group.

Parameters:: value (int) – The group to filter by
Return type:: Self
Returns:: Filtered UserQuerySet

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

Filter users by last name.

Parameters:

value (str) – The last name to filter by
exact (bool) – If True, match the exact last name, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered UserQuerySet

staff(value=True)[source]

Filter users by staff status.

Parameters:: value (bool) – If True, filter users that are staff
Return type:: Self
Returns:: Filtered UserQuerySet

superuser(value=True)[source]

Filter users by superuser status.

Parameters:: value (bool) – If True, filter users that are superusers
Return type:: Self
Returns:: Filtered UserQuerySet

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

Filter users by username.

Parameters:

value (str) – The username to filter by
exact (bool) – If True, match the exact username, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered UserQuerySet

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

Bases: StandardQuerySet[Group]

A lazy-loaded, chainable query interface for Paperless NGX resources.

BaseQuerySet provides pagination, filtering, and caching functionality similar to Django’s BaseQuerySet. It’s designed to be lazy - only fetching data when it’s actually needed.

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)

has_permission(value)[source]

Filter groups by permission.

Parameters:: value (str) – The permission to filter by
Return type:: Self
Returns:: Filtered GroupQuerySet

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

Filter groups by name.

Parameters:

value (str) – The name to filter by
exact (bool) – If True, match the exact name, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Return type:

Self

Returns:

Filtered GroupQuerySet

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

Bases: StandardQuerySet[Task]

A lazy-loaded, chainable query interface for Paperless NGX resources.

BaseQuerySet provides pagination, filtering, and caching functionality similar to Django’s BaseQuerySet. It’s designed to be lazy - only fetching data when it’s actually needed.

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)

acknowledged(value)[source]

Filter tasks by acknowledged.

Parameters:: value (bool) – The acknowledged to filter by
Returns:: The filtered queryset
Return type:: TaskQuerySet

date_done(value)[source]

Filter tasks by date_done.

Parameters:: value (str | None) – The date_done to filter by
Returns:: The filtered queryset
Return type:: TaskQuerySet

related_document(value)[source]

Filter tasks by related_document.

Parameters:: value (int | list[int]) – The related_document to filter by
Returns:: The filtered queryset
Return type:: TaskQuerySet

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

Filter tasks by result.

Parameters:

value (str | None) – The result to filter by
exact (bool) – If True, match the exact result, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Returns:

The filtered queryset

Return type:

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

Filter tasks by status.

Parameters:

value (str) – The status to filter by
exact (bool) – If True, match the exact status, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Returns:

The filtered queryset

Return type:

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

Filter tasks by task_file_name.

Parameters:

value (str) – The task_file_name to filter by
exact (bool) – If True, match the exact task_file_name, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Returns:

The filtered queryset

Return type:

task_id(value)[source]

Filter tasks by task_id.

Parameters:: value (int) – The task_id to filter by
Returns:: The filtered queryset
Return type:: TaskQuerySet

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

Filter tasks by type.

Parameters:

value (str) – The type to filter by
exact (bool) – If True, match the exact type, otherwise use contains
case_insensitive (bool) – If True, ignore case when matching

Returns:

The filtered queryset

Return type: