paperap.models.tag.model module

Define the Tag model for interacting with Paperless-NgX tags.

This module provides the Tag model class for working with tags in Paperless-NgX. Tags are used to categorize and organize documents, and this module enables creating, retrieving, updating, and deleting tags, as well as accessing documents associated with specific tags.

class paperap.models.tag.model.Tag(**data)[source]

Bases: StandardModel, MatcherMixin

Represent a tag in Paperless-NgX for document categorization.

Tags are used to categorize and organize documents in Paperless-NgX. Each tag has a name, color, and can be designated as an inbox tag. Tags can be assigned to documents and used for filtering and searching.

This class provides methods for interacting with tags, including retrieving associated documents and managing tag properties.

name

The display name of the tag.

Type:

str, optional

slug

The URL-friendly version of the name (auto-generated).

Type:

str, optional

colour

The color of the tag (hex string or integer).

Type:

str or int, optional

is_inbox_tag

Whether this tag is used to mark documents for review.

Type:

bool, optional

document_count

The number of documents with this tag (read-only).

Type:

int

owner

The ID of the user who owns this tag.

Type:

int, optional

user_can_change

Whether the current user has permission to modify this tag.

Type:

bool, optional

Examples

Create a new tag: ```python tag = client.tags.create(

name=”Tax Documents”, color=”#ff0000”, is_inbox_tag=False

Update an existing tag: `python tag = client.tags.get(5) tag.name = "Important Tax Documents" tag.color = "#00ff00" tag.save() `

Parameters:

data (Any)

name: str | None
slug: str | None
colour: str | int | None
is_inbox_tag: bool | None
document_count: int
owner: int | None
user_can_change: bool | None
classmethod handle_text_color_alias(data)[source]

Handle ‘text_color’ as an alias for ‘colour’.

Ensure compatibility with different API versions by accepting ‘text_color’ as an alternative field name for the tag color.

Parameters:

data (dict[str, Any]) – The input data dictionary to validate.

Returns:

The modified data dictionary with normalized color field.

Return type:

dict[str, Any]

property color: str | int | None

Get the tag color (alias for the colour field).

Provide American English spelling alternative for the British ‘colour’ field.

Returns:

The color value as a string (hex code) or integer.

Return type:

str | int | None

class Meta(model)[source]

Bases: Meta

Define metadata for the Tag model.

Specify model-specific metadata including read-only fields and the associated queryset class.

read_only_fields

Fields that cannot be modified by the client.

Type:

set

queryset

The queryset class used for querying tags.

Type:

TagQuerySet

Parameters:

model (type[_Self])

read_only_fields: ClassVar[set[str]] = {'document_count', 'id', 'slug'}
queryset

alias of TagQuerySet

blacklist_filtering_params: ClassVar[set[str]] = {}
field_map: dict[str, str] = {}
filtering_disabled: ClassVar[set[str]] = {}
filtering_fields: ClassVar[set[str]] = {'_resource', 'colour', 'document_count', 'id', 'is_inbox_tag', 'name', 'owner', 'slug', 'user_can_change'}
supported_filtering_params: ClassVar[set[str]] = {'id', 'id__in', 'limit'}
model: type[_Self]
name: str
property documents: DocumentQuerySet

Get all documents associated with this tag.

Retrieve a queryset of all documents that have been tagged with this tag. The queryset is lazy-loaded, so no API requests are made until the queryset is evaluated.

Returns:

A queryset containing all documents with this tag.

Return type:

DocumentQuerySet

Examples

Get documents with a specific tag: ```python # Get a tag tax_tag = client.tags.get(5)

# Get all documents with this tag tax_documents = tax_tag.documents

# Count documents with this tag count = tax_tag.documents.count()

# Filter documents with this tag further recent_tax_docs = tax_tag.documents.filter(created__gt=”2023-01-01”) ```

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