paperap.models.document.model module

METADATA:

File: model.py

Project: paperap

Created: 2025-03-09

Version: 0.0.10

Author: Jess Mann Email: jess@jmann.me

Copyright (c) 2025 Jess Mann

LAST MODIFIED:

2025-03-09 By Jess Mann

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

Bases: StandardModel

Represents a note on a Paperless-NgX document.

Parameters:

data (Any)

deleted_at: datetime | None
restored_at: datetime | None
transaction_id: int | None
note: str
created: datetime
document: int
user: int
class Meta(model)[source]

Bases: Meta

Parameters:

model (type[_Self])

read_only_fields: ClassVar[set[str]] = {'created', 'deleted_at', 'id', 'restored_at', 'transaction_id'}
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'}
supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}
model: type[_Self]
name: str
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.

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:
Return type:

None

id: int
class paperap.models.document.model.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)

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 Meta(model)[source]

Bases: Meta

Parameters:

model (type[_Self])

read_only_fields: ClassVar[set[str]] = {'archived_file_name', 'deleted_at', 'id', 'is_shared_by_requester', 'page_count'}
filtering_disabled: ClassVar[set[str]] = {'deleted_at', 'is_shared_by_requester', 'page_count'}
filtering_strategies: ClassVar[set[FilteringStrategies]] = {FilteringStrategies.WHITELIST}
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'}
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'}
blacklist_filtering_params: ClassVar[set[str]] = {}
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'}
model: type[_Self]
name: str
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.

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

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

property custom_field_ids: list[int]

Get the IDs of the custom fields for this document.

property custom_field_values: list[Any]

Get the values of the custom fields for this document.

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}')
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 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
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 custom_fields: CustomFieldQuerySet

Get the custom fields for this document.

Returns:

List of custom fields associated with this document.

property has_search_hit: bool
property search_hit: dict[str, Any] | None
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.

add_tag(tag)[source]

Add a tag to the document.

Parameters:

tag (Tag | int | str) – The tag to add.

Return type:

None

remove_tag(tag)[source]

Remove a tag from the document.

Parameters:

tag (Tag | int | str) – The tag to remove.

Return type:

None

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)
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)
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:
Return type:

None

preview(original=False)[source]

Get a preview of the document.

Parameters:

original (bool) – Whether to preview the original file instead of the archived version.

Return type:

DownloadedDocument

Returns:

The document preview.

id: int
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.

get_suggestions()[source]

Get suggestions for this document.

Return type:

DocumentSuggestions

Returns:

The document suggestions.

Examples

>>> suggestions = document.get_suggestions()
>>> print(suggestions.tags)
append_content(value)[source]

Append content to the document.

Parameters:

value (str) – The content to append.

Return type:

None

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

Update the document locally with the provided data.

Parameters:

  • from_db (bool | None) – Whether to update from the database.

  • **kwargs (Any) – Additional data to update the document with.

Raises:

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

Return type:

None