paperap.const module

Constants and base types for the Paperap library.

This module defines enumerations, constants, and base types used throughout the Paperap library for interacting with Paperless-ngx. It includes status enums, model configurations, URL templates, and type definitions that provide a foundation for the API client.

class paperap.const.StrEnumWithUnknown(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: StrEnum

String enumeration that handles unknown values gracefully.

This base class extends StrEnum to automatically handle unknown values by returning a designated UNKNOWN value instead of raising an exception. Subclasses must define an UNKNOWN member.

Example

>>> class Status(StrEnumWithUnknown):
...     ACTIVE = "active"
...     INACTIVE = "inactive"
...     UNKNOWN = "unknown"
>>> Status("active")
<Status.ACTIVE: 'active'>
>>> Status("nonexistent")
<Status.UNKNOWN: 'unknown'>
class paperap.const.IntEnumWithUnknown(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: IntEnum

Integer enumeration that handles unknown values gracefully.

This base class extends IntEnum to automatically handle unknown values by returning a designated UNKNOWN value instead of raising an exception. Subclasses must define an UNKNOWN member.

Example

>>> class Priority(IntEnumWithUnknown):
...     HIGH = 3
...     MEDIUM = 2
...     LOW = 1
...     UNKNOWN = -1
>>> Priority(2)
<Priority.MEDIUM: 2>
>>> Priority(99)
<Priority.UNKNOWN: -1>
class paperap.const.ConstModel(**data)[source]

Bases: BaseModel

Base model for constant data structures with strict validation.

This model provides consistent configuration for all constant data structures in the application, with strict validation and comparison capabilities. It enforces validation on assignment and defaults, and provides custom equality comparison with dictionaries.

model_config

Pydantic configuration dictionary that enforces strict validation.

Parameters:

data (Any)

model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

__eq__(other)[source]

Compare this model with another object for equality.

Supports comparison with dictionaries by checking that all fields match, and with other ConstModel instances by comparing their serialized forms.

Parameters:

other (Any) – The object to compare with this model.

Returns:

True if the objects are equal, False otherwise.

Return type:

bool

class paperap.const.URLS[source]

Bases: object

URL templates for Paperless-ngx API endpoints.

This class provides string templates for all API endpoints used by the client. Templates can be formatted with parameters like ${resource} and ${pk} to generate specific endpoint URLs.

Note

This class may be deprecated in the future. It is currently used for reference.

index

API root endpoint.

token

Authentication token endpoint.

list

List endpoint for a resource type.

detail

Detail endpoint for a specific resource.

create

Creation endpoint for a resource type.

update

Update endpoint for a specific resource.

delete

Deletion endpoint for a specific resource.

meta

Document metadata endpoint.

next_asn

Endpoint to get the next available ASN.

notes

Document notes endpoint.

post

Document upload endpoint.

single

Single document endpoint.

suggestions

Suggestions endpoint for a resource.

preview

Document preview endpoint.

thumbnail

Document thumbnail endpoint.

download

Document download endpoint.

index: Template = <string.Template object>
token: Template = <string.Template object>
list: Template = <string.Template object>
detail: Template = <string.Template object>
create: Template = <string.Template object>
update: Template = <string.Template object>
delete: Template = <string.Template object>
meta: Template = <string.Template object>
next_asn: Template = <string.Template object>
notes: Template = <string.Template object>
post: Template = <string.Template object>
single: Template = <string.Template object>
suggestions: Template = <string.Template object>
preview: Template = <string.Template object>
thumbnail: Template = <string.Template object>
download: Template = <string.Template object>
paperap.const.CommonEndpoints

Type alias for common API endpoint names.

alias of Literal[‘list’, ‘detail’, ‘create’, ‘update’, ‘delete’]

paperap.const.Endpoints

Type alias for a dictionary mapping endpoint names to URL templates.

alias of dict[Literal[‘list’, ‘detail’, ‘create’, ‘update’, ‘delete’] | str, Template]

class paperap.const.FilteringStrategies(*values)[source]

Bases: StrEnum

Enumeration of filtering strategies for API queries.

These strategies determine how field filtering is applied when querying resources.

WHITELIST

Only allow filtering on explicitly listed fields.

BLACKLIST

Allow filtering on all fields except those explicitly listed.

ALLOW_ALL

Allow filtering on all fields.

ALLOW_NONE

Disallow filtering on all fields.

WHITELIST = 'whitelist'
BLACKLIST = 'blacklist'
ALLOW_ALL = 'allow_all'
ALLOW_NONE = 'allow_none'
class paperap.const.ModelStatus(*values)[source]

Bases: StrEnum

Enumeration of possible model states during lifecycle operations.

These states track the current operation being performed on a model instance.

INITIALIZING

Model is being initialized with data.

UPDATING

Model is being updated with new data.

SAVING

Model is being saved to the server.

READY

Model is ready for use.

ERROR

An error occurred during a model operation.

INITIALIZING = 'initializing'
UPDATING = 'updating'
SAVING = 'saving'
READY = 'ready'
ERROR = 'error'
class paperap.const.CustomFieldTypes(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of supported custom field data types in Paperless-ngx.

These types determine how custom field values are validated, stored, and displayed.

STRING

Text string value.

BOOLEAN

Boolean (true/false) value.

INTEGER

Whole number value.

FLOAT

Decimal number value.

MONETARY

Currency value.

DATE

Date value.

URL

Web URL value.

Link to another document.

UNKNOWN

Unknown field type (fallback).

STRING = 'string'
BOOLEAN = 'boolean'
INTEGER = 'integer'
FLOAT = 'float'
MONETARY = 'monetary'
DATE = 'date'
URL = 'url'
DOCUMENT_LINK = 'documentlink'
UNKNOWN = 'unknown'
class paperap.const.CustomFieldValues(**data)[source]

Bases: ConstModel

Model for custom field values associated with a document.

field

The ID of the custom field.

value

The value of the custom field, which can be of any type depending on the field’s data_type.

Parameters:

data (Any)

field: int
value: Any
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.CustomFieldTypedDict[source]

Bases: TypedDict

TypedDict for custom field values, used for type checking.

This provides the same structure as CustomFieldValues but as a TypedDict for use in function signatures and type annotations.

field

The ID of the custom field.

value

The value of the custom field.

field: int
value: Any
class paperap.const.DocumentMetadataType(**data)[source]

Bases: ConstModel

Model for document metadata extracted from files.

This model represents metadata extracted from document files, such as PDF metadata, EXIF data, or other embedded information.

Note

This class may not be used after refactoring.

namespace

The metadata namespace (e.g., “pdf”, “exif”).

prefix

The metadata prefix.

key

The metadata key name.

value

The metadata value.

Parameters:

data (Any)

namespace: str | None
prefix: str | None
key: str | None
value: str | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.DocumentSearchHitType(**data)[source]

Bases: ConstModel

Model for search result hits with relevance information.

This model represents a document search result with relevance scoring and highlighted text snippets showing where matches occurred.

score

The relevance score of the search hit.

highlights

Highlighted text snippets from the document content.

note_highlights

Highlighted text snippets from document notes.

rank

The rank of this result in the overall search results.

Parameters:

data (Any)

score: float | None
highlights: str | None
note_highlights: str | None
rank: int | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.MatchingAlgorithmType(*values)[source]

Bases: IntEnumWithUnknown

Enumeration of matching algorithms used for document classification.

These algorithms determine how Paperless-ngx matches documents to correspondents, document types, and tags during automatic classification.

NONE

No matching (manual assignment only).

ANY

Match if any of the terms are found.

ALL

Match only if all terms are found.

LITERAL

Match the exact string.

REGEX

Match using regular expressions.

FUZZY

Match using fuzzy string matching.

AUTO

Automatically select the best matching algorithm.

UNKNOWN

Unknown algorithm type (fallback).

NONE = 0
ANY = 1
ALL = 2
LITERAL = 3
REGEX = 4
FUZZY = 5
AUTO = 6
UNKNOWN = -1
class paperap.const.PermissionSetType(**data)[source]

Bases: ConstModel

Model for a set of user and group permissions.

This model represents a collection of users and groups that have a specific permission on a resource.

users

List of user IDs with the permission.

groups

List of group IDs with the permission.

Parameters:

data (Any)

users: list[int]
groups: list[int]
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.PermissionTableType(**data)[source]

Bases: ConstModel

Model for a complete permission table for a resource.

This model represents all permissions for a resource, organized by permission type (view, change).

view

The set of users and groups with view permission.

change

The set of users and groups with change permission.

Parameters:

data (Any)

view: PermissionSetType
change: PermissionSetType
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.RetrieveFileMode(*values)[source]

Bases: StrEnum

Enumeration of file retrieval modes.

These modes determine how a document file is retrieved from the server.

DOWNLOAD

Download the full document file.

PREVIEW

Get a preview version of the document.

THUMBNAIL

Get a thumbnail image of the document.

DOWNLOAD = 'download'
PREVIEW = 'preview'
THUMBNAIL = 'thumb'
class paperap.const.SavedViewFilterRuleType(**data)[source]

Bases: ConstModel

Model for a filter rule in a saved view.

This model represents a single filtering rule that is part of a saved view, specifying how documents should be filtered.

rule_type

The type of filter rule (corresponds to FilterRuleType enum).

value

The value to filter by.

saved_view

The ID of the saved view this rule belongs to.

Parameters:

data (Any)

rule_type: int
value: str | None
saved_view: int | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.ShareLinkFileVersionType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of file versions available for share links.

These determine which version of a document is shared via a share link.

ARCHIVE

The archived version of the document (typically processed PDF).

ORIGINAL

The original uploaded file.

UNKNOWN

Unknown file version type (fallback).

ARCHIVE = 'archive'
ORIGINAL = 'original'
UNKNOWN = 'unknown'
class paperap.const.StatusType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of general status values for system components.

These status values indicate the operational state of various system components.

OK

The component is functioning normally.

ERROR

The component has encountered an error.

UNKNOWN

The component’s status is unknown (fallback).

OK = 'OK'
ERROR = 'ERROR'
UNKNOWN = 'UNKNOWN'
class paperap.const.StatusDatabaseMigrationStatusType(**data)[source]

Bases: ConstModel

Model for database migration status information.

This model represents the current state of database migrations in the system.

latest_migration

The name of the most recently applied migration.

unapplied_migrations

List of migration names that have not been applied.

Parameters:

data (Any)

latest_migration: str | None
unapplied_migrations: list[str]
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.StatusDatabaseType(**data)[source]

Bases: ConstModel

Model for database status information.

This model represents the current status of the database system.

type

The type of database (e.g., “postgresql”, “sqlite”).

url

The database connection URL.

status

The operational status of the database.

error

Error message if the database has encountered an error.

migration_status

Information about database migrations.

Parameters:

data (Any)

type: str | None
url: str | None
status: StatusType | None
error: str | None
migration_status: StatusDatabaseMigrationStatusType | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.StatusStorageType(**data)[source]

Bases: ConstModel

Model for storage status information.

This model represents the current status of the storage system.

total

Total storage space in bytes.

available

Available storage space in bytes.

Parameters:

data (Any)

total: int | None
available: int | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.StatusTasksType(**data)[source]

Bases: ConstModel

Model for task system status information.

This model represents the current status of the task processing system, including Redis, Celery, indexing, and classification components.

redis_url

The Redis connection URL.

redis_status

The operational status of Redis.

redis_error

Error message if Redis has encountered an error.

celery_status

The operational status of Celery.

index_status

The operational status of the document index.

index_last_modified

When the index was last modified.

index_error

Error message if the index has encountered an error.

classifier_status

The operational status of the document classifier.

classifier_last_trained

When the classifier was last trained.

classifier_error

Error message if the classifier has encountered an error.

Parameters:

data (Any)

redis_url: str | None
redis_status: StatusType | None
redis_error: str | None
celery_status: StatusType | None
index_status: StatusType | None
index_last_modified: datetime | None
index_error: str | None
classifier_status: StatusType | None
classifier_last_trained: datetime | None
classifier_error: str | None
model_config: ClassVar[ConfigDict] = {'extra': 'forbid', 'from_attributes': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class paperap.const.TaskStatusType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of possible task statuses.

These statuses represent the current state of a background task.

PENDING

Task is waiting to be executed.

STARTED

Task has started execution.

SUCCESS

Task has completed successfully.

FAILURE

Task has failed.

UNKNOWN

Task status is unknown (fallback).

PENDING = 'PENDING'
STARTED = 'STARTED'
SUCCESS = 'SUCCESS'
FAILURE = 'FAILURE'
UNKNOWN = 'UNKNOWN'
class paperap.const.TaskTypeType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of task types.

These types categorize tasks based on how they were initiated.

AUTO

Task was automatically triggered by the system.

SCHEDULED_TASK

Task was scheduled to run at a specific time.

MANUAL_TASK

Task was manually triggered by a user.

UNKNOWN

Task type is unknown (fallback).

AUTO = 'auto_task'
SCHEDULED_TASK = 'scheduled_task'
MANUAL_TASK = 'manual_task'
UNKNOWN = 'unknown'
class paperap.const.WorkflowActionType(*values)[source]

Bases: IntEnumWithUnknown

Enumeration of workflow action types.

These types define what actions can be performed by a workflow.

ASSIGNMENT

Assign a value to a document field.

REMOVAL

Remove a value from a document field.

EMAIL

Send an email notification.

WEBHOOK

Trigger a webhook.

UNKNOWN

Unknown action type (fallback).

ASSIGNMENT = 1
REMOVAL = 2
EMAIL = 3
WEBHOOK = 4
UNKNOWN = -1
class paperap.const.WorkflowTriggerType(*values)[source]

Bases: IntEnumWithUnknown

Enumeration of workflow trigger types.

These types define what events can trigger a workflow.

CONSUMPTION

Triggered when a document is consumed (processed).

DOCUMENT_ADDED

Triggered when a document is added to the system.

DOCUMENT_UPDATED

Triggered when a document is updated.

UNKNOWN

Unknown trigger type (fallback).

CONSUMPTION = 1
DOCUMENT_ADDED = 2
DOCUMENT_UPDATED = 3
UNKNOWN = -1
class paperap.const.WorkflowTriggerSourceType(*values)[source]

Bases: IntEnumWithUnknown

Enumeration of workflow trigger source types.

These types define the source of documents that can trigger a workflow.

CONSUME_FOLDER

Documents from the consumption folder.

API_UPLOAD

Documents uploaded via the API.

MAIL_FETCH

Documents fetched from email.

UNKNOWN

Unknown source type (fallback).

CONSUME_FOLDER = 1
API_UPLOAD = 2
MAIL_FETCH = 3
UNKNOWN = -1
class paperap.const.WorkflowTriggerMatchingType(*values)[source]

Bases: IntEnumWithUnknown

Enumeration of workflow trigger matching algorithms.

These algorithms determine how workflow triggers match documents.

NONE

No matching (triggers for all documents).

ANY

Match if any of the terms are found.

ALL

Match only if all terms are found.

LITERAL

Match the exact string.

REGEX

Match using regular expressions.

FUZZY

Match using fuzzy string matching.

UNKNOWN

Unknown matching type (fallback).

NONE = 0
ANY = 1
ALL = 2
LITERAL = 3
REGEX = 4
FUZZY = 5
UNKNOWN = -1
class paperap.const.ScheduleDateFieldType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of date fields that can be used for scheduling.

These fields determine which document date is used for scheduling operations.

ADDED

The date the document was added to the system.

CREATED

The date the document was created.

MODIFIED

The date the document was last modified.

CUSTOM_FIELD

A custom date field.

UNKNOWN

Unknown date field type (fallback).

ADDED = 'added'
CREATED = 'created'
MODIFIED = 'modified'
CUSTOM_FIELD = 'custom_field'
UNKNOWN = 'unknown'
class paperap.const.WorkflowTriggerScheduleDateFieldType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of date fields that can trigger scheduled workflows.

These fields determine which document date is used for triggering scheduled workflows.

ADDED

The date the document was added to the system.

CREATED

The date the document was created.

MODIFIED

The date the document was last modified.

CUSTOM_FIELD

A custom date field.

UNKNOWN

Unknown date field type (fallback).

ADDED = 'added'
CREATED = 'created'
MODIFIED = 'modified'
CUSTOM_FIELD = 'custom_field'
UNKNOWN = 'unknown'
class paperap.const.SavedViewDisplayModeType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of display modes for saved views.

These modes determine how documents are displayed in a saved view.

TABLE

Display documents in a table format.

SMALL_CARDS

Display documents as small cards.

LARGE_CARDS

Display documents as large cards.

UNKNOWN

Unknown display mode (fallback).

TABLE = 'table'
SMALL_CARDS = 'smallCards'
LARGE_CARDS = 'largeCards'
UNKNOWN = 'unknown'
class paperap.const.SavedViewDisplayFieldType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of field types that can be displayed in saved views.

These fields determine which document attributes are displayed in a saved view.

TITLE

Document title.

CREATED

Document creation date.

ADDED

Date the document was added to the system.

TAGS

Document tags.

CORRESPONDENT

Document correspondent.

DOCUMENT_TYPE

Document type.

STORAGE_PATH

Document storage path.

NOTES

Document notes.

OWNER

Document owner.

SHARED

Whether the document is shared.

ASN

Document archive serial number.

PAGE_COUNT

Number of pages in the document.

CUSTOM_FIELD

Custom field (format string with field ID).

UNKNOWN

Unknown field type (fallback).

TITLE = 'title'
CREATED = 'created'
ADDED = 'added'
TAGS = 'tag'
CORRESPONDENT = 'correspondent'
DOCUMENT_TYPE = 'documenttype'
STORAGE_PATH = 'storagepath'
NOTES = 'note'
OWNER = 'owner'
SHARED = 'shared'
ASN = 'asn'
PAGE_COUNT = 'pagecount'
CUSTOM_FIELD = 'custom_field_%d'
UNKNOWN = 'unknown'
class paperap.const.DocumentStorageType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of document storage encryption types.

These types determine how documents are encrypted in storage.

UNENCRYPTED

Documents are stored without encryption.

GPG

Documents are encrypted using GPG.

UNKNOWN

Unknown storage type (fallback).

UNENCRYPTED = 'unencrypted'
GPG = 'gpg'
UNKNOWN = 'unknown'
class paperap.const.TaskNameType(*values)[source]

Bases: StrEnumWithUnknown

Enumeration of background task names.

These names identify specific background tasks in the system.

CONSUME_FILE

Task for consuming and processing a document file.

TRAIN_CLASSIFIER

Task for training the document classifier.

CHECK_SANITY

Task for checking system sanity/integrity.

INDEX_OPTIMIZE

Task for optimizing the document index.

UNKNOWN

Unknown task name (fallback).

CONSUME_FILE = 'consume_file'
TRAIN_CLASSIFIER = 'train_classifier'
CHECK_SANITY = 'check_sanity'
INDEX_OPTIMIZE = 'index_optimize'
UNKNOWN = 'unknown'