paperap.models.abstract.queryset module

METADATA:

File: queryset.py

Project: paperap

Created: 2025-03-04

Version: 0.0.10

Author: Jess Mann Email: jess@jmann.me

Copyright (c) 2025 Jess Mann

LAST MODIFIED:

2025-03-04 By Jess Mann

class paperap.models.abstract.queryset.BaseQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: Iterable, Generic

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)

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

resource: BaseResource[TypeVar(_Model, bound= BaseModel), Self]
filters: dict[str, Any]
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])

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)

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:

Examples

# Get document with ID 123 doc = client.documents.get(123)

count()[source]

Return the total number of objects in the queryset.

Return type:

int

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:

int

Returns:

The count of objects on the current page

Raises:

NotImplementedError – If _last_response is not set

all()[source]

Return a new QuerySet that copies the current one.

Return type:

Self

Returns:

A copy of the current BaseQuerySet

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

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

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

exists()[source]

Return True if the QuerySet contains any results.

Return type:

bool

Returns:

True if there are any objects matching the filters

none()[source]

Return an empty QuerySet.

Return type:

Self

Returns:

An empty QuerySet

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.

Parameters:

  • field (str) – The field name to filter by.

  • value (str) – The value to filter against.

  • exact (bool) – Whether to filter by an exact match.

  • case_insensitive (bool) – Whether the filter should be case-insensitive.

Return type:

Self

Returns:

A new QuerySet instance with the filter applied.

__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:

int

Returns:

The count of objects

__bool__()[source]

Return True if the QuerySet has any results.

Return type:

bool

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

__contains__(item)[source]

Return True if the QuerySet contains the given object.

Parameters:

item (Any) – The object to check for

Return type:

bool

Returns:

True if the object is in the QuerySet

class paperap.models.abstract.queryset.StandardQuerySet(resource, filters=None, _cache=None, _fetch_all=False, _next_url=None, _last_response=None, _iter=None, _urls_fetched=None)[source]

Bases: BaseQuerySet, Generic

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

resource: StandardResource[TypeVar(_Model, bound= StandardModel), Self]
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)

id(value)[source]

Filter models by ID.

Parameters:

value (int | list[int]) – The ID or list of IDs to filter by

Return type:

Self

Returns:

Filtered QuerySet

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

Parameters:

item (Any) – The object or ID to check for

Return type:

bool

Returns:

True if the object is in the QuerySet

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:

  • action (str) – The action to perform

  • **kwargs (Any) – Additional parameters for the action

Return type:

TypeAliasType

Returns:

The API response

Raises:

NotImplementedError – If the resource doesn’t support bulk actions

filters: dict[str, Any]
delete()[source]

Delete all objects in the queryset.

Return type:

TypeAliasType

Returns:

The API response

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

bulk_assign_tags(tag_ids, remove_existing=False)[source]

Assign tags to all objects in the queryset.

Parameters:

  • tag_ids (list[int]) – List of tag IDs to assign

  • remove_existing (bool) – If True, remove existing tags before assigning new ones

Return type:

TypeAliasType

Returns:

The API response

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