paperap.resources.base module

METADATA:

File: base.py: Project: paperap
Created: 2025-03-21: Version: 0.0.10

Author: Jess Mann Email: jess@jmann.me

Copyright (c) 2025 Jess Mann

LAST MODIFIED:

2025-03-21 By Jess Mann

class paperap.resources.base.BaseResource(client)[source]

Bases: ABC, Generic[_BaseModel, _BaseQuerySet]

Base class for API resources.

Parameters:

client (PaperlessClient) – The PaperlessClient instance.
endpoint – The API endpoint for this resource.
model_class – The model class for this resource.

model_class: type[TypeVar(_BaseModel, bound= BaseModel)]

queryset_class: type[TypeVar(_BaseQuerySet, bound= BaseQuerySet[Any])]

endpoints: ClassVar[dict[Union[Literal['list', 'detail', 'create', 'update', 'delete'], str], Template]]

__init__(client)[source]

Parameters:: client (PaperlessClient)

client: PaperlessClient

name: str

classmethod __init_subclass__(**kwargs)[source]

Initialize the subclass.

Parameters:: **kwargs (Any) – Arbitrary keyword arguments
Return type:: None

get_endpoint(name, **kwargs)[source]

Parameters:

name (str)
kwargs (Any)

Return type:

str | HttpUrl

all()[source]

Return a QuerySet representing all objects of this resource type.

Return type:: TypeVar(_BaseQuerySet, bound= BaseQuerySet[Any])
Returns:: A QuerySet for this resource

filter(**kwargs)[source]

Return a QuerySet filtered by the given parameters.

Parameters:: **kwargs (Any) – Filter parameters
Return type:: TypeVar(_BaseQuerySet, bound= BaseQuerySet[Any])
Returns:: A filtered QuerySet

get(*args, **kwargs)[source]

Get a model by ID.

Raises NotImplementedError. Subclasses may implement this.

Raises:

NotImplementedError – Unless implemented by a subclass.

Return type:

TypeVar(_BaseModel, bound= BaseModel)

Returns:

The model retrieved.

Parameters:

args (Any)
kwargs (Any)

create(**kwargs)[source]

Create a new resource.

Parameters:

data – Resource data.
kwargs (Any)

Return type:

TypeVar(_BaseModel, bound= BaseModel)

Returns:

The created resource.

update(model)[source]

Update a resource.

Parameters:

resource – The resource to update.
model (TypeVar(_BaseModel, bound= BaseModel))

Return type:

TypeVar(_BaseModel, bound= BaseModel)

Returns:

The updated resource.

update_dict(*args, **kwargs)[source]

Update a resource.

Subclasses may implement this.

Parameters:

args (Any)
kwargs (Any)

Return type:

TypeVar(_BaseModel, bound= BaseModel)

delete(*args, **kwargs)[source]

Delete a resource.

Parameters:

model_id – ID of the resource.
args (Any)
kwargs (Any)

Return type:

None

parse_to_model(item)[source]

Parse an item dictionary into a model instance, handling date parsing.

Parameters:: item (dict[str, Any]) – The item dictionary.
Return type:: TypeVar(_BaseModel, bound= BaseModel)
Returns:: The parsed model instance.

transform_data_input(**data)[source]

Transform data after receiving it from the API.

Parameters:: data (Any) – The data to transform.
Return type:: dict[str, Any]
Returns:: The transformed data.

transform_data_output(model=None, exclude_unset=True, **data)[source]

Transform data before sending it to the API.

Parameters:

model (Optional[TypeVar(_BaseModel, bound= BaseModel)]) – The model to transform.
exclude_unset (bool) – If model is provided, exclude unset fields when calling to_dict()
data (Any) – The data to transform.

Return type:

dict[str, Any]

Returns:

The transformed data.

create_model(**kwargs)[source]

Create a new model instance.

Parameters:: **kwargs (Any) – Model field values
Return type:: TypeVar(_BaseModel, bound= BaseModel)
Returns:: A new model instance.

request_raw(url=None, method='GET', params=None, data=None)[source]

Make an HTTP request to the API, and return the raw json response.

Parameters:

method (str) – The HTTP method to use
url (str | Template | HttpUrl | None) – The full URL to request
params (dict[str, Any] | None) – Query parameters
data (dict[str, Any] | None) – Request body data

Return type:

dict[str, Any] | list[dict[str, Any]] | None

Returns:

The JSON-decoded response from the API

handle_response(response)[source]

Parameters:: response (Any)
Return type:: Iterator[TypeVar(_BaseModel, bound= BaseModel)]

handle_dict_response(**response)[source]

Handle a response from the API and yield results.

Override in subclasses to implement custom response logic.

Parameters:: response (dict[str, Any])
Return type:: Iterator[TypeVar(_BaseModel, bound= BaseModel)]

handle_results(results)[source]

Yield parsed models from a list of results.

Override in subclasses to implement custom result handling.

Parameters:: results (list[dict[str, Any]])
Return type:: Iterator[TypeVar(_BaseModel, bound= BaseModel)]

__call__(*args, **keywords)[source]

Make the resource callable to get a BaseQuerySet.

This allows usage like: client.documents(title__contains=’invoice’)

Parameters:

*args (Any) – Unused
**keywords (Any) – Filter parameters

Return type:

TypeVar(_BaseQuerySet, bound= BaseQuerySet[Any])

Returns:

A filtered QuerySet

class paperap.resources.base.StandardResource(client)[source]

Bases: BaseResource[_StandardModel, _StandardQuerySet]

Base class for API resources.

Parameters:

client (PaperlessClient) – The PaperlessClient instance.
endpoint – The API endpoint for this resource.
model_class – The model class for this resource.

get(model_id, *args, **kwargs)[source]

Get a model within this resource by ID.

Parameters:

model_id (int) – ID of the model to retrieve.
args (Any)
kwargs (Any)

Return type:

TypeVar(_StandardModel, bound= StandardModel)

Returns:

The model retrieved

update(model)[source]

Update a model.

Parameters:: model (TypeVar(_StandardModel, bound= StandardModel)) – The model to update.
Return type:: TypeVar(_StandardModel, bound= StandardModel)
Returns:: The updated model.

delete(model_id)[source]

Delete a resource.

Parameters:: model_id (Union[int, TypeVar(_StandardModel, bound= StandardModel)]) – ID of the resource.
Return type:: None

update_dict(model_id, **data)[source]

Update a resource.

Parameters:

model_id (int) – ID of the resource.
data (dict[str, Any]) – Resource data.

Raises:

ResourceNotFoundError – If the resource with the given id is not found

Return type:

TypeVar(_StandardModel, bound= StandardModel)

Returns:

The updated resource.

class paperap.resources.base.BulkEditing[source]

Bases: object

bulk_edit_objects(object_type, ids, operation, permissions=None, owner_id=None, merge=False)[source]

Bulk edit non-document objects (tags, correspondents, document types, storage paths).

Parameters:

object_type (str) – Type of objects to edit (‘tags’, ‘correspondents’, ‘document_types’, ‘storage_paths’)
ids (list[int]) – List of object IDs to edit
operation (str) – Operation to perform (‘set_permissions’ or ‘delete’)
permissions (dict[str, Any] | None) – Permissions object for ‘set_permissions’ operation
owner_id (int | None) – Owner ID to assign
merge (bool) – Whether to merge permissions with existing ones (True) or replace them (False)
self (BaseResource)

Return type:

dict[str, Any]

Returns:

The API response

Raises:

ValueError – If operation is not valid
ConfigurationError – If the bulk edit endpoint is not defined