paperap.models.abstract.model module

---

METADATA:

File: base.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.abstract.model.ModelConfigType

Bases: TypedDict

populate_by_name: bool

validate_assignment: bool

validate_default: bool

use_enum_values: bool

extra: Literal['ignore']

arbitrary_types_allowed: bool

class paperap.models.abstract.model.BaseModel(**data)

Bases: BaseModel, ABC

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)

Bases: Generic

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

name: str

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

filtering_disabled: ClassVar[set[str]] = {}

filtering_fields: ClassVar[set[str]] = {}

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

blacklist_filtering_params: ClassVar[set[str]] = {}

filtering_strategies: ClassVar[set[FilteringStrategies]] = {FilteringStrategies.BLACKLIST}

field_map: dict[str, str] = {}

save_on_write: bool | None = None

save_timeout: int = ModelPrivateAttr(default=60)

__init__(model)

Parameters:

model (type[_Self])

model: type[TypeVar(_Self, bound= BaseModel)]

filter_allowed(filter_param)

Check if a filter is allowed based on the filtering strategies.

Parameters:

filter_param (str) – The filter parameter to check.

Return type:

bool

Returns:

True if the filter is allowed, False otherwise.

classmethod __init_subclass__(**kwargs)

Initialize subclass and set up metadata.

Parameters:

**kwargs (Any) – Additional keyword arguments.

Return type:

None

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

__init__(**data)

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.

property resource: BaseResource[Self, BaseQuerySet]

property save_executor: ThreadPoolExecutor

cleanup()

Clean up resources used by the model class.

Return type:

None

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:

• self (BaseModel)

• context (Any)

Return type:

None

classmethod from_dict(data)

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)

to_dict(*, include_read_only=True, exclude_none=False, exclude_unset=True)

Convert the model to a dictionary for API requests.

Parameters:

• include_read_only (bool) – Whether to include read-only fields.

• exclude_none (bool) – Whether to exclude fields with None values.

• exclude_unset (bool) – Whether to exclude fields that are not set.

Return type:

dict[str, Any]

Returns:

A dictionary with model data ready for API submission.

Examples

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

dirty_fields(comparison='both')

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

is_dirty(comparison='both')

Check if any field has 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

Return type:

bool

Returns:

True if any field has changed.

classmethod create(**kwargs)

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

delete()

Return type:

None

update_locally(*, from_db=None, skip_changed_fields=False, **kwargs)

Update model attributes without triggering automatic save.

Parameters:

• **kwargs (Any) – Field values to update

• from_db (bool | None)

• skip_changed_fields (bool)

Return type:

None

Returns:

Self with updated values

update(**kwargs)

Update this model with new values.

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

Parameters:

**kwargs (Any) – New field values.

Return type:

None

Examples

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

abstractmethod is_new()

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

Return type:

bool

Returns:

True if the model is new, False otherwise.

Examples

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

should_save_on_write()

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

Return type:

bool

enable_save_on_write()

Enable automatic saving on attribute write.

Return type:

None

disable_save_on_write()

Disable automatic saving on attribute write.

Return type:

None

matches_dict(data)

Check if the model matches the provided data.

Parameters:

data (dict[str, Any]) – Dictionary containing the data to compare.

Return type:

bool

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)

__str__()

Human-readable string representation.

Return type:

str

Returns:

A string representation of the model.

class paperap.models.abstract.model.StandardModel(**data)

Bases: BaseModel, ABC

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

id

Unique identifier for the model.

Parameters:

data (Any)

id: int

class Meta(model)

Bases: Meta

Metadata for the StandardModel.

read_only_fields

Fields that should not be modified.

supported_filtering_params

Params allowed during queryset filtering.

Parameters:

model (type[_Self])

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

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

blacklist_filtering_params: ClassVar[set[str]] = {}

field_map: dict[str, str] = {}

filtering_disabled: ClassVar[set[str]] = {}

filtering_fields: ClassVar[set[str]] = {'_resource', 'id'}

model: type[_Self]

name: str

property resource: StandardResource[Self, StandardQuerySet]

update(**kwargs)

Update this model with new values and save changes.

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

Parameters:

**kwargs (Any) – New field values.

Return type:

None

refresh()

Refresh the model with the latest data from the server.

Return type:

bool

Returns:

True if the model data changes, False on failure or if the data does not change.

Raises:

ResourceNotFoundError – If the model is not found on Paperless. (e.g. it was deleted remotely)

save(*, force=False)

Parameters:

force (bool)

Return type:

bool

save_sync(*, force=False)

Save this model instance synchronously.

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

Return type:

bool

Returns:

True if the save was successful, False otherwise.

Raises:

• ResourceNotFoundError – If the resource doesn’t exist on the server

• RequestError – If there’s a communication error with the server

• PermissionError – If the user doesn’t have permission to update the resource

Parameters:

force (bool)

save_async(*, force=False)

Save this model instance asynchronously.

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

Return type:

bool

Returns:

True if the save was successfully submitted async, False otherwise.

Parameters:

force (bool)

is_new()

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

Return type:

bool

Returns:

True if the model is new, False otherwise.

Examples

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

__setattr__(name, value)

Override attribute setting to automatically trigger async save.

Parameters:

• name (str) – Attribute name

• value (Any) – New attribute value

Return type:

None

__str__()

Human-readable string representation.

Return type:

str

Returns:

A string representation of the model.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'extra': 'ignore', 'populate_by_name': True, 'use_enum_values': True, 'validate_assignment': True, 'validate_default': True}

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

model_post_init(context: Any, /) → None

We need to both initialize private attributes and call the user-defined model_post_init method.

Parameters:

• self (BaseModel)

• context (Any)

Return type:

None