paperap.models package
METADATA:
- File: __init__.py
Project: paperap
- Created: 2025-03-04
Version: 0.0.9
Author: Jess Mann Email: jess@jmann.me
Copyright (c) 2025 Jess Mann
LAST MODIFIED:
2025-03-04 By Jess Mann
- class paperap.models.BaseModel(**data)[source]
-
Base model for all Paperless-ngx API objects.
Provides automatic serialization, deserialization, and API interactions with minimal configuration needed.
- _meta
Metadata for the model, including filtering and resource information.
- _save_lock
Lock for saving operations.
- _pending_save
Future object for pending save operations.
- Raises:
ValueError – If resource is not provided.
- Parameters:
data (
Any)
- class Meta(model)[source]
Bases:
GenericMetadata for the Model.
- name
The name of the model.
- read_only_fields
Fields that should not be modified.
- filtering_disabled
Fields disabled for filtering.
- filtering_fields
Fields allowed for filtering.
- supported_filtering_params
Params allowed during queryset filtering.
- blacklist_filtering_params
Params disallowed during queryset filtering.
- filtering_strategies
Strategies for filtering.
- resource
The BaseResource instance.
- queryset
The type of QuerySet for the model.
- Raises:
ValueError – If both ALLOW_ALL and ALLOW_NONE filtering strategies are set.
- Parameters:
model (type[_Self])
- filter_allowed(filter_param)[source]
Check if a filter is allowed based on the filtering strategies.
-
filtering_strategies:
ClassVar[set[FilteringStrategies]] = {FilteringStrategies.BLACKLIST}
- __init__(**data)[source]
Initialize the model with resource and data.
- Parameters:
resource – The BaseResource instance.
**data (
Any) – Additional data to initialize the model.
- Raises:
ValueError – If resource is not provided.
- __str__()[source]
Human-readable string representation.
- Return type:
- Returns:
A string representation of the model.
- classmethod create(**kwargs)[source]
Create a new model instance.
- Parameters:
**kwargs (
Any) – Field values to set.- Return type:
Self- Returns:
A new model instance.
Examples
# Create a new Document instance doc = Document.create(filename=”example.pdf”, contents=b”PDF data”)
- dirty_fields(comparison='both')[source]
Show which fields have changed since last update from the paperless ngx db.
- Parameters:
comparison (
Literal['saved','db','both']) – Specify the data to compare (‘saved’ or ‘db’). Db is the last data retrieved from Paperless NGX Saved is the last data sent to Paperless NGX to be saved- Returns:
(original_value, new_value)} of fields that have changed since last update from the paperless ngx db.
- Return type:
A dictionary {field
- classmethod from_dict(data)[source]
Create a model instance from API response data.
- Parameters:
data (
dict[str,Any]) – Dictionary containing the API response data.- Return type:
Self- Returns:
A model instance initialized with the provided data.
Examples
# Create a Document instance from API data doc = Document.from_dict(api_data)
- is_dirty(comparison='both')[source]
Check if any field has changed since last update from the paperless ngx db.
- abstractmethod is_new()[source]
Check if this model represents a new (unsaved) object.
- Return type:
- Returns:
True if the model is new, False otherwise.
Examples
# Check if a Document instance is new is_new = doc.is_new()
- matches_dict(data)[source]
Check if the model matches the provided data.
- Parameters:
data (
dict[str,Any]) – Dictionary containing the data to compare.- Return type:
- Returns:
True if the model matches the data, False otherwise.
Examples
# Check if a Document instance matches API data matches = doc.matches_dict(api_data)
- 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.
- 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:
- to_dict(*, include_read_only=True, exclude_none=False, exclude_unset=True)[source]
Convert the model to a dictionary for API requests.
- Parameters:
- Return type:
- Returns:
A dictionary with model data ready for API submission.
Examples
# Convert a Document instance to a dictionary data = doc.to_dict()
- class paperap.models.StandardModel(**data)[source]
-
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:
MetaMetadata 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'}
- __str__()[source]
Human-readable string representation.
- Return type:
- Returns:
A string representation of the model.
- is_new()[source]
Check if this model represents a new (unsaved) object.
- Return type:
- 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.
- refresh()[source]
Refresh the model with the latest data from the server.
- Return type:
- 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_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.
- 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:
- 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)
- id: int
- class paperap.models.DocumentNote(**data)[source]
Bases:
StandardModelRepresents 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'}
- get_document()[source]
Get the document associated with this note.
- Return type:
- Returns:
The document associated with this note.
- get_user()[source]
Get the user who created this note.
- Return type:
- 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.
- deleted_at: datetime | None
- restored_at: datetime | None
- transaction_id: int | None
- note: str
- created: datetime
- document: int
- user: int
- class paperap.models.Document(**data)[source]
Bases:
StandardModelRepresents 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.
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'}
- 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'
- custom_field_value(field_id, default=None, *, raise_errors=False)[source]
Get the value of a custom field by ID.
- 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:
- 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:
- Returns:
The document metadata.
Examples
>>> metadata = document.get_metadata() >>> print(metadata.original_mime_type)
- get_suggestions()[source]
Get suggestions for this document.
- Return type:
- Returns:
The document suggestions.
Examples
>>> suggestions = document.get_suggestions() >>> print(suggestions.tags)
- 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.
- 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:
- Returns:
The document preview.
- 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 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:
- Returns:
The document thumbnail.
- update_locally(from_db=None, **kwargs)[source]
Update the document locally with the provided data.
- Parameters:
- 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:
- Returns:
A list of validated custom field dictionaries.
Validate and return the is_shared_by_requester flag.
- 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
- class paperap.models.Correspondent(**data)[source]
Bases:
StandardModel,MatcherMixinRepresents 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'}
- 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.
- slug: str | None
- name: str | None
- document_count: int
- owner: int | None
- user_can_change: bool | None
- class paperap.models.Tag(**data)[source]
Bases:
StandardModel,MatcherMixinRepresents 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'}
- property documents: DocumentQuerySet
Get documents with this tag.
- Returns:
List of documents.
- 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.
- 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
- class paperap.models.DocumentType(**data)[source]
Bases:
StandardModel,MatcherMixinRepresents 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'}
- 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.
- name: str
- slug: str | None
- document_count: int
- owner: int | None
- user_can_change: bool | None
- class paperap.models.StoragePath(**data)[source]
Bases:
StandardModel,MatcherMixinRepresents 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'}
- 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.
- name: str
- slug: str | None
- path: str | None
- document_count: int
- owner: int | None
- user_can_change: bool | None
- class paperap.models.CustomField(**data)[source]
Bases:
StandardModelRepresents 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'}
- 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.
- classmethod validate_data_type(v)[source]
Validate the data_type field.
- Parameters:
v (
Any) – The value to validate.- Return type:
- 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
- class paperap.models.User(**data)[source]
Bases:
StandardModelRepresents 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'}
- get_groups()[source]
Get the groups this user is a member of.
- Returns:
The groups this user is a member
- Return 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.
- 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]
- class paperap.models.Group(**data)[source]
Bases:
StandardModelRepresents 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_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.
- property users: UserQuerySet
Get the users in this group.
- Returns:
The users in this group
- Return type:
- name: str | None
- permissions: list[str]
- class paperap.models.Task(**data)[source]
Bases:
StandardModelRepresents 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_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.
- 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
- class paperap.models.SavedView(**data)[source]
Bases:
StandardModelRepresents 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_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.
- 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
- class paperap.models.UISettings(**data)[source]
Bases:
StandardModelRepresents 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_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.
- user: dict[str, Any]
- settings: dict[str, Any]
- permissions: list[str]
- class paperap.models.Workflow(**data)[source]
Bases:
StandardModelRepresents a workflow in Paperless-NgX.
- Parameters:
data (
Any)
- class Meta(model)[source]
Bases:
MetaMetadata 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_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.
- name: str
- order: int | None
- enabled: bool | None
- triggers: list[dict[str, Any]]
- actions: list[dict[str, Any]]
- class paperap.models.WorkflowTrigger(**data)[source]
Bases:
StandardModel,MatcherMixinRepresents 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_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.
- 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
- class paperap.models.WorkflowAction(**data)[source]
Bases:
StandardModelRepresents 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_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.
- 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
- class paperap.models.Profile(**data)[source]
Bases:
StandardModelRepresents 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_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.
- 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
Bases:
StandardModel- Parameters:
data (
Any)
Bases:
Meta- Parameters:
model (type[_Self])
alias of
ShareLinksQuerySet
Get the document associated with this share link
- Returns:
The document object
- Return type:
Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
We need to both initialize private attributes and call the user-defined model_post_init method.
Serialize a datetime object to an ISO 8601 formatted string
- Parameters:
value (
datetime) – The datetime object to serialize- Returns:
The serialized datetime
- Return type:
- class paperap.models.BaseQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]
-
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:
- Returns:
True if there are any objects matching the filters
- __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:
- 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:
- 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:
- 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:
- 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.
- 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
- 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]
- 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,GenericA 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.
- 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:
- 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.
- 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)
-
resource:
StandardResource[TypeVar(_Model, bound=StandardModel),Self]
- 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],HasOwnerQuerySet 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.
- 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:
- 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.
- correspondent_slug(slug, *, exact=True, case_insensitive=True)[source]
Filter documents by correspondent slug.
- custom_field(field, value, *, exact=False, case_insensitive=True)[source]
Filter documents by custom field.
- custom_field_contains(field, values)[source]
Filter documents with a custom field that contains all specified values.
- custom_field_exact(field, value)[source]
Filter documents with a custom field value that matches exactly.
- custom_field_exists(field, exists=True)[source]
Filter documents based on the existence of a custom field.
- custom_field_fullsearch(value, *, case_insensitive=True)[source]
Filter documents by searching through both custom field name and value.
- custom_field_in(field, values)[source]
Filter documents with a custom field value in a list of values.
- 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_range(field, start, end)[source]
Filter documents with a custom field value within a specified range.
- 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:
- 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.
- has_custom_field_id(pk, *, exact=False)[source]
Filter documents that have a custom field with the specified ID(s).
- merge(metadata_document_id=None, delete_originals=False)[source]
Merge all documents in the current queryset.
- Parameters:
- Return type:
- 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:
- 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:
- 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:
- Returns:
A queryset with similar documents.
Examples
>>> similar_docs = client.documents().more_like(42) >>> for doc in similar_docs: ... print(doc.title)
- 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.
- 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:
- 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:
- 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:
- 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.
- tag_name(tag_name, *, exact=True, case_insensitive=True)[source]
Filter documents that have a tag with the specified name.
- 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 documentsdocument_type (
DocumentType|int|None) – Set document type for all documentsstorage_path (
StoragePath|int|None) – Set storage path for all documents
- 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
- 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,HasDocumentCountQuerySet 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
- 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
- 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],HasStandardQuerySet 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
- 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
- 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,HasDocumentCountQuerySet 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
- 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:
- Return type:
Self- Returns:
Filtered DocumentTypeQuerySet
Examples
# Filter document types by name filtered = queryset.name(“Invoice”)
- 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],HasStandardQuerySet 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
- 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
- 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],HasDocumentCountQuerySet 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)
- 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
- 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
- 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
- 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
- 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:
- 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:
Filter tasks by related_document.
- Parameters:
value (
int | list[int]) – The related_document to filter by- Returns:
The filtered queryset
- Return type:
- result(value, *, exact=True, case_insensitive=True)[source]
Filter tasks by result.
- Parameters:
- Returns:
The filtered queryset
- Return type:
- status(value, *, exact=True, case_insensitive=True)[source]
Filter tasks by status.
- Parameters:
- Returns:
The filtered queryset
- Return type:
- task_file_name(value, *, exact=True, case_insensitive=True)[source]
Filter tasks by task_file_name.
- Parameters:
- 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:
- class paperap.models.SavedViewQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]
Bases:
StandardQuerySet[SavedView],HasOwnerQuerySet for Paperless-ngx saved views 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)
- display_mode(mode)[source]
Filter saved views by display mode.
- Parameters:
mode (
str) – The display mode to filter by- Return type:
Self- Returns:
Filtered SavedViewQuerySet
- page_size(size)[source]
Filter saved views by page size.
- Parameters:
size (
int) – The number of items per page- Return type:
Self- Returns:
Filtered SavedViewQuerySet
- page_size_over(size)[source]
Filter saved views by page size over a limit.
- Parameters:
size (
int) – The minimum number of items per page- Return type:
Self- Returns:
Filtered SavedViewQuerySet
- page_size_under(size)[source]
Filter saved views by page size under a limit.
- Parameters:
size (
int) – The maximum number of items per page- Return type:
Self- Returns:
Filtered SavedViewQuerySet
- show_in_sidebar(show=True)[source]
Filter saved views by sidebar visibility.
- Parameters:
show (
bool) – If True, get views shown in sidebar, otherwise those hidden- Return type:
Self- Returns:
Filtered SavedViewQuerySet
- show_on_dashboard(show=True)[source]
Filter saved views by dashboard visibility.
- Parameters:
show (
bool) – If True, get views shown on dashboard, otherwise those hidden- Return type:
Self- Returns:
Filtered SavedViewQuerySet
- class paperap.models.UISettingsQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]
Bases:
StandardQuerySet[UISettings]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)
- count()[source]
Count the number of UI settings.
UISettings only ever returns one element.
- Returns:
The number of UI settings
- Return type:
- class paperap.models.WorkflowQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]
Bases:
StandardQuerySet[Workflow]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)
- enabled(value=True)[source]
Filter workflows by enabled status.
- Parameters:
value (
bool) – If True, get enabled workflows, otherwise disabled- Return type:
Self- Returns:
Filtered WorkflowQuerySet
- class paperap.models.WorkflowTriggerQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]
Bases:
StandardQuerySet[WorkflowTrigger]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)
- filter_filename(value, *, exact=True, case_insensitive=True)[source]
Filter workflow triggers by filename filter.
- filter_mailrule(value, *, exact=True, case_insensitive=True)[source]
Filter workflow triggers by mail rule filter.
- filter_path(value, *, exact=True, case_insensitive=True)[source]
Filter workflow triggers by path filter.
- has_correspondent(value)[source]
Filter workflow triggers by correspondent filter.
- Parameters:
value (
int) – The correspondent ID to filter by- Return type:
Self- Returns:
Filtered WorkflowTriggerQuerySet
- has_document_type(value)[source]
Filter workflow triggers by document type filter.
- Parameters:
value (
int) – The document type ID to filter by- Return type:
Self- Returns:
Filtered WorkflowTriggerQuerySet
- class paperap.models.WorkflowActionQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]
Bases:
StandardQuerySet[WorkflowAction]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)
- assign_correspondent(value)[source]
Filter workflow actions by assigned correspondent.
- Parameters:
value (
int) – The correspondent ID to filter by- Return type:
Self- Returns:
Filtered WorkflowActionQuerySet
- assign_document_type(value)[source]
Filter workflow actions by assigned document type.
- Parameters:
value (
int) – The document type ID to filter by- Return type:
Self- Returns:
Filtered WorkflowActionQuerySet
- assign_owner(value)[source]
Filter workflow actions by assigned owner.
- Parameters:
value (
int) – The owner ID to filter by- Return type:
Self- Returns:
Filtered WorkflowActionQuerySet
- assign_storage_path(value)[source]
Filter workflow actions by assigned storage path.
- Parameters:
value (
int) – The storage path ID to filter by- Return type:
Self- Returns:
Filtered WorkflowActionQuerySet
- assign_title(value, *, exact=True, case_insensitive=True)[source]
Filter workflow actions by assigned title.
- class paperap.models.ProfileQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]
Bases:
StandardQuerySet[Profile]A lazy-loaded, chainable query interface for Profile resources in Paperless NGX.
Provides pagination, filtering, and caching functionality similar to Django’s BaseQuerySet. Designed to be lazy - only fetching data when it’s actually needed.
Examples
>>> profiles = ProfileQuerySet() >>> profiles = profiles.email("example@example.com") >>> for profile in profiles: >>> print(profile.first_name)
- 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)
- email(value, *, exact=True, case_insensitive=True)[source]
Filter by email.
- Parameters:
- Return type:
- Returns:
A new ProfileQuerySet instance with the filter applied.
Examples
>>> profiles = ProfileQuerySet() >>> profiles = profiles.email("example@example.com")
Examples
>>> profiles = client.profiles().email("john.doe@gmail.com") >>> profiles = client.profiles().email("gmail.com", exact=False) >>> profiles = client.profiles().email("jOhN.DOE@gmail.com", case_insensitive=True)
- first_name(value, *, exact=True, case_insensitive=True)[source]
Filter by first name.
- Parameters:
- Return type:
- Returns:
A new ProfileQuerySet instance with the filter applied.
Examples
>>> profiles = client.profiles().first_name("John") >>> profiles = client.profiles().first_name("John", exact=False) >>> profiles = client.profiles().first_name("JOHN", case_insensitive=False)
- Parameters:
value (
str)
- has_usable_password(value=True)[source]
Filter by has usable password.
- Parameters:
has_usable_password – The has usable password to filter by.
- Return type:
- Returns:
A new ProfileQuerySet instance with the filter applied.
Examples
>>> profiles = client.profiles().has_usable_password() >>> profiles = client.profiles().has_usable_password(False)
- Parameters:
value (
bool)
- last_name(value, *, exact=True, case_insensitive=True)[source]
Filter by last name.
- Parameters:
last_name – The last name to filter by.
exact (
bool) – Whether to filter by an exact match.
- Return type:
- Returns:
A new ProfileQuerySet instance with the filter applied.
Examples
>>> profiles = client.profiles().last_name("Doe") >>> profiles = client.profiles().last_name("Doe", exact=False) >>> profiles = client.profiles().last_name("DOE", case_insensitive=False)
Bases:
StandardQuerySet[ShareLinks]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)
Filter models created after a given date.
- Parameters:
date (
datetime) – The date to filter by- Return type:
Self- Returns:
Filtered QuerySet
Filter models created before a given date.
- Parameters:
date (
datetime) – The date to filter by- Return type:
Self- Returns:
Filtered QuerySet
Filter models created between two dates.
Filter ShareLinks where document is value
- Parameters:
value (
int | list[int]) – The value to compare against- Returns:
The filtered queryset
- Return type:
Filter ShareLinks where expiration is after value
- Parameters:
value (
datetime.datetime | str) – The value to compare against- Returns:
The filtered queryset
- Return type:
Filter ShareLinks where expiration is before value
- Parameters:
value (
datetime.datetime | str) – The value to compare against- Returns:
The filtered queryset
- Return type:
Filter ShareLinks where file_version is value
- Parameters:
value (
str) – The value to compare against- Returns:
The filtered queryset
- Return type:
Filter ShareLinks where slug is value
- Parameters:
- Returns:
The filtered queryset
- Return type:
Subpackages
- paperap.models.abstract package
BaseModelBaseModel._metaBaseModel._save_lockBaseModel._pending_saveBaseModel.MetaBaseModel.Meta.nameBaseModel.Meta.read_only_fieldsBaseModel.Meta.filtering_disabledBaseModel.Meta.filtering_fieldsBaseModel.Meta.supported_filtering_paramsBaseModel.Meta.blacklist_filtering_paramsBaseModel.Meta.filtering_strategiesBaseModel.Meta.resourceBaseModel.Meta.querysetBaseModel.Meta.__init__()BaseModel.Meta.blacklist_filtering_paramsBaseModel.Meta.field_mapBaseModel.Meta.filter_allowed()BaseModel.Meta.filtering_disabledBaseModel.Meta.filtering_fieldsBaseModel.Meta.filtering_strategiesBaseModel.Meta.read_only_fieldsBaseModel.Meta.save_on_writeBaseModel.Meta.save_timeoutBaseModel.Meta.supported_filtering_paramsBaseModel.Meta.modelBaseModel.Meta.name
BaseModel.__init__()BaseModel.__init_subclass__()BaseModel.__str__()BaseModel.cleanup()BaseModel.create()BaseModel.delete()BaseModel.dirty_fields()BaseModel.disable_save_on_write()BaseModel.enable_save_on_write()BaseModel.from_dict()BaseModel.is_dirty()BaseModel.is_new()BaseModel.matches_dict()BaseModel.model_configBaseModel.model_post_init()BaseModel.resourceBaseModel.save_executorBaseModel.should_save_on_write()BaseModel.to_dict()BaseModel.update()BaseModel.update_locally()
StandardModelStandardModel.idStandardModel.MetaStandardModel.Meta.read_only_fieldsStandardModel.Meta.supported_filtering_paramsStandardModel.Meta.blacklist_filtering_paramsStandardModel.Meta.field_mapStandardModel.Meta.filtering_disabledStandardModel.Meta.filtering_fieldsStandardModel.Meta.read_only_fieldsStandardModel.Meta.supported_filtering_paramsStandardModel.Meta.modelStandardModel.Meta.name
StandardModel.__setattr__()StandardModel.__str__()StandardModel.is_new()StandardModel.model_configStandardModel.model_post_init()StandardModel.refresh()StandardModel.resourceStandardModel.save()StandardModel.save_async()StandardModel.save_sync()StandardModel.update()StandardModel.id
BaseQuerySetBaseQuerySet.__bool__()BaseQuerySet.__contains__()BaseQuerySet.__getitem__()BaseQuerySet.__init__()BaseQuerySet.__iter__()BaseQuerySet.__len__()BaseQuerySet.all()BaseQuerySet.count()BaseQuerySet.count_this_page()BaseQuerySet.exclude()BaseQuerySet.exists()BaseQuerySet.filter()BaseQuerySet.filter_field_by_str()BaseQuerySet.first()BaseQuerySet.get()BaseQuerySet.last()BaseQuerySet.none()BaseQuerySet.order_by()BaseQuerySet.resourceBaseQuerySet.filters
StandardQuerySetStandardQuerySet.__contains__()StandardQuerySet.bulk_action()StandardQuerySet.bulk_assign_correspondent()StandardQuerySet.bulk_assign_document_type()StandardQuerySet.bulk_assign_owner()StandardQuerySet.bulk_assign_storage_path()StandardQuerySet.bulk_assign_tags()StandardQuerySet.bulk_update()StandardQuerySet.delete()StandardQuerySet.get()StandardQuerySet.id()StandardQuerySet.resourceStandardQuerySet.filters
FilteringStrategiesStatusContext- Submodules
- paperap.models.config package
- paperap.models.correspondent package
- paperap.models.custom_field package
- paperap.models.document package
DocumentDocument.addedDocument.archive_serial_numberDocument.archived_file_nameDocument.contentDocument.correspondentDocument.createdDocument.created_dateDocument.updatedDocument.custom_fieldsDocument.deleted_atDocument.document_typeDocument.is_shared_by_requesterDocument.notesDocument.original_filenameDocument.ownerDocument.page_countDocument.storage_pathDocument.tagsDocument.titleDocument.user_can_changeDocument.checksumDocument.MetaDocument.add_tag()Document.append_content()Document.correspondentDocument.custom_field_idsDocument.custom_field_value()Document.custom_field_valuesDocument.custom_fieldsDocument.document_typeDocument.download()Document.get_metadata()Document.get_suggestions()Document.has_search_hitDocument.model_configDocument.model_post_init()Document.preview()Document.remove_tag()Document.search_hitDocument.serialize_datetime()Document.serialize_notes()Document.storage_pathDocument.tag_namesDocument.tagsDocument.thumbnail()Document.update_locally()Document.validate_custom_fields()Document.validate_is_shared_by_requester()Document.validate_notes()Document.validate_tags()Document.validate_text()Document.addedDocument.archive_checksumDocument.archive_filenameDocument.archive_serial_numberDocument.archived_file_nameDocument.checksumDocument.contentDocument.correspondent_idDocument.createdDocument.created_dateDocument.custom_field_dictsDocument.deleted_atDocument.document_type_idDocument.filenameDocument.is_shared_by_requesterDocument.notesDocument.original_filenameDocument.ownerDocument.page_countDocument.storage_path_idDocument.storage_typeDocument.tag_idsDocument.titleDocument.user_can_changeDocument.id
DocumentNoteDocumentNote.MetaDocumentNote.get_document()DocumentNote.get_user()DocumentNote.model_configDocumentNote.model_post_init()DocumentNote.serialize_datetime()DocumentNote.deleted_atDocumentNote.restored_atDocumentNote.transaction_idDocumentNote.noteDocumentNote.createdDocumentNote.documentDocumentNote.userDocumentNote.id
DocumentQuerySetDocumentQuerySet.add_tag()DocumentQuerySet.added_after()DocumentQuerySet.added_before()DocumentQuerySet.asn()DocumentQuerySet.content()DocumentQuerySet.correspondent()DocumentQuerySet.correspondent_id()DocumentQuerySet.correspondent_name()DocumentQuerySet.correspondent_slug()DocumentQuerySet.created_after()DocumentQuerySet.created_before()DocumentQuerySet.created_between()DocumentQuerySet.custom_field()DocumentQuerySet.custom_field_contains()DocumentQuerySet.custom_field_exact()DocumentQuerySet.custom_field_exists()DocumentQuerySet.custom_field_fullsearch()DocumentQuerySet.custom_field_in()DocumentQuerySet.custom_field_isnull()DocumentQuerySet.custom_field_query()DocumentQuerySet.custom_field_range()DocumentQuerySet.delete()DocumentQuerySet.document_type()DocumentQuerySet.document_type_id()DocumentQuerySet.document_type_name()DocumentQuerySet.has_custom_field_id()DocumentQuerySet.has_custom_fields()DocumentQuerySet.merge()DocumentQuerySet.modify_custom_fields()DocumentQuerySet.modify_tags()DocumentQuerySet.more_like()DocumentQuerySet.no_custom_fields()DocumentQuerySet.notes()DocumentQuerySet.original_filename()DocumentQuerySet.remove_tag()DocumentQuerySet.reprocess()DocumentQuerySet.rotate()DocumentQuerySet.search()DocumentQuerySet.set_permissions()DocumentQuerySet.storage_path()DocumentQuerySet.storage_path_id()DocumentQuerySet.storage_path_name()DocumentQuerySet.tag_id()DocumentQuerySet.tag_name()DocumentQuerySet.title()DocumentQuerySet.update()DocumentQuerySet.user_can_change()DocumentQuerySet.resourceDocumentQuerySet.filters
DocumentNoteQuerySetDownloadedDocumentDownloadedDocument.modeDownloadedDocument.originalDownloadedDocument.contentDownloadedDocument.content_typeDownloadedDocument.disposition_filenameDownloadedDocument.disposition_typeDownloadedDocument.MetaDownloadedDocument.model_configDownloadedDocument.model_post_init()DownloadedDocument.modeDownloadedDocument.originalDownloadedDocument.contentDownloadedDocument.content_typeDownloadedDocument.disposition_filenameDownloadedDocument.disposition_type
DownloadedDocumentQuerySetDocumentMetadataDocumentMetadata.original_checksumDocumentMetadata.original_sizeDocumentMetadata.original_mime_typeDocumentMetadata.media_filenameDocumentMetadata.has_archive_versionDocumentMetadata.original_metadataDocumentMetadata.archive_checksumDocumentMetadata.archive_media_filenameDocumentMetadata.original_filenameDocumentMetadata.langDocumentMetadata.archive_sizeDocumentMetadata.archive_metadataDocumentMetadata.MetaDocumentMetadata.model_configDocumentMetadata.model_post_init()DocumentMetadata.original_checksumDocumentMetadata.original_sizeDocumentMetadata.original_mime_typeDocumentMetadata.media_filenameDocumentMetadata.has_archive_versionDocumentMetadata.original_metadataDocumentMetadata.archive_checksumDocumentMetadata.archive_media_filenameDocumentMetadata.original_filenameDocumentMetadata.langDocumentMetadata.archive_sizeDocumentMetadata.archive_metadata
DocumentMetadataQuerySetMetadataElementCustomFieldValuesDocumentSuggestionsDocumentSuggestions.correspondentsDocumentSuggestions.tagsDocumentSuggestions.document_typesDocumentSuggestions.storage_pathsDocumentSuggestions.datesDocumentSuggestions.MetaDocumentSuggestions.model_configDocumentSuggestions.model_post_init()DocumentSuggestions.correspondentsDocumentSuggestions.tagsDocumentSuggestions.document_typesDocumentSuggestions.storage_pathsDocumentSuggestions.dates
DocumentSuggestionsQuerySet- Subpackages
- Submodules
- paperap.models.document_type package
- paperap.models.mixins package
- paperap.models.profile package
- paperap.models.responses package
- paperap.models.saved_view package
- paperap.models.share_links package
- paperap.models.storage_path package
- paperap.models.tag package
- paperap.models.task package
- paperap.models.ui_settings package
- paperap.models.user package
- paperap.models.workflow package