easypaperless.resources

Resource Classes

The following resource classes are _internal classes. Methods can be accessed via the instance of easypaperless.PaperlessClient or easypaperless.SyncPaperlessClient

Example:

async with PaperlessClient(url="http://localhost:8000", api_token="abc") as client: docs = await client.documents.list(max_results=10)

 1"""Resource Classes
 2
 3The following resource classes are _internal classes. Methods can be accessed via the instance of
 4`easypaperless.PaperlessClient` or `easypaperless.SyncPaperlessClient`
 5
 6Example:
 7    async with PaperlessClient(url="http://localhost:8000", api_token="abc") as client:
 8        docs = await client.documents.list(max_results=10)
 9
10"""
11
12# internal comment: the doc string above is also rendered in the pdoc documentation.
13#
14# original was:
15#
16# Public resource classes — for type annotations and IDE support.
17#
18# Re-exports all async and sync resource classes from the internal modules
19# so that pdoc can document them as a full page with all methods.
20#
21# Example:
22#    from easypaperless.resources import DocumentsResource
23
24from easypaperless._internal.resources.correspondents import CorrespondentsResource
25from easypaperless._internal.resources.custom_fields import CustomFieldsResource
26from easypaperless._internal.resources.document_types import DocumentTypesResource
27from easypaperless._internal.resources.documents import DocumentsResource
28from easypaperless._internal.resources.groups import GroupsResource
29from easypaperless._internal.resources.notes import NotesResource
30from easypaperless._internal.resources.storage_paths import StoragePathsResource
31from easypaperless._internal.resources.tags import TagsResource
32from easypaperless._internal.resources.tasks import TasksResource
33from easypaperless._internal.resources.trash import TrashResource
34from easypaperless._internal.resources.users import UsersResource
35from easypaperless._internal.sync_resources.correspondents import SyncCorrespondentsResource
36from easypaperless._internal.sync_resources.custom_fields import SyncCustomFieldsResource
37from easypaperless._internal.sync_resources.document_types import SyncDocumentTypesResource
38from easypaperless._internal.sync_resources.documents import SyncDocumentsResource
39from easypaperless._internal.sync_resources.groups import SyncGroupsResource
40from easypaperless._internal.sync_resources.notes import SyncNotesResource
41from easypaperless._internal.sync_resources.storage_paths import SyncStoragePathsResource
42from easypaperless._internal.sync_resources.tags import SyncTagsResource
43from easypaperless._internal.sync_resources.tasks import SyncTasksResource
44from easypaperless._internal.sync_resources.trash import SyncTrashResource
45from easypaperless._internal.sync_resources.users import SyncUsersResource
46
47__all__ = [
48    "CorrespondentsResource",
49    "CustomFieldsResource",
50    "DocumentTypesResource",
51    "DocumentsResource",
52    "NotesResource",
53    "StoragePathsResource",
54    "TagsResource",
55    "SyncCorrespondentsResource",
56    "SyncCustomFieldsResource",
57    "SyncDocumentTypesResource",
58    "SyncDocumentsResource",
59    "SyncNotesResource",
60    "SyncStoragePathsResource",
61    "SyncTagsResource",
62    "UsersResource",
63    "SyncUsersResource",
64    "GroupsResource",
65    "SyncGroupsResource",
66    "TrashResource",
67    "SyncTrashResource",
68    "TasksResource",
69    "SyncTasksResource",
70]
class CorrespondentsResource:
 21class CorrespondentsResource:
 22    """Accessor for correspondents: ``client.correspondents``."""
 23
 24    def __init__(self, core: _ClientCore) -> None:
 25        self._core = core
 26
 27    async def list(
 28        self,
 29        *,
 30        ids: List[int] | None = None,
 31        name_contains: str | None = None,
 32        name_exact: str | None = None,
 33        page: int | None = None,
 34        page_size: int | None = None,
 35        ordering: str | None = None,
 36        descending: bool = False,
 37        full_perms: bool = False,
 38    ) -> PagedResult[Correspondent]:
 39        """Return correspondents defined in paperless-ngx.
 40
 41        When ``page`` is ``None`` (the default), all pages are fetched
 42        automatically and ``next`` / ``previous`` in the result are always
 43        ``None``.  When ``page`` is set, only that page is fetched and
 44        ``next`` / ``previous`` reflect the raw API values.
 45
 46        Args:
 47            ids: Return only correspondents whose ID is in this list.
 48            name_contains: Case-insensitive substring filter on name.
 49            name_exact: Case-insensitive exact match on name.
 50            page: Return only this specific page (1-based).
 51            page_size: Number of results per page.
 52            ordering: Field to sort by.
 53            descending: When ``True``, reverses the sort direction.
 54            full_perms: When ``True``, paperless-ngx returns the full view/change
 55                permissions of every object, available as
 56                ``Correspondent.permissions``; ``user_can_change`` is then ``None``.
 57                Default: ``False``.
 58
 59        Returns:
 60            :class:`~easypaperless.models.paged_result.PagedResult` of
 61            :class:`~easypaperless.models.correspondents.Correspondent` objects.
 62        """
 63        logger.info("Listing correspondents")
 64        params: dict[str, Any] = {}
 65        if ids is not None:
 66            params["id__in"] = ",".join(str(i) for i in ids)
 67        if name_contains is not None:
 68            params["name__icontains"] = name_contains
 69        if name_exact is not None:
 70            params["name__iexact"] = name_exact
 71        if page is not None:
 72            params["page"] = page
 73        if page_size is not None:
 74            params["page_size"] = page_size
 75        if ordering is not None:
 76            params["ordering"] = f"-{ordering}" if descending else ordering
 77        return cast(
 78            PagedResult[Correspondent],
 79            await self._core._list_resource(
 80                "correspondents", Correspondent, params or None, full_perms=full_perms
 81            ),
 82        )
 83
 84    async def get(self, id: int, *, full_perms: bool = False) -> Correspondent:
 85        """Fetch a single correspondent by its ID.
 86
 87        Args:
 88            id: Numeric correspondent ID.
 89            full_perms: When ``True``, paperless-ngx returns the full view/change
 90                permissions, available as ``Correspondent.permissions``;
 91                ``user_can_change`` is then ``None``. Default: ``False``.
 92
 93        Returns:
 94            The :class:`~easypaperless.models.correspondents.Correspondent` with the given ID.
 95
 96        Raises:
 97            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
 98        """
 99        logger.info("Getting correspondent id=%d full_perms=%s", id, full_perms)
100        return cast(
101            Correspondent,
102            await self._core._get_resource(
103                "correspondents", id, Correspondent, full_perms=full_perms
104            ),
105        )
106
107    async def create(
108        self,
109        *,
110        name: str,
111        match: str | Unset = UNSET,
112        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
113        is_insensitive: bool = True,
114        owner: int | None | Unset = UNSET,
115        set_permissions: SetPermissions | None | Unset = UNSET,
116    ) -> Correspondent:
117        """Create a new correspondent.
118
119        Args:
120            name: Correspondent name. Must be unique.
121            match: Auto-matching pattern.
122            matching_algorithm: Controls how ``match`` is applied.
123                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
124                regular-expression matching.
125            is_insensitive: When ``True``, ``match`` is case-insensitive.
126                Defaults to ``True``, matching the paperless-ngx API default.
127            owner: Numeric user ID to assign as owner.
128            set_permissions: Explicit view/change permission sets.
129                Pass ``None`` to create with empty permissions.
130
131        Returns:
132            The newly created :class:`~easypaperless.models.correspondents.Correspondent`.
133        """
134        logger.info("Creating correspondent name=%r", name)
135        return cast(
136            Correspondent,
137            await self._core._create_resource(
138                "correspondents",
139                Correspondent,
140                owner=owner,
141                set_permissions=set_permissions,
142                name=name,
143                match=match,
144                matching_algorithm=matching_algorithm,
145                is_insensitive=is_insensitive,
146            ),
147        )
148
149    async def update(
150        self,
151        id: int,
152        *,
153        name: str | Unset = UNSET,
154        match: str | Unset = UNSET,
155        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
156        is_insensitive: bool | Unset = UNSET,
157        owner: int | None | Unset = UNSET,
158        set_permissions: SetPermissions | None | Unset = UNSET,
159    ) -> Correspondent:
160        """Partially update a correspondent (PATCH semantics).
161
162        Args:
163            id: Numeric ID of the correspondent to update.
164            name: Correspondent name.
165            match: Auto-matching pattern.
166            matching_algorithm: Controls how ``match`` is applied.
167                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
168                regular-expression matching.
169            is_insensitive: When ``True``, ``match`` is case-insensitive.
170            owner: Numeric user ID to assign as owner.
171                Pass ``None`` to clear the owner.
172                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
173            set_permissions: Explicit view/change permission sets.
174                Pass ``None`` to clear all permissions (overwrite with empty).
175                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
176
177        Returns:
178            The updated :class:`~easypaperless.models.correspondents.Correspondent`.
179        """
180        logger.info("Updating correspondent id=%d", id)
181        return cast(
182            Correspondent,
183            await self._core._update_resource(
184                "correspondents",
185                id,
186                Correspondent,
187                name=name,
188                match=match,
189                matching_algorithm=matching_algorithm,
190                is_insensitive=is_insensitive,
191                owner=owner,
192                set_permissions=set_permissions,
193            ),
194        )
195
196    async def delete(self, id: int) -> None:
197        """Delete a correspondent.
198
199        Args:
200            id: Numeric ID of the correspondent to delete.
201
202        Raises:
203            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
204        """
205        logger.info("Deleting correspondent id=%d", id)
206        await self._core._delete_resource("correspondents", id)
207
208    async def bulk_delete(self, ids: List[int]) -> None:
209        """Permanently delete multiple correspondents in a single request.
210
211        Args:
212            ids: List of correspondent IDs to delete.
213        """
214        logger.info("Bulk deleting %d correspondents", len(ids))
215        await self._core._bulk_edit_objects("correspondents", ids, "delete")
216
217    async def bulk_set_permissions(
218        self,
219        ids: List[int],
220        *,
221        set_permissions: SetPermissions | Unset = UNSET,
222        owner: int | None | Unset = UNSET,
223        merge: bool = False,
224    ) -> None:
225        """Set permissions and/or owner on multiple correspondents.
226
227        Args:
228            ids: List of correspondent IDs to modify.
229            set_permissions: Explicit view/change permission sets.
230                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
231            owner: Numeric user ID to assign as owner.
232                Pass ``None`` to clear the owner.
233                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
234            merge: When ``True``, new permissions are merged with existing ones.
235        """
236        logger.info("Bulk setting permissions on %d correspondents", len(ids))
237        params: dict[str, Any] = {"merge": merge}
238        if not isinstance(set_permissions, Unset):
239            params["permissions"] = set_permissions.model_dump()
240        if not isinstance(owner, Unset):
241            params["owner"] = owner
242        await self._core._bulk_edit_objects("correspondents", ids, "set_permissions", **params)

Accessor for correspondents: client.correspondents.

CorrespondentsResource(core: easypaperless.client._ClientCore)
24    def __init__(self, core: _ClientCore) -> None:
25        self._core = core
async def list( self, *, ids: Optional[List[int]] = None, name_contains: str | None = None, name_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False, full_perms: bool = False) -> easypaperless.PagedResult[Correspondent]:
27    async def list(
28        self,
29        *,
30        ids: List[int] | None = None,
31        name_contains: str | None = None,
32        name_exact: str | None = None,
33        page: int | None = None,
34        page_size: int | None = None,
35        ordering: str | None = None,
36        descending: bool = False,
37        full_perms: bool = False,
38    ) -> PagedResult[Correspondent]:
39        """Return correspondents defined in paperless-ngx.
40
41        When ``page`` is ``None`` (the default), all pages are fetched
42        automatically and ``next`` / ``previous`` in the result are always
43        ``None``.  When ``page`` is set, only that page is fetched and
44        ``next`` / ``previous`` reflect the raw API values.
45
46        Args:
47            ids: Return only correspondents whose ID is in this list.
48            name_contains: Case-insensitive substring filter on name.
49            name_exact: Case-insensitive exact match on name.
50            page: Return only this specific page (1-based).
51            page_size: Number of results per page.
52            ordering: Field to sort by.
53            descending: When ``True``, reverses the sort direction.
54            full_perms: When ``True``, paperless-ngx returns the full view/change
55                permissions of every object, available as
56                ``Correspondent.permissions``; ``user_can_change`` is then ``None``.
57                Default: ``False``.
58
59        Returns:
60            :class:`~easypaperless.models.paged_result.PagedResult` of
61            :class:`~easypaperless.models.correspondents.Correspondent` objects.
62        """
63        logger.info("Listing correspondents")
64        params: dict[str, Any] = {}
65        if ids is not None:
66            params["id__in"] = ",".join(str(i) for i in ids)
67        if name_contains is not None:
68            params["name__icontains"] = name_contains
69        if name_exact is not None:
70            params["name__iexact"] = name_exact
71        if page is not None:
72            params["page"] = page
73        if page_size is not None:
74            params["page_size"] = page_size
75        if ordering is not None:
76            params["ordering"] = f"-{ordering}" if descending else ordering
77        return cast(
78            PagedResult[Correspondent],
79            await self._core._list_resource(
80                "correspondents", Correspondent, params or None, full_perms=full_perms
81            ),
82        )

Return correspondents defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • ids: Return only correspondents whose ID is in this list.
  • name_contains: Case-insensitive substring filter on name.
  • name_exact: Case-insensitive exact match on name.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every object, available as Correspondent.permissions; user_can_change is then None. Default: False.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.correspondents.Correspondent objects.

async def get( self, id: int, *, full_perms: bool = False) -> easypaperless.Correspondent:
 84    async def get(self, id: int, *, full_perms: bool = False) -> Correspondent:
 85        """Fetch a single correspondent by its ID.
 86
 87        Args:
 88            id: Numeric correspondent ID.
 89            full_perms: When ``True``, paperless-ngx returns the full view/change
 90                permissions, available as ``Correspondent.permissions``;
 91                ``user_can_change`` is then ``None``. Default: ``False``.
 92
 93        Returns:
 94            The :class:`~easypaperless.models.correspondents.Correspondent` with the given ID.
 95
 96        Raises:
 97            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
 98        """
 99        logger.info("Getting correspondent id=%d full_perms=%s", id, full_perms)
100        return cast(
101            Correspondent,
102            await self._core._get_resource(
103                "correspondents", id, Correspondent, full_perms=full_perms
104            ),
105        )

Fetch a single correspondent by its ID.

Arguments:
  • id: Numeric correspondent ID.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as Correspondent.permissions; user_can_change is then None. Default: False.
Returns:

The ~easypaperless.models.correspondents.Correspondent with the given ID.

Raises:
async def create( self, *, name: str, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool = True, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.Correspondent:
107    async def create(
108        self,
109        *,
110        name: str,
111        match: str | Unset = UNSET,
112        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
113        is_insensitive: bool = True,
114        owner: int | None | Unset = UNSET,
115        set_permissions: SetPermissions | None | Unset = UNSET,
116    ) -> Correspondent:
117        """Create a new correspondent.
118
119        Args:
120            name: Correspondent name. Must be unique.
121            match: Auto-matching pattern.
122            matching_algorithm: Controls how ``match`` is applied.
123                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
124                regular-expression matching.
125            is_insensitive: When ``True``, ``match`` is case-insensitive.
126                Defaults to ``True``, matching the paperless-ngx API default.
127            owner: Numeric user ID to assign as owner.
128            set_permissions: Explicit view/change permission sets.
129                Pass ``None`` to create with empty permissions.
130
131        Returns:
132            The newly created :class:`~easypaperless.models.correspondents.Correspondent`.
133        """
134        logger.info("Creating correspondent name=%r", name)
135        return cast(
136            Correspondent,
137            await self._core._create_resource(
138                "correspondents",
139                Correspondent,
140                owner=owner,
141                set_permissions=set_permissions,
142                name=name,
143                match=match,
144                matching_algorithm=matching_algorithm,
145                is_insensitive=is_insensitive,
146            ),
147        )

Create a new correspondent.

Arguments:
  • name: Correspondent name. Must be unique.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive. Defaults to True, matching the paperless-ngx API default.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.correspondents.Correspondent.

async def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.Correspondent:
149    async def update(
150        self,
151        id: int,
152        *,
153        name: str | Unset = UNSET,
154        match: str | Unset = UNSET,
155        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
156        is_insensitive: bool | Unset = UNSET,
157        owner: int | None | Unset = UNSET,
158        set_permissions: SetPermissions | None | Unset = UNSET,
159    ) -> Correspondent:
160        """Partially update a correspondent (PATCH semantics).
161
162        Args:
163            id: Numeric ID of the correspondent to update.
164            name: Correspondent name.
165            match: Auto-matching pattern.
166            matching_algorithm: Controls how ``match`` is applied.
167                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
168                regular-expression matching.
169            is_insensitive: When ``True``, ``match`` is case-insensitive.
170            owner: Numeric user ID to assign as owner.
171                Pass ``None`` to clear the owner.
172                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
173            set_permissions: Explicit view/change permission sets.
174                Pass ``None`` to clear all permissions (overwrite with empty).
175                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
176
177        Returns:
178            The updated :class:`~easypaperless.models.correspondents.Correspondent`.
179        """
180        logger.info("Updating correspondent id=%d", id)
181        return cast(
182            Correspondent,
183            await self._core._update_resource(
184                "correspondents",
185                id,
186                Correspondent,
187                name=name,
188                match=match,
189                matching_algorithm=matching_algorithm,
190                is_insensitive=is_insensitive,
191                owner=owner,
192                set_permissions=set_permissions,
193            ),
194        )

Partially update a correspondent (PATCH semantics).

Arguments:
  • id: Numeric ID of the correspondent to update.
  • name: Correspondent name.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.correspondents.Correspondent.

async def delete(self, id: int) -> None:
196    async def delete(self, id: int) -> None:
197        """Delete a correspondent.
198
199        Args:
200            id: Numeric ID of the correspondent to delete.
201
202        Raises:
203            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
204        """
205        logger.info("Deleting correspondent id=%d", id)
206        await self._core._delete_resource("correspondents", id)

Delete a correspondent.

Arguments:
  • id: Numeric ID of the correspondent to delete.
Raises:
async def bulk_delete(self, ids: List[int]) -> None:
208    async def bulk_delete(self, ids: List[int]) -> None:
209        """Permanently delete multiple correspondents in a single request.
210
211        Args:
212            ids: List of correspondent IDs to delete.
213        """
214        logger.info("Bulk deleting %d correspondents", len(ids))
215        await self._core._bulk_edit_objects("correspondents", ids, "delete")

Permanently delete multiple correspondents in a single request.

Arguments:
  • ids: List of correspondent IDs to delete.
async def bulk_set_permissions( self, ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
217    async def bulk_set_permissions(
218        self,
219        ids: List[int],
220        *,
221        set_permissions: SetPermissions | Unset = UNSET,
222        owner: int | None | Unset = UNSET,
223        merge: bool = False,
224    ) -> None:
225        """Set permissions and/or owner on multiple correspondents.
226
227        Args:
228            ids: List of correspondent IDs to modify.
229            set_permissions: Explicit view/change permission sets.
230                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
231            owner: Numeric user ID to assign as owner.
232                Pass ``None`` to clear the owner.
233                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
234            merge: When ``True``, new permissions are merged with existing ones.
235        """
236        logger.info("Bulk setting permissions on %d correspondents", len(ids))
237        params: dict[str, Any] = {"merge": merge}
238        if not isinstance(set_permissions, Unset):
239            params["permissions"] = set_permissions.model_dump()
240        if not isinstance(owner, Unset):
241            params["owner"] = owner
242        await self._core._bulk_edit_objects("correspondents", ids, "set_permissions", **params)

Set permissions and/or owner on multiple correspondents.

Arguments:
  • ids: List of correspondent IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
class CustomFieldsResource:
 20class CustomFieldsResource:
 21    """Accessor for custom fields: ``client.custom_fields``."""
 22
 23    def __init__(self, core: _ClientCore) -> None:
 24        self._core = core
 25
 26    async def list(
 27        self,
 28        *,
 29        name_contains: str | None = None,
 30        name_exact: str | None = None,
 31        page: int | None = None,
 32        page_size: int | None = None,
 33        ordering: str | None = None,
 34        descending: bool = False,
 35    ) -> PagedResult[CustomField]:
 36        """Return all custom fields defined in paperless-ngx.
 37
 38        When ``page`` is ``None`` (the default), all pages are fetched
 39        automatically and ``next`` / ``previous`` in the result are always
 40        ``None``.  When ``page`` is set, only that page is fetched and
 41        ``next`` / ``previous`` reflect the raw API values.
 42
 43        Args:
 44            name_contains: Case-insensitive substring filter on name.
 45            name_exact: Case-insensitive exact match on name.
 46            page: Return only this specific page (1-based).
 47            page_size: Number of results per page.
 48            ordering: Field to sort by.
 49            descending: When ``True``, reverses the sort direction.
 50
 51        Returns:
 52            :class:`~easypaperless.models.paged_result.PagedResult` of
 53            :class:`~easypaperless.models.custom_fields.CustomField` objects.
 54        """
 55        logger.info("Listing custom fields")
 56        params: dict[str, Any] = {}
 57        if name_contains is not None:
 58            params["name__icontains"] = name_contains
 59        if name_exact is not None:
 60            params["name__iexact"] = name_exact
 61        if page is not None:
 62            params["page"] = page
 63        if page_size is not None:
 64            params["page_size"] = page_size
 65        if ordering is not None:
 66            params["ordering"] = f"-{ordering}" if descending else ordering
 67        return cast(
 68            PagedResult[CustomField],
 69            await self._core._list_resource("custom_fields", CustomField, params or None),
 70        )
 71
 72    async def get(self, id: int) -> CustomField:
 73        """Fetch a single custom field by its ID.
 74
 75        Args:
 76            id: Numeric custom-field ID.
 77
 78        Returns:
 79            The :class:`~easypaperless.models.custom_fields.CustomField` with the given ID.
 80
 81        Raises:
 82            ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
 83        """
 84        logger.info("Getting custom field id=%d", id)
 85        return cast(CustomField, await self._core._get_resource("custom_fields", id, CustomField))
 86
 87    async def create(
 88        self,
 89        *,
 90        name: str,
 91        data_type: str,
 92        extra_data: Any | None = None,
 93        owner: int | None | Unset = UNSET,
 94        set_permissions: SetPermissions | None | Unset = UNSET,
 95    ) -> CustomField:
 96        """Create a new custom field.
 97
 98        Args:
 99            name: Field name shown in the UI. Must be unique.
100            data_type: Value type. One of ``"string"``, ``"boolean"``,
101                ``"integer"``, ``"float"``, ``"monetary"``, ``"date"``,
102                ``"url"``, ``"documentlink"``, ``"select"``.
103            extra_data: Additional configuration for the field type.
104            owner: Numeric user ID to assign as owner.
105            set_permissions: Explicit view/change permission sets.
106                Pass ``None`` to create with empty permissions.
107
108        Returns:
109            The newly created :class:`~easypaperless.models.custom_fields.CustomField`.
110        """
111        logger.info("Creating custom field name=%r data_type=%r", name, data_type)
112        return cast(
113            CustomField,
114            await self._core._create_resource(
115                "custom_fields",
116                CustomField,
117                owner=owner,
118                set_permissions=set_permissions,
119                name=name,
120                data_type=data_type,
121                extra_data=extra_data,
122            ),
123        )
124
125    async def update(
126        self,
127        id: int,
128        *,
129        name: str | Unset = UNSET,
130        data_type: str | Unset = UNSET,
131        extra_data: Any | None | Unset = UNSET,
132        owner: int | None | Unset = UNSET,
133        set_permissions: SetPermissions | None | Unset = UNSET,
134    ) -> CustomField:
135        """Partially update a custom field (PATCH semantics).
136
137        Args:
138            id: Numeric ID of the custom field to update.
139            name: Field name shown in the UI.
140            data_type: Value type (e.g. ``"string"``, ``"boolean"``, ``"integer"``).
141                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
142            extra_data: Additional configuration for the field type.
143            owner: Numeric user ID to assign as owner.
144                Pass ``None`` to clear the owner.
145                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
146            set_permissions: Explicit view/change permission sets.
147                Pass ``None`` to clear all permissions (overwrite with empty).
148                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
149
150        Returns:
151            The updated :class:`~easypaperless.models.custom_fields.CustomField`.
152        """
153        logger.info("Updating custom field id=%d", id)
154        return cast(
155            CustomField,
156            await self._core._update_resource(
157                "custom_fields",
158                id,
159                CustomField,
160                name=name,
161                data_type=data_type,
162                extra_data=extra_data,
163                owner=owner,
164                set_permissions=set_permissions,
165            ),
166        )
167
168    async def delete(self, id: int) -> None:
169        """Delete a custom field.
170
171        Args:
172            id: Numeric ID of the custom field to delete.
173
174        Raises:
175            ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
176        """
177        logger.info("Deleting custom field id=%d", id)
178        await self._core._delete_resource("custom_fields", id)

Accessor for custom fields: client.custom_fields.

CustomFieldsResource(core: easypaperless.client._ClientCore)
23    def __init__(self, core: _ClientCore) -> None:
24        self._core = core
async def list( self, *, name_contains: str | None = None, name_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False) -> easypaperless.PagedResult[CustomField]:
26    async def list(
27        self,
28        *,
29        name_contains: str | None = None,
30        name_exact: str | None = None,
31        page: int | None = None,
32        page_size: int | None = None,
33        ordering: str | None = None,
34        descending: bool = False,
35    ) -> PagedResult[CustomField]:
36        """Return all custom fields defined in paperless-ngx.
37
38        When ``page`` is ``None`` (the default), all pages are fetched
39        automatically and ``next`` / ``previous`` in the result are always
40        ``None``.  When ``page`` is set, only that page is fetched and
41        ``next`` / ``previous`` reflect the raw API values.
42
43        Args:
44            name_contains: Case-insensitive substring filter on name.
45            name_exact: Case-insensitive exact match on name.
46            page: Return only this specific page (1-based).
47            page_size: Number of results per page.
48            ordering: Field to sort by.
49            descending: When ``True``, reverses the sort direction.
50
51        Returns:
52            :class:`~easypaperless.models.paged_result.PagedResult` of
53            :class:`~easypaperless.models.custom_fields.CustomField` objects.
54        """
55        logger.info("Listing custom fields")
56        params: dict[str, Any] = {}
57        if name_contains is not None:
58            params["name__icontains"] = name_contains
59        if name_exact is not None:
60            params["name__iexact"] = name_exact
61        if page is not None:
62            params["page"] = page
63        if page_size is not None:
64            params["page_size"] = page_size
65        if ordering is not None:
66            params["ordering"] = f"-{ordering}" if descending else ordering
67        return cast(
68            PagedResult[CustomField],
69            await self._core._list_resource("custom_fields", CustomField, params or None),
70        )

Return all custom fields defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • name_contains: Case-insensitive substring filter on name.
  • name_exact: Case-insensitive exact match on name.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.custom_fields.CustomField objects.

async def get(self, id: int) -> easypaperless.CustomField:
72    async def get(self, id: int) -> CustomField:
73        """Fetch a single custom field by its ID.
74
75        Args:
76            id: Numeric custom-field ID.
77
78        Returns:
79            The :class:`~easypaperless.models.custom_fields.CustomField` with the given ID.
80
81        Raises:
82            ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
83        """
84        logger.info("Getting custom field id=%d", id)
85        return cast(CustomField, await self._core._get_resource("custom_fields", id, CustomField))

Fetch a single custom field by its ID.

Arguments:
  • id: Numeric custom-field ID.
Returns:

The ~easypaperless.models.custom_fields.CustomField with the given ID.

Raises:
async def create( self, *, name: str, data_type: str, extra_data: typing.Any | None = None, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.CustomField:
 87    async def create(
 88        self,
 89        *,
 90        name: str,
 91        data_type: str,
 92        extra_data: Any | None = None,
 93        owner: int | None | Unset = UNSET,
 94        set_permissions: SetPermissions | None | Unset = UNSET,
 95    ) -> CustomField:
 96        """Create a new custom field.
 97
 98        Args:
 99            name: Field name shown in the UI. Must be unique.
100            data_type: Value type. One of ``"string"``, ``"boolean"``,
101                ``"integer"``, ``"float"``, ``"monetary"``, ``"date"``,
102                ``"url"``, ``"documentlink"``, ``"select"``.
103            extra_data: Additional configuration for the field type.
104            owner: Numeric user ID to assign as owner.
105            set_permissions: Explicit view/change permission sets.
106                Pass ``None`` to create with empty permissions.
107
108        Returns:
109            The newly created :class:`~easypaperless.models.custom_fields.CustomField`.
110        """
111        logger.info("Creating custom field name=%r data_type=%r", name, data_type)
112        return cast(
113            CustomField,
114            await self._core._create_resource(
115                "custom_fields",
116                CustomField,
117                owner=owner,
118                set_permissions=set_permissions,
119                name=name,
120                data_type=data_type,
121                extra_data=extra_data,
122            ),
123        )

Create a new custom field.

Arguments:
  • name: Field name shown in the UI. Must be unique.
  • data_type: Value type. One of "string", "boolean", "integer", "float", "monetary", "date", "url", "documentlink", "select".
  • extra_data: Additional configuration for the field type.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.custom_fields.CustomField.

async def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, data_type: str | easypaperless.Unset = UNSET, extra_data: typing.Any | None | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.CustomField:
125    async def update(
126        self,
127        id: int,
128        *,
129        name: str | Unset = UNSET,
130        data_type: str | Unset = UNSET,
131        extra_data: Any | None | Unset = UNSET,
132        owner: int | None | Unset = UNSET,
133        set_permissions: SetPermissions | None | Unset = UNSET,
134    ) -> CustomField:
135        """Partially update a custom field (PATCH semantics).
136
137        Args:
138            id: Numeric ID of the custom field to update.
139            name: Field name shown in the UI.
140            data_type: Value type (e.g. ``"string"``, ``"boolean"``, ``"integer"``).
141                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
142            extra_data: Additional configuration for the field type.
143            owner: Numeric user ID to assign as owner.
144                Pass ``None`` to clear the owner.
145                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
146            set_permissions: Explicit view/change permission sets.
147                Pass ``None`` to clear all permissions (overwrite with empty).
148                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
149
150        Returns:
151            The updated :class:`~easypaperless.models.custom_fields.CustomField`.
152        """
153        logger.info("Updating custom field id=%d", id)
154        return cast(
155            CustomField,
156            await self._core._update_resource(
157                "custom_fields",
158                id,
159                CustomField,
160                name=name,
161                data_type=data_type,
162                extra_data=extra_data,
163                owner=owner,
164                set_permissions=set_permissions,
165            ),
166        )

Partially update a custom field (PATCH semantics).

Arguments:
  • id: Numeric ID of the custom field to update.
  • name: Field name shown in the UI.
  • data_type: Value type (e.g. "string", "boolean", "integer"). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • extra_data: Additional configuration for the field type.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.custom_fields.CustomField.

async def delete(self, id: int) -> None:
168    async def delete(self, id: int) -> None:
169        """Delete a custom field.
170
171        Args:
172            id: Numeric ID of the custom field to delete.
173
174        Raises:
175            ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
176        """
177        logger.info("Deleting custom field id=%d", id)
178        await self._core._delete_resource("custom_fields", id)

Delete a custom field.

Arguments:
  • id: Numeric ID of the custom field to delete.
Raises:
class DocumentTypesResource:
 21class DocumentTypesResource:
 22    """Accessor for document types: ``client.document_types``."""
 23
 24    def __init__(self, core: _ClientCore) -> None:
 25        self._core = core
 26
 27    async def list(
 28        self,
 29        *,
 30        ids: List[int] | None = None,
 31        name_contains: str | None = None,
 32        name_exact: str | None = None,
 33        page: int | None = None,
 34        page_size: int | None = None,
 35        ordering: str | None = None,
 36        descending: bool = False,
 37        full_perms: bool = False,
 38    ) -> PagedResult[DocumentType]:
 39        """Return document types defined in paperless-ngx.
 40
 41        When ``page`` is ``None`` (the default), all pages are fetched
 42        automatically and ``next`` / ``previous`` in the result are always
 43        ``None``.  When ``page`` is set, only that page is fetched and
 44        ``next`` / ``previous`` reflect the raw API values.
 45
 46        Args:
 47            ids: Return only document types whose ID is in this list.
 48            name_contains: Case-insensitive substring filter on name.
 49            name_exact: Case-insensitive exact match on name.
 50            page: Return only this specific page (1-based).
 51            page_size: Number of results per page.
 52            ordering: Field to sort by.
 53            descending: When ``True``, reverses the sort direction.
 54            full_perms: When ``True``, paperless-ngx returns the full view/change
 55                permissions of every object, available as
 56                ``DocumentType.permissions``; ``user_can_change`` is then ``None``.
 57                Default: ``False``.
 58
 59        Returns:
 60            :class:`~easypaperless.models.paged_result.PagedResult` of
 61            :class:`~easypaperless.models.document_types.DocumentType` objects.
 62        """
 63        logger.info("Listing document types")
 64        params: dict[str, Any] = {}
 65        if ids is not None:
 66            params["id__in"] = ",".join(str(i) for i in ids)
 67        if name_contains is not None:
 68            params["name__icontains"] = name_contains
 69        if name_exact is not None:
 70            params["name__iexact"] = name_exact
 71        if page is not None:
 72            params["page"] = page
 73        if page_size is not None:
 74            params["page_size"] = page_size
 75        if ordering is not None:
 76            params["ordering"] = f"-{ordering}" if descending else ordering
 77        return cast(
 78            PagedResult[DocumentType],
 79            await self._core._list_resource(
 80                "document_types", DocumentType, params or None, full_perms=full_perms
 81            ),
 82        )
 83
 84    async def get(self, id: int, *, full_perms: bool = False) -> DocumentType:
 85        """Fetch a single document type by its ID.
 86
 87        Args:
 88            id: Numeric document-type ID.
 89            full_perms: When ``True``, paperless-ngx returns the full view/change
 90                permissions, available as ``DocumentType.permissions``;
 91                ``user_can_change`` is then ``None``. Default: ``False``.
 92
 93        Returns:
 94            The :class:`~easypaperless.models.document_types.DocumentType` with the given ID.
 95
 96        Raises:
 97            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
 98        """
 99        logger.info("Getting document type id=%d full_perms=%s", id, full_perms)
100        return cast(
101            DocumentType,
102            await self._core._get_resource(
103                "document_types", id, DocumentType, full_perms=full_perms
104            ),
105        )
106
107    async def create(
108        self,
109        *,
110        name: str,
111        match: str | Unset = UNSET,
112        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
113        is_insensitive: bool = True,
114        owner: int | None | Unset = UNSET,
115        set_permissions: SetPermissions | None | Unset = UNSET,
116    ) -> DocumentType:
117        """Create a new document type.
118
119        Args:
120            name: Document-type name. Must be unique.
121            match: Auto-matching pattern.
122            matching_algorithm: Controls how ``match`` is applied.
123                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
124                regular-expression matching.
125            is_insensitive: When ``True``, ``match`` is case-insensitive.
126                Defaults to ``True``, matching the paperless-ngx API default.
127            owner: Numeric user ID to assign as owner.
128            set_permissions: Explicit view/change permission sets.
129                Pass ``None`` to create with empty permissions.
130
131        Returns:
132            The newly created :class:`~easypaperless.models.document_types.DocumentType`.
133        """
134        logger.info("Creating document type name=%r", name)
135        return cast(
136            DocumentType,
137            await self._core._create_resource(
138                "document_types",
139                DocumentType,
140                owner=owner,
141                set_permissions=set_permissions,
142                name=name,
143                match=match,
144                matching_algorithm=matching_algorithm,
145                is_insensitive=is_insensitive,
146            ),
147        )
148
149    async def update(
150        self,
151        id: int,
152        *,
153        name: str | Unset = UNSET,
154        match: str | Unset = UNSET,
155        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
156        is_insensitive: bool | Unset = UNSET,
157        owner: int | None | Unset = UNSET,
158        set_permissions: SetPermissions | None | Unset = UNSET,
159    ) -> DocumentType:
160        """Partially update a document type (PATCH semantics).
161
162        Args:
163            id: Numeric ID of the document type to update.
164            name: Document-type name.
165            match: Auto-matching pattern.
166            matching_algorithm: Controls how ``match`` is applied.
167                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
168                regular-expression matching.
169            is_insensitive: When ``True``, ``match`` is case-insensitive.
170            owner: Numeric user ID to assign as owner.
171                Pass ``None`` to clear the owner.
172                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
173            set_permissions: Explicit view/change permission sets.
174                Pass ``None`` to clear all permissions (overwrite with empty).
175                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
176
177        Returns:
178            The updated :class:`~easypaperless.models.document_types.DocumentType`.
179        """
180        logger.info("Updating document type id=%d", id)
181        return cast(
182            DocumentType,
183            await self._core._update_resource(
184                "document_types",
185                id,
186                DocumentType,
187                name=name,
188                match=match,
189                matching_algorithm=matching_algorithm,
190                is_insensitive=is_insensitive,
191                owner=owner,
192                set_permissions=set_permissions,
193            ),
194        )
195
196    async def delete(self, id: int) -> None:
197        """Delete a document type.
198
199        Args:
200            id: Numeric ID of the document type to delete.
201
202        Raises:
203            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
204        """
205        logger.info("Deleting document type id=%d", id)
206        await self._core._delete_resource("document_types", id)
207
208    async def bulk_delete(self, ids: List[int]) -> None:
209        """Permanently delete multiple document types in a single request.
210
211        Args:
212            ids: List of document type IDs to delete.
213        """
214        logger.info("Bulk deleting %d document types", len(ids))
215        await self._core._bulk_edit_objects("document_types", ids, "delete")
216
217    async def bulk_set_permissions(
218        self,
219        ids: List[int],
220        *,
221        set_permissions: SetPermissions | Unset = UNSET,
222        owner: int | None | Unset = UNSET,
223        merge: bool = False,
224    ) -> None:
225        """Set permissions and/or owner on multiple document types.
226
227        Args:
228            ids: List of document type IDs to modify.
229            set_permissions: Explicit view/change permission sets.
230                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
231            owner: Numeric user ID to assign as owner.
232                Pass ``None`` to clear the owner.
233                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
234            merge: When ``True``, new permissions are merged with existing ones.
235        """
236        logger.info("Bulk setting permissions on %d document types", len(ids))
237        params: dict[str, Any] = {"merge": merge}
238        if not isinstance(set_permissions, Unset):
239            params["permissions"] = set_permissions.model_dump()
240        if not isinstance(owner, Unset):
241            params["owner"] = owner
242        await self._core._bulk_edit_objects("document_types", ids, "set_permissions", **params)

Accessor for document types: client.document_types.

DocumentTypesResource(core: easypaperless.client._ClientCore)
24    def __init__(self, core: _ClientCore) -> None:
25        self._core = core
async def list( self, *, ids: Optional[List[int]] = None, name_contains: str | None = None, name_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False, full_perms: bool = False) -> easypaperless.PagedResult[DocumentType]:
27    async def list(
28        self,
29        *,
30        ids: List[int] | None = None,
31        name_contains: str | None = None,
32        name_exact: str | None = None,
33        page: int | None = None,
34        page_size: int | None = None,
35        ordering: str | None = None,
36        descending: bool = False,
37        full_perms: bool = False,
38    ) -> PagedResult[DocumentType]:
39        """Return document types defined in paperless-ngx.
40
41        When ``page`` is ``None`` (the default), all pages are fetched
42        automatically and ``next`` / ``previous`` in the result are always
43        ``None``.  When ``page`` is set, only that page is fetched and
44        ``next`` / ``previous`` reflect the raw API values.
45
46        Args:
47            ids: Return only document types whose ID is in this list.
48            name_contains: Case-insensitive substring filter on name.
49            name_exact: Case-insensitive exact match on name.
50            page: Return only this specific page (1-based).
51            page_size: Number of results per page.
52            ordering: Field to sort by.
53            descending: When ``True``, reverses the sort direction.
54            full_perms: When ``True``, paperless-ngx returns the full view/change
55                permissions of every object, available as
56                ``DocumentType.permissions``; ``user_can_change`` is then ``None``.
57                Default: ``False``.
58
59        Returns:
60            :class:`~easypaperless.models.paged_result.PagedResult` of
61            :class:`~easypaperless.models.document_types.DocumentType` objects.
62        """
63        logger.info("Listing document types")
64        params: dict[str, Any] = {}
65        if ids is not None:
66            params["id__in"] = ",".join(str(i) for i in ids)
67        if name_contains is not None:
68            params["name__icontains"] = name_contains
69        if name_exact is not None:
70            params["name__iexact"] = name_exact
71        if page is not None:
72            params["page"] = page
73        if page_size is not None:
74            params["page_size"] = page_size
75        if ordering is not None:
76            params["ordering"] = f"-{ordering}" if descending else ordering
77        return cast(
78            PagedResult[DocumentType],
79            await self._core._list_resource(
80                "document_types", DocumentType, params or None, full_perms=full_perms
81            ),
82        )

Return document types defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • ids: Return only document types whose ID is in this list.
  • name_contains: Case-insensitive substring filter on name.
  • name_exact: Case-insensitive exact match on name.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every object, available as DocumentType.permissions; user_can_change is then None. Default: False.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.document_types.DocumentType objects.

async def get( self, id: int, *, full_perms: bool = False) -> easypaperless.DocumentType:
 84    async def get(self, id: int, *, full_perms: bool = False) -> DocumentType:
 85        """Fetch a single document type by its ID.
 86
 87        Args:
 88            id: Numeric document-type ID.
 89            full_perms: When ``True``, paperless-ngx returns the full view/change
 90                permissions, available as ``DocumentType.permissions``;
 91                ``user_can_change`` is then ``None``. Default: ``False``.
 92
 93        Returns:
 94            The :class:`~easypaperless.models.document_types.DocumentType` with the given ID.
 95
 96        Raises:
 97            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
 98        """
 99        logger.info("Getting document type id=%d full_perms=%s", id, full_perms)
100        return cast(
101            DocumentType,
102            await self._core._get_resource(
103                "document_types", id, DocumentType, full_perms=full_perms
104            ),
105        )

Fetch a single document type by its ID.

Arguments:
  • id: Numeric document-type ID.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as DocumentType.permissions; user_can_change is then None. Default: False.
Returns:

The ~easypaperless.models.document_types.DocumentType with the given ID.

Raises:
async def create( self, *, name: str, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool = True, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.DocumentType:
107    async def create(
108        self,
109        *,
110        name: str,
111        match: str | Unset = UNSET,
112        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
113        is_insensitive: bool = True,
114        owner: int | None | Unset = UNSET,
115        set_permissions: SetPermissions | None | Unset = UNSET,
116    ) -> DocumentType:
117        """Create a new document type.
118
119        Args:
120            name: Document-type name. Must be unique.
121            match: Auto-matching pattern.
122            matching_algorithm: Controls how ``match`` is applied.
123                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
124                regular-expression matching.
125            is_insensitive: When ``True``, ``match`` is case-insensitive.
126                Defaults to ``True``, matching the paperless-ngx API default.
127            owner: Numeric user ID to assign as owner.
128            set_permissions: Explicit view/change permission sets.
129                Pass ``None`` to create with empty permissions.
130
131        Returns:
132            The newly created :class:`~easypaperless.models.document_types.DocumentType`.
133        """
134        logger.info("Creating document type name=%r", name)
135        return cast(
136            DocumentType,
137            await self._core._create_resource(
138                "document_types",
139                DocumentType,
140                owner=owner,
141                set_permissions=set_permissions,
142                name=name,
143                match=match,
144                matching_algorithm=matching_algorithm,
145                is_insensitive=is_insensitive,
146            ),
147        )

Create a new document type.

Arguments:
  • name: Document-type name. Must be unique.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive. Defaults to True, matching the paperless-ngx API default.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.document_types.DocumentType.

async def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.DocumentType:
149    async def update(
150        self,
151        id: int,
152        *,
153        name: str | Unset = UNSET,
154        match: str | Unset = UNSET,
155        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
156        is_insensitive: bool | Unset = UNSET,
157        owner: int | None | Unset = UNSET,
158        set_permissions: SetPermissions | None | Unset = UNSET,
159    ) -> DocumentType:
160        """Partially update a document type (PATCH semantics).
161
162        Args:
163            id: Numeric ID of the document type to update.
164            name: Document-type name.
165            match: Auto-matching pattern.
166            matching_algorithm: Controls how ``match`` is applied.
167                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
168                regular-expression matching.
169            is_insensitive: When ``True``, ``match`` is case-insensitive.
170            owner: Numeric user ID to assign as owner.
171                Pass ``None`` to clear the owner.
172                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
173            set_permissions: Explicit view/change permission sets.
174                Pass ``None`` to clear all permissions (overwrite with empty).
175                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
176
177        Returns:
178            The updated :class:`~easypaperless.models.document_types.DocumentType`.
179        """
180        logger.info("Updating document type id=%d", id)
181        return cast(
182            DocumentType,
183            await self._core._update_resource(
184                "document_types",
185                id,
186                DocumentType,
187                name=name,
188                match=match,
189                matching_algorithm=matching_algorithm,
190                is_insensitive=is_insensitive,
191                owner=owner,
192                set_permissions=set_permissions,
193            ),
194        )

Partially update a document type (PATCH semantics).

Arguments:
  • id: Numeric ID of the document type to update.
  • name: Document-type name.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.document_types.DocumentType.

async def delete(self, id: int) -> None:
196    async def delete(self, id: int) -> None:
197        """Delete a document type.
198
199        Args:
200            id: Numeric ID of the document type to delete.
201
202        Raises:
203            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
204        """
205        logger.info("Deleting document type id=%d", id)
206        await self._core._delete_resource("document_types", id)

Delete a document type.

Arguments:
  • id: Numeric ID of the document type to delete.
Raises:
async def bulk_delete(self, ids: List[int]) -> None:
208    async def bulk_delete(self, ids: List[int]) -> None:
209        """Permanently delete multiple document types in a single request.
210
211        Args:
212            ids: List of document type IDs to delete.
213        """
214        logger.info("Bulk deleting %d document types", len(ids))
215        await self._core._bulk_edit_objects("document_types", ids, "delete")

Permanently delete multiple document types in a single request.

Arguments:
  • ids: List of document type IDs to delete.
async def bulk_set_permissions( self, ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
217    async def bulk_set_permissions(
218        self,
219        ids: List[int],
220        *,
221        set_permissions: SetPermissions | Unset = UNSET,
222        owner: int | None | Unset = UNSET,
223        merge: bool = False,
224    ) -> None:
225        """Set permissions and/or owner on multiple document types.
226
227        Args:
228            ids: List of document type IDs to modify.
229            set_permissions: Explicit view/change permission sets.
230                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
231            owner: Numeric user ID to assign as owner.
232                Pass ``None`` to clear the owner.
233                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
234            merge: When ``True``, new permissions are merged with existing ones.
235        """
236        logger.info("Bulk setting permissions on %d document types", len(ids))
237        params: dict[str, Any] = {"merge": merge}
238        if not isinstance(set_permissions, Unset):
239            params["permissions"] = set_permissions.model_dump()
240        if not isinstance(owner, Unset):
241            params["owner"] = owner
242        await self._core._bulk_edit_objects("document_types", ids, "set_permissions", **params)

Set permissions and/or owner on multiple document types.

Arguments:
  • ids: List of document type IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
class DocumentsResource:
  64class DocumentsResource:
  65    """Accessor for documents: ``client.documents``."""
  66
  67    def __init__(self, core: _ClientCore) -> None:
  68        self._core = core
  69        self.notes = NotesResource(core)
  70
  71    async def history(
  72        self,
  73        document_id: int,
  74        *,
  75        page: int | None = None,
  76        page_size: int | None = None,
  77    ) -> PagedResult[AuditLogEntry]:
  78        """Fetch the audit log for a document.
  79
  80        The paperless-ngx ``/api/documents/{id}/history/`` endpoint returns a
  81        plain JSON array rather than a paginated envelope.  This method wraps
  82        the response into a :class:`~easypaperless.models.paged_result.PagedResult`
  83        so callers always receive a consistent return type.
  84
  85        Args:
  86            document_id: Numeric ID of the document whose history to retrieve.
  87            page: Forwarded to the API as a query parameter when provided.
  88                Effect depends on the paperless-ngx version; the server may
  89                ignore this parameter.
  90            page_size: Forwarded to the API as a query parameter when provided.
  91
  92        Returns:
  93            :class:`~easypaperless.models.paged_result.PagedResult` of
  94            :class:`~easypaperless.models.documents.AuditLogEntry` objects,
  95            ordered by timestamp descending.
  96
  97        Raises:
  98            ~easypaperless.exceptions.NotFoundError: If no document exists
  99                with that ID.
 100        """
 101        logger.info("Fetching history for document id=%d", document_id)
 102        path = f"/documents/{document_id}/history/"
 103        params: dict[str, Any] = {}
 104        if page is not None:
 105            params["page"] = page
 106        if page_size is not None:
 107            params["page_size"] = page_size
 108
 109        resp = await self._core._session.get(path, params=params or None)
 110        data = resp.json()
 111
 112        if isinstance(data, list):
 113            entries = [AuditLogEntry.model_validate(item) for item in data]
 114            entry_ids: list[int] = [e.id for e in entries]
 115            return PagedResult(
 116                count=len(entries),
 117                next=None,
 118                previous=None,
 119                all=entry_ids if entry_ids else None,
 120                results=entries,
 121            )
 122
 123        # Forward-compatible: handle a paginated envelope if the API ever adds one.
 124        items: list[Any] = list(data.get("results", []))
 125        count: int = data.get("count", 0)
 126        all_ids: list[int] | None = data.get("all")
 127        return PagedResult(
 128            count=count,
 129            next=data.get("next"),
 130            previous=data.get("previous"),
 131            all=all_ids,
 132            results=[AuditLogEntry.model_validate(item) for item in items],
 133        )
 134
 135    @staticmethod
 136    def _format_date_value(value: date | datetime | str) -> str:
 137        if isinstance(value, datetime):
 138            return value.isoformat()
 139        if isinstance(value, date):
 140            return value.isoformat()
 141        return value
 142
 143    @staticmethod
 144    def _is_datetime(value: date | datetime | str) -> bool:
 145        if isinstance(value, datetime):
 146            return True
 147        if isinstance(value, str):
 148            return bool(_DATETIME_STR_RE.match(value))
 149        return False
 150
 151    async def get(
 152        self, id: int, *, include_metadata: bool = False, full_perms: bool = False
 153    ) -> Document:
 154        """Fetch a single document by its ID.
 155
 156        Args:
 157            id: Numeric paperless-ngx document ID.
 158            include_metadata: When ``True``, the extended file-level metadata
 159                is fetched concurrently and attached to the document.
 160                Default: ``False``.
 161            full_perms: When ``True``, paperless-ngx returns the full view/change
 162                permissions, available as ``Document.permissions``. paperless-ngx
 163                then omits ``user_can_change`` and ``is_shared_by_requester``
 164                (both ``None`` on the model). Default: ``False``.
 165
 166        Returns:
 167            The :class:`~easypaperless.models.documents.Document` with the
 168            given ID.
 169
 170        Raises:
 171            ~easypaperless.exceptions.NotFoundError: If no document exists
 172                with that ID.
 173        """
 174        logger.info("Getting document id=%d full_perms=%s", id, full_perms)
 175        params = self._core._with_full_perms(None, full_perms)
 176        if include_metadata:
 177            doc_resp, meta_resp = await asyncio.gather(
 178                self._core._session.get(f"/documents/{id}/", params=params),
 179                self._core._session.get(f"/documents/{id}/metadata/"),
 180            )
 181            data = doc_resp.json()
 182            data["metadata"] = meta_resp.json()
 183        else:
 184            resp = await self._core._session.get(f"/documents/{id}/", params=params)
 185            data = resp.json()
 186        return Document.model_validate(data)
 187
 188    async def get_metadata(self, id: int) -> DocumentMetadata:
 189        """Fetch the extended file-level metadata for a document.
 190
 191        Args:
 192            id: Numeric paperless-ngx document ID.
 193
 194        Returns:
 195            A :class:`~easypaperless.models.documents.DocumentMetadata` instance.
 196
 197        Raises:
 198            ~easypaperless.exceptions.NotFoundError: If no document exists
 199                with that ID.
 200        """
 201        logger.info("Getting metadata for document id=%d", id)
 202        resp = await self._core._session.get(f"/documents/{id}/metadata/")
 203        return DocumentMetadata.model_validate(resp.json())
 204
 205    async def list(
 206        self,
 207        *,
 208        search: str | None = None,
 209        search_mode: str = "title_or_content",
 210        ids: List[int] | None = None,
 211        tags: List[int | str] | None = None,
 212        any_tags: List[int | str] | None = None,
 213        exclude_tags: List[int | str] | None = None,
 214        correspondent: int | str | None | Unset = UNSET,
 215        any_correspondent: List[int | str] | None = None,
 216        exclude_correspondents: List[int | str] | None = None,
 217        document_type: int | str | None | Unset = UNSET,
 218        document_type_name_contains: str | None = None,
 219        document_type_name_exact: str | None = None,
 220        any_document_type: List[int | str] | None = None,
 221        exclude_document_types: List[int | str] | None = None,
 222        storage_path: int | str | None | Unset = UNSET,
 223        any_storage_paths: List[int | str] | None = None,
 224        exclude_storage_paths: List[int | str] | None = None,
 225        owner: int | None | Unset = UNSET,
 226        exclude_owners: List[int] | None = None,
 227        custom_fields: List[int | str] | None = None,
 228        any_custom_fields: List[int | str] | None = None,
 229        exclude_custom_fields: List[int | str] | None = None,
 230        custom_field_query: List[Any] | None = None,
 231        archive_serial_number: int | None | Unset = UNSET,
 232        archive_serial_number_from: int | None = None,
 233        archive_serial_number_till: int | None = None,
 234        created_after: date | str | None = None,
 235        created_before: date | str | None = None,
 236        added_after: date | datetime | str | None = None,
 237        added_from: date | datetime | str | None = None,
 238        added_before: date | datetime | str | None = None,
 239        added_until: date | datetime | str | None = None,
 240        modified_after: date | datetime | str | None = None,
 241        modified_from: date | datetime | str | None = None,
 242        modified_before: date | datetime | str | None = None,
 243        modified_until: date | datetime | str | None = None,
 244        checksum: str | None = None,
 245        full_perms: bool = False,
 246        page_size: int = 25,
 247        page: int | None = None,
 248        ordering: str | None = None,
 249        descending: bool = False,
 250        max_results: int | None = None,
 251        on_page: Callable[[int, int | None], None] | None = None,
 252    ) -> PagedResult[Document]:
 253        """Return a filtered list of documents.
 254
 255        All tag, correspondent, document-type, storage-path, and custom-field
 256        parameters accept either integer IDs or string names.
 257
 258        When ``page`` is ``None`` (the default), all pages are fetched
 259        automatically and ``next`` / ``previous`` in the returned
 260        :class:`~easypaperless.models.paged_result.PagedResult` are always
 261        ``None`` — even if ``max_results`` truncates the final result set.
 262        ``count`` always reflects the server total, not the truncated length.
 263        When ``page`` is set to a specific integer, only that one page is
 264        fetched and ``next`` / ``previous`` contain the raw API values.
 265
 266        Args:
 267            search: Search string.  Behaviour depends on ``search_mode``.
 268            search_mode: How ``search`` is applied.  One of:
 269                ``"title_or_content"`` *(default)*, ``"title"``, ``"query"``,
 270                ``"original_filename"``.
 271            ids: Return only documents whose ID is in this list.
 272            tags: Documents must have **all** of these tags (AND semantics).
 273            any_tags: Documents must have **at least one** of these tags.
 274            exclude_tags: Documents must have **none** of these tags.
 275            correspondent: Filter to documents assigned to this correspondent.
 276                Pass ``None`` to return only documents with no correspondent set.
 277            any_correspondent: Filter to documents assigned to any of these.
 278            exclude_correspondents: Exclude documents assigned to any of these.
 279            document_type: Filter to documents of exactly this type.
 280                Pass ``None`` to return only documents with no document type set.
 281            document_type_name_contains: Case-insensitive substring filter on document type name.
 282            document_type_name_exact: Case-insensitive exact match on document type name.
 283            any_document_type: Filter to documents whose type is any of these.
 284            exclude_document_types: Exclude documents whose type is any of these.
 285            storage_path: Filter to documents assigned to this storage path.
 286                Pass ``None`` to return only documents with no storage path set.
 287            any_storage_paths: Filter to documents assigned to any of these paths.
 288            exclude_storage_paths: Exclude documents assigned to any of these paths.
 289            owner: Filter to documents owned by this user ID.
 290                Pass ``None`` to return only documents with no owner set.
 291            exclude_owners: Exclude documents owned by any of these user IDs.
 292            custom_fields: Documents must have **all** of these custom fields set.
 293            any_custom_fields: Documents must have **at least one** of these fields.
 294            exclude_custom_fields: Documents must have **none** of these fields.
 295            custom_field_query: Filter documents by custom field values using a nested
 296                query structure. See the `paperless-ngx API docs
 297                <https://docs.paperless-ngx.com/api/#filtering-by-custom-fields>`_ for
 298                the query format.
 299            archive_serial_number: Filter by exact archive serial number.
 300                Pass ``None`` to return only documents with no ASN set.
 301            archive_serial_number_from: Filter by ASN >= this value.
 302            archive_serial_number_till: Filter by ASN <= this value.
 303            created_after: Only documents created after this date.
 304                String input must be ISO-8601: ``"YYYY-MM-DD"``.
 305            created_before: Only documents created before this date.
 306                String input must be ISO-8601: ``"YYYY-MM-DD"``.
 307            added_after: Only documents added after this date/time.
 308                String input must be ISO-8601: ``"YYYY-MM-DD"`` for date precision or
 309                ``"YYYY-MM-DDTHH:MM:SS"`` for datetime precision.
 310            added_from: Only documents added on or after this date/time.
 311                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
 312            added_before: Only documents added before this date/time.
 313                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
 314            added_until: Only documents added on or before this date/time.
 315                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
 316            modified_after: Only documents modified after this date/time.
 317                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
 318            modified_from: Only documents modified on or after this date/time.
 319                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
 320            modified_before: Only documents modified before this date/time.
 321                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
 322            modified_until: Only documents modified on or before this date/time.
 323                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
 324            checksum: MD5 checksum (hex) of the original uploaded file, matched
 325                exactly but case-insensitively (sent as ``checksum__iexact``).
 326                Documents in the trash are **not** found, yet paperless-ngx
 327                still rejects a re-upload of the same file as a duplicate.  To
 328                detect that case, catch the
 329                :exc:`~easypaperless.exceptions.UploadError` of
 330                ``upload(wait=True)`` (or of ``tasks.wait()``): ``err.task.result``
 331                contains ``": It is a duplicate of "`` and ends in
 332                ``"Note: existing document is in the trash."``, and
 333                ``err.task.related_document`` is ``None`` (for a live duplicate
 334                it is the existing document's ID).  ``client.trash.list()``
 335                shows the trashed document; ``client.trash.restore()`` brings
 336                it back.
 337            full_perms: When ``True``, paperless-ngx returns the full view/change
 338                permissions of every document, available as
 339                ``Document.permissions``. paperless-ngx then omits
 340                ``user_can_change`` and ``is_shared_by_requester`` (both ``None``
 341                on the model). Default: ``False``.
 342            page_size: Number of results per API page.  Default: ``25``.
 343            page: Return only this specific page (1-based).
 344            ordering: Field name to sort by.
 345            descending: When ``True``, reverses the sort direction.
 346            max_results: Stop after collecting this many documents.
 347            on_page: Callback invoked after each page fetch.
 348
 349        Returns:
 350            :class:`~easypaperless.models.paged_result.PagedResult` of
 351            :class:`~easypaperless.models.documents.Document` objects.
 352        """
 353        logger.info("Listing documents")
 354        resolver = self._core._resolver
 355        params: dict[str, Any] = {"page_size": page_size}
 356
 357        if search is not None:
 358            api_param = _SEARCH_MODE_MAP.get(search_mode, "search")
 359            params[api_param] = search
 360
 361        if ids is not None:
 362            params["id__in"] = ",".join(str(i) for i in ids)
 363
 364        if tags is not None:
 365            resolved = await resolver.resolve_list("tags", tags)
 366            params["tags__id__all"] = ",".join(str(t) for t in resolved)
 367
 368        if any_tags is not None:
 369            resolved = await resolver.resolve_list("tags", any_tags)
 370            params["tags__id__in"] = ",".join(str(t) for t in resolved)
 371
 372        if exclude_tags is not None:
 373            resolved = await resolver.resolve_list("tags", exclude_tags)
 374            params["tags__id__none"] = ",".join(str(t) for t in resolved)
 375
 376        if any_correspondent is not None:
 377            resolved = await resolver.resolve_list("correspondents", any_correspondent)
 378            params["correspondent__id__in"] = ",".join(str(c) for c in resolved)
 379        elif not isinstance(correspondent, Unset):
 380            if correspondent is None:
 381                params["correspondent__isnull"] = "true"
 382            else:
 383                resolved_id = await resolver.resolve("correspondents", correspondent)
 384                params["correspondent__id"] = resolved_id
 385
 386        if exclude_correspondents is not None:
 387            resolved = await resolver.resolve_list("correspondents", exclude_correspondents)
 388            params["correspondent__id__none"] = ",".join(str(c) for c in resolved)
 389
 390        if document_type_name_contains is not None:
 391            params["document_type__name__icontains"] = document_type_name_contains
 392        if document_type_name_exact is not None:
 393            params["document_type__name__iexact"] = document_type_name_exact
 394
 395        if any_document_type is not None:
 396            resolved = await resolver.resolve_list("document_types", any_document_type)
 397            params["document_type__id__in"] = ",".join(str(d) for d in resolved)
 398        elif not isinstance(document_type, Unset):
 399            if document_type is None:
 400                params["document_type__isnull"] = "true"
 401            else:
 402                resolved_id = await resolver.resolve("document_types", document_type)
 403                params["document_type__id"] = resolved_id
 404
 405        if exclude_document_types is not None:
 406            resolved = await resolver.resolve_list("document_types", exclude_document_types)
 407            params["document_type__id__none"] = ",".join(str(d) for d in resolved)
 408
 409        if any_storage_paths is not None:
 410            resolved = await resolver.resolve_list("storage_paths", any_storage_paths)
 411            params["storage_path__id__in"] = ",".join(str(s) for s in resolved)
 412        elif not isinstance(storage_path, Unset):
 413            if storage_path is None:
 414                params["storage_path__isnull"] = "true"
 415            else:
 416                resolved_id = await resolver.resolve("storage_paths", storage_path)
 417                params["storage_path__id"] = resolved_id
 418
 419        if exclude_storage_paths is not None:
 420            resolved = await resolver.resolve_list("storage_paths", exclude_storage_paths)
 421            params["storage_path__id__none"] = ",".join(str(s) for s in resolved)
 422
 423        if not isinstance(owner, Unset):
 424            if owner is None:
 425                params["owner__isnull"] = "true"
 426            else:
 427                params["owner__id"] = owner
 428
 429        if exclude_owners is not None:
 430            params["owner__id__none"] = ",".join(str(o) for o in exclude_owners)
 431
 432        if custom_fields is not None:
 433            resolved = await resolver.resolve_list("custom_fields", custom_fields)
 434            params["custom_fields__id__all"] = ",".join(str(f) for f in resolved)
 435
 436        if any_custom_fields is not None:
 437            resolved = await resolver.resolve_list("custom_fields", any_custom_fields)
 438            params["custom_fields__id__in"] = ",".join(str(f) for f in resolved)
 439
 440        if exclude_custom_fields is not None:
 441            resolved = await resolver.resolve_list("custom_fields", exclude_custom_fields)
 442            params["custom_fields__id__none"] = ",".join(str(f) for f in resolved)
 443
 444        if custom_field_query is not None:
 445            params["custom_field_query"] = json.dumps(custom_field_query)
 446
 447        if not isinstance(archive_serial_number, Unset):
 448            if archive_serial_number is None:
 449                params["archive_serial_number__isnull"] = "true"
 450            else:
 451                params["archive_serial_number"] = archive_serial_number
 452
 453        if archive_serial_number_from is not None:
 454            params["archive_serial_number__gte"] = archive_serial_number_from
 455
 456        if archive_serial_number_till is not None:
 457            params["archive_serial_number__lte"] = archive_serial_number_till
 458
 459        if created_after is not None:
 460            params["created__date__gt"] = self._format_date_value(created_after)
 461
 462        if created_before is not None:
 463            params["created__date__lt"] = self._format_date_value(created_before)
 464
 465        if added_after is not None:
 466            key = "added__gt" if self._is_datetime(added_after) else "added__date__gt"
 467            params[key] = self._format_date_value(added_after)
 468
 469        if added_from is not None:
 470            key = "added__gte" if self._is_datetime(added_from) else "added__date__gte"
 471            params[key] = self._format_date_value(added_from)
 472
 473        if added_before is not None:
 474            key = "added__lt" if self._is_datetime(added_before) else "added__date__lt"
 475            params[key] = self._format_date_value(added_before)
 476
 477        if added_until is not None:
 478            key = "added__lte" if self._is_datetime(added_until) else "added__date__lte"
 479            params[key] = self._format_date_value(added_until)
 480
 481        if modified_after is not None:
 482            key = "modified__gt" if self._is_datetime(modified_after) else "modified__date__gt"
 483            params[key] = self._format_date_value(modified_after)
 484
 485        if modified_from is not None:
 486            key = "modified__gte" if self._is_datetime(modified_from) else "modified__date__gte"
 487            params[key] = self._format_date_value(modified_from)
 488
 489        if modified_before is not None:
 490            key = "modified__lt" if self._is_datetime(modified_before) else "modified__date__lt"
 491            params[key] = self._format_date_value(modified_before)
 492
 493        if modified_until is not None:
 494            key = "modified__lte" if self._is_datetime(modified_until) else "modified__date__lte"
 495            params[key] = self._format_date_value(modified_until)
 496
 497        if checksum is not None:
 498            params["checksum__iexact"] = checksum
 499
 500        params = self._core._with_full_perms(params, full_perms) or {}
 501
 502        if ordering is not None:
 503            params["ordering"] = f"-{ordering}" if descending else ordering
 504
 505        if page is not None:
 506            params["page"] = page
 507            raw = await self._core._session.get_page("/documents/", params=params)
 508            items = raw.items
 509            if max_results is not None:
 510                items = items[:max_results]
 511            return PagedResult(
 512                count=raw.count,
 513                next=raw.next,
 514                previous=raw.previous,
 515                all=raw.all_ids,
 516                results=[Document.model_validate(item) for item in items],
 517            )
 518
 519        raw = await self._core._session.get_all_pages_paged(
 520            "/documents/", params, max_results=max_results, on_page=on_page
 521        )
 522        return PagedResult(
 523            count=raw.count,
 524            next=raw.next,
 525            previous=raw.previous,
 526            all=raw.all_ids,
 527            results=[Document.model_validate(item) for item in raw.items],
 528        )
 529
 530    async def update(
 531        self,
 532        id: int,
 533        *,
 534        title: str | Unset = UNSET,
 535        content: str | Unset = UNSET,
 536        created: date | str | None | Unset = UNSET,
 537        correspondent: int | str | None | Unset = UNSET,
 538        document_type: int | str | None | Unset = UNSET,
 539        storage_path: int | str | None | Unset = UNSET,
 540        tags: List[int | str] | None | Unset = UNSET,
 541        archive_serial_number: int | None | Unset = UNSET,
 542        custom_fields: List[dict[str, Any]] | None | Unset = UNSET,
 543        owner: int | None | Unset = UNSET,
 544        set_permissions: SetPermissions | None | Unset = UNSET,
 545        remove_inbox_tags: bool | None | Unset = UNSET,
 546    ) -> Document:
 547        """Partially update a document (PATCH semantics).
 548
 549        Args:
 550            id: Numeric ID of the document to update.
 551            title: New document title.
 552            content: OCR text content of the document.
 553            created: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``) or a
 554                :class:`~datetime.date` object.
 555            correspondent: Correspondent to assign, as an ID or name.
 556                Pass ``None`` to clear the correspondent.
 557            document_type: Document type to assign, as an ID or name.
 558                Pass ``None`` to clear the document type.
 559            storage_path: Storage path to assign, as an ID or name.
 560                Pass ``None`` to clear the storage path.
 561            tags: Full replacement list of tags (IDs or names).
 562            archive_serial_number: Archive serial number to assign.
 563                Pass ``None`` to clear the archive serial number.
 564            custom_fields: List of ``{"field": <field_id>, "value": ...}`` dicts.
 565            owner: Numeric user ID to assign as document owner.
 566                Pass ``None`` to clear the owner.
 567            set_permissions: Explicit view/change permission sets.
 568                Pass ``None`` to clear all permissions (overwrite with empty).
 569                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
 570                The given sets replace the document's current view and change
 571                users and groups.  Together with ``owner`` everything goes out
 572                in one PATCH, which paperless-ngx applies as a whole.
 573            remove_inbox_tags: When ``True``, removes all inbox tags from the document.
 574
 575        Returns:
 576            The updated :class:`~easypaperless.models.documents.Document`.
 577        """
 578        logger.info("Updating document id=%d", id)
 579        resolver = self._core._resolver
 580        payload: dict[str, Any] = {}
 581
 582        if not isinstance(title, Unset):
 583            payload["title"] = title
 584        if not isinstance(content, Unset):
 585            payload["content"] = content
 586        if not isinstance(created, Unset):
 587            payload["created"] = self._format_date_value(created) if created is not None else None
 588        if not isinstance(correspondent, Unset):
 589            payload["correspondent"] = (
 590                None
 591                if correspondent is None
 592                else await resolver.resolve("correspondents", correspondent)
 593            )
 594        if not isinstance(document_type, Unset):
 595            payload["document_type"] = (
 596                None
 597                if document_type is None
 598                else await resolver.resolve("document_types", document_type)
 599            )
 600        if not isinstance(storage_path, Unset):
 601            payload["storage_path"] = (
 602                None
 603                if storage_path is None
 604                else await resolver.resolve("storage_paths", storage_path)
 605            )
 606        if not isinstance(tags, Unset):
 607            payload["tags"] = await resolver.resolve_list("tags", tags or [])
 608        if not isinstance(archive_serial_number, Unset):
 609            payload["archive_serial_number"] = archive_serial_number
 610        if not isinstance(custom_fields, Unset):
 611            payload["custom_fields"] = custom_fields
 612        if not isinstance(owner, Unset):
 613            payload["owner"] = owner
 614        if not isinstance(set_permissions, Unset):
 615            payload["set_permissions"] = (
 616                SetPermissions().model_dump()
 617                if set_permissions is None
 618                else set_permissions.model_dump()
 619            )
 620        if not isinstance(remove_inbox_tags, Unset):
 621            payload["remove_inbox_tags"] = remove_inbox_tags
 622
 623        resp = await self._core._session.patch(f"/documents/{id}/", json=payload)
 624        return Document.model_validate(resp.json())
 625
 626    async def delete(self, id: int) -> None:
 627        """Permanently delete a document.
 628
 629        Args:
 630            id: Numeric ID of the document to delete.
 631
 632        Raises:
 633            ~easypaperless.exceptions.NotFoundError: If no document exists
 634                with that ID.
 635        """
 636        logger.info("Deleting document id=%d", id)
 637        await self._core._session.delete(f"/documents/{id}/")
 638
 639    async def download(self, id: int, *, original: bool = False) -> bytes:
 640        """Download the binary content of a document.
 641
 642        Args:
 643            id: Numeric ID of the document to download.
 644            original: If ``False`` *(default)*, returns the archived PDF
 645                (``GET /documents/{id}/download/``).
 646                If ``True``, returns the original uploaded file
 647                (``GET /documents/{id}/download/?original=true``).
 648
 649        Returns:
 650            Raw file bytes.
 651        """
 652        logger.info("Downloading document id=%d (original=%s)", id, original)
 653        path = f"/documents/{id}/download/"
 654        if original:
 655            path += "?original=true"
 656        resp = await self._core._session.get_download(path)
 657        return _binary_content(resp, "Download")
 658
 659    async def thumbnail(self, id: int) -> bytes:
 660        """Fetch the thumbnail image of a document.
 661
 662        Args:
 663            id: Numeric ID of the document whose thumbnail to retrieve.
 664
 665        Returns:
 666            Raw binary content of the thumbnail image.
 667
 668        Raises:
 669            ~easypaperless.exceptions.NotFoundError: If no document exists
 670                with that ID.
 671            ~easypaperless.exceptions.ServerResponseError: If the server returns an
 672                HTML page (e.g. an auth redirect) instead of the image.
 673        """
 674        logger.info("Fetching thumbnail for document id=%d", id)
 675        resp = await self._core._session.get_download(f"/documents/{id}/thumb/")
 676        return _binary_content(resp, "Thumbnail")
 677
 678    async def upload(
 679        self,
 680        file: str | Path | bytes,
 681        *,
 682        filename: str | None = None,
 683        content_type: str | None = None,
 684        request_timeout: float | None = None,
 685        title: str | Unset = UNSET,
 686        created: date | str | None = None,
 687        correspondent: int | str | None | Unset = UNSET,
 688        document_type: int | str | None | Unset = UNSET,
 689        storage_path: int | str | None | Unset = UNSET,
 690        tags: List[int | str] | None = None,
 691        archive_serial_number: int | None | Unset = UNSET,
 692        custom_fields: List[dict[str, Any]] | None = None,
 693        wait: bool = False,
 694        poll_interval: float | None = None,
 695        poll_timeout: float | None = None,
 696    ) -> str | Document:
 697        """Upload a document to paperless-ngx.
 698
 699        The upload request is never retried automatically, whatever the
 700        client's ``retry_attempts`` / ``tenacity_retrying`` settings: if the
 701        connection fails after paperless-ngx has accepted the file, a retry
 702        would create a duplicate.  A failed upload raises (e.g.
 703        :exc:`~easypaperless.exceptions.TransportTimeoutError`) so you can
 704        decide whether to check for the document and upload again.
 705
 706        Args:
 707            file: Path to the file to upload (``str`` or :class:`~pathlib.Path`),
 708                or the file content as ``bytes``.  Bytes are sent directly; no
 709                temporary file is written.
 710            filename: File name sent to paperless-ngx.  Required when *file* is
 711                ``bytes`` (omitting it raises
 712                :exc:`~easypaperless.exceptions.ValidationError` before any
 713                request).  For a path, overrides the name taken from the path.
 714            content_type: MIME type of the file part, sent as given (e.g.
 715                ``"application/pdf"``).  When omitted, it is guessed from the
 716                file name as before.  paperless-ngx detects the file type from
 717                the bytes and does not rely on this value to accept the file.
 718            request_timeout: HTTP timeout in seconds for the upload request
 719                only, overriding the client's ``timeout`` for this call.  Does
 720                not affect task polling (see ``poll_timeout``).  When omitted,
 721                the client's ``timeout`` applies.
 722            title: Title to assign to the document.
 723            created: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``) or a
 724                :class:`~datetime.date` object.
 725            correspondent: Correspondent to assign, as an ID or name.
 726            document_type: Document type to assign, as an ID or name.
 727            storage_path: Storage path to assign, as an ID or name.
 728            tags: Tags to assign, as IDs or names.
 729            archive_serial_number: Archive serial number to assign.
 730            custom_fields: List of ``{"field": <field_id>, "value": ...}`` dicts.
 731            wait: If ``False`` *(default)*, returns immediately with the task ID.
 732                If ``True``, polls until processing completes.
 733            poll_interval: Seconds between task-status checks while waiting for
 734                processing to complete (requires ``wait=True``). Overrides the
 735                client-level default. When omitted, falls back to the client-level
 736                ``poll_interval`` (``2.0`` s unless changed at construction).
 737            poll_timeout: Maximum seconds to wait before raising
 738                :exc:`~easypaperless.exceptions.TaskTimeoutError` (requires
 739                ``wait=True``). Overrides the client-level default. When omitted,
 740                falls back to the client-level ``poll_timeout`` (``60.0`` s unless
 741                changed at construction).
 742
 743        Returns:
 744            The Celery task ID string when ``wait=False``, or the fully
 745            processed :class:`~easypaperless.models.documents.Document`
 746            when ``wait=True``.
 747
 748        Raises:
 749            ~easypaperless.exceptions.ValidationError: If *file* is ``bytes``
 750                and no *filename* is given.
 751            ~easypaperless.exceptions.BadRequestError: If paperless-ngx rejects
 752                the file before processing starts, e.g. an unsupported file
 753                type or an empty file (``err.field_errors["document"]``).
 754            ~easypaperless.exceptions.UploadError: If processing fails;
 755                ``err.task`` holds the task with paperless-ngx's ``result``
 756                unaltered.  For a duplicate, ``err.task.result`` contains
 757                ``": It is a duplicate of "`` and ``err.task.related_document``
 758                is the existing document's ID (``None`` if that document is
 759                in the trash).
 760            ~easypaperless.exceptions.TaskTimeoutError: If timeout is exceeded;
 761                resume with ``client.tasks.wait(err.task_id)``.
 762        """
 763        resolver = self._core._resolver
 764        if isinstance(file, bytes):
 765            if not filename:
 766                raise ValidationError("filename is required when uploading from bytes")
 767            file_bytes = file
 768            upload_name = filename
 769        else:
 770            file_path = Path(file)
 771            file_bytes = file_path.read_bytes()
 772            upload_name = filename if filename is not None else file_path.name
 773        logger.info("Uploading %r (%d bytes)", upload_name, len(file_bytes))
 774
 775        data: dict[str, Any] = {}
 776        if not isinstance(title, Unset):
 777            data["title"] = title
 778        if created is not None:
 779            data["created"] = self._format_date_value(created)
 780        if not isinstance(correspondent, Unset) and correspondent is not None:
 781            data["correspondent"] = await resolver.resolve("correspondents", correspondent)
 782        if not isinstance(document_type, Unset) and document_type is not None:
 783            data["document_type"] = await resolver.resolve("document_types", document_type)
 784        if not isinstance(storage_path, Unset) and storage_path is not None:
 785            data["storage_path"] = await resolver.resolve("storage_paths", storage_path)
 786        if tags is not None:
 787            resolved = await resolver.resolve_list("tags", tags)
 788            data["tags"] = resolved
 789        if not isinstance(archive_serial_number, Unset) and archive_serial_number is not None:
 790            data["archive_serial_number"] = archive_serial_number
 791        if custom_fields is not None:
 792            data["custom_fields"] = json.dumps(custom_fields)
 793
 794        # Without content_type httpx derives it from the file name (previous behaviour).
 795        document_part: tuple[str, bytes] | tuple[str, bytes, str] = (
 796            (upload_name, file_bytes)
 797            if content_type is None
 798            else (upload_name, file_bytes, content_type)
 799        )
 800        files = {"document": document_part}
 801        resp = await self._core._session.post(
 802            "/documents/post_document/",
 803            data=data,
 804            files=files,
 805            timeout=request_timeout,
 806            retry=False,  # a retry after a lost response would upload a duplicate
 807        )
 808        task_id: str = resp.text.strip('"')
 809        logger.debug("Upload accepted, task_id=%r", task_id)
 810
 811        if not wait:
 812            return task_id
 813
 814        task = await self._core.tasks.wait(
 815            task_id, poll_interval=poll_interval, poll_timeout=poll_timeout
 816        )
 817        if task.related_document is None:
 818            raise UploadError(f"Task {task_id!r} succeeded but returned no document ID", task=task)
 819        doc_id = int(task.related_document)
 820        logger.info("Task %r produced document_id=%d", task_id, doc_id)
 821        return await self.get(doc_id)
 822
 823    # -------------------------------------------------------------------------
 824    # Document bulk operations
 825    # -------------------------------------------------------------------------
 826
 827    async def _bulk_edit(self, document_ids: List[int], method: str, **parameters: Any) -> None:
 828        """Execute a bulk-edit operation on a list of documents.
 829
 830        Args:
 831            document_ids: List of document IDs to operate on.
 832            method: Bulk-edit method name (e.g. ``"add_tag"``, ``"delete"``).
 833            **parameters: Additional keyword arguments forwarded to the API.
 834        """
 835        payload = {"documents": document_ids, "method": method, "parameters": parameters}
 836        await self._core._session.post("/documents/bulk_edit/", json=payload, timeout=120.0)
 837
 838    async def bulk_add_tag(self, document_ids: List[int], tag: int | str) -> None:
 839        """Add a tag to multiple documents in a single request.
 840
 841        Args:
 842            document_ids: List of document IDs to tag.
 843            tag: Tag to add, as an ID or name.
 844        """
 845        logger.info("Bulk adding tag %r to %d documents", tag, len(document_ids))
 846        tag_id = await self._core._resolver.resolve("tags", tag)
 847        await self._bulk_edit(document_ids, "add_tag", tag=tag_id)
 848
 849    async def bulk_remove_tag(self, document_ids: List[int], tag: int | str) -> None:
 850        """Remove a tag from multiple documents in a single request.
 851
 852        Args:
 853            document_ids: List of document IDs to un-tag.
 854            tag: Tag to remove, as an ID or name.
 855        """
 856        logger.info("Bulk removing tag %r from %d documents", tag, len(document_ids))
 857        tag_id = await self._core._resolver.resolve("tags", tag)
 858        await self._bulk_edit(document_ids, "remove_tag", tag=tag_id)
 859
 860    async def bulk_modify_tags(
 861        self,
 862        document_ids: List[int],
 863        *,
 864        add_tags: List[int | str] | None = None,
 865        remove_tags: List[int | str] | None = None,
 866    ) -> None:
 867        """Add and/or remove tags on multiple documents atomically.
 868
 869        Args:
 870            document_ids: List of document IDs to modify.
 871            add_tags: Tags to add, as IDs or names.
 872            remove_tags: Tags to remove, as IDs or names.
 873        """
 874        logger.info("Bulk modifying tags on %d documents", len(document_ids))
 875        resolver = self._core._resolver
 876        add_ids = await resolver.resolve_list("tags", add_tags or [])
 877        remove_ids = await resolver.resolve_list("tags", remove_tags or [])
 878        await self._bulk_edit(document_ids, "modify_tags", add_tags=add_ids, remove_tags=remove_ids)
 879
 880    async def bulk_delete(self, document_ids: List[int]) -> None:
 881        """Permanently delete multiple documents in a single request.
 882
 883        Args:
 884            document_ids: List of document IDs to delete.
 885        """
 886        logger.info("Bulk deleting %d documents", len(document_ids))
 887        await self._bulk_edit(document_ids, "delete")
 888
 889    async def bulk_set_correspondent(
 890        self, document_ids: List[int], correspondent: int | str | None
 891    ) -> None:
 892        """Assign a correspondent to multiple documents in a single request.
 893
 894        Args:
 895            document_ids: List of document IDs to modify.
 896            correspondent: Correspondent to assign, as an ID or name.
 897                Pass ``None`` to clear.
 898        """
 899        logger.info(
 900            "Bulk setting correspondent %r on %d documents", correspondent, len(document_ids)
 901        )
 902        cor_id: int | None = None
 903        if correspondent is not None:
 904            cor_id = await self._core._resolver.resolve("correspondents", correspondent)
 905        await self._bulk_edit(document_ids, "set_correspondent", correspondent=cor_id)
 906
 907    async def bulk_set_document_type(
 908        self, document_ids: List[int], document_type: int | str | None
 909    ) -> None:
 910        """Assign a document type to multiple documents in a single request.
 911
 912        Args:
 913            document_ids: List of document IDs to modify.
 914            document_type: Document type to assign, as an ID or name.
 915                Pass ``None`` to clear.
 916        """
 917        logger.info(
 918            "Bulk setting document type %r on %d documents", document_type, len(document_ids)
 919        )
 920        dt_id: int | None = None
 921        if document_type is not None:
 922            dt_id = await self._core._resolver.resolve("document_types", document_type)
 923        await self._bulk_edit(document_ids, "set_document_type", document_type=dt_id)
 924
 925    async def bulk_set_storage_path(
 926        self, document_ids: List[int], storage_path: int | str | None
 927    ) -> None:
 928        """Assign a storage path to multiple documents in a single request.
 929
 930        Args:
 931            document_ids: List of document IDs to modify.
 932            storage_path: Storage path to assign, as an ID or name.
 933                Pass ``None`` to clear.
 934        """
 935        logger.info("Bulk setting storage path %r on %d documents", storage_path, len(document_ids))
 936        sp_id: int | None = None
 937        if storage_path is not None:
 938            sp_id = await self._core._resolver.resolve("storage_paths", storage_path)
 939        await self._bulk_edit(document_ids, "set_storage_path", storage_path=sp_id)
 940
 941    async def bulk_modify_custom_fields(
 942        self,
 943        document_ids: List[int],
 944        *,
 945        add_fields: List[dict[str, Any]] | None = None,
 946        remove_fields: List[int] | None = None,
 947    ) -> None:
 948        """Add and/or remove custom field values on multiple documents.
 949
 950        Args:
 951            document_ids: List of document IDs to modify.
 952            add_fields: Custom-field value dicts to add.
 953            remove_fields: Custom-field IDs whose values should be removed.
 954        """
 955        logger.info("Bulk modifying custom fields on %d documents", len(document_ids))
 956        await self._bulk_edit(
 957            document_ids,
 958            "modify_custom_fields",
 959            add_custom_fields=add_fields or [],
 960            remove_custom_fields=remove_fields or [],
 961        )
 962
 963    async def bulk_set_permissions(
 964        self,
 965        document_ids: List[int],
 966        *,
 967        set_permissions: SetPermissions | Unset = UNSET,
 968        owner: int | None | Unset = UNSET,
 969        merge: bool = False,
 970    ) -> None:
 971        """Set permissions and/or owner on multiple documents.
 972
 973        Args:
 974            document_ids: List of document IDs to modify.
 975            set_permissions: Explicit view/change permission sets.
 976                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
 977            owner: Numeric user ID to assign as document owner.
 978                Pass ``None`` to clear the owner.
 979                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
 980            merge: When ``True``, new permissions are merged with existing ones.
 981        """
 982        logger.info("Bulk setting permissions on %d documents", len(document_ids))
 983        params: dict[str, Any] = {"merge": merge}
 984        if not isinstance(set_permissions, Unset):
 985            params["set_permissions"] = set_permissions.model_dump()
 986        if not isinstance(owner, Unset):
 987            params["owner"] = owner
 988        await self._bulk_edit(document_ids, "set_permissions", **params)
 989
 990    async def bulk_download(
 991        self,
 992        document_ids: List[int],
 993        *,
 994        content: Literal["archive", "originals", "both"] = "archive",
 995        compression: Literal["none", "deflated", "bzip2", "lzma"] = "none",
 996        follow_formatting: bool = False,
 997    ) -> bytes:
 998        """Download multiple documents as a single ZIP archive.
 999
1000        Args:
1001            document_ids: List of document IDs to include in the ZIP.
1002            content: File variant to include.  One of ``"archive"`` *(default)*,
1003                ``"originals"``, or ``"both"``.
1004            compression: ZIP compression algorithm.  One of ``"none"`` *(default)*,
1005                ``"deflated"``, ``"bzip2"``, or ``"lzma"``.
1006            follow_formatting: When ``True``, filenames inside the ZIP follow
1007                the storage path formatting configured in paperless-ngx.
1008                Default: ``False``.
1009
1010        Returns:
1011            Raw bytes of the ZIP archive.
1012        """
1013        logger.info(
1014            "Bulk downloading %d documents (content=%s, compression=%s)",
1015            len(document_ids),
1016            content,
1017            compression,
1018        )
1019        payload: dict[str, Any] = {
1020            "documents": document_ids,
1021            "content": content,
1022            "compression": compression,
1023            "follow_formatting": follow_formatting,
1024        }
1025        resp = await self._core._session.post("/documents/bulk_download/", json=payload)
1026        return resp.content

Accessor for documents: client.documents.

DocumentsResource(core: easypaperless.client._ClientCore)
67    def __init__(self, core: _ClientCore) -> None:
68        self._core = core
69        self.notes = NotesResource(core)
notes
async def history( self, document_id: int, *, page: int | None = None, page_size: int | None = None) -> easypaperless.PagedResult[AuditLogEntry]:
 71    async def history(
 72        self,
 73        document_id: int,
 74        *,
 75        page: int | None = None,
 76        page_size: int | None = None,
 77    ) -> PagedResult[AuditLogEntry]:
 78        """Fetch the audit log for a document.
 79
 80        The paperless-ngx ``/api/documents/{id}/history/`` endpoint returns a
 81        plain JSON array rather than a paginated envelope.  This method wraps
 82        the response into a :class:`~easypaperless.models.paged_result.PagedResult`
 83        so callers always receive a consistent return type.
 84
 85        Args:
 86            document_id: Numeric ID of the document whose history to retrieve.
 87            page: Forwarded to the API as a query parameter when provided.
 88                Effect depends on the paperless-ngx version; the server may
 89                ignore this parameter.
 90            page_size: Forwarded to the API as a query parameter when provided.
 91
 92        Returns:
 93            :class:`~easypaperless.models.paged_result.PagedResult` of
 94            :class:`~easypaperless.models.documents.AuditLogEntry` objects,
 95            ordered by timestamp descending.
 96
 97        Raises:
 98            ~easypaperless.exceptions.NotFoundError: If no document exists
 99                with that ID.
100        """
101        logger.info("Fetching history for document id=%d", document_id)
102        path = f"/documents/{document_id}/history/"
103        params: dict[str, Any] = {}
104        if page is not None:
105            params["page"] = page
106        if page_size is not None:
107            params["page_size"] = page_size
108
109        resp = await self._core._session.get(path, params=params or None)
110        data = resp.json()
111
112        if isinstance(data, list):
113            entries = [AuditLogEntry.model_validate(item) for item in data]
114            entry_ids: list[int] = [e.id for e in entries]
115            return PagedResult(
116                count=len(entries),
117                next=None,
118                previous=None,
119                all=entry_ids if entry_ids else None,
120                results=entries,
121            )
122
123        # Forward-compatible: handle a paginated envelope if the API ever adds one.
124        items: list[Any] = list(data.get("results", []))
125        count: int = data.get("count", 0)
126        all_ids: list[int] | None = data.get("all")
127        return PagedResult(
128            count=count,
129            next=data.get("next"),
130            previous=data.get("previous"),
131            all=all_ids,
132            results=[AuditLogEntry.model_validate(item) for item in items],
133        )

Fetch the audit log for a document.

The paperless-ngx /api/documents/{id}/history/ endpoint returns a plain JSON array rather than a paginated envelope. This method wraps the response into a ~easypaperless.models.paged_result.PagedResult so callers always receive a consistent return type.

Arguments:
  • document_id: Numeric ID of the document whose history to retrieve.
  • page: Forwarded to the API as a query parameter when provided. Effect depends on the paperless-ngx version; the server may ignore this parameter.
  • page_size: Forwarded to the API as a query parameter when provided.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.documents.AuditLogEntry objects, ordered by timestamp descending.

Raises:
async def get( self, id: int, *, include_metadata: bool = False, full_perms: bool = False) -> easypaperless.Document:
151    async def get(
152        self, id: int, *, include_metadata: bool = False, full_perms: bool = False
153    ) -> Document:
154        """Fetch a single document by its ID.
155
156        Args:
157            id: Numeric paperless-ngx document ID.
158            include_metadata: When ``True``, the extended file-level metadata
159                is fetched concurrently and attached to the document.
160                Default: ``False``.
161            full_perms: When ``True``, paperless-ngx returns the full view/change
162                permissions, available as ``Document.permissions``. paperless-ngx
163                then omits ``user_can_change`` and ``is_shared_by_requester``
164                (both ``None`` on the model). Default: ``False``.
165
166        Returns:
167            The :class:`~easypaperless.models.documents.Document` with the
168            given ID.
169
170        Raises:
171            ~easypaperless.exceptions.NotFoundError: If no document exists
172                with that ID.
173        """
174        logger.info("Getting document id=%d full_perms=%s", id, full_perms)
175        params = self._core._with_full_perms(None, full_perms)
176        if include_metadata:
177            doc_resp, meta_resp = await asyncio.gather(
178                self._core._session.get(f"/documents/{id}/", params=params),
179                self._core._session.get(f"/documents/{id}/metadata/"),
180            )
181            data = doc_resp.json()
182            data["metadata"] = meta_resp.json()
183        else:
184            resp = await self._core._session.get(f"/documents/{id}/", params=params)
185            data = resp.json()
186        return Document.model_validate(data)

Fetch a single document by its ID.

Arguments:
  • id: Numeric paperless-ngx document ID.
  • include_metadata: When True, the extended file-level metadata is fetched concurrently and attached to the document. Default: False.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as Document.permissions. paperless-ngx then omits user_can_change and is_shared_by_requester (both None on the model). Default: False.
Returns:

The ~easypaperless.models.documents.Document with the given ID.

Raises:
async def get_metadata(self, id: int) -> easypaperless.DocumentMetadata:
188    async def get_metadata(self, id: int) -> DocumentMetadata:
189        """Fetch the extended file-level metadata for a document.
190
191        Args:
192            id: Numeric paperless-ngx document ID.
193
194        Returns:
195            A :class:`~easypaperless.models.documents.DocumentMetadata` instance.
196
197        Raises:
198            ~easypaperless.exceptions.NotFoundError: If no document exists
199                with that ID.
200        """
201        logger.info("Getting metadata for document id=%d", id)
202        resp = await self._core._session.get(f"/documents/{id}/metadata/")
203        return DocumentMetadata.model_validate(resp.json())

Fetch the extended file-level metadata for a document.

Arguments:
  • id: Numeric paperless-ngx document ID.
Returns:

A ~easypaperless.models.documents.DocumentMetadata instance.

Raises:
async def list( self, *, search: str | None = None, search_mode: str = 'title_or_content', ids: Optional[List[int]] = None, tags: Optional[List[Union[str, int]]] = None, any_tags: Optional[List[Union[str, int]]] = None, exclude_tags: Optional[List[Union[str, int]]] = None, correspondent: int | str | None | easypaperless.Unset = UNSET, any_correspondent: Optional[List[Union[str, int]]] = None, exclude_correspondents: Optional[List[Union[str, int]]] = None, document_type: int | str | None | easypaperless.Unset = UNSET, document_type_name_contains: str | None = None, document_type_name_exact: str | None = None, any_document_type: Optional[List[Union[str, int]]] = None, exclude_document_types: Optional[List[Union[str, int]]] = None, storage_path: int | str | None | easypaperless.Unset = UNSET, any_storage_paths: Optional[List[Union[str, int]]] = None, exclude_storage_paths: Optional[List[Union[str, int]]] = None, owner: int | None | easypaperless.Unset = UNSET, exclude_owners: Optional[List[int]] = None, custom_fields: Optional[List[Union[str, int]]] = None, any_custom_fields: Optional[List[Union[str, int]]] = None, exclude_custom_fields: Optional[List[Union[str, int]]] = None, custom_field_query: Optional[List[Any]] = None, archive_serial_number: int | None | easypaperless.Unset = UNSET, archive_serial_number_from: int | None = None, archive_serial_number_till: int | None = None, created_after: datetime.date | str | None = None, created_before: datetime.date | str | None = None, added_after: datetime.date | datetime.datetime | str | None = None, added_from: datetime.date | datetime.datetime | str | None = None, added_before: datetime.date | datetime.datetime | str | None = None, added_until: datetime.date | datetime.datetime | str | None = None, modified_after: datetime.date | datetime.datetime | str | None = None, modified_from: datetime.date | datetime.datetime | str | None = None, modified_before: datetime.date | datetime.datetime | str | None = None, modified_until: datetime.date | datetime.datetime | str | None = None, checksum: str | None = None, full_perms: bool = False, page_size: int = 25, page: int | None = None, ordering: str | None = None, descending: bool = False, max_results: int | None = None, on_page: Callable[[int, int | None], None] | None = None) -> easypaperless.PagedResult[Document]:
205    async def list(
206        self,
207        *,
208        search: str | None = None,
209        search_mode: str = "title_or_content",
210        ids: List[int] | None = None,
211        tags: List[int | str] | None = None,
212        any_tags: List[int | str] | None = None,
213        exclude_tags: List[int | str] | None = None,
214        correspondent: int | str | None | Unset = UNSET,
215        any_correspondent: List[int | str] | None = None,
216        exclude_correspondents: List[int | str] | None = None,
217        document_type: int | str | None | Unset = UNSET,
218        document_type_name_contains: str | None = None,
219        document_type_name_exact: str | None = None,
220        any_document_type: List[int | str] | None = None,
221        exclude_document_types: List[int | str] | None = None,
222        storage_path: int | str | None | Unset = UNSET,
223        any_storage_paths: List[int | str] | None = None,
224        exclude_storage_paths: List[int | str] | None = None,
225        owner: int | None | Unset = UNSET,
226        exclude_owners: List[int] | None = None,
227        custom_fields: List[int | str] | None = None,
228        any_custom_fields: List[int | str] | None = None,
229        exclude_custom_fields: List[int | str] | None = None,
230        custom_field_query: List[Any] | None = None,
231        archive_serial_number: int | None | Unset = UNSET,
232        archive_serial_number_from: int | None = None,
233        archive_serial_number_till: int | None = None,
234        created_after: date | str | None = None,
235        created_before: date | str | None = None,
236        added_after: date | datetime | str | None = None,
237        added_from: date | datetime | str | None = None,
238        added_before: date | datetime | str | None = None,
239        added_until: date | datetime | str | None = None,
240        modified_after: date | datetime | str | None = None,
241        modified_from: date | datetime | str | None = None,
242        modified_before: date | datetime | str | None = None,
243        modified_until: date | datetime | str | None = None,
244        checksum: str | None = None,
245        full_perms: bool = False,
246        page_size: int = 25,
247        page: int | None = None,
248        ordering: str | None = None,
249        descending: bool = False,
250        max_results: int | None = None,
251        on_page: Callable[[int, int | None], None] | None = None,
252    ) -> PagedResult[Document]:
253        """Return a filtered list of documents.
254
255        All tag, correspondent, document-type, storage-path, and custom-field
256        parameters accept either integer IDs or string names.
257
258        When ``page`` is ``None`` (the default), all pages are fetched
259        automatically and ``next`` / ``previous`` in the returned
260        :class:`~easypaperless.models.paged_result.PagedResult` are always
261        ``None`` — even if ``max_results`` truncates the final result set.
262        ``count`` always reflects the server total, not the truncated length.
263        When ``page`` is set to a specific integer, only that one page is
264        fetched and ``next`` / ``previous`` contain the raw API values.
265
266        Args:
267            search: Search string.  Behaviour depends on ``search_mode``.
268            search_mode: How ``search`` is applied.  One of:
269                ``"title_or_content"`` *(default)*, ``"title"``, ``"query"``,
270                ``"original_filename"``.
271            ids: Return only documents whose ID is in this list.
272            tags: Documents must have **all** of these tags (AND semantics).
273            any_tags: Documents must have **at least one** of these tags.
274            exclude_tags: Documents must have **none** of these tags.
275            correspondent: Filter to documents assigned to this correspondent.
276                Pass ``None`` to return only documents with no correspondent set.
277            any_correspondent: Filter to documents assigned to any of these.
278            exclude_correspondents: Exclude documents assigned to any of these.
279            document_type: Filter to documents of exactly this type.
280                Pass ``None`` to return only documents with no document type set.
281            document_type_name_contains: Case-insensitive substring filter on document type name.
282            document_type_name_exact: Case-insensitive exact match on document type name.
283            any_document_type: Filter to documents whose type is any of these.
284            exclude_document_types: Exclude documents whose type is any of these.
285            storage_path: Filter to documents assigned to this storage path.
286                Pass ``None`` to return only documents with no storage path set.
287            any_storage_paths: Filter to documents assigned to any of these paths.
288            exclude_storage_paths: Exclude documents assigned to any of these paths.
289            owner: Filter to documents owned by this user ID.
290                Pass ``None`` to return only documents with no owner set.
291            exclude_owners: Exclude documents owned by any of these user IDs.
292            custom_fields: Documents must have **all** of these custom fields set.
293            any_custom_fields: Documents must have **at least one** of these fields.
294            exclude_custom_fields: Documents must have **none** of these fields.
295            custom_field_query: Filter documents by custom field values using a nested
296                query structure. See the `paperless-ngx API docs
297                <https://docs.paperless-ngx.com/api/#filtering-by-custom-fields>`_ for
298                the query format.
299            archive_serial_number: Filter by exact archive serial number.
300                Pass ``None`` to return only documents with no ASN set.
301            archive_serial_number_from: Filter by ASN >= this value.
302            archive_serial_number_till: Filter by ASN <= this value.
303            created_after: Only documents created after this date.
304                String input must be ISO-8601: ``"YYYY-MM-DD"``.
305            created_before: Only documents created before this date.
306                String input must be ISO-8601: ``"YYYY-MM-DD"``.
307            added_after: Only documents added after this date/time.
308                String input must be ISO-8601: ``"YYYY-MM-DD"`` for date precision or
309                ``"YYYY-MM-DDTHH:MM:SS"`` for datetime precision.
310            added_from: Only documents added on or after this date/time.
311                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
312            added_before: Only documents added before this date/time.
313                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
314            added_until: Only documents added on or before this date/time.
315                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
316            modified_after: Only documents modified after this date/time.
317                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
318            modified_from: Only documents modified on or after this date/time.
319                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
320            modified_before: Only documents modified before this date/time.
321                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
322            modified_until: Only documents modified on or before this date/time.
323                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
324            checksum: MD5 checksum (hex) of the original uploaded file, matched
325                exactly but case-insensitively (sent as ``checksum__iexact``).
326                Documents in the trash are **not** found, yet paperless-ngx
327                still rejects a re-upload of the same file as a duplicate.  To
328                detect that case, catch the
329                :exc:`~easypaperless.exceptions.UploadError` of
330                ``upload(wait=True)`` (or of ``tasks.wait()``): ``err.task.result``
331                contains ``": It is a duplicate of "`` and ends in
332                ``"Note: existing document is in the trash."``, and
333                ``err.task.related_document`` is ``None`` (for a live duplicate
334                it is the existing document's ID).  ``client.trash.list()``
335                shows the trashed document; ``client.trash.restore()`` brings
336                it back.
337            full_perms: When ``True``, paperless-ngx returns the full view/change
338                permissions of every document, available as
339                ``Document.permissions``. paperless-ngx then omits
340                ``user_can_change`` and ``is_shared_by_requester`` (both ``None``
341                on the model). Default: ``False``.
342            page_size: Number of results per API page.  Default: ``25``.
343            page: Return only this specific page (1-based).
344            ordering: Field name to sort by.
345            descending: When ``True``, reverses the sort direction.
346            max_results: Stop after collecting this many documents.
347            on_page: Callback invoked after each page fetch.
348
349        Returns:
350            :class:`~easypaperless.models.paged_result.PagedResult` of
351            :class:`~easypaperless.models.documents.Document` objects.
352        """
353        logger.info("Listing documents")
354        resolver = self._core._resolver
355        params: dict[str, Any] = {"page_size": page_size}
356
357        if search is not None:
358            api_param = _SEARCH_MODE_MAP.get(search_mode, "search")
359            params[api_param] = search
360
361        if ids is not None:
362            params["id__in"] = ",".join(str(i) for i in ids)
363
364        if tags is not None:
365            resolved = await resolver.resolve_list("tags", tags)
366            params["tags__id__all"] = ",".join(str(t) for t in resolved)
367
368        if any_tags is not None:
369            resolved = await resolver.resolve_list("tags", any_tags)
370            params["tags__id__in"] = ",".join(str(t) for t in resolved)
371
372        if exclude_tags is not None:
373            resolved = await resolver.resolve_list("tags", exclude_tags)
374            params["tags__id__none"] = ",".join(str(t) for t in resolved)
375
376        if any_correspondent is not None:
377            resolved = await resolver.resolve_list("correspondents", any_correspondent)
378            params["correspondent__id__in"] = ",".join(str(c) for c in resolved)
379        elif not isinstance(correspondent, Unset):
380            if correspondent is None:
381                params["correspondent__isnull"] = "true"
382            else:
383                resolved_id = await resolver.resolve("correspondents", correspondent)
384                params["correspondent__id"] = resolved_id
385
386        if exclude_correspondents is not None:
387            resolved = await resolver.resolve_list("correspondents", exclude_correspondents)
388            params["correspondent__id__none"] = ",".join(str(c) for c in resolved)
389
390        if document_type_name_contains is not None:
391            params["document_type__name__icontains"] = document_type_name_contains
392        if document_type_name_exact is not None:
393            params["document_type__name__iexact"] = document_type_name_exact
394
395        if any_document_type is not None:
396            resolved = await resolver.resolve_list("document_types", any_document_type)
397            params["document_type__id__in"] = ",".join(str(d) for d in resolved)
398        elif not isinstance(document_type, Unset):
399            if document_type is None:
400                params["document_type__isnull"] = "true"
401            else:
402                resolved_id = await resolver.resolve("document_types", document_type)
403                params["document_type__id"] = resolved_id
404
405        if exclude_document_types is not None:
406            resolved = await resolver.resolve_list("document_types", exclude_document_types)
407            params["document_type__id__none"] = ",".join(str(d) for d in resolved)
408
409        if any_storage_paths is not None:
410            resolved = await resolver.resolve_list("storage_paths", any_storage_paths)
411            params["storage_path__id__in"] = ",".join(str(s) for s in resolved)
412        elif not isinstance(storage_path, Unset):
413            if storage_path is None:
414                params["storage_path__isnull"] = "true"
415            else:
416                resolved_id = await resolver.resolve("storage_paths", storage_path)
417                params["storage_path__id"] = resolved_id
418
419        if exclude_storage_paths is not None:
420            resolved = await resolver.resolve_list("storage_paths", exclude_storage_paths)
421            params["storage_path__id__none"] = ",".join(str(s) for s in resolved)
422
423        if not isinstance(owner, Unset):
424            if owner is None:
425                params["owner__isnull"] = "true"
426            else:
427                params["owner__id"] = owner
428
429        if exclude_owners is not None:
430            params["owner__id__none"] = ",".join(str(o) for o in exclude_owners)
431
432        if custom_fields is not None:
433            resolved = await resolver.resolve_list("custom_fields", custom_fields)
434            params["custom_fields__id__all"] = ",".join(str(f) for f in resolved)
435
436        if any_custom_fields is not None:
437            resolved = await resolver.resolve_list("custom_fields", any_custom_fields)
438            params["custom_fields__id__in"] = ",".join(str(f) for f in resolved)
439
440        if exclude_custom_fields is not None:
441            resolved = await resolver.resolve_list("custom_fields", exclude_custom_fields)
442            params["custom_fields__id__none"] = ",".join(str(f) for f in resolved)
443
444        if custom_field_query is not None:
445            params["custom_field_query"] = json.dumps(custom_field_query)
446
447        if not isinstance(archive_serial_number, Unset):
448            if archive_serial_number is None:
449                params["archive_serial_number__isnull"] = "true"
450            else:
451                params["archive_serial_number"] = archive_serial_number
452
453        if archive_serial_number_from is not None:
454            params["archive_serial_number__gte"] = archive_serial_number_from
455
456        if archive_serial_number_till is not None:
457            params["archive_serial_number__lte"] = archive_serial_number_till
458
459        if created_after is not None:
460            params["created__date__gt"] = self._format_date_value(created_after)
461
462        if created_before is not None:
463            params["created__date__lt"] = self._format_date_value(created_before)
464
465        if added_after is not None:
466            key = "added__gt" if self._is_datetime(added_after) else "added__date__gt"
467            params[key] = self._format_date_value(added_after)
468
469        if added_from is not None:
470            key = "added__gte" if self._is_datetime(added_from) else "added__date__gte"
471            params[key] = self._format_date_value(added_from)
472
473        if added_before is not None:
474            key = "added__lt" if self._is_datetime(added_before) else "added__date__lt"
475            params[key] = self._format_date_value(added_before)
476
477        if added_until is not None:
478            key = "added__lte" if self._is_datetime(added_until) else "added__date__lte"
479            params[key] = self._format_date_value(added_until)
480
481        if modified_after is not None:
482            key = "modified__gt" if self._is_datetime(modified_after) else "modified__date__gt"
483            params[key] = self._format_date_value(modified_after)
484
485        if modified_from is not None:
486            key = "modified__gte" if self._is_datetime(modified_from) else "modified__date__gte"
487            params[key] = self._format_date_value(modified_from)
488
489        if modified_before is not None:
490            key = "modified__lt" if self._is_datetime(modified_before) else "modified__date__lt"
491            params[key] = self._format_date_value(modified_before)
492
493        if modified_until is not None:
494            key = "modified__lte" if self._is_datetime(modified_until) else "modified__date__lte"
495            params[key] = self._format_date_value(modified_until)
496
497        if checksum is not None:
498            params["checksum__iexact"] = checksum
499
500        params = self._core._with_full_perms(params, full_perms) or {}
501
502        if ordering is not None:
503            params["ordering"] = f"-{ordering}" if descending else ordering
504
505        if page is not None:
506            params["page"] = page
507            raw = await self._core._session.get_page("/documents/", params=params)
508            items = raw.items
509            if max_results is not None:
510                items = items[:max_results]
511            return PagedResult(
512                count=raw.count,
513                next=raw.next,
514                previous=raw.previous,
515                all=raw.all_ids,
516                results=[Document.model_validate(item) for item in items],
517            )
518
519        raw = await self._core._session.get_all_pages_paged(
520            "/documents/", params, max_results=max_results, on_page=on_page
521        )
522        return PagedResult(
523            count=raw.count,
524            next=raw.next,
525            previous=raw.previous,
526            all=raw.all_ids,
527            results=[Document.model_validate(item) for item in raw.items],
528        )

Return a filtered list of documents.

All tag, correspondent, document-type, storage-path, and custom-field parameters accept either integer IDs or string names.

When page is None (the default), all pages are fetched automatically and next / previous in the returned ~easypaperless.models.paged_result.PagedResult are always None — even if max_results truncates the final result set. count always reflects the server total, not the truncated length. When page is set to a specific integer, only that one page is fetched and next / previous contain the raw API values.

Arguments:
  • search: Search string. Behaviour depends on search_mode.
  • search_mode: How search is applied. One of: "title_or_content" (default), "title", "query", "original_filename".
  • ids: Return only documents whose ID is in this list.
  • tags: Documents must have all of these tags (AND semantics).
  • any_tags: Documents must have at least one of these tags.
  • exclude_tags: Documents must have none of these tags.
  • correspondent: Filter to documents assigned to this correspondent. Pass None to return only documents with no correspondent set.
  • any_correspondent: Filter to documents assigned to any of these.
  • exclude_correspondents: Exclude documents assigned to any of these.
  • document_type: Filter to documents of exactly this type. Pass None to return only documents with no document type set.
  • document_type_name_contains: Case-insensitive substring filter on document type name.
  • document_type_name_exact: Case-insensitive exact match on document type name.
  • any_document_type: Filter to documents whose type is any of these.
  • exclude_document_types: Exclude documents whose type is any of these.
  • storage_path: Filter to documents assigned to this storage path. Pass None to return only documents with no storage path set.
  • any_storage_paths: Filter to documents assigned to any of these paths.
  • exclude_storage_paths: Exclude documents assigned to any of these paths.
  • owner: Filter to documents owned by this user ID. Pass None to return only documents with no owner set.
  • exclude_owners: Exclude documents owned by any of these user IDs.
  • custom_fields: Documents must have all of these custom fields set.
  • any_custom_fields: Documents must have at least one of these fields.
  • exclude_custom_fields: Documents must have none of these fields.
  • custom_field_query: Filter documents by custom field values using a nested query structure. See the paperless-ngx API docs for the query format.
  • archive_serial_number: Filter by exact archive serial number. Pass None to return only documents with no ASN set.
  • archive_serial_number_from: Filter by ASN >= this value.
  • archive_serial_number_till: Filter by ASN <= this value.
  • created_after: Only documents created after this date. String input must be ISO-8601: "YYYY-MM-DD".
  • created_before: Only documents created before this date. String input must be ISO-8601: "YYYY-MM-DD".
  • added_after: Only documents added after this date/time. String input must be ISO-8601: "YYYY-MM-DD" for date precision or "YYYY-MM-DDTHH:MM:SS" for datetime precision.
  • added_from: Only documents added on or after this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • added_before: Only documents added before this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • added_until: Only documents added on or before this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • modified_after: Only documents modified after this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • modified_from: Only documents modified on or after this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • modified_before: Only documents modified before this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • modified_until: Only documents modified on or before this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • checksum: MD5 checksum (hex) of the original uploaded file, matched exactly but case-insensitively (sent as checksum__iexact). Documents in the trash are not found, yet paperless-ngx still rejects a re-upload of the same file as a duplicate. To detect that case, catch the ~easypaperless.exceptions.UploadError of upload(wait=True) (or of tasks.wait()): err.task.result contains ": It is a duplicate of " and ends in "Note: existing document is in the trash.", and err.task.related_document is None (for a live duplicate it is the existing document's ID). client.trash.list() shows the trashed document; client.trash.restore() brings it back.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every document, available as Document.permissions. paperless-ngx then omits user_can_change and is_shared_by_requester (both None on the model). Default: False.
  • page_size: Number of results per API page. Default: 25.
  • page: Return only this specific page (1-based).
  • ordering: Field name to sort by.
  • descending: When True, reverses the sort direction.
  • max_results: Stop after collecting this many documents.
  • on_page: Callback invoked after each page fetch.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.documents.Document objects.

async def update( self, id: int, *, title: str | easypaperless.Unset = UNSET, content: str | easypaperless.Unset = UNSET, created: datetime.date | str | None | easypaperless.Unset = UNSET, correspondent: int | str | None | easypaperless.Unset = UNSET, document_type: int | str | None | easypaperless.Unset = UNSET, storage_path: int | str | None | easypaperless.Unset = UNSET, tags: Union[List[Union[str, int]], NoneType, easypaperless.Unset] = UNSET, archive_serial_number: int | None | easypaperless.Unset = UNSET, custom_fields: Union[List[dict[str, Any]], NoneType, easypaperless.Unset] = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET, remove_inbox_tags: bool | None | easypaperless.Unset = UNSET) -> easypaperless.Document:
530    async def update(
531        self,
532        id: int,
533        *,
534        title: str | Unset = UNSET,
535        content: str | Unset = UNSET,
536        created: date | str | None | Unset = UNSET,
537        correspondent: int | str | None | Unset = UNSET,
538        document_type: int | str | None | Unset = UNSET,
539        storage_path: int | str | None | Unset = UNSET,
540        tags: List[int | str] | None | Unset = UNSET,
541        archive_serial_number: int | None | Unset = UNSET,
542        custom_fields: List[dict[str, Any]] | None | Unset = UNSET,
543        owner: int | None | Unset = UNSET,
544        set_permissions: SetPermissions | None | Unset = UNSET,
545        remove_inbox_tags: bool | None | Unset = UNSET,
546    ) -> Document:
547        """Partially update a document (PATCH semantics).
548
549        Args:
550            id: Numeric ID of the document to update.
551            title: New document title.
552            content: OCR text content of the document.
553            created: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``) or a
554                :class:`~datetime.date` object.
555            correspondent: Correspondent to assign, as an ID or name.
556                Pass ``None`` to clear the correspondent.
557            document_type: Document type to assign, as an ID or name.
558                Pass ``None`` to clear the document type.
559            storage_path: Storage path to assign, as an ID or name.
560                Pass ``None`` to clear the storage path.
561            tags: Full replacement list of tags (IDs or names).
562            archive_serial_number: Archive serial number to assign.
563                Pass ``None`` to clear the archive serial number.
564            custom_fields: List of ``{"field": <field_id>, "value": ...}`` dicts.
565            owner: Numeric user ID to assign as document owner.
566                Pass ``None`` to clear the owner.
567            set_permissions: Explicit view/change permission sets.
568                Pass ``None`` to clear all permissions (overwrite with empty).
569                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
570                The given sets replace the document's current view and change
571                users and groups.  Together with ``owner`` everything goes out
572                in one PATCH, which paperless-ngx applies as a whole.
573            remove_inbox_tags: When ``True``, removes all inbox tags from the document.
574
575        Returns:
576            The updated :class:`~easypaperless.models.documents.Document`.
577        """
578        logger.info("Updating document id=%d", id)
579        resolver = self._core._resolver
580        payload: dict[str, Any] = {}
581
582        if not isinstance(title, Unset):
583            payload["title"] = title
584        if not isinstance(content, Unset):
585            payload["content"] = content
586        if not isinstance(created, Unset):
587            payload["created"] = self._format_date_value(created) if created is not None else None
588        if not isinstance(correspondent, Unset):
589            payload["correspondent"] = (
590                None
591                if correspondent is None
592                else await resolver.resolve("correspondents", correspondent)
593            )
594        if not isinstance(document_type, Unset):
595            payload["document_type"] = (
596                None
597                if document_type is None
598                else await resolver.resolve("document_types", document_type)
599            )
600        if not isinstance(storage_path, Unset):
601            payload["storage_path"] = (
602                None
603                if storage_path is None
604                else await resolver.resolve("storage_paths", storage_path)
605            )
606        if not isinstance(tags, Unset):
607            payload["tags"] = await resolver.resolve_list("tags", tags or [])
608        if not isinstance(archive_serial_number, Unset):
609            payload["archive_serial_number"] = archive_serial_number
610        if not isinstance(custom_fields, Unset):
611            payload["custom_fields"] = custom_fields
612        if not isinstance(owner, Unset):
613            payload["owner"] = owner
614        if not isinstance(set_permissions, Unset):
615            payload["set_permissions"] = (
616                SetPermissions().model_dump()
617                if set_permissions is None
618                else set_permissions.model_dump()
619            )
620        if not isinstance(remove_inbox_tags, Unset):
621            payload["remove_inbox_tags"] = remove_inbox_tags
622
623        resp = await self._core._session.patch(f"/documents/{id}/", json=payload)
624        return Document.model_validate(resp.json())

Partially update a document (PATCH semantics).

Arguments:
  • id: Numeric ID of the document to update.
  • title: New document title.
  • content: OCR text content of the document.
  • created: Creation date as an ISO-8601 string ("YYYY-MM-DD") or a ~datetime.date object.
  • correspondent: Correspondent to assign, as an ID or name. Pass None to clear the correspondent.
  • document_type: Document type to assign, as an ID or name. Pass None to clear the document type.
  • storage_path: Storage path to assign, as an ID or name. Pass None to clear the storage path.
  • tags: Full replacement list of tags (IDs or names).
  • archive_serial_number: Archive serial number to assign. Pass None to clear the archive serial number.
  • custom_fields: List of {"field": <field_id>, "value": ...} dicts.
  • owner: Numeric user ID to assign as document owner. Pass None to clear the owner.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged. The given sets replace the document's current view and change users and groups. Together with owner everything goes out in one PATCH, which paperless-ngx applies as a whole.
  • remove_inbox_tags: When True, removes all inbox tags from the document.
Returns:

The updated ~easypaperless.models.documents.Document.

async def delete(self, id: int) -> None:
626    async def delete(self, id: int) -> None:
627        """Permanently delete a document.
628
629        Args:
630            id: Numeric ID of the document to delete.
631
632        Raises:
633            ~easypaperless.exceptions.NotFoundError: If no document exists
634                with that ID.
635        """
636        logger.info("Deleting document id=%d", id)
637        await self._core._session.delete(f"/documents/{id}/")

Permanently delete a document.

Arguments:
  • id: Numeric ID of the document to delete.
Raises:
async def download(self, id: int, *, original: bool = False) -> bytes:
639    async def download(self, id: int, *, original: bool = False) -> bytes:
640        """Download the binary content of a document.
641
642        Args:
643            id: Numeric ID of the document to download.
644            original: If ``False`` *(default)*, returns the archived PDF
645                (``GET /documents/{id}/download/``).
646                If ``True``, returns the original uploaded file
647                (``GET /documents/{id}/download/?original=true``).
648
649        Returns:
650            Raw file bytes.
651        """
652        logger.info("Downloading document id=%d (original=%s)", id, original)
653        path = f"/documents/{id}/download/"
654        if original:
655            path += "?original=true"
656        resp = await self._core._session.get_download(path)
657        return _binary_content(resp, "Download")

Download the binary content of a document.

Arguments:
  • id: Numeric ID of the document to download.
  • original: If False (default), returns the archived PDF (GET /documents/{id}/download/). If True, returns the original uploaded file (GET /documents/{id}/download/?original=true).
Returns:

Raw file bytes.

async def thumbnail(self, id: int) -> bytes:
659    async def thumbnail(self, id: int) -> bytes:
660        """Fetch the thumbnail image of a document.
661
662        Args:
663            id: Numeric ID of the document whose thumbnail to retrieve.
664
665        Returns:
666            Raw binary content of the thumbnail image.
667
668        Raises:
669            ~easypaperless.exceptions.NotFoundError: If no document exists
670                with that ID.
671            ~easypaperless.exceptions.ServerResponseError: If the server returns an
672                HTML page (e.g. an auth redirect) instead of the image.
673        """
674        logger.info("Fetching thumbnail for document id=%d", id)
675        resp = await self._core._session.get_download(f"/documents/{id}/thumb/")
676        return _binary_content(resp, "Thumbnail")

Fetch the thumbnail image of a document.

Arguments:
  • id: Numeric ID of the document whose thumbnail to retrieve.
Returns:

Raw binary content of the thumbnail image.

Raises:
async def upload( self, file: str | pathlib._local.Path | bytes, *, filename: str | None = None, content_type: str | None = None, request_timeout: float | None = None, title: str | easypaperless.Unset = UNSET, created: datetime.date | str | None = None, correspondent: int | str | None | easypaperless.Unset = UNSET, document_type: int | str | None | easypaperless.Unset = UNSET, storage_path: int | str | None | easypaperless.Unset = UNSET, tags: Optional[List[Union[str, int]]] = None, archive_serial_number: int | None | easypaperless.Unset = UNSET, custom_fields: Optional[List[dict[str, Any]]] = None, wait: bool = False, poll_interval: float | None = None, poll_timeout: float | None = None) -> str | easypaperless.Document:
678    async def upload(
679        self,
680        file: str | Path | bytes,
681        *,
682        filename: str | None = None,
683        content_type: str | None = None,
684        request_timeout: float | None = None,
685        title: str | Unset = UNSET,
686        created: date | str | None = None,
687        correspondent: int | str | None | Unset = UNSET,
688        document_type: int | str | None | Unset = UNSET,
689        storage_path: int | str | None | Unset = UNSET,
690        tags: List[int | str] | None = None,
691        archive_serial_number: int | None | Unset = UNSET,
692        custom_fields: List[dict[str, Any]] | None = None,
693        wait: bool = False,
694        poll_interval: float | None = None,
695        poll_timeout: float | None = None,
696    ) -> str | Document:
697        """Upload a document to paperless-ngx.
698
699        The upload request is never retried automatically, whatever the
700        client's ``retry_attempts`` / ``tenacity_retrying`` settings: if the
701        connection fails after paperless-ngx has accepted the file, a retry
702        would create a duplicate.  A failed upload raises (e.g.
703        :exc:`~easypaperless.exceptions.TransportTimeoutError`) so you can
704        decide whether to check for the document and upload again.
705
706        Args:
707            file: Path to the file to upload (``str`` or :class:`~pathlib.Path`),
708                or the file content as ``bytes``.  Bytes are sent directly; no
709                temporary file is written.
710            filename: File name sent to paperless-ngx.  Required when *file* is
711                ``bytes`` (omitting it raises
712                :exc:`~easypaperless.exceptions.ValidationError` before any
713                request).  For a path, overrides the name taken from the path.
714            content_type: MIME type of the file part, sent as given (e.g.
715                ``"application/pdf"``).  When omitted, it is guessed from the
716                file name as before.  paperless-ngx detects the file type from
717                the bytes and does not rely on this value to accept the file.
718            request_timeout: HTTP timeout in seconds for the upload request
719                only, overriding the client's ``timeout`` for this call.  Does
720                not affect task polling (see ``poll_timeout``).  When omitted,
721                the client's ``timeout`` applies.
722            title: Title to assign to the document.
723            created: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``) or a
724                :class:`~datetime.date` object.
725            correspondent: Correspondent to assign, as an ID or name.
726            document_type: Document type to assign, as an ID or name.
727            storage_path: Storage path to assign, as an ID or name.
728            tags: Tags to assign, as IDs or names.
729            archive_serial_number: Archive serial number to assign.
730            custom_fields: List of ``{"field": <field_id>, "value": ...}`` dicts.
731            wait: If ``False`` *(default)*, returns immediately with the task ID.
732                If ``True``, polls until processing completes.
733            poll_interval: Seconds between task-status checks while waiting for
734                processing to complete (requires ``wait=True``). Overrides the
735                client-level default. When omitted, falls back to the client-level
736                ``poll_interval`` (``2.0`` s unless changed at construction).
737            poll_timeout: Maximum seconds to wait before raising
738                :exc:`~easypaperless.exceptions.TaskTimeoutError` (requires
739                ``wait=True``). Overrides the client-level default. When omitted,
740                falls back to the client-level ``poll_timeout`` (``60.0`` s unless
741                changed at construction).
742
743        Returns:
744            The Celery task ID string when ``wait=False``, or the fully
745            processed :class:`~easypaperless.models.documents.Document`
746            when ``wait=True``.
747
748        Raises:
749            ~easypaperless.exceptions.ValidationError: If *file* is ``bytes``
750                and no *filename* is given.
751            ~easypaperless.exceptions.BadRequestError: If paperless-ngx rejects
752                the file before processing starts, e.g. an unsupported file
753                type or an empty file (``err.field_errors["document"]``).
754            ~easypaperless.exceptions.UploadError: If processing fails;
755                ``err.task`` holds the task with paperless-ngx's ``result``
756                unaltered.  For a duplicate, ``err.task.result`` contains
757                ``": It is a duplicate of "`` and ``err.task.related_document``
758                is the existing document's ID (``None`` if that document is
759                in the trash).
760            ~easypaperless.exceptions.TaskTimeoutError: If timeout is exceeded;
761                resume with ``client.tasks.wait(err.task_id)``.
762        """
763        resolver = self._core._resolver
764        if isinstance(file, bytes):
765            if not filename:
766                raise ValidationError("filename is required when uploading from bytes")
767            file_bytes = file
768            upload_name = filename
769        else:
770            file_path = Path(file)
771            file_bytes = file_path.read_bytes()
772            upload_name = filename if filename is not None else file_path.name
773        logger.info("Uploading %r (%d bytes)", upload_name, len(file_bytes))
774
775        data: dict[str, Any] = {}
776        if not isinstance(title, Unset):
777            data["title"] = title
778        if created is not None:
779            data["created"] = self._format_date_value(created)
780        if not isinstance(correspondent, Unset) and correspondent is not None:
781            data["correspondent"] = await resolver.resolve("correspondents", correspondent)
782        if not isinstance(document_type, Unset) and document_type is not None:
783            data["document_type"] = await resolver.resolve("document_types", document_type)
784        if not isinstance(storage_path, Unset) and storage_path is not None:
785            data["storage_path"] = await resolver.resolve("storage_paths", storage_path)
786        if tags is not None:
787            resolved = await resolver.resolve_list("tags", tags)
788            data["tags"] = resolved
789        if not isinstance(archive_serial_number, Unset) and archive_serial_number is not None:
790            data["archive_serial_number"] = archive_serial_number
791        if custom_fields is not None:
792            data["custom_fields"] = json.dumps(custom_fields)
793
794        # Without content_type httpx derives it from the file name (previous behaviour).
795        document_part: tuple[str, bytes] | tuple[str, bytes, str] = (
796            (upload_name, file_bytes)
797            if content_type is None
798            else (upload_name, file_bytes, content_type)
799        )
800        files = {"document": document_part}
801        resp = await self._core._session.post(
802            "/documents/post_document/",
803            data=data,
804            files=files,
805            timeout=request_timeout,
806            retry=False,  # a retry after a lost response would upload a duplicate
807        )
808        task_id: str = resp.text.strip('"')
809        logger.debug("Upload accepted, task_id=%r", task_id)
810
811        if not wait:
812            return task_id
813
814        task = await self._core.tasks.wait(
815            task_id, poll_interval=poll_interval, poll_timeout=poll_timeout
816        )
817        if task.related_document is None:
818            raise UploadError(f"Task {task_id!r} succeeded but returned no document ID", task=task)
819        doc_id = int(task.related_document)
820        logger.info("Task %r produced document_id=%d", task_id, doc_id)
821        return await self.get(doc_id)

Upload a document to paperless-ngx.

The upload request is never retried automatically, whatever the client's retry_attempts / tenacity_retrying settings: if the connection fails after paperless-ngx has accepted the file, a retry would create a duplicate. A failed upload raises (e.g. ~easypaperless.exceptions.TransportTimeoutError) so you can decide whether to check for the document and upload again.

Arguments:
  • file: Path to the file to upload (str or ~pathlib.Path), or the file content as bytes. Bytes are sent directly; no temporary file is written.
  • filename: File name sent to paperless-ngx. Required when file is bytes (omitting it raises ~easypaperless.exceptions.ValidationError before any request). For a path, overrides the name taken from the path.
  • content_type: MIME type of the file part, sent as given (e.g. "application/pdf"). When omitted, it is guessed from the file name as before. paperless-ngx detects the file type from the bytes and does not rely on this value to accept the file.
  • request_timeout: HTTP timeout in seconds for the upload request only, overriding the client's timeout for this call. Does not affect task polling (see poll_timeout). When omitted, the client's timeout applies.
  • title: Title to assign to the document.
  • created: Creation date as an ISO-8601 string ("YYYY-MM-DD") or a ~datetime.date object.
  • correspondent: Correspondent to assign, as an ID or name.
  • document_type: Document type to assign, as an ID or name.
  • storage_path: Storage path to assign, as an ID or name.
  • tags: Tags to assign, as IDs or names.
  • archive_serial_number: Archive serial number to assign.
  • custom_fields: List of {"field": <field_id>, "value": ...} dicts.
  • wait: If False (default), returns immediately with the task ID. If True, polls until processing completes.
  • poll_interval: Seconds between task-status checks while waiting for processing to complete (requires wait=True). Overrides the client-level default. When omitted, falls back to the client-level poll_interval (2.0 s unless changed at construction).
  • poll_timeout: Maximum seconds to wait before raising ~easypaperless.exceptions.TaskTimeoutError (requires wait=True). Overrides the client-level default. When omitted, falls back to the client-level poll_timeout (60.0 s unless changed at construction).
Returns:

The Celery task ID string when wait=False, or the fully processed ~easypaperless.models.documents.Document when wait=True.

Raises:
async def bulk_add_tag(self, document_ids: List[int], tag: int | str) -> None:
838    async def bulk_add_tag(self, document_ids: List[int], tag: int | str) -> None:
839        """Add a tag to multiple documents in a single request.
840
841        Args:
842            document_ids: List of document IDs to tag.
843            tag: Tag to add, as an ID or name.
844        """
845        logger.info("Bulk adding tag %r to %d documents", tag, len(document_ids))
846        tag_id = await self._core._resolver.resolve("tags", tag)
847        await self._bulk_edit(document_ids, "add_tag", tag=tag_id)

Add a tag to multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to tag.
  • tag: Tag to add, as an ID or name.
async def bulk_remove_tag(self, document_ids: List[int], tag: int | str) -> None:
849    async def bulk_remove_tag(self, document_ids: List[int], tag: int | str) -> None:
850        """Remove a tag from multiple documents in a single request.
851
852        Args:
853            document_ids: List of document IDs to un-tag.
854            tag: Tag to remove, as an ID or name.
855        """
856        logger.info("Bulk removing tag %r from %d documents", tag, len(document_ids))
857        tag_id = await self._core._resolver.resolve("tags", tag)
858        await self._bulk_edit(document_ids, "remove_tag", tag=tag_id)

Remove a tag from multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to un-tag.
  • tag: Tag to remove, as an ID or name.
async def bulk_modify_tags( self, document_ids: List[int], *, add_tags: Optional[List[Union[str, int]]] = None, remove_tags: Optional[List[Union[str, int]]] = None) -> None:
860    async def bulk_modify_tags(
861        self,
862        document_ids: List[int],
863        *,
864        add_tags: List[int | str] | None = None,
865        remove_tags: List[int | str] | None = None,
866    ) -> None:
867        """Add and/or remove tags on multiple documents atomically.
868
869        Args:
870            document_ids: List of document IDs to modify.
871            add_tags: Tags to add, as IDs or names.
872            remove_tags: Tags to remove, as IDs or names.
873        """
874        logger.info("Bulk modifying tags on %d documents", len(document_ids))
875        resolver = self._core._resolver
876        add_ids = await resolver.resolve_list("tags", add_tags or [])
877        remove_ids = await resolver.resolve_list("tags", remove_tags or [])
878        await self._bulk_edit(document_ids, "modify_tags", add_tags=add_ids, remove_tags=remove_ids)

Add and/or remove tags on multiple documents atomically.

Arguments:
  • document_ids: List of document IDs to modify.
  • add_tags: Tags to add, as IDs or names.
  • remove_tags: Tags to remove, as IDs or names.
async def bulk_delete(self, document_ids: List[int]) -> None:
880    async def bulk_delete(self, document_ids: List[int]) -> None:
881        """Permanently delete multiple documents in a single request.
882
883        Args:
884            document_ids: List of document IDs to delete.
885        """
886        logger.info("Bulk deleting %d documents", len(document_ids))
887        await self._bulk_edit(document_ids, "delete")

Permanently delete multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to delete.
async def bulk_set_correspondent(self, document_ids: List[int], correspondent: int | str | None) -> None:
889    async def bulk_set_correspondent(
890        self, document_ids: List[int], correspondent: int | str | None
891    ) -> None:
892        """Assign a correspondent to multiple documents in a single request.
893
894        Args:
895            document_ids: List of document IDs to modify.
896            correspondent: Correspondent to assign, as an ID or name.
897                Pass ``None`` to clear.
898        """
899        logger.info(
900            "Bulk setting correspondent %r on %d documents", correspondent, len(document_ids)
901        )
902        cor_id: int | None = None
903        if correspondent is not None:
904            cor_id = await self._core._resolver.resolve("correspondents", correspondent)
905        await self._bulk_edit(document_ids, "set_correspondent", correspondent=cor_id)

Assign a correspondent to multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to modify.
  • correspondent: Correspondent to assign, as an ID or name. Pass None to clear.
async def bulk_set_document_type(self, document_ids: List[int], document_type: int | str | None) -> None:
907    async def bulk_set_document_type(
908        self, document_ids: List[int], document_type: int | str | None
909    ) -> None:
910        """Assign a document type to multiple documents in a single request.
911
912        Args:
913            document_ids: List of document IDs to modify.
914            document_type: Document type to assign, as an ID or name.
915                Pass ``None`` to clear.
916        """
917        logger.info(
918            "Bulk setting document type %r on %d documents", document_type, len(document_ids)
919        )
920        dt_id: int | None = None
921        if document_type is not None:
922            dt_id = await self._core._resolver.resolve("document_types", document_type)
923        await self._bulk_edit(document_ids, "set_document_type", document_type=dt_id)

Assign a document type to multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to modify.
  • document_type: Document type to assign, as an ID or name. Pass None to clear.
async def bulk_set_storage_path(self, document_ids: List[int], storage_path: int | str | None) -> None:
925    async def bulk_set_storage_path(
926        self, document_ids: List[int], storage_path: int | str | None
927    ) -> None:
928        """Assign a storage path to multiple documents in a single request.
929
930        Args:
931            document_ids: List of document IDs to modify.
932            storage_path: Storage path to assign, as an ID or name.
933                Pass ``None`` to clear.
934        """
935        logger.info("Bulk setting storage path %r on %d documents", storage_path, len(document_ids))
936        sp_id: int | None = None
937        if storage_path is not None:
938            sp_id = await self._core._resolver.resolve("storage_paths", storage_path)
939        await self._bulk_edit(document_ids, "set_storage_path", storage_path=sp_id)

Assign a storage path to multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to modify.
  • storage_path: Storage path to assign, as an ID or name. Pass None to clear.
async def bulk_modify_custom_fields( self, document_ids: List[int], *, add_fields: Optional[List[dict[str, Any]]] = None, remove_fields: Optional[List[int]] = None) -> None:
941    async def bulk_modify_custom_fields(
942        self,
943        document_ids: List[int],
944        *,
945        add_fields: List[dict[str, Any]] | None = None,
946        remove_fields: List[int] | None = None,
947    ) -> None:
948        """Add and/or remove custom field values on multiple documents.
949
950        Args:
951            document_ids: List of document IDs to modify.
952            add_fields: Custom-field value dicts to add.
953            remove_fields: Custom-field IDs whose values should be removed.
954        """
955        logger.info("Bulk modifying custom fields on %d documents", len(document_ids))
956        await self._bulk_edit(
957            document_ids,
958            "modify_custom_fields",
959            add_custom_fields=add_fields or [],
960            remove_custom_fields=remove_fields or [],
961        )

Add and/or remove custom field values on multiple documents.

Arguments:
  • document_ids: List of document IDs to modify.
  • add_fields: Custom-field value dicts to add.
  • remove_fields: Custom-field IDs whose values should be removed.
async def bulk_set_permissions( self, document_ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
963    async def bulk_set_permissions(
964        self,
965        document_ids: List[int],
966        *,
967        set_permissions: SetPermissions | Unset = UNSET,
968        owner: int | None | Unset = UNSET,
969        merge: bool = False,
970    ) -> None:
971        """Set permissions and/or owner on multiple documents.
972
973        Args:
974            document_ids: List of document IDs to modify.
975            set_permissions: Explicit view/change permission sets.
976                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
977            owner: Numeric user ID to assign as document owner.
978                Pass ``None`` to clear the owner.
979                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
980            merge: When ``True``, new permissions are merged with existing ones.
981        """
982        logger.info("Bulk setting permissions on %d documents", len(document_ids))
983        params: dict[str, Any] = {"merge": merge}
984        if not isinstance(set_permissions, Unset):
985            params["set_permissions"] = set_permissions.model_dump()
986        if not isinstance(owner, Unset):
987            params["owner"] = owner
988        await self._bulk_edit(document_ids, "set_permissions", **params)

Set permissions and/or owner on multiple documents.

Arguments:
  • document_ids: List of document IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as document owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
async def bulk_download( self, document_ids: List[int], *, content: Literal['archive', 'originals', 'both'] = 'archive', compression: Literal['none', 'deflated', 'bzip2', 'lzma'] = 'none', follow_formatting: bool = False) -> bytes:
 990    async def bulk_download(
 991        self,
 992        document_ids: List[int],
 993        *,
 994        content: Literal["archive", "originals", "both"] = "archive",
 995        compression: Literal["none", "deflated", "bzip2", "lzma"] = "none",
 996        follow_formatting: bool = False,
 997    ) -> bytes:
 998        """Download multiple documents as a single ZIP archive.
 999
1000        Args:
1001            document_ids: List of document IDs to include in the ZIP.
1002            content: File variant to include.  One of ``"archive"`` *(default)*,
1003                ``"originals"``, or ``"both"``.
1004            compression: ZIP compression algorithm.  One of ``"none"`` *(default)*,
1005                ``"deflated"``, ``"bzip2"``, or ``"lzma"``.
1006            follow_formatting: When ``True``, filenames inside the ZIP follow
1007                the storage path formatting configured in paperless-ngx.
1008                Default: ``False``.
1009
1010        Returns:
1011            Raw bytes of the ZIP archive.
1012        """
1013        logger.info(
1014            "Bulk downloading %d documents (content=%s, compression=%s)",
1015            len(document_ids),
1016            content,
1017            compression,
1018        )
1019        payload: dict[str, Any] = {
1020            "documents": document_ids,
1021            "content": content,
1022            "compression": compression,
1023            "follow_formatting": follow_formatting,
1024        }
1025        resp = await self._core._session.post("/documents/bulk_download/", json=payload)
1026        return resp.content

Download multiple documents as a single ZIP archive.

Arguments:
  • document_ids: List of document IDs to include in the ZIP.
  • content: File variant to include. One of "archive" (default), "originals", or "both".
  • compression: ZIP compression algorithm. One of "none" (default), "deflated", "bzip2", or "lzma".
  • follow_formatting: When True, filenames inside the ZIP follow the storage path formatting configured in paperless-ngx. Default: False.
Returns:

Raw bytes of the ZIP archive.

class NotesResource:
 26class NotesResource:
 27    """Accessor for document notes: ``client.documents.notes``."""
 28
 29    def __init__(self, core: _ClientCore) -> None:
 30        self._core = core
 31        # Token user's ID; ``None`` = not looked up yet or lookup failed.
 32        self._user_id: int | None = None
 33        self._user_lookup_done = False
 34
 35    async def list(
 36        self,
 37        document_id: int,
 38        *,
 39        page: int | None = None,
 40        page_size: int | None = None,
 41    ) -> PagedResult[DocumentNote]:
 42        """Fetch notes attached to a document.
 43
 44        When ``page`` is ``None`` (the default), all pages are fetched
 45        automatically and ``next`` / ``previous`` in the returned
 46        :class:`~easypaperless.models.paged_result.PagedResult` are always
 47        ``None``.  When ``page`` is set to a specific integer, only that one
 48        page is fetched and ``next`` / ``previous`` contain the raw API values.
 49
 50        Args:
 51            document_id: Numeric ID of the document whose notes to retrieve.
 52            page: Return only this specific page (1-based).
 53            page_size: Number of results per page.
 54
 55        Returns:
 56            :class:`~easypaperless.models.paged_result.PagedResult` of
 57            :class:`~easypaperless.models.documents.DocumentNote` objects,
 58            ordered by creation time.
 59
 60        Raises:
 61            ~easypaperless.exceptions.NotFoundError: If no document exists
 62                with that ID.
 63        """
 64        logger.info("Listing notes for document id=%d", document_id)
 65        path = f"/documents/{document_id}/notes/"
 66        params: dict[str, Any] = {}
 67        if page_size is not None:
 68            params["page_size"] = page_size
 69        if page is not None:
 70            params["page"] = page
 71
 72        raw = await self._core._session.get_list(
 73            path, params=params or None, all_pages=page is None
 74        )
 75        notes = [DocumentNote.model_validate(item) for item in raw.items]
 76        all_ids = raw.all_ids
 77        if not raw.paginated:
 78            # paperless-ngx answers with a plain JSON array: list the note IDs.
 79            all_ids = [n.id for n in notes if n.id is not None] or None
 80        return PagedResult(
 81            count=raw.count,
 82            next=raw.next,
 83            previous=raw.previous,
 84            all=all_ids,
 85            results=notes,
 86        )
 87
 88    async def create(self, document_id: int, *, note: str) -> DocumentNote:
 89        """Create a new note on a document.
 90
 91        paperless-ngx answers with the document's full note list, not with
 92        the new note alone.  The created note is picked from that list as the
 93        note whose text equals ``note``, so a note another user adds to the
 94        same document at the same moment is not returned by mistake.  Only if
 95        that text occurs more than once does the client look up the token's
 96        user once (``GET /api/ui_settings/``, cached per client) and keep only
 97        that user's notes; of the remaining notes the newest (highest ID) is
 98        returned.
 99
100        Telling identical texts of different users apart needs the
101        ``view_uisettings`` permission (or a superuser), because that lookup
102        uses ``/api/ui_settings/``.  Without it the lookup fails (403), the
103        failure is cached per client and logged as a warning, no error is
104        raised (the note already exists), and the newest note with that text
105        is returned, which may belong to another user.
106
107        Ambiguous case: if the token's user already has a note with the same
108        text on the document, or creates one concurrently, the notes cannot be
109        told apart and the newest one is returned.  It has the same text, user
110        and document; only ``id`` and ``created`` may differ from the note this
111        call created.  If no note in the response has the sent text (not
112        observed with paperless-ngx 2.18), the newest note is returned and a
113        warning is logged.
114
115        Args:
116            document_id: Numeric ID of the document to annotate.
117            note: Text content of the note.
118
119        Returns:
120            The newly created :class:`~easypaperless.models.documents.DocumentNote`.
121
122        Raises:
123            ~easypaperless.exceptions.NotFoundError: If no document exists
124                with that ID.
125            ~easypaperless.exceptions.ServerResponseError: If paperless-ngx
126                answers with an empty note list.
127        """
128        logger.info("Creating note for document id=%d", document_id)
129        resp = await self._core._session.post(
130            f"/documents/{document_id}/notes/",
131            json={"note": note},
132            retry=False,  # a retry after a lost response could add the note twice
133        )
134        data = resp.json()
135        if not isinstance(data, list):
136            return DocumentNote.model_validate(data)
137        notes = [DocumentNote.model_validate(item) for item in data]
138        if not notes:
139            raise ServerResponseError(
140                f"paperless-ngx returned no notes after creating a note on document {document_id}",
141                status_code=resp.status_code,
142            )
143        candidates = [n for n in notes if n.note == note]
144        if not candidates:
145            logger.warning(
146                "Created note not found in the response for document id=%d; "
147                "returning the newest note instead",
148                document_id,
149            )
150            candidates = notes
151        elif len(candidates) > 1:
152            user_id = await self._current_user_id()
153            if user_id is None:
154                logger.warning(
155                    "Several notes with the same text on document id=%d and the current "
156                    "user is unknown (needs view_uisettings); returning the newest one",
157                    document_id,
158                )
159            else:
160                candidates = [n for n in candidates if n.user == user_id] or candidates
161        return max(candidates, key=_note_sort_key)
162
163    async def _current_user_id(self) -> int | None:
164        """ID of the token's user, or ``None`` if the lookup failed (cached per client)."""
165        if not self._user_lookup_done:
166            self._user_lookup_done = True
167            try:
168                self._user_id = (await self._core._get_ui_settings()).user.id
169            except (PaperlessError, ValidationError) as exc:
170                # The note already exists; do not turn a failed lookup into an error.
171                logger.warning(
172                    "Could not look up the current user via /ui_settings/ "
173                    "(needs view_uisettings): %s",
174                    exc,
175                )
176        return self._user_id
177
178    async def delete(self, document_id: int, note_id: int) -> None:
179        """Delete a note from a document.
180
181        Args:
182            document_id: Numeric ID of the document that owns the note.
183            note_id: Numeric ID of the note to delete.
184
185        Raises:
186            ~easypaperless.exceptions.NotFoundError: If no document exists with
187                that ID.
188            ~easypaperless.exceptions.ServerResponseError: If the document has
189                no note with ``note_id``.  paperless-ngx answers an unknown note
190                ID with ``500 Server Error`` instead of 404 (verified against
191                paperless-ngx 2.18.2), so it cannot be told apart from a real
192                server error.  With ``retry_attempts`` set, the 500 is retried
193                like any other and ends in
194                :exc:`~easypaperless.exceptions.RetryExhaustedError`.  Use
195                ``notes.list(document_id)`` first if you need to be sure the
196                note exists.
197        """
198        logger.info("Deleting note id=%d from document id=%d", note_id, document_id)
199        await self._core._session.delete(f"/documents/{document_id}/notes/", params={"id": note_id})

Accessor for document notes: client.documents.notes.

NotesResource(core: easypaperless.client._ClientCore)
29    def __init__(self, core: _ClientCore) -> None:
30        self._core = core
31        # Token user's ID; ``None`` = not looked up yet or lookup failed.
32        self._user_id: int | None = None
33        self._user_lookup_done = False
async def list( self, document_id: int, *, page: int | None = None, page_size: int | None = None) -> easypaperless.PagedResult[DocumentNote]:
35    async def list(
36        self,
37        document_id: int,
38        *,
39        page: int | None = None,
40        page_size: int | None = None,
41    ) -> PagedResult[DocumentNote]:
42        """Fetch notes attached to a document.
43
44        When ``page`` is ``None`` (the default), all pages are fetched
45        automatically and ``next`` / ``previous`` in the returned
46        :class:`~easypaperless.models.paged_result.PagedResult` are always
47        ``None``.  When ``page`` is set to a specific integer, only that one
48        page is fetched and ``next`` / ``previous`` contain the raw API values.
49
50        Args:
51            document_id: Numeric ID of the document whose notes to retrieve.
52            page: Return only this specific page (1-based).
53            page_size: Number of results per page.
54
55        Returns:
56            :class:`~easypaperless.models.paged_result.PagedResult` of
57            :class:`~easypaperless.models.documents.DocumentNote` objects,
58            ordered by creation time.
59
60        Raises:
61            ~easypaperless.exceptions.NotFoundError: If no document exists
62                with that ID.
63        """
64        logger.info("Listing notes for document id=%d", document_id)
65        path = f"/documents/{document_id}/notes/"
66        params: dict[str, Any] = {}
67        if page_size is not None:
68            params["page_size"] = page_size
69        if page is not None:
70            params["page"] = page
71
72        raw = await self._core._session.get_list(
73            path, params=params or None, all_pages=page is None
74        )
75        notes = [DocumentNote.model_validate(item) for item in raw.items]
76        all_ids = raw.all_ids
77        if not raw.paginated:
78            # paperless-ngx answers with a plain JSON array: list the note IDs.
79            all_ids = [n.id for n in notes if n.id is not None] or None
80        return PagedResult(
81            count=raw.count,
82            next=raw.next,
83            previous=raw.previous,
84            all=all_ids,
85            results=notes,
86        )

Fetch notes attached to a document.

When page is None (the default), all pages are fetched automatically and next / previous in the returned ~easypaperless.models.paged_result.PagedResult are always None. When page is set to a specific integer, only that one page is fetched and next / previous contain the raw API values.

Arguments:
  • document_id: Numeric ID of the document whose notes to retrieve.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.documents.DocumentNote objects, ordered by creation time.

Raises:
async def create( self, document_id: int, *, note: str) -> easypaperless.DocumentNote:
 88    async def create(self, document_id: int, *, note: str) -> DocumentNote:
 89        """Create a new note on a document.
 90
 91        paperless-ngx answers with the document's full note list, not with
 92        the new note alone.  The created note is picked from that list as the
 93        note whose text equals ``note``, so a note another user adds to the
 94        same document at the same moment is not returned by mistake.  Only if
 95        that text occurs more than once does the client look up the token's
 96        user once (``GET /api/ui_settings/``, cached per client) and keep only
 97        that user's notes; of the remaining notes the newest (highest ID) is
 98        returned.
 99
100        Telling identical texts of different users apart needs the
101        ``view_uisettings`` permission (or a superuser), because that lookup
102        uses ``/api/ui_settings/``.  Without it the lookup fails (403), the
103        failure is cached per client and logged as a warning, no error is
104        raised (the note already exists), and the newest note with that text
105        is returned, which may belong to another user.
106
107        Ambiguous case: if the token's user already has a note with the same
108        text on the document, or creates one concurrently, the notes cannot be
109        told apart and the newest one is returned.  It has the same text, user
110        and document; only ``id`` and ``created`` may differ from the note this
111        call created.  If no note in the response has the sent text (not
112        observed with paperless-ngx 2.18), the newest note is returned and a
113        warning is logged.
114
115        Args:
116            document_id: Numeric ID of the document to annotate.
117            note: Text content of the note.
118
119        Returns:
120            The newly created :class:`~easypaperless.models.documents.DocumentNote`.
121
122        Raises:
123            ~easypaperless.exceptions.NotFoundError: If no document exists
124                with that ID.
125            ~easypaperless.exceptions.ServerResponseError: If paperless-ngx
126                answers with an empty note list.
127        """
128        logger.info("Creating note for document id=%d", document_id)
129        resp = await self._core._session.post(
130            f"/documents/{document_id}/notes/",
131            json={"note": note},
132            retry=False,  # a retry after a lost response could add the note twice
133        )
134        data = resp.json()
135        if not isinstance(data, list):
136            return DocumentNote.model_validate(data)
137        notes = [DocumentNote.model_validate(item) for item in data]
138        if not notes:
139            raise ServerResponseError(
140                f"paperless-ngx returned no notes after creating a note on document {document_id}",
141                status_code=resp.status_code,
142            )
143        candidates = [n for n in notes if n.note == note]
144        if not candidates:
145            logger.warning(
146                "Created note not found in the response for document id=%d; "
147                "returning the newest note instead",
148                document_id,
149            )
150            candidates = notes
151        elif len(candidates) > 1:
152            user_id = await self._current_user_id()
153            if user_id is None:
154                logger.warning(
155                    "Several notes with the same text on document id=%d and the current "
156                    "user is unknown (needs view_uisettings); returning the newest one",
157                    document_id,
158                )
159            else:
160                candidates = [n for n in candidates if n.user == user_id] or candidates
161        return max(candidates, key=_note_sort_key)

Create a new note on a document.

paperless-ngx answers with the document's full note list, not with the new note alone. The created note is picked from that list as the note whose text equals note, so a note another user adds to the same document at the same moment is not returned by mistake. Only if that text occurs more than once does the client look up the token's user once (GET /api/ui_settings/, cached per client) and keep only that user's notes; of the remaining notes the newest (highest ID) is returned.

Telling identical texts of different users apart needs the view_uisettings permission (or a superuser), because that lookup uses /api/ui_settings/. Without it the lookup fails (403), the failure is cached per client and logged as a warning, no error is raised (the note already exists), and the newest note with that text is returned, which may belong to another user.

Ambiguous case: if the token's user already has a note with the same text on the document, or creates one concurrently, the notes cannot be told apart and the newest one is returned. It has the same text, user and document; only id and created may differ from the note this call created. If no note in the response has the sent text (not observed with paperless-ngx 2.18), the newest note is returned and a warning is logged.

Arguments:
  • document_id: Numeric ID of the document to annotate.
  • note: Text content of the note.
Returns:

The newly created ~easypaperless.models.documents.DocumentNote.

Raises:
async def delete(self, document_id: int, note_id: int) -> None:
178    async def delete(self, document_id: int, note_id: int) -> None:
179        """Delete a note from a document.
180
181        Args:
182            document_id: Numeric ID of the document that owns the note.
183            note_id: Numeric ID of the note to delete.
184
185        Raises:
186            ~easypaperless.exceptions.NotFoundError: If no document exists with
187                that ID.
188            ~easypaperless.exceptions.ServerResponseError: If the document has
189                no note with ``note_id``.  paperless-ngx answers an unknown note
190                ID with ``500 Server Error`` instead of 404 (verified against
191                paperless-ngx 2.18.2), so it cannot be told apart from a real
192                server error.  With ``retry_attempts`` set, the 500 is retried
193                like any other and ends in
194                :exc:`~easypaperless.exceptions.RetryExhaustedError`.  Use
195                ``notes.list(document_id)`` first if you need to be sure the
196                note exists.
197        """
198        logger.info("Deleting note id=%d from document id=%d", note_id, document_id)
199        await self._core._session.delete(f"/documents/{document_id}/notes/", params={"id": note_id})

Delete a note from a document.

Arguments:
  • document_id: Numeric ID of the document that owns the note.
  • note_id: Numeric ID of the note to delete.
Raises:
class StoragePathsResource:
 21class StoragePathsResource:
 22    """Accessor for storage paths: ``client.storage_paths``."""
 23
 24    def __init__(self, core: _ClientCore) -> None:
 25        self._core = core
 26
 27    async def list(
 28        self,
 29        *,
 30        ids: List[int] | None = None,
 31        name_contains: str | None = None,
 32        name_exact: str | None = None,
 33        path_contains: str | None = None,
 34        path_exact: str | None = None,
 35        page: int | None = None,
 36        page_size: int | None = None,
 37        ordering: str | None = None,
 38        descending: bool = False,
 39        full_perms: bool = False,
 40    ) -> PagedResult[StoragePath]:
 41        """Return storage paths defined in paperless-ngx.
 42
 43        When ``page`` is ``None`` (the default), all pages are fetched
 44        automatically and ``next`` / ``previous`` in the result are always
 45        ``None``.  When ``page`` is set, only that page is fetched and
 46        ``next`` / ``previous`` reflect the raw API values.
 47
 48        Args:
 49            ids: Return only storage paths whose ID is in this list.
 50            name_contains: Case-insensitive substring filter on name.
 51            name_exact: Case-insensitive exact match on name.
 52            path_contains: Case-insensitive substring filter on path template.
 53            path_exact: Case-insensitive exact match on path template.
 54            page: Return only this specific page (1-based).
 55            page_size: Number of results per page.
 56            ordering: Field to sort by.
 57            descending: When ``True``, reverses the sort direction.
 58            full_perms: When ``True``, paperless-ngx returns the full view/change
 59                permissions of every object, available as
 60                ``StoragePath.permissions``; ``user_can_change`` is then ``None``.
 61                Default: ``False``.
 62
 63        Returns:
 64            :class:`~easypaperless.models.paged_result.PagedResult` of
 65            :class:`~easypaperless.models.storage_paths.StoragePath` objects.
 66        """
 67        logger.info("Listing storage paths")
 68        params: dict[str, Any] = {}
 69        if ids is not None:
 70            params["id__in"] = ",".join(str(i) for i in ids)
 71        if name_contains is not None:
 72            params["name__icontains"] = name_contains
 73        if name_exact is not None:
 74            params["name__iexact"] = name_exact
 75        if path_contains is not None:
 76            params["path__icontains"] = path_contains
 77        if path_exact is not None:
 78            params["path__iexact"] = path_exact
 79        if page is not None:
 80            params["page"] = page
 81        if page_size is not None:
 82            params["page_size"] = page_size
 83        if ordering is not None:
 84            params["ordering"] = f"-{ordering}" if descending else ordering
 85        return cast(
 86            PagedResult[StoragePath],
 87            await self._core._list_resource(
 88                "storage_paths", StoragePath, params or None, full_perms=full_perms
 89            ),
 90        )
 91
 92    async def get(self, id: int, *, full_perms: bool = False) -> StoragePath:
 93        """Fetch a single storage path by its ID.
 94
 95        Args:
 96            id: Numeric storage-path ID.
 97            full_perms: When ``True``, paperless-ngx returns the full view/change
 98                permissions, available as ``StoragePath.permissions``;
 99                ``user_can_change`` is then ``None``. Default: ``False``.
100
101        Returns:
102            The :class:`~easypaperless.models.storage_paths.StoragePath` with the given ID.
103
104        Raises:
105            ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
106        """
107        logger.info("Getting storage path id=%d full_perms=%s", id, full_perms)
108        return cast(
109            StoragePath,
110            await self._core._get_resource("storage_paths", id, StoragePath, full_perms=full_perms),
111        )
112
113    async def create(
114        self,
115        *,
116        name: str,
117        path: str | Unset = UNSET,
118        match: str | Unset = UNSET,
119        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
120        is_insensitive: bool = True,
121        owner: int | None | Unset = UNSET,
122        set_permissions: SetPermissions | None | Unset = UNSET,
123    ) -> StoragePath:
124        """Create a new storage path.
125
126        Args:
127            name: Storage-path name. Must be unique.
128            path: Template string for the archive file path.
129            match: Auto-matching pattern.
130            matching_algorithm: Controls how ``match`` is applied.
131                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
132                regular-expression matching.
133            is_insensitive: When ``True``, ``match`` is case-insensitive.
134                Defaults to ``True``, matching the paperless-ngx API default.
135            owner: Numeric user ID to assign as owner.
136            set_permissions: Explicit view/change permission sets.
137                Pass ``None`` to create with empty permissions.
138
139        Returns:
140            The newly created :class:`~easypaperless.models.storage_paths.StoragePath`.
141        """
142        logger.info("Creating storage path name=%r", name)
143        return cast(
144            StoragePath,
145            await self._core._create_resource(
146                "storage_paths",
147                StoragePath,
148                owner=owner,
149                set_permissions=set_permissions,
150                name=name,
151                path=path,
152                match=match,
153                matching_algorithm=matching_algorithm,
154                is_insensitive=is_insensitive,
155            ),
156        )
157
158    async def update(
159        self,
160        id: int,
161        *,
162        name: str | Unset = UNSET,
163        path: str | Unset = UNSET,
164        match: str | Unset = UNSET,
165        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
166        is_insensitive: bool | Unset = UNSET,
167        owner: int | None | Unset = UNSET,
168        set_permissions: SetPermissions | None | Unset = UNSET,
169    ) -> StoragePath:
170        """Partially update a storage path (PATCH semantics).
171
172        Args:
173            id: Numeric ID of the storage path to update.
174            name: Storage-path name.
175            path: Template string for the archive file path.
176            match: Auto-matching pattern.
177            matching_algorithm: Controls how ``match`` is applied.
178                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
179                regular-expression matching.
180            is_insensitive: When ``True``, ``match`` is case-insensitive.
181            owner: Numeric user ID to assign as owner.
182                Pass ``None`` to clear the owner.
183                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
184            set_permissions: Explicit view/change permission sets.
185                Pass ``None`` to clear all permissions (overwrite with empty).
186                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
187
188        Returns:
189            The updated :class:`~easypaperless.models.storage_paths.StoragePath`.
190        """
191        logger.info("Updating storage path id=%d", id)
192        return cast(
193            StoragePath,
194            await self._core._update_resource(
195                "storage_paths",
196                id,
197                StoragePath,
198                name=name,
199                path=path,
200                match=match,
201                matching_algorithm=matching_algorithm,
202                is_insensitive=is_insensitive,
203                owner=owner,
204                set_permissions=set_permissions,
205            ),
206        )
207
208    async def delete(self, id: int) -> None:
209        """Delete a storage path.
210
211        Args:
212            id: Numeric ID of the storage path to delete.
213
214        Raises:
215            ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
216        """
217        logger.info("Deleting storage path id=%d", id)
218        await self._core._delete_resource("storage_paths", id)
219
220    async def bulk_delete(self, ids: List[int]) -> None:
221        """Permanently delete multiple storage paths in a single request.
222
223        Args:
224            ids: List of storage path IDs to delete.
225        """
226        logger.info("Bulk deleting %d storage paths", len(ids))
227        await self._core._bulk_edit_objects("storage_paths", ids, "delete")
228
229    async def bulk_set_permissions(
230        self,
231        ids: List[int],
232        *,
233        set_permissions: SetPermissions | Unset = UNSET,
234        owner: int | None | Unset = UNSET,
235        merge: bool = False,
236    ) -> None:
237        """Set permissions and/or owner on multiple storage paths.
238
239        Args:
240            ids: List of storage path IDs to modify.
241            set_permissions: Explicit view/change permission sets.
242                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
243            owner: Numeric user ID to assign as owner.
244                Pass ``None`` to clear the owner.
245                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
246            merge: When ``True``, new permissions are merged with existing ones.
247        """
248        logger.info("Bulk setting permissions on %d storage paths", len(ids))
249        params: dict[str, Any] = {"merge": merge}
250        if not isinstance(set_permissions, Unset):
251            params["permissions"] = set_permissions.model_dump()
252        if not isinstance(owner, Unset):
253            params["owner"] = owner
254        await self._core._bulk_edit_objects("storage_paths", ids, "set_permissions", **params)

Accessor for storage paths: client.storage_paths.

StoragePathsResource(core: easypaperless.client._ClientCore)
24    def __init__(self, core: _ClientCore) -> None:
25        self._core = core
async def list( self, *, ids: Optional[List[int]] = None, name_contains: str | None = None, name_exact: str | None = None, path_contains: str | None = None, path_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False, full_perms: bool = False) -> easypaperless.PagedResult[StoragePath]:
27    async def list(
28        self,
29        *,
30        ids: List[int] | None = None,
31        name_contains: str | None = None,
32        name_exact: str | None = None,
33        path_contains: str | None = None,
34        path_exact: str | None = None,
35        page: int | None = None,
36        page_size: int | None = None,
37        ordering: str | None = None,
38        descending: bool = False,
39        full_perms: bool = False,
40    ) -> PagedResult[StoragePath]:
41        """Return storage paths defined in paperless-ngx.
42
43        When ``page`` is ``None`` (the default), all pages are fetched
44        automatically and ``next`` / ``previous`` in the result are always
45        ``None``.  When ``page`` is set, only that page is fetched and
46        ``next`` / ``previous`` reflect the raw API values.
47
48        Args:
49            ids: Return only storage paths whose ID is in this list.
50            name_contains: Case-insensitive substring filter on name.
51            name_exact: Case-insensitive exact match on name.
52            path_contains: Case-insensitive substring filter on path template.
53            path_exact: Case-insensitive exact match on path template.
54            page: Return only this specific page (1-based).
55            page_size: Number of results per page.
56            ordering: Field to sort by.
57            descending: When ``True``, reverses the sort direction.
58            full_perms: When ``True``, paperless-ngx returns the full view/change
59                permissions of every object, available as
60                ``StoragePath.permissions``; ``user_can_change`` is then ``None``.
61                Default: ``False``.
62
63        Returns:
64            :class:`~easypaperless.models.paged_result.PagedResult` of
65            :class:`~easypaperless.models.storage_paths.StoragePath` objects.
66        """
67        logger.info("Listing storage paths")
68        params: dict[str, Any] = {}
69        if ids is not None:
70            params["id__in"] = ",".join(str(i) for i in ids)
71        if name_contains is not None:
72            params["name__icontains"] = name_contains
73        if name_exact is not None:
74            params["name__iexact"] = name_exact
75        if path_contains is not None:
76            params["path__icontains"] = path_contains
77        if path_exact is not None:
78            params["path__iexact"] = path_exact
79        if page is not None:
80            params["page"] = page
81        if page_size is not None:
82            params["page_size"] = page_size
83        if ordering is not None:
84            params["ordering"] = f"-{ordering}" if descending else ordering
85        return cast(
86            PagedResult[StoragePath],
87            await self._core._list_resource(
88                "storage_paths", StoragePath, params or None, full_perms=full_perms
89            ),
90        )

Return storage paths defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • ids: Return only storage paths whose ID is in this list.
  • name_contains: Case-insensitive substring filter on name.
  • name_exact: Case-insensitive exact match on name.
  • path_contains: Case-insensitive substring filter on path template.
  • path_exact: Case-insensitive exact match on path template.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every object, available as StoragePath.permissions; user_can_change is then None. Default: False.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.storage_paths.StoragePath objects.

async def get( self, id: int, *, full_perms: bool = False) -> easypaperless.StoragePath:
 92    async def get(self, id: int, *, full_perms: bool = False) -> StoragePath:
 93        """Fetch a single storage path by its ID.
 94
 95        Args:
 96            id: Numeric storage-path ID.
 97            full_perms: When ``True``, paperless-ngx returns the full view/change
 98                permissions, available as ``StoragePath.permissions``;
 99                ``user_can_change`` is then ``None``. Default: ``False``.
100
101        Returns:
102            The :class:`~easypaperless.models.storage_paths.StoragePath` with the given ID.
103
104        Raises:
105            ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
106        """
107        logger.info("Getting storage path id=%d full_perms=%s", id, full_perms)
108        return cast(
109            StoragePath,
110            await self._core._get_resource("storage_paths", id, StoragePath, full_perms=full_perms),
111        )

Fetch a single storage path by its ID.

Arguments:
  • id: Numeric storage-path ID.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as StoragePath.permissions; user_can_change is then None. Default: False.
Returns:

The ~easypaperless.models.storage_paths.StoragePath with the given ID.

Raises:
async def create( self, *, name: str, path: str | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool = True, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.StoragePath:
113    async def create(
114        self,
115        *,
116        name: str,
117        path: str | Unset = UNSET,
118        match: str | Unset = UNSET,
119        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
120        is_insensitive: bool = True,
121        owner: int | None | Unset = UNSET,
122        set_permissions: SetPermissions | None | Unset = UNSET,
123    ) -> StoragePath:
124        """Create a new storage path.
125
126        Args:
127            name: Storage-path name. Must be unique.
128            path: Template string for the archive file path.
129            match: Auto-matching pattern.
130            matching_algorithm: Controls how ``match`` is applied.
131                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
132                regular-expression matching.
133            is_insensitive: When ``True``, ``match`` is case-insensitive.
134                Defaults to ``True``, matching the paperless-ngx API default.
135            owner: Numeric user ID to assign as owner.
136            set_permissions: Explicit view/change permission sets.
137                Pass ``None`` to create with empty permissions.
138
139        Returns:
140            The newly created :class:`~easypaperless.models.storage_paths.StoragePath`.
141        """
142        logger.info("Creating storage path name=%r", name)
143        return cast(
144            StoragePath,
145            await self._core._create_resource(
146                "storage_paths",
147                StoragePath,
148                owner=owner,
149                set_permissions=set_permissions,
150                name=name,
151                path=path,
152                match=match,
153                matching_algorithm=matching_algorithm,
154                is_insensitive=is_insensitive,
155            ),
156        )

Create a new storage path.

Arguments:
  • name: Storage-path name. Must be unique.
  • path: Template string for the archive file path.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive. Defaults to True, matching the paperless-ngx API default.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.storage_paths.StoragePath.

async def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, path: str | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.StoragePath:
158    async def update(
159        self,
160        id: int,
161        *,
162        name: str | Unset = UNSET,
163        path: str | Unset = UNSET,
164        match: str | Unset = UNSET,
165        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
166        is_insensitive: bool | Unset = UNSET,
167        owner: int | None | Unset = UNSET,
168        set_permissions: SetPermissions | None | Unset = UNSET,
169    ) -> StoragePath:
170        """Partially update a storage path (PATCH semantics).
171
172        Args:
173            id: Numeric ID of the storage path to update.
174            name: Storage-path name.
175            path: Template string for the archive file path.
176            match: Auto-matching pattern.
177            matching_algorithm: Controls how ``match`` is applied.
178                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
179                regular-expression matching.
180            is_insensitive: When ``True``, ``match`` is case-insensitive.
181            owner: Numeric user ID to assign as owner.
182                Pass ``None`` to clear the owner.
183                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
184            set_permissions: Explicit view/change permission sets.
185                Pass ``None`` to clear all permissions (overwrite with empty).
186                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
187
188        Returns:
189            The updated :class:`~easypaperless.models.storage_paths.StoragePath`.
190        """
191        logger.info("Updating storage path id=%d", id)
192        return cast(
193            StoragePath,
194            await self._core._update_resource(
195                "storage_paths",
196                id,
197                StoragePath,
198                name=name,
199                path=path,
200                match=match,
201                matching_algorithm=matching_algorithm,
202                is_insensitive=is_insensitive,
203                owner=owner,
204                set_permissions=set_permissions,
205            ),
206        )

Partially update a storage path (PATCH semantics).

Arguments:
  • id: Numeric ID of the storage path to update.
  • name: Storage-path name.
  • path: Template string for the archive file path.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.storage_paths.StoragePath.

async def delete(self, id: int) -> None:
208    async def delete(self, id: int) -> None:
209        """Delete a storage path.
210
211        Args:
212            id: Numeric ID of the storage path to delete.
213
214        Raises:
215            ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
216        """
217        logger.info("Deleting storage path id=%d", id)
218        await self._core._delete_resource("storage_paths", id)

Delete a storage path.

Arguments:
  • id: Numeric ID of the storage path to delete.
Raises:
async def bulk_delete(self, ids: List[int]) -> None:
220    async def bulk_delete(self, ids: List[int]) -> None:
221        """Permanently delete multiple storage paths in a single request.
222
223        Args:
224            ids: List of storage path IDs to delete.
225        """
226        logger.info("Bulk deleting %d storage paths", len(ids))
227        await self._core._bulk_edit_objects("storage_paths", ids, "delete")

Permanently delete multiple storage paths in a single request.

Arguments:
  • ids: List of storage path IDs to delete.
async def bulk_set_permissions( self, ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
229    async def bulk_set_permissions(
230        self,
231        ids: List[int],
232        *,
233        set_permissions: SetPermissions | Unset = UNSET,
234        owner: int | None | Unset = UNSET,
235        merge: bool = False,
236    ) -> None:
237        """Set permissions and/or owner on multiple storage paths.
238
239        Args:
240            ids: List of storage path IDs to modify.
241            set_permissions: Explicit view/change permission sets.
242                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
243            owner: Numeric user ID to assign as owner.
244                Pass ``None`` to clear the owner.
245                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
246            merge: When ``True``, new permissions are merged with existing ones.
247        """
248        logger.info("Bulk setting permissions on %d storage paths", len(ids))
249        params: dict[str, Any] = {"merge": merge}
250        if not isinstance(set_permissions, Unset):
251            params["permissions"] = set_permissions.model_dump()
252        if not isinstance(owner, Unset):
253            params["owner"] = owner
254        await self._core._bulk_edit_objects("storage_paths", ids, "set_permissions", **params)

Set permissions and/or owner on multiple storage paths.

Arguments:
  • ids: List of storage path IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
class TagsResource:
 21class TagsResource:
 22    """Accessor for tags: ``client.tags``."""
 23
 24    def __init__(self, core: _ClientCore) -> None:
 25        self._core = core
 26
 27    async def list(
 28        self,
 29        *,
 30        ids: List[int] | None = None,
 31        name_contains: str | None = None,
 32        name_exact: str | None = None,
 33        page: int | None = None,
 34        page_size: int | None = None,
 35        ordering: str | None = None,
 36        descending: bool = False,
 37        full_perms: bool = False,
 38    ) -> PagedResult[Tag]:
 39        """Return tags defined in paperless-ngx.
 40
 41        When ``page`` is ``None`` (the default), all pages are fetched
 42        automatically and ``next`` / ``previous`` in the result are always
 43        ``None``.  When ``page`` is set, only that page is fetched and
 44        ``next`` / ``previous`` reflect the raw API values.
 45
 46        Args:
 47            ids: Return only tags whose ID is in this list.
 48            name_contains: Case-insensitive substring filter on tag name.
 49            name_exact: Case-insensitive exact match on tag name.
 50            page: Return only this specific page (1-based).
 51            page_size: Number of results per page.
 52            ordering: Field to sort by.
 53            descending: When ``True``, reverses the sort direction.
 54            full_perms: When ``True``, paperless-ngx returns the full view/change
 55                permissions of every object, available as
 56                ``Tag.permissions``; ``user_can_change`` is then ``None``.
 57                Default: ``False``.
 58
 59        Returns:
 60            :class:`~easypaperless.models.paged_result.PagedResult` of
 61            :class:`~easypaperless.models.tags.Tag` objects.
 62        """
 63        logger.info("Listing tags")
 64        params: dict[str, Any] = {}
 65        if ids is not None:
 66            params["id__in"] = ",".join(str(i) for i in ids)
 67        if name_contains is not None:
 68            params["name__icontains"] = name_contains
 69        if name_exact is not None:
 70            params["name__iexact"] = name_exact
 71        if page is not None:
 72            params["page"] = page
 73        if page_size is not None:
 74            params["page_size"] = page_size
 75        if ordering is not None:
 76            params["ordering"] = f"-{ordering}" if descending else ordering
 77        return cast(
 78            PagedResult[Tag],
 79            await self._core._list_resource("tags", Tag, params or None, full_perms=full_perms),
 80        )
 81
 82    async def get(self, id: int, *, full_perms: bool = False) -> Tag:
 83        """Fetch a single tag by its ID.
 84
 85        Args:
 86            id: Numeric tag ID.
 87            full_perms: When ``True``, paperless-ngx returns the full view/change
 88                permissions, available as ``Tag.permissions``;
 89                ``user_can_change`` is then ``None``. Default: ``False``.
 90
 91        Returns:
 92            The :class:`~easypaperless.models.tags.Tag` with the given ID.
 93
 94        Raises:
 95            ~easypaperless.exceptions.NotFoundError: If no tag exists with
 96                that ID.
 97        """
 98        logger.info("Getting tag id=%d full_perms=%s", id, full_perms)
 99        return cast(Tag, await self._core._get_resource("tags", id, Tag, full_perms=full_perms))
100
101    async def create(
102        self,
103        *,
104        name: str,
105        color: str | Unset = UNSET,
106        is_inbox_tag: bool | Unset = UNSET,
107        match: str | Unset = UNSET,
108        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
109        is_insensitive: bool = True,
110        parent: int | None | Unset = UNSET,
111        owner: int | None | Unset = UNSET,
112        set_permissions: SetPermissions | None | Unset = UNSET,
113    ) -> Tag:
114        """Create a new tag.
115
116        Args:
117            name: Tag name. Must be unique.
118            color: Background colour as a CSS hex string.
119            is_inbox_tag: When ``True``, newly ingested documents get this tag.
120            match: Auto-matching pattern.
121            matching_algorithm: Controls how ``match`` is applied.
122                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
123                regular-expression matching.
124            is_insensitive: When ``True``, ``match`` is case-insensitive.
125                Defaults to ``True``, matching the paperless-ngx API default.
126            parent: ID of parent tag for hierarchical trees.
127            owner: Numeric user ID to assign as owner.
128            set_permissions: Explicit view/change permission sets.
129                Pass ``None`` to create with empty permissions.
130
131        Returns:
132            The newly created :class:`~easypaperless.models.tags.Tag`.
133        """
134        logger.info("Creating tag name=%r", name)
135        return cast(
136            Tag,
137            await self._core._create_resource(
138                "tags",
139                Tag,
140                owner=owner,
141                set_permissions=set_permissions,
142                name=name,
143                color=color,
144                is_inbox_tag=is_inbox_tag,
145                match=match,
146                matching_algorithm=matching_algorithm,
147                is_insensitive=is_insensitive,
148                parent=parent,
149            ),
150        )
151
152    async def update(
153        self,
154        id: int,
155        *,
156        name: str | Unset = UNSET,
157        color: str | Unset = UNSET,
158        is_inbox_tag: bool | Unset = UNSET,
159        match: str | Unset = UNSET,
160        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
161        is_insensitive: bool | Unset = UNSET,
162        parent: int | None | Unset = UNSET,
163        owner: int | None | Unset = UNSET,
164        set_permissions: SetPermissions | None | Unset = UNSET,
165    ) -> Tag:
166        """Partially update a tag (PATCH semantics).
167
168        Args:
169            id: Numeric ID of the tag to update.
170            name: Tag name.
171            color: Background colour as a CSS hex string.
172            is_inbox_tag: When ``True``, newly ingested documents get this tag.
173            match: Auto-matching pattern.
174            matching_algorithm: Controls how ``match`` is applied.
175                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
176                regular-expression matching.
177            is_insensitive: When ``True``, ``match`` is case-insensitive.
178            parent: ID of parent tag.
179                Pass ``None`` to clear (make root tag).
180                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
181            owner: Numeric user ID to assign as owner.
182                Pass ``None`` to clear the owner.
183                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
184            set_permissions: Explicit view/change permission sets.
185                Pass ``None`` to clear all permissions (overwrite with empty).
186                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
187
188        Returns:
189            The updated :class:`~easypaperless.models.tags.Tag`.
190        """
191        logger.info("Updating tag id=%d", id)
192        return cast(
193            Tag,
194            await self._core._update_resource(
195                "tags",
196                id,
197                Tag,
198                name=name,
199                color=color,
200                is_inbox_tag=is_inbox_tag,
201                match=match,
202                matching_algorithm=matching_algorithm,
203                is_insensitive=is_insensitive,
204                parent=parent,
205                owner=owner,
206                set_permissions=set_permissions,
207            ),
208        )
209
210    async def delete(self, id: int) -> None:
211        """Delete a tag.
212
213        Args:
214            id: Numeric ID of the tag to delete.
215
216        Raises:
217            ~easypaperless.exceptions.NotFoundError: If no tag exists with
218                that ID.
219        """
220        logger.info("Deleting tag id=%d", id)
221        await self._core._delete_resource("tags", id)
222
223    async def bulk_delete(self, ids: List[int]) -> None:
224        """Permanently delete multiple tags in a single request.
225
226        Args:
227            ids: List of tag IDs to delete.
228        """
229        logger.info("Bulk deleting %d tags", len(ids))
230        await self._core._bulk_edit_objects("tags", ids, "delete")
231
232    async def bulk_set_permissions(
233        self,
234        ids: List[int],
235        *,
236        set_permissions: SetPermissions | Unset = UNSET,
237        owner: int | None | Unset = UNSET,
238        merge: bool = False,
239    ) -> None:
240        """Set permissions and/or owner on multiple tags.
241
242        Args:
243            ids: List of tag IDs to modify.
244            set_permissions: Explicit view/change permission sets.
245                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
246            owner: Numeric user ID to assign as owner.
247                Pass ``None`` to clear the owner.
248                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
249            merge: When ``True``, new permissions are merged with existing ones.
250        """
251        logger.info("Bulk setting permissions on %d tags", len(ids))
252        params: dict[str, Any] = {"merge": merge}
253        if not isinstance(set_permissions, Unset):
254            params["permissions"] = set_permissions.model_dump()
255        if not isinstance(owner, Unset):
256            params["owner"] = owner
257        await self._core._bulk_edit_objects("tags", ids, "set_permissions", **params)

Accessor for tags: client.tags.

TagsResource(core: easypaperless.client._ClientCore)
24    def __init__(self, core: _ClientCore) -> None:
25        self._core = core
async def list( self, *, ids: Optional[List[int]] = None, name_contains: str | None = None, name_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False, full_perms: bool = False) -> easypaperless.PagedResult[Tag]:
27    async def list(
28        self,
29        *,
30        ids: List[int] | None = None,
31        name_contains: str | None = None,
32        name_exact: str | None = None,
33        page: int | None = None,
34        page_size: int | None = None,
35        ordering: str | None = None,
36        descending: bool = False,
37        full_perms: bool = False,
38    ) -> PagedResult[Tag]:
39        """Return tags defined in paperless-ngx.
40
41        When ``page`` is ``None`` (the default), all pages are fetched
42        automatically and ``next`` / ``previous`` in the result are always
43        ``None``.  When ``page`` is set, only that page is fetched and
44        ``next`` / ``previous`` reflect the raw API values.
45
46        Args:
47            ids: Return only tags whose ID is in this list.
48            name_contains: Case-insensitive substring filter on tag name.
49            name_exact: Case-insensitive exact match on tag name.
50            page: Return only this specific page (1-based).
51            page_size: Number of results per page.
52            ordering: Field to sort by.
53            descending: When ``True``, reverses the sort direction.
54            full_perms: When ``True``, paperless-ngx returns the full view/change
55                permissions of every object, available as
56                ``Tag.permissions``; ``user_can_change`` is then ``None``.
57                Default: ``False``.
58
59        Returns:
60            :class:`~easypaperless.models.paged_result.PagedResult` of
61            :class:`~easypaperless.models.tags.Tag` objects.
62        """
63        logger.info("Listing tags")
64        params: dict[str, Any] = {}
65        if ids is not None:
66            params["id__in"] = ",".join(str(i) for i in ids)
67        if name_contains is not None:
68            params["name__icontains"] = name_contains
69        if name_exact is not None:
70            params["name__iexact"] = name_exact
71        if page is not None:
72            params["page"] = page
73        if page_size is not None:
74            params["page_size"] = page_size
75        if ordering is not None:
76            params["ordering"] = f"-{ordering}" if descending else ordering
77        return cast(
78            PagedResult[Tag],
79            await self._core._list_resource("tags", Tag, params or None, full_perms=full_perms),
80        )

Return tags defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • ids: Return only tags whose ID is in this list.
  • name_contains: Case-insensitive substring filter on tag name.
  • name_exact: Case-insensitive exact match on tag name.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every object, available as Tag.permissions; user_can_change is then None. Default: False.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.tags.Tag objects.

async def get( self, id: int, *, full_perms: bool = False) -> easypaperless.Tag:
82    async def get(self, id: int, *, full_perms: bool = False) -> Tag:
83        """Fetch a single tag by its ID.
84
85        Args:
86            id: Numeric tag ID.
87            full_perms: When ``True``, paperless-ngx returns the full view/change
88                permissions, available as ``Tag.permissions``;
89                ``user_can_change`` is then ``None``. Default: ``False``.
90
91        Returns:
92            The :class:`~easypaperless.models.tags.Tag` with the given ID.
93
94        Raises:
95            ~easypaperless.exceptions.NotFoundError: If no tag exists with
96                that ID.
97        """
98        logger.info("Getting tag id=%d full_perms=%s", id, full_perms)
99        return cast(Tag, await self._core._get_resource("tags", id, Tag, full_perms=full_perms))

Fetch a single tag by its ID.

Arguments:
  • id: Numeric tag ID.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as Tag.permissions; user_can_change is then None. Default: False.
Returns:

The ~easypaperless.models.tags.Tag with the given ID.

Raises:
async def create( self, *, name: str, color: str | easypaperless.Unset = UNSET, is_inbox_tag: bool | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool = True, parent: int | None | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.Tag:
101    async def create(
102        self,
103        *,
104        name: str,
105        color: str | Unset = UNSET,
106        is_inbox_tag: bool | Unset = UNSET,
107        match: str | Unset = UNSET,
108        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
109        is_insensitive: bool = True,
110        parent: int | None | Unset = UNSET,
111        owner: int | None | Unset = UNSET,
112        set_permissions: SetPermissions | None | Unset = UNSET,
113    ) -> Tag:
114        """Create a new tag.
115
116        Args:
117            name: Tag name. Must be unique.
118            color: Background colour as a CSS hex string.
119            is_inbox_tag: When ``True``, newly ingested documents get this tag.
120            match: Auto-matching pattern.
121            matching_algorithm: Controls how ``match`` is applied.
122                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
123                regular-expression matching.
124            is_insensitive: When ``True``, ``match`` is case-insensitive.
125                Defaults to ``True``, matching the paperless-ngx API default.
126            parent: ID of parent tag for hierarchical trees.
127            owner: Numeric user ID to assign as owner.
128            set_permissions: Explicit view/change permission sets.
129                Pass ``None`` to create with empty permissions.
130
131        Returns:
132            The newly created :class:`~easypaperless.models.tags.Tag`.
133        """
134        logger.info("Creating tag name=%r", name)
135        return cast(
136            Tag,
137            await self._core._create_resource(
138                "tags",
139                Tag,
140                owner=owner,
141                set_permissions=set_permissions,
142                name=name,
143                color=color,
144                is_inbox_tag=is_inbox_tag,
145                match=match,
146                matching_algorithm=matching_algorithm,
147                is_insensitive=is_insensitive,
148                parent=parent,
149            ),
150        )

Create a new tag.

Arguments:
  • name: Tag name. Must be unique.
  • color: Background colour as a CSS hex string.
  • is_inbox_tag: When True, newly ingested documents get this tag.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive. Defaults to True, matching the paperless-ngx API default.
  • parent: ID of parent tag for hierarchical trees.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.tags.Tag.

async def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, color: str | easypaperless.Unset = UNSET, is_inbox_tag: bool | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool | easypaperless.Unset = UNSET, parent: int | None | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.Tag:
152    async def update(
153        self,
154        id: int,
155        *,
156        name: str | Unset = UNSET,
157        color: str | Unset = UNSET,
158        is_inbox_tag: bool | Unset = UNSET,
159        match: str | Unset = UNSET,
160        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
161        is_insensitive: bool | Unset = UNSET,
162        parent: int | None | Unset = UNSET,
163        owner: int | None | Unset = UNSET,
164        set_permissions: SetPermissions | None | Unset = UNSET,
165    ) -> Tag:
166        """Partially update a tag (PATCH semantics).
167
168        Args:
169            id: Numeric ID of the tag to update.
170            name: Tag name.
171            color: Background colour as a CSS hex string.
172            is_inbox_tag: When ``True``, newly ingested documents get this tag.
173            match: Auto-matching pattern.
174            matching_algorithm: Controls how ``match`` is applied.
175                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
176                regular-expression matching.
177            is_insensitive: When ``True``, ``match`` is case-insensitive.
178            parent: ID of parent tag.
179                Pass ``None`` to clear (make root tag).
180                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
181            owner: Numeric user ID to assign as owner.
182                Pass ``None`` to clear the owner.
183                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
184            set_permissions: Explicit view/change permission sets.
185                Pass ``None`` to clear all permissions (overwrite with empty).
186                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
187
188        Returns:
189            The updated :class:`~easypaperless.models.tags.Tag`.
190        """
191        logger.info("Updating tag id=%d", id)
192        return cast(
193            Tag,
194            await self._core._update_resource(
195                "tags",
196                id,
197                Tag,
198                name=name,
199                color=color,
200                is_inbox_tag=is_inbox_tag,
201                match=match,
202                matching_algorithm=matching_algorithm,
203                is_insensitive=is_insensitive,
204                parent=parent,
205                owner=owner,
206                set_permissions=set_permissions,
207            ),
208        )

Partially update a tag (PATCH semantics).

Arguments:
  • id: Numeric ID of the tag to update.
  • name: Tag name.
  • color: Background colour as a CSS hex string.
  • is_inbox_tag: When True, newly ingested documents get this tag.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive.
  • parent: ID of parent tag. Pass None to clear (make root tag). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.tags.Tag.

async def delete(self, id: int) -> None:
210    async def delete(self, id: int) -> None:
211        """Delete a tag.
212
213        Args:
214            id: Numeric ID of the tag to delete.
215
216        Raises:
217            ~easypaperless.exceptions.NotFoundError: If no tag exists with
218                that ID.
219        """
220        logger.info("Deleting tag id=%d", id)
221        await self._core._delete_resource("tags", id)

Delete a tag.

Arguments:
  • id: Numeric ID of the tag to delete.
Raises:
async def bulk_delete(self, ids: List[int]) -> None:
223    async def bulk_delete(self, ids: List[int]) -> None:
224        """Permanently delete multiple tags in a single request.
225
226        Args:
227            ids: List of tag IDs to delete.
228        """
229        logger.info("Bulk deleting %d tags", len(ids))
230        await self._core._bulk_edit_objects("tags", ids, "delete")

Permanently delete multiple tags in a single request.

Arguments:
  • ids: List of tag IDs to delete.
async def bulk_set_permissions( self, ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
232    async def bulk_set_permissions(
233        self,
234        ids: List[int],
235        *,
236        set_permissions: SetPermissions | Unset = UNSET,
237        owner: int | None | Unset = UNSET,
238        merge: bool = False,
239    ) -> None:
240        """Set permissions and/or owner on multiple tags.
241
242        Args:
243            ids: List of tag IDs to modify.
244            set_permissions: Explicit view/change permission sets.
245                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
246            owner: Numeric user ID to assign as owner.
247                Pass ``None`` to clear the owner.
248                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
249            merge: When ``True``, new permissions are merged with existing ones.
250        """
251        logger.info("Bulk setting permissions on %d tags", len(ids))
252        params: dict[str, Any] = {"merge": merge}
253        if not isinstance(set_permissions, Unset):
254            params["permissions"] = set_permissions.model_dump()
255        if not isinstance(owner, Unset):
256            params["owner"] = owner
257        await self._core._bulk_edit_objects("tags", ids, "set_permissions", **params)

Set permissions and/or owner on multiple tags.

Arguments:
  • ids: List of tag IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
class SyncCorrespondentsResource:
 18class SyncCorrespondentsResource:
 19    """Sync accessor for correspondents: ``client.correspondents``."""
 20
 21    def __init__(self, async_correspondents: CorrespondentsResource, run: Any) -> None:
 22        self._async_correspondents = async_correspondents
 23        self._run = run
 24
 25    def list(
 26        self,
 27        *,
 28        ids: List[int] | None = None,
 29        name_contains: str | None = None,
 30        name_exact: str | None = None,
 31        page: int | None = None,
 32        page_size: int | None = None,
 33        ordering: str | None = None,
 34        descending: bool = False,
 35        full_perms: bool = False,
 36    ) -> PagedResult[Correspondent]:
 37        """Return correspondents defined in paperless-ngx.
 38
 39        When ``page`` is ``None`` (the default), all pages are fetched
 40        automatically and ``next`` / ``previous`` in the result are always
 41        ``None``.  When ``page`` is set, only that page is fetched and
 42        ``next`` / ``previous`` reflect the raw API values.
 43
 44        Args:
 45            ids: Return only correspondents whose ID is in this list.
 46            name_contains: Case-insensitive substring filter on name.
 47            name_exact: Case-insensitive exact match on name.
 48            page: Return only this specific page (1-based).
 49            page_size: Number of results per page.
 50            ordering: Field to sort by.
 51            descending: When ``True``, reverses the sort direction.
 52            full_perms: When ``True``, paperless-ngx returns the full view/change
 53                permissions of every object, available as
 54                ``Correspondent.permissions``; ``user_can_change`` is then ``None``.
 55                Default: ``False``.
 56
 57        Returns:
 58            :class:`~easypaperless.models.paged_result.PagedResult` of
 59            :class:`~easypaperless.models.correspondents.Correspondent` objects.
 60        """
 61        return cast(
 62            PagedResult[Correspondent],
 63            self._run(
 64                self._async_correspondents.list(
 65                    ids=ids,
 66                    name_contains=name_contains,
 67                    name_exact=name_exact,
 68                    page=page,
 69                    page_size=page_size,
 70                    ordering=ordering,
 71                    descending=descending,
 72                    full_perms=full_perms,
 73                )
 74            ),
 75        )
 76
 77    def get(self, id: int, *, full_perms: bool = False) -> Correspondent:
 78        """Fetch a single correspondent by its ID.
 79
 80        Args:
 81            id: Numeric correspondent ID.
 82            full_perms: When ``True``, paperless-ngx returns the full view/change
 83                permissions, available as ``Correspondent.permissions``;
 84                ``user_can_change`` is then ``None``. Default: ``False``.
 85
 86        Returns:
 87            The :class:`~easypaperless.models.correspondents.Correspondent` with the given ID.
 88
 89        Raises:
 90            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
 91        """
 92        return cast(
 93            Correspondent, self._run(self._async_correspondents.get(id, full_perms=full_perms))
 94        )
 95
 96    def create(
 97        self,
 98        *,
 99        name: str,
100        match: str | Unset = UNSET,
101        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
102        is_insensitive: bool = True,
103        owner: int | None | Unset = UNSET,
104        set_permissions: SetPermissions | None | Unset = UNSET,
105    ) -> Correspondent:
106        """Create a new correspondent.
107
108        Args:
109            name: Correspondent name. Must be unique.
110            match: Auto-matching pattern.
111            matching_algorithm: Controls how ``match`` is applied.
112                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
113                regular-expression matching.
114            is_insensitive: When ``True``, ``match`` is case-insensitive.
115                Defaults to ``True``, matching the paperless-ngx API default.
116            owner: Numeric user ID to assign as owner.
117            set_permissions: Explicit view/change permission sets.
118                Pass ``None`` to create with empty permissions.
119
120        Returns:
121            The newly created :class:`~easypaperless.models.correspondents.Correspondent`.
122        """
123        return cast(
124            Correspondent,
125            self._run(
126                self._async_correspondents.create(
127                    name=name,
128                    match=match,
129                    matching_algorithm=matching_algorithm,
130                    is_insensitive=is_insensitive,
131                    owner=owner,
132                    set_permissions=set_permissions,
133                )
134            ),
135        )
136
137    def update(
138        self,
139        id: int,
140        *,
141        name: str | Unset = UNSET,
142        match: str | Unset = UNSET,
143        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
144        is_insensitive: bool | Unset = UNSET,
145        owner: int | None | Unset = UNSET,
146        set_permissions: SetPermissions | None | Unset = UNSET,
147    ) -> Correspondent:
148        """Partially update a correspondent (PATCH semantics).
149
150        Args:
151            id: Numeric ID of the correspondent to update.
152            name: Correspondent name.
153            match: Auto-matching pattern.
154            matching_algorithm: Controls how ``match`` is applied.
155                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
156                regular-expression matching.
157            is_insensitive: When ``True``, ``match`` is case-insensitive.
158            owner: Numeric user ID to assign as owner.
159                Pass ``None`` to clear the owner.
160                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
161            set_permissions: Explicit view/change permission sets.
162                Pass ``None`` to clear all permissions (overwrite with empty).
163                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
164
165        Returns:
166            The updated :class:`~easypaperless.models.correspondents.Correspondent`.
167        """
168        return cast(
169            Correspondent,
170            self._run(
171                self._async_correspondents.update(
172                    id,
173                    name=name,
174                    match=match,
175                    matching_algorithm=matching_algorithm,
176                    is_insensitive=is_insensitive,
177                    owner=owner,
178                    set_permissions=set_permissions,
179                )
180            ),
181        )
182
183    def delete(self, id: int) -> None:
184        """Delete a correspondent.
185
186        Args:
187            id: Numeric ID of the correspondent to delete.
188
189        Raises:
190            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
191        """
192        self._run(self._async_correspondents.delete(id))
193
194    def bulk_delete(self, ids: List[int]) -> None:
195        """Permanently delete multiple correspondents in a single request.
196
197        Args:
198            ids: List of correspondent IDs to delete.
199        """
200        self._run(self._async_correspondents.bulk_delete(ids))
201
202    def bulk_set_permissions(
203        self,
204        ids: List[int],
205        *,
206        set_permissions: SetPermissions | Unset = UNSET,
207        owner: int | None | Unset = UNSET,
208        merge: bool = False,
209    ) -> None:
210        """Set permissions and/or owner on multiple correspondents.
211
212        Args:
213            ids: List of correspondent IDs to modify.
214            set_permissions: Explicit view/change permission sets.
215                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
216            owner: Numeric user ID to assign as owner.
217                Pass ``None`` to clear the owner.
218                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
219            merge: When ``True``, new permissions are merged with existing ones.
220        """
221        self._run(
222            self._async_correspondents.bulk_set_permissions(
223                ids, set_permissions=set_permissions, owner=owner, merge=merge
224            )
225        )

Sync accessor for correspondents: client.correspondents.

SyncCorrespondentsResource( async_correspondents: CorrespondentsResource, run: Any)
21    def __init__(self, async_correspondents: CorrespondentsResource, run: Any) -> None:
22        self._async_correspondents = async_correspondents
23        self._run = run
def list( self, *, ids: Optional[List[int]] = None, name_contains: str | None = None, name_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False, full_perms: bool = False) -> easypaperless.PagedResult[Correspondent]:
25    def list(
26        self,
27        *,
28        ids: List[int] | None = None,
29        name_contains: str | None = None,
30        name_exact: str | None = None,
31        page: int | None = None,
32        page_size: int | None = None,
33        ordering: str | None = None,
34        descending: bool = False,
35        full_perms: bool = False,
36    ) -> PagedResult[Correspondent]:
37        """Return correspondents defined in paperless-ngx.
38
39        When ``page`` is ``None`` (the default), all pages are fetched
40        automatically and ``next`` / ``previous`` in the result are always
41        ``None``.  When ``page`` is set, only that page is fetched and
42        ``next`` / ``previous`` reflect the raw API values.
43
44        Args:
45            ids: Return only correspondents whose ID is in this list.
46            name_contains: Case-insensitive substring filter on name.
47            name_exact: Case-insensitive exact match on name.
48            page: Return only this specific page (1-based).
49            page_size: Number of results per page.
50            ordering: Field to sort by.
51            descending: When ``True``, reverses the sort direction.
52            full_perms: When ``True``, paperless-ngx returns the full view/change
53                permissions of every object, available as
54                ``Correspondent.permissions``; ``user_can_change`` is then ``None``.
55                Default: ``False``.
56
57        Returns:
58            :class:`~easypaperless.models.paged_result.PagedResult` of
59            :class:`~easypaperless.models.correspondents.Correspondent` objects.
60        """
61        return cast(
62            PagedResult[Correspondent],
63            self._run(
64                self._async_correspondents.list(
65                    ids=ids,
66                    name_contains=name_contains,
67                    name_exact=name_exact,
68                    page=page,
69                    page_size=page_size,
70                    ordering=ordering,
71                    descending=descending,
72                    full_perms=full_perms,
73                )
74            ),
75        )

Return correspondents defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • ids: Return only correspondents whose ID is in this list.
  • name_contains: Case-insensitive substring filter on name.
  • name_exact: Case-insensitive exact match on name.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every object, available as Correspondent.permissions; user_can_change is then None. Default: False.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.correspondents.Correspondent objects.

def get( self, id: int, *, full_perms: bool = False) -> easypaperless.Correspondent:
77    def get(self, id: int, *, full_perms: bool = False) -> Correspondent:
78        """Fetch a single correspondent by its ID.
79
80        Args:
81            id: Numeric correspondent ID.
82            full_perms: When ``True``, paperless-ngx returns the full view/change
83                permissions, available as ``Correspondent.permissions``;
84                ``user_can_change`` is then ``None``. Default: ``False``.
85
86        Returns:
87            The :class:`~easypaperless.models.correspondents.Correspondent` with the given ID.
88
89        Raises:
90            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
91        """
92        return cast(
93            Correspondent, self._run(self._async_correspondents.get(id, full_perms=full_perms))
94        )

Fetch a single correspondent by its ID.

Arguments:
  • id: Numeric correspondent ID.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as Correspondent.permissions; user_can_change is then None. Default: False.
Returns:

The ~easypaperless.models.correspondents.Correspondent with the given ID.

Raises:
def create( self, *, name: str, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool = True, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.Correspondent:
 96    def create(
 97        self,
 98        *,
 99        name: str,
100        match: str | Unset = UNSET,
101        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
102        is_insensitive: bool = True,
103        owner: int | None | Unset = UNSET,
104        set_permissions: SetPermissions | None | Unset = UNSET,
105    ) -> Correspondent:
106        """Create a new correspondent.
107
108        Args:
109            name: Correspondent name. Must be unique.
110            match: Auto-matching pattern.
111            matching_algorithm: Controls how ``match`` is applied.
112                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
113                regular-expression matching.
114            is_insensitive: When ``True``, ``match`` is case-insensitive.
115                Defaults to ``True``, matching the paperless-ngx API default.
116            owner: Numeric user ID to assign as owner.
117            set_permissions: Explicit view/change permission sets.
118                Pass ``None`` to create with empty permissions.
119
120        Returns:
121            The newly created :class:`~easypaperless.models.correspondents.Correspondent`.
122        """
123        return cast(
124            Correspondent,
125            self._run(
126                self._async_correspondents.create(
127                    name=name,
128                    match=match,
129                    matching_algorithm=matching_algorithm,
130                    is_insensitive=is_insensitive,
131                    owner=owner,
132                    set_permissions=set_permissions,
133                )
134            ),
135        )

Create a new correspondent.

Arguments:
  • name: Correspondent name. Must be unique.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive. Defaults to True, matching the paperless-ngx API default.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.correspondents.Correspondent.

def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.Correspondent:
137    def update(
138        self,
139        id: int,
140        *,
141        name: str | Unset = UNSET,
142        match: str | Unset = UNSET,
143        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
144        is_insensitive: bool | Unset = UNSET,
145        owner: int | None | Unset = UNSET,
146        set_permissions: SetPermissions | None | Unset = UNSET,
147    ) -> Correspondent:
148        """Partially update a correspondent (PATCH semantics).
149
150        Args:
151            id: Numeric ID of the correspondent to update.
152            name: Correspondent name.
153            match: Auto-matching pattern.
154            matching_algorithm: Controls how ``match`` is applied.
155                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
156                regular-expression matching.
157            is_insensitive: When ``True``, ``match`` is case-insensitive.
158            owner: Numeric user ID to assign as owner.
159                Pass ``None`` to clear the owner.
160                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
161            set_permissions: Explicit view/change permission sets.
162                Pass ``None`` to clear all permissions (overwrite with empty).
163                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
164
165        Returns:
166            The updated :class:`~easypaperless.models.correspondents.Correspondent`.
167        """
168        return cast(
169            Correspondent,
170            self._run(
171                self._async_correspondents.update(
172                    id,
173                    name=name,
174                    match=match,
175                    matching_algorithm=matching_algorithm,
176                    is_insensitive=is_insensitive,
177                    owner=owner,
178                    set_permissions=set_permissions,
179                )
180            ),
181        )

Partially update a correspondent (PATCH semantics).

Arguments:
  • id: Numeric ID of the correspondent to update.
  • name: Correspondent name.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.correspondents.Correspondent.

def delete(self, id: int) -> None:
183    def delete(self, id: int) -> None:
184        """Delete a correspondent.
185
186        Args:
187            id: Numeric ID of the correspondent to delete.
188
189        Raises:
190            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
191        """
192        self._run(self._async_correspondents.delete(id))

Delete a correspondent.

Arguments:
  • id: Numeric ID of the correspondent to delete.
Raises:
def bulk_delete(self, ids: List[int]) -> None:
194    def bulk_delete(self, ids: List[int]) -> None:
195        """Permanently delete multiple correspondents in a single request.
196
197        Args:
198            ids: List of correspondent IDs to delete.
199        """
200        self._run(self._async_correspondents.bulk_delete(ids))

Permanently delete multiple correspondents in a single request.

Arguments:
  • ids: List of correspondent IDs to delete.
def bulk_set_permissions( self, ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
202    def bulk_set_permissions(
203        self,
204        ids: List[int],
205        *,
206        set_permissions: SetPermissions | Unset = UNSET,
207        owner: int | None | Unset = UNSET,
208        merge: bool = False,
209    ) -> None:
210        """Set permissions and/or owner on multiple correspondents.
211
212        Args:
213            ids: List of correspondent IDs to modify.
214            set_permissions: Explicit view/change permission sets.
215                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
216            owner: Numeric user ID to assign as owner.
217                Pass ``None`` to clear the owner.
218                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
219            merge: When ``True``, new permissions are merged with existing ones.
220        """
221        self._run(
222            self._async_correspondents.bulk_set_permissions(
223                ids, set_permissions=set_permissions, owner=owner, merge=merge
224            )
225        )

Set permissions and/or owner on multiple correspondents.

Arguments:
  • ids: List of correspondent IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
class SyncCustomFieldsResource:
 17class SyncCustomFieldsResource:
 18    """Sync accessor for custom fields: ``client.custom_fields``."""
 19
 20    def __init__(self, async_custom_fields: CustomFieldsResource, run: Any) -> None:
 21        self._async_custom_fields = async_custom_fields
 22        self._run = run
 23
 24    def list(
 25        self,
 26        *,
 27        name_contains: str | None = None,
 28        name_exact: str | None = None,
 29        page: int | None = None,
 30        page_size: int | None = None,
 31        ordering: str | None = None,
 32        descending: bool = False,
 33    ) -> PagedResult[CustomField]:
 34        """Return all custom fields defined in paperless-ngx.
 35
 36        When ``page`` is ``None`` (the default), all pages are fetched
 37        automatically and ``next`` / ``previous`` in the result are always
 38        ``None``.  When ``page`` is set, only that page is fetched and
 39        ``next`` / ``previous`` reflect the raw API values.
 40
 41        Args:
 42            name_contains: Case-insensitive substring filter on name.
 43            name_exact: Case-insensitive exact match on name.
 44            page: Return only this specific page (1-based).
 45            page_size: Number of results per page.
 46            ordering: Field to sort by.
 47            descending: When ``True``, reverses the sort direction.
 48
 49        Returns:
 50            :class:`~easypaperless.models.paged_result.PagedResult` of
 51            :class:`~easypaperless.models.custom_fields.CustomField` objects.
 52        """
 53        return cast(
 54            PagedResult[CustomField],
 55            self._run(
 56                self._async_custom_fields.list(
 57                    name_contains=name_contains,
 58                    name_exact=name_exact,
 59                    page=page,
 60                    page_size=page_size,
 61                    ordering=ordering,
 62                    descending=descending,
 63                )
 64            ),
 65        )
 66
 67    def get(self, id: int) -> CustomField:
 68        """Fetch a single custom field by its ID.
 69
 70        Args:
 71            id: Numeric custom-field ID.
 72
 73        Returns:
 74            The :class:`~easypaperless.models.custom_fields.CustomField` with the given ID.
 75
 76        Raises:
 77            ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
 78        """
 79        return cast(CustomField, self._run(self._async_custom_fields.get(id)))
 80
 81    def create(
 82        self,
 83        *,
 84        name: str,
 85        data_type: str,
 86        extra_data: Any | None = None,
 87        owner: int | None | Unset = UNSET,
 88        set_permissions: SetPermissions | None | Unset = UNSET,
 89    ) -> CustomField:
 90        """Create a new custom field.
 91
 92        Args:
 93            name: Field name shown in the UI. Must be unique.
 94            data_type: Value type. One of ``"string"``, ``"boolean"``,
 95                ``"integer"``, ``"float"``, ``"monetary"``, ``"date"``,
 96                ``"url"``, ``"documentlink"``, ``"select"``.
 97            extra_data: Additional configuration for the field type.
 98            owner: Numeric user ID to assign as owner.
 99            set_permissions: Explicit view/change permission sets.
100                Pass ``None`` to create with empty permissions.
101
102        Returns:
103            The newly created :class:`~easypaperless.models.custom_fields.CustomField`.
104        """
105        return cast(
106            CustomField,
107            self._run(
108                self._async_custom_fields.create(
109                    name=name,
110                    data_type=data_type,
111                    extra_data=extra_data,
112                    owner=owner,
113                    set_permissions=set_permissions,
114                )
115            ),
116        )
117
118    def update(
119        self,
120        id: int,
121        *,
122        name: str | Unset = UNSET,
123        data_type: str | Unset = UNSET,
124        extra_data: Any | None | Unset = UNSET,
125        owner: int | None | Unset = UNSET,
126        set_permissions: SetPermissions | None | Unset = UNSET,
127    ) -> CustomField:
128        """Partially update a custom field (PATCH semantics).
129
130        Args:
131            id: Numeric ID of the custom field to update.
132            name: Field name shown in the UI.
133            data_type: Value type (e.g. ``"string"``, ``"boolean"``, ``"integer"``).
134                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
135            extra_data: Additional configuration for the field type.
136            owner: Numeric user ID to assign as owner.
137                Pass ``None`` to clear the owner.
138                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
139            set_permissions: Explicit view/change permission sets.
140                Pass ``None`` to clear all permissions (overwrite with empty).
141                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
142
143        Returns:
144            The updated :class:`~easypaperless.models.custom_fields.CustomField`.
145        """
146        return cast(
147            CustomField,
148            self._run(
149                self._async_custom_fields.update(
150                    id,
151                    name=name,
152                    data_type=data_type,
153                    extra_data=extra_data,
154                    owner=owner,
155                    set_permissions=set_permissions,
156                )
157            ),
158        )
159
160    def delete(self, id: int) -> None:
161        """Delete a custom field.
162
163        Args:
164            id: Numeric ID of the custom field to delete.
165
166        Raises:
167            ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
168        """
169        self._run(self._async_custom_fields.delete(id))

Sync accessor for custom fields: client.custom_fields.

SyncCustomFieldsResource( async_custom_fields: CustomFieldsResource, run: Any)
20    def __init__(self, async_custom_fields: CustomFieldsResource, run: Any) -> None:
21        self._async_custom_fields = async_custom_fields
22        self._run = run
def list( self, *, name_contains: str | None = None, name_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False) -> easypaperless.PagedResult[CustomField]:
24    def list(
25        self,
26        *,
27        name_contains: str | None = None,
28        name_exact: str | None = None,
29        page: int | None = None,
30        page_size: int | None = None,
31        ordering: str | None = None,
32        descending: bool = False,
33    ) -> PagedResult[CustomField]:
34        """Return all custom fields defined in paperless-ngx.
35
36        When ``page`` is ``None`` (the default), all pages are fetched
37        automatically and ``next`` / ``previous`` in the result are always
38        ``None``.  When ``page`` is set, only that page is fetched and
39        ``next`` / ``previous`` reflect the raw API values.
40
41        Args:
42            name_contains: Case-insensitive substring filter on name.
43            name_exact: Case-insensitive exact match on name.
44            page: Return only this specific page (1-based).
45            page_size: Number of results per page.
46            ordering: Field to sort by.
47            descending: When ``True``, reverses the sort direction.
48
49        Returns:
50            :class:`~easypaperless.models.paged_result.PagedResult` of
51            :class:`~easypaperless.models.custom_fields.CustomField` objects.
52        """
53        return cast(
54            PagedResult[CustomField],
55            self._run(
56                self._async_custom_fields.list(
57                    name_contains=name_contains,
58                    name_exact=name_exact,
59                    page=page,
60                    page_size=page_size,
61                    ordering=ordering,
62                    descending=descending,
63                )
64            ),
65        )

Return all custom fields defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • name_contains: Case-insensitive substring filter on name.
  • name_exact: Case-insensitive exact match on name.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.custom_fields.CustomField objects.

def get(self, id: int) -> easypaperless.CustomField:
67    def get(self, id: int) -> CustomField:
68        """Fetch a single custom field by its ID.
69
70        Args:
71            id: Numeric custom-field ID.
72
73        Returns:
74            The :class:`~easypaperless.models.custom_fields.CustomField` with the given ID.
75
76        Raises:
77            ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
78        """
79        return cast(CustomField, self._run(self._async_custom_fields.get(id)))

Fetch a single custom field by its ID.

Arguments:
  • id: Numeric custom-field ID.
Returns:

The ~easypaperless.models.custom_fields.CustomField with the given ID.

Raises:
def create( self, *, name: str, data_type: str, extra_data: typing.Any | None = None, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.CustomField:
 81    def create(
 82        self,
 83        *,
 84        name: str,
 85        data_type: str,
 86        extra_data: Any | None = None,
 87        owner: int | None | Unset = UNSET,
 88        set_permissions: SetPermissions | None | Unset = UNSET,
 89    ) -> CustomField:
 90        """Create a new custom field.
 91
 92        Args:
 93            name: Field name shown in the UI. Must be unique.
 94            data_type: Value type. One of ``"string"``, ``"boolean"``,
 95                ``"integer"``, ``"float"``, ``"monetary"``, ``"date"``,
 96                ``"url"``, ``"documentlink"``, ``"select"``.
 97            extra_data: Additional configuration for the field type.
 98            owner: Numeric user ID to assign as owner.
 99            set_permissions: Explicit view/change permission sets.
100                Pass ``None`` to create with empty permissions.
101
102        Returns:
103            The newly created :class:`~easypaperless.models.custom_fields.CustomField`.
104        """
105        return cast(
106            CustomField,
107            self._run(
108                self._async_custom_fields.create(
109                    name=name,
110                    data_type=data_type,
111                    extra_data=extra_data,
112                    owner=owner,
113                    set_permissions=set_permissions,
114                )
115            ),
116        )

Create a new custom field.

Arguments:
  • name: Field name shown in the UI. Must be unique.
  • data_type: Value type. One of "string", "boolean", "integer", "float", "monetary", "date", "url", "documentlink", "select".
  • extra_data: Additional configuration for the field type.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.custom_fields.CustomField.

def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, data_type: str | easypaperless.Unset = UNSET, extra_data: typing.Any | None | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.CustomField:
118    def update(
119        self,
120        id: int,
121        *,
122        name: str | Unset = UNSET,
123        data_type: str | Unset = UNSET,
124        extra_data: Any | None | Unset = UNSET,
125        owner: int | None | Unset = UNSET,
126        set_permissions: SetPermissions | None | Unset = UNSET,
127    ) -> CustomField:
128        """Partially update a custom field (PATCH semantics).
129
130        Args:
131            id: Numeric ID of the custom field to update.
132            name: Field name shown in the UI.
133            data_type: Value type (e.g. ``"string"``, ``"boolean"``, ``"integer"``).
134                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
135            extra_data: Additional configuration for the field type.
136            owner: Numeric user ID to assign as owner.
137                Pass ``None`` to clear the owner.
138                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
139            set_permissions: Explicit view/change permission sets.
140                Pass ``None`` to clear all permissions (overwrite with empty).
141                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
142
143        Returns:
144            The updated :class:`~easypaperless.models.custom_fields.CustomField`.
145        """
146        return cast(
147            CustomField,
148            self._run(
149                self._async_custom_fields.update(
150                    id,
151                    name=name,
152                    data_type=data_type,
153                    extra_data=extra_data,
154                    owner=owner,
155                    set_permissions=set_permissions,
156                )
157            ),
158        )

Partially update a custom field (PATCH semantics).

Arguments:
  • id: Numeric ID of the custom field to update.
  • name: Field name shown in the UI.
  • data_type: Value type (e.g. "string", "boolean", "integer"). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • extra_data: Additional configuration for the field type.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.custom_fields.CustomField.

def delete(self, id: int) -> None:
160    def delete(self, id: int) -> None:
161        """Delete a custom field.
162
163        Args:
164            id: Numeric ID of the custom field to delete.
165
166        Raises:
167            ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
168        """
169        self._run(self._async_custom_fields.delete(id))

Delete a custom field.

Arguments:
  • id: Numeric ID of the custom field to delete.
Raises:
class SyncDocumentTypesResource:
 18class SyncDocumentTypesResource:
 19    """Sync accessor for document types: ``client.document_types``."""
 20
 21    def __init__(self, async_document_types: DocumentTypesResource, run: Any) -> None:
 22        self._async_document_types = async_document_types
 23        self._run = run
 24
 25    def list(
 26        self,
 27        *,
 28        ids: List[int] | None = None,
 29        name_contains: str | None = None,
 30        name_exact: str | None = None,
 31        page: int | None = None,
 32        page_size: int | None = None,
 33        ordering: str | None = None,
 34        descending: bool = False,
 35        full_perms: bool = False,
 36    ) -> PagedResult[DocumentType]:
 37        """Return document types defined in paperless-ngx.
 38
 39        When ``page`` is ``None`` (the default), all pages are fetched
 40        automatically and ``next`` / ``previous`` in the result are always
 41        ``None``.  When ``page`` is set, only that page is fetched and
 42        ``next`` / ``previous`` reflect the raw API values.
 43
 44        Args:
 45            ids: Return only document types whose ID is in this list.
 46            name_contains: Case-insensitive substring filter on name.
 47            name_exact: Case-insensitive exact match on name.
 48            page: Return only this specific page (1-based).
 49            page_size: Number of results per page.
 50            ordering: Field to sort by.
 51            descending: When ``True``, reverses the sort direction.
 52            full_perms: When ``True``, paperless-ngx returns the full view/change
 53                permissions of every object, available as
 54                ``DocumentType.permissions``; ``user_can_change`` is then ``None``.
 55                Default: ``False``.
 56
 57        Returns:
 58            :class:`~easypaperless.models.paged_result.PagedResult` of
 59            :class:`~easypaperless.models.document_types.DocumentType` objects.
 60        """
 61        return cast(
 62            PagedResult[DocumentType],
 63            self._run(
 64                self._async_document_types.list(
 65                    ids=ids,
 66                    name_contains=name_contains,
 67                    name_exact=name_exact,
 68                    page=page,
 69                    page_size=page_size,
 70                    ordering=ordering,
 71                    descending=descending,
 72                    full_perms=full_perms,
 73                )
 74            ),
 75        )
 76
 77    def get(self, id: int, *, full_perms: bool = False) -> DocumentType:
 78        """Fetch a single document type by its ID.
 79
 80        Args:
 81            id: Numeric document-type ID.
 82            full_perms: When ``True``, paperless-ngx returns the full view/change
 83                permissions, available as ``DocumentType.permissions``;
 84                ``user_can_change`` is then ``None``. Default: ``False``.
 85
 86        Returns:
 87            The :class:`~easypaperless.models.document_types.DocumentType` with the given ID.
 88
 89        Raises:
 90            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
 91        """
 92        return cast(
 93            DocumentType, self._run(self._async_document_types.get(id, full_perms=full_perms))
 94        )
 95
 96    def create(
 97        self,
 98        *,
 99        name: str,
100        match: str | Unset = UNSET,
101        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
102        is_insensitive: bool = True,
103        owner: int | None | Unset = UNSET,
104        set_permissions: SetPermissions | None | Unset = UNSET,
105    ) -> DocumentType:
106        """Create a new document type.
107
108        Args:
109            name: Document-type name. Must be unique.
110            match: Auto-matching pattern.
111            matching_algorithm: Controls how ``match`` is applied.
112                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
113                regular-expression matching.
114            is_insensitive: When ``True``, ``match`` is case-insensitive.
115                Defaults to ``True``, matching the paperless-ngx API default.
116            owner: Numeric user ID to assign as owner.
117            set_permissions: Explicit view/change permission sets.
118                Pass ``None`` to create with empty permissions.
119
120        Returns:
121            The newly created :class:`~easypaperless.models.document_types.DocumentType`.
122        """
123        return cast(
124            DocumentType,
125            self._run(
126                self._async_document_types.create(
127                    name=name,
128                    match=match,
129                    matching_algorithm=matching_algorithm,
130                    is_insensitive=is_insensitive,
131                    owner=owner,
132                    set_permissions=set_permissions,
133                )
134            ),
135        )
136
137    def update(
138        self,
139        id: int,
140        *,
141        name: str | Unset = UNSET,
142        match: str | Unset = UNSET,
143        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
144        is_insensitive: bool | Unset = UNSET,
145        owner: int | None | Unset = UNSET,
146        set_permissions: SetPermissions | None | Unset = UNSET,
147    ) -> DocumentType:
148        """Partially update a document type (PATCH semantics).
149
150        Args:
151            id: Numeric ID of the document type to update.
152            name: Document-type name.
153            match: Auto-matching pattern.
154            matching_algorithm: Controls how ``match`` is applied.
155                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
156                regular-expression matching.
157            is_insensitive: When ``True``, ``match`` is case-insensitive.
158            owner: Numeric user ID to assign as owner.
159                Pass ``None`` to clear the owner.
160                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
161            set_permissions: Explicit view/change permission sets.
162                Pass ``None`` to clear all permissions (overwrite with empty).
163                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
164
165        Returns:
166            The updated :class:`~easypaperless.models.document_types.DocumentType`.
167        """
168        return cast(
169            DocumentType,
170            self._run(
171                self._async_document_types.update(
172                    id,
173                    name=name,
174                    match=match,
175                    matching_algorithm=matching_algorithm,
176                    is_insensitive=is_insensitive,
177                    owner=owner,
178                    set_permissions=set_permissions,
179                )
180            ),
181        )
182
183    def delete(self, id: int) -> None:
184        """Delete a document type.
185
186        Args:
187            id: Numeric ID of the document type to delete.
188
189        Raises:
190            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
191        """
192        self._run(self._async_document_types.delete(id))
193
194    def bulk_delete(self, ids: List[int]) -> None:
195        """Permanently delete multiple document types in a single request.
196
197        Args:
198            ids: List of document type IDs to delete.
199        """
200        self._run(self._async_document_types.bulk_delete(ids))
201
202    def bulk_set_permissions(
203        self,
204        ids: List[int],
205        *,
206        set_permissions: SetPermissions | Unset = UNSET,
207        owner: int | None | Unset = UNSET,
208        merge: bool = False,
209    ) -> None:
210        """Set permissions and/or owner on multiple document types.
211
212        Args:
213            ids: List of document type IDs to modify.
214            set_permissions: Explicit view/change permission sets.
215                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
216            owner: Numeric user ID to assign as owner.
217                Pass ``None`` to clear the owner.
218                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
219            merge: When ``True``, new permissions are merged with existing ones.
220        """
221        self._run(
222            self._async_document_types.bulk_set_permissions(
223                ids, set_permissions=set_permissions, owner=owner, merge=merge
224            )
225        )

Sync accessor for document types: client.document_types.

SyncDocumentTypesResource( async_document_types: DocumentTypesResource, run: Any)
21    def __init__(self, async_document_types: DocumentTypesResource, run: Any) -> None:
22        self._async_document_types = async_document_types
23        self._run = run
def list( self, *, ids: Optional[List[int]] = None, name_contains: str | None = None, name_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False, full_perms: bool = False) -> easypaperless.PagedResult[DocumentType]:
25    def list(
26        self,
27        *,
28        ids: List[int] | None = None,
29        name_contains: str | None = None,
30        name_exact: str | None = None,
31        page: int | None = None,
32        page_size: int | None = None,
33        ordering: str | None = None,
34        descending: bool = False,
35        full_perms: bool = False,
36    ) -> PagedResult[DocumentType]:
37        """Return document types defined in paperless-ngx.
38
39        When ``page`` is ``None`` (the default), all pages are fetched
40        automatically and ``next`` / ``previous`` in the result are always
41        ``None``.  When ``page`` is set, only that page is fetched and
42        ``next`` / ``previous`` reflect the raw API values.
43
44        Args:
45            ids: Return only document types whose ID is in this list.
46            name_contains: Case-insensitive substring filter on name.
47            name_exact: Case-insensitive exact match on name.
48            page: Return only this specific page (1-based).
49            page_size: Number of results per page.
50            ordering: Field to sort by.
51            descending: When ``True``, reverses the sort direction.
52            full_perms: When ``True``, paperless-ngx returns the full view/change
53                permissions of every object, available as
54                ``DocumentType.permissions``; ``user_can_change`` is then ``None``.
55                Default: ``False``.
56
57        Returns:
58            :class:`~easypaperless.models.paged_result.PagedResult` of
59            :class:`~easypaperless.models.document_types.DocumentType` objects.
60        """
61        return cast(
62            PagedResult[DocumentType],
63            self._run(
64                self._async_document_types.list(
65                    ids=ids,
66                    name_contains=name_contains,
67                    name_exact=name_exact,
68                    page=page,
69                    page_size=page_size,
70                    ordering=ordering,
71                    descending=descending,
72                    full_perms=full_perms,
73                )
74            ),
75        )

Return document types defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • ids: Return only document types whose ID is in this list.
  • name_contains: Case-insensitive substring filter on name.
  • name_exact: Case-insensitive exact match on name.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every object, available as DocumentType.permissions; user_can_change is then None. Default: False.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.document_types.DocumentType objects.

def get( self, id: int, *, full_perms: bool = False) -> easypaperless.DocumentType:
77    def get(self, id: int, *, full_perms: bool = False) -> DocumentType:
78        """Fetch a single document type by its ID.
79
80        Args:
81            id: Numeric document-type ID.
82            full_perms: When ``True``, paperless-ngx returns the full view/change
83                permissions, available as ``DocumentType.permissions``;
84                ``user_can_change`` is then ``None``. Default: ``False``.
85
86        Returns:
87            The :class:`~easypaperless.models.document_types.DocumentType` with the given ID.
88
89        Raises:
90            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
91        """
92        return cast(
93            DocumentType, self._run(self._async_document_types.get(id, full_perms=full_perms))
94        )

Fetch a single document type by its ID.

Arguments:
  • id: Numeric document-type ID.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as DocumentType.permissions; user_can_change is then None. Default: False.
Returns:

The ~easypaperless.models.document_types.DocumentType with the given ID.

Raises:
def create( self, *, name: str, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool = True, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.DocumentType:
 96    def create(
 97        self,
 98        *,
 99        name: str,
100        match: str | Unset = UNSET,
101        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
102        is_insensitive: bool = True,
103        owner: int | None | Unset = UNSET,
104        set_permissions: SetPermissions | None | Unset = UNSET,
105    ) -> DocumentType:
106        """Create a new document type.
107
108        Args:
109            name: Document-type name. Must be unique.
110            match: Auto-matching pattern.
111            matching_algorithm: Controls how ``match`` is applied.
112                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
113                regular-expression matching.
114            is_insensitive: When ``True``, ``match`` is case-insensitive.
115                Defaults to ``True``, matching the paperless-ngx API default.
116            owner: Numeric user ID to assign as owner.
117            set_permissions: Explicit view/change permission sets.
118                Pass ``None`` to create with empty permissions.
119
120        Returns:
121            The newly created :class:`~easypaperless.models.document_types.DocumentType`.
122        """
123        return cast(
124            DocumentType,
125            self._run(
126                self._async_document_types.create(
127                    name=name,
128                    match=match,
129                    matching_algorithm=matching_algorithm,
130                    is_insensitive=is_insensitive,
131                    owner=owner,
132                    set_permissions=set_permissions,
133                )
134            ),
135        )

Create a new document type.

Arguments:
  • name: Document-type name. Must be unique.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive. Defaults to True, matching the paperless-ngx API default.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.document_types.DocumentType.

def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.DocumentType:
137    def update(
138        self,
139        id: int,
140        *,
141        name: str | Unset = UNSET,
142        match: str | Unset = UNSET,
143        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
144        is_insensitive: bool | Unset = UNSET,
145        owner: int | None | Unset = UNSET,
146        set_permissions: SetPermissions | None | Unset = UNSET,
147    ) -> DocumentType:
148        """Partially update a document type (PATCH semantics).
149
150        Args:
151            id: Numeric ID of the document type to update.
152            name: Document-type name.
153            match: Auto-matching pattern.
154            matching_algorithm: Controls how ``match`` is applied.
155                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
156                regular-expression matching.
157            is_insensitive: When ``True``, ``match`` is case-insensitive.
158            owner: Numeric user ID to assign as owner.
159                Pass ``None`` to clear the owner.
160                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
161            set_permissions: Explicit view/change permission sets.
162                Pass ``None`` to clear all permissions (overwrite with empty).
163                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
164
165        Returns:
166            The updated :class:`~easypaperless.models.document_types.DocumentType`.
167        """
168        return cast(
169            DocumentType,
170            self._run(
171                self._async_document_types.update(
172                    id,
173                    name=name,
174                    match=match,
175                    matching_algorithm=matching_algorithm,
176                    is_insensitive=is_insensitive,
177                    owner=owner,
178                    set_permissions=set_permissions,
179                )
180            ),
181        )

Partially update a document type (PATCH semantics).

Arguments:
  • id: Numeric ID of the document type to update.
  • name: Document-type name.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.document_types.DocumentType.

def delete(self, id: int) -> None:
183    def delete(self, id: int) -> None:
184        """Delete a document type.
185
186        Args:
187            id: Numeric ID of the document type to delete.
188
189        Raises:
190            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
191        """
192        self._run(self._async_document_types.delete(id))

Delete a document type.

Arguments:
  • id: Numeric ID of the document type to delete.
Raises:
def bulk_delete(self, ids: List[int]) -> None:
194    def bulk_delete(self, ids: List[int]) -> None:
195        """Permanently delete multiple document types in a single request.
196
197        Args:
198            ids: List of document type IDs to delete.
199        """
200        self._run(self._async_document_types.bulk_delete(ids))

Permanently delete multiple document types in a single request.

Arguments:
  • ids: List of document type IDs to delete.
def bulk_set_permissions( self, ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
202    def bulk_set_permissions(
203        self,
204        ids: List[int],
205        *,
206        set_permissions: SetPermissions | Unset = UNSET,
207        owner: int | None | Unset = UNSET,
208        merge: bool = False,
209    ) -> None:
210        """Set permissions and/or owner on multiple document types.
211
212        Args:
213            ids: List of document type IDs to modify.
214            set_permissions: Explicit view/change permission sets.
215                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
216            owner: Numeric user ID to assign as owner.
217                Pass ``None`` to clear the owner.
218                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
219            merge: When ``True``, new permissions are merged with existing ones.
220        """
221        self._run(
222            self._async_document_types.bulk_set_permissions(
223                ids, set_permissions=set_permissions, owner=owner, merge=merge
224            )
225        )

Set permissions and/or owner on multiple document types.

Arguments:
  • ids: List of document type IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
class SyncDocumentsResource:
 23class SyncDocumentsResource:
 24    """Sync accessor for documents: ``client.documents``."""
 25
 26    def __init__(self, async_documents: DocumentsResource, run: Any) -> None:
 27        self._async_documents = async_documents
 28        self._run = run
 29        self.notes = SyncNotesResource(async_documents.notes, run)
 30
 31    def history(
 32        self,
 33        document_id: int,
 34        *,
 35        page: int | None = None,
 36        page_size: int | None = None,
 37    ) -> PagedResult[AuditLogEntry]:
 38        """Fetch the audit log for a document.
 39
 40        The paperless-ngx ``/api/documents/{id}/history/`` endpoint returns a
 41        plain JSON array rather than a paginated envelope.  This method wraps
 42        the response into a :class:`~easypaperless.models.paged_result.PagedResult`
 43        so callers always receive a consistent return type.
 44
 45        Args:
 46            document_id: Numeric ID of the document whose history to retrieve.
 47            page: Forwarded to the API as a query parameter when provided.
 48                Effect depends on the paperless-ngx version; the server may
 49                ignore this parameter.
 50            page_size: Forwarded to the API as a query parameter when provided.
 51
 52        Returns:
 53            :class:`~easypaperless.models.paged_result.PagedResult` of
 54            :class:`~easypaperless.models.documents.AuditLogEntry` objects,
 55            ordered by timestamp descending.
 56
 57        Raises:
 58            ~easypaperless.exceptions.NotFoundError: If no document exists
 59                with that ID.
 60        """
 61        return cast(
 62            PagedResult[AuditLogEntry],
 63            self._run(self._async_documents.history(document_id, page=page, page_size=page_size)),
 64        )
 65
 66    def get(self, id: int, *, include_metadata: bool = False, full_perms: bool = False) -> Document:
 67        """Fetch a single document by its ID.
 68
 69        Args:
 70            id: Numeric paperless-ngx document ID.
 71            include_metadata: When ``True``, the extended file-level metadata
 72                is fetched concurrently and attached to the document.
 73                Default: ``False``.
 74            full_perms: When ``True``, paperless-ngx returns the full view/change
 75                permissions, available as ``Document.permissions``. paperless-ngx
 76                then omits ``user_can_change`` and ``is_shared_by_requester``
 77                (both ``None`` on the model). Default: ``False``.
 78
 79        Returns:
 80            The :class:`~easypaperless.models.documents.Document` with the
 81            given ID.
 82
 83        Raises:
 84            ~easypaperless.exceptions.NotFoundError: If no document exists
 85                with that ID.
 86        """
 87        return cast(
 88            Document,
 89            self._run(
 90                self._async_documents.get(
 91                    id, include_metadata=include_metadata, full_perms=full_perms
 92                )
 93            ),
 94        )
 95
 96    def get_metadata(self, id: int) -> DocumentMetadata:
 97        """Fetch the extended file-level metadata for a document.
 98
 99        Args:
100            id: Numeric paperless-ngx document ID.
101
102        Returns:
103            A :class:`~easypaperless.models.documents.DocumentMetadata` instance.
104
105        Raises:
106            ~easypaperless.exceptions.NotFoundError: If no document exists
107                with that ID.
108        """
109        return cast(DocumentMetadata, self._run(self._async_documents.get_metadata(id)))
110
111    def list(
112        self,
113        *,
114        search: str | None = None,
115        search_mode: str = "title_or_content",
116        ids: List[int] | None = None,
117        tags: List[int | str] | None = None,
118        any_tags: List[int | str] | None = None,
119        exclude_tags: List[int | str] | None = None,
120        correspondent: int | str | None | Unset = UNSET,
121        any_correspondent: List[int | str] | None = None,
122        exclude_correspondents: List[int | str] | None = None,
123        document_type: int | str | None | Unset = UNSET,
124        document_type_name_contains: str | None = None,
125        document_type_name_exact: str | None = None,
126        any_document_type: List[int | str] | None = None,
127        exclude_document_types: List[int | str] | None = None,
128        storage_path: int | str | None | Unset = UNSET,
129        any_storage_paths: List[int | str] | None = None,
130        exclude_storage_paths: List[int | str] | None = None,
131        owner: int | None | Unset = UNSET,
132        exclude_owners: List[int] | None = None,
133        custom_fields: List[int | str] | None = None,
134        any_custom_fields: List[int | str] | None = None,
135        exclude_custom_fields: List[int | str] | None = None,
136        custom_field_query: List[Any] | None = None,
137        archive_serial_number: int | None | Unset = UNSET,
138        archive_serial_number_from: int | None = None,
139        archive_serial_number_till: int | None = None,
140        created_after: date | str | None = None,
141        created_before: date | str | None = None,
142        added_after: date | datetime | str | None = None,
143        added_from: date | datetime | str | None = None,
144        added_before: date | datetime | str | None = None,
145        added_until: date | datetime | str | None = None,
146        modified_after: date | datetime | str | None = None,
147        modified_from: date | datetime | str | None = None,
148        modified_before: date | datetime | str | None = None,
149        modified_until: date | datetime | str | None = None,
150        checksum: str | None = None,
151        full_perms: bool = False,
152        page_size: int = 25,
153        page: int | None = None,
154        ordering: str | None = None,
155        descending: bool = False,
156        max_results: int | None = None,
157        on_page: Callable[[int, int | None], None] | None = None,
158    ) -> PagedResult[Document]:
159        """Return a filtered list of documents.
160
161        All tag, correspondent, document-type, storage-path, and custom-field
162        parameters accept either integer IDs or string names.
163
164        When ``page`` is ``None`` (the default), all pages are fetched
165        automatically and ``next`` / ``previous`` in the returned
166        :class:`~easypaperless.models.paged_result.PagedResult` are always
167        ``None`` — even if ``max_results`` truncates the final result set.
168        ``count`` always reflects the server total, not the truncated length.
169        When ``page`` is set to a specific integer, only that one page is
170        fetched and ``next`` / ``previous`` contain the raw API values.
171
172        Args:
173            search: Search string.  Behaviour depends on ``search_mode``.
174            search_mode: How ``search`` is applied.  One of:
175                ``"title_or_content"`` *(default)*, ``"title"``, ``"query"``,
176                ``"original_filename"``.
177            ids: Return only documents whose ID is in this list.
178            tags: Documents must have **all** of these tags (AND semantics).
179            any_tags: Documents must have **at least one** of these tags.
180            exclude_tags: Documents must have **none** of these tags.
181            correspondent: Filter to documents assigned to this correspondent.
182                Pass ``None`` to return only documents with no correspondent set.
183            any_correspondent: Filter to documents assigned to any of these.
184            exclude_correspondents: Exclude documents assigned to any of these.
185            document_type: Filter to documents of exactly this type.
186                Pass ``None`` to return only documents with no document type set.
187            document_type_name_contains: Case-insensitive substring filter on document type name.
188            document_type_name_exact: Case-insensitive exact match on document type name.
189            any_document_type: Filter to documents whose type is any of these.
190            exclude_document_types: Exclude documents whose type is any of these.
191            storage_path: Filter to documents assigned to this storage path.
192                Pass ``None`` to return only documents with no storage path set.
193            any_storage_paths: Filter to documents assigned to any of these paths.
194            exclude_storage_paths: Exclude documents assigned to any of these paths.
195            owner: Filter to documents owned by this user ID.
196                Pass ``None`` to return only documents with no owner set.
197            exclude_owners: Exclude documents owned by any of these user IDs.
198            custom_fields: Documents must have **all** of these custom fields set.
199            any_custom_fields: Documents must have **at least one** of these fields.
200            exclude_custom_fields: Documents must have **none** of these fields.
201            custom_field_query: Filter documents by custom field values using a nested
202                query structure. See the `paperless-ngx API docs
203                <https://docs.paperless-ngx.com/api/#filtering-by-custom-fields>`_ for
204                the query format.
205            archive_serial_number: Filter by exact archive serial number.
206                Pass ``None`` to return only documents with no ASN set.
207            archive_serial_number_from: Filter by ASN >= this value.
208            archive_serial_number_till: Filter by ASN <= this value.
209            created_after: Only documents created after this date.
210                String input must be ISO-8601: ``"YYYY-MM-DD"``.
211            created_before: Only documents created before this date.
212                String input must be ISO-8601: ``"YYYY-MM-DD"``.
213            added_after: Only documents added after this date/time.
214                String input must be ISO-8601: ``"YYYY-MM-DD"`` for date precision or
215                ``"YYYY-MM-DDTHH:MM:SS"`` for datetime precision.
216            added_from: Only documents added on or after this date/time.
217                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
218            added_before: Only documents added before this date/time.
219                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
220            added_until: Only documents added on or before this date/time.
221                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
222            modified_after: Only documents modified after this date/time.
223                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
224            modified_from: Only documents modified on or after this date/time.
225                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
226            modified_before: Only documents modified before this date/time.
227                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
228            modified_until: Only documents modified on or before this date/time.
229                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
230            checksum: MD5 checksum (hex) of the original uploaded file, matched
231                exactly but case-insensitively (sent as ``checksum__iexact``).
232                Documents in the trash are **not** found, yet paperless-ngx
233                still rejects a re-upload of the same file as a duplicate.  To
234                detect that case, catch the
235                :exc:`~easypaperless.exceptions.UploadError` of
236                ``upload(wait=True)`` (or of ``tasks.wait()``): ``err.task.result``
237                contains ``": It is a duplicate of "`` and ends in
238                ``"Note: existing document is in the trash."``, and
239                ``err.task.related_document`` is ``None`` (for a live duplicate
240                it is the existing document's ID).  ``client.trash.list()``
241                shows the trashed document; ``client.trash.restore()`` brings
242                it back.
243            full_perms: When ``True``, paperless-ngx returns the full view/change
244                permissions of every document, available as
245                ``Document.permissions``. paperless-ngx then omits
246                ``user_can_change`` and ``is_shared_by_requester`` (both ``None``
247                on the model). Default: ``False``.
248            page_size: Number of results per API page.  Default: ``25``.
249            page: Return only this specific page (1-based).
250            ordering: Field name to sort by.
251            descending: When ``True``, reverses the sort direction.
252            max_results: Stop after collecting this many documents.
253            on_page: Callback invoked after each page fetch.
254
255        Returns:
256            :class:`~easypaperless.models.paged_result.PagedResult` of
257            :class:`~easypaperless.models.documents.Document` objects.
258        """
259        return cast(
260            PagedResult[Document],
261            self._run(
262                self._async_documents.list(
263                    search=search,
264                    search_mode=search_mode,
265                    ids=ids,
266                    tags=tags,
267                    any_tags=any_tags,
268                    exclude_tags=exclude_tags,
269                    correspondent=correspondent,
270                    any_correspondent=any_correspondent,
271                    exclude_correspondents=exclude_correspondents,
272                    document_type=document_type,
273                    document_type_name_contains=document_type_name_contains,
274                    document_type_name_exact=document_type_name_exact,
275                    any_document_type=any_document_type,
276                    exclude_document_types=exclude_document_types,
277                    storage_path=storage_path,
278                    any_storage_paths=any_storage_paths,
279                    exclude_storage_paths=exclude_storage_paths,
280                    owner=owner,
281                    exclude_owners=exclude_owners,
282                    custom_fields=custom_fields,
283                    any_custom_fields=any_custom_fields,
284                    exclude_custom_fields=exclude_custom_fields,
285                    custom_field_query=custom_field_query,
286                    archive_serial_number=archive_serial_number,
287                    archive_serial_number_from=archive_serial_number_from,
288                    archive_serial_number_till=archive_serial_number_till,
289                    created_after=created_after,
290                    created_before=created_before,
291                    added_after=added_after,
292                    added_from=added_from,
293                    added_before=added_before,
294                    added_until=added_until,
295                    modified_after=modified_after,
296                    modified_from=modified_from,
297                    modified_before=modified_before,
298                    modified_until=modified_until,
299                    checksum=checksum,
300                    full_perms=full_perms,
301                    page_size=page_size,
302                    page=page,
303                    ordering=ordering,
304                    descending=descending,
305                    max_results=max_results,
306                    on_page=on_page,
307                )
308            ),
309        )
310
311    def update(
312        self,
313        id: int,
314        *,
315        title: str | Unset = UNSET,
316        content: str | Unset = UNSET,
317        created: date | str | None | Unset = UNSET,
318        correspondent: int | str | None | Unset = UNSET,
319        document_type: int | str | None | Unset = UNSET,
320        storage_path: int | str | None | Unset = UNSET,
321        tags: List[int | str] | None | Unset = UNSET,
322        archive_serial_number: int | None | Unset = UNSET,
323        custom_fields: List[dict[str, Any]] | None | Unset = UNSET,
324        owner: int | None | Unset = UNSET,
325        set_permissions: SetPermissions | None | Unset = UNSET,
326        remove_inbox_tags: bool | None | Unset = UNSET,
327    ) -> Document:
328        """Partially update a document (PATCH semantics).
329
330        Args:
331            id: Numeric ID of the document to update.
332            title: New document title.
333            content: OCR text content of the document.
334            created: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``) or a
335                :class:`~datetime.date` object.
336            correspondent: Correspondent to assign, as an ID or name.
337                Pass ``None`` to clear the correspondent.
338            document_type: Document type to assign, as an ID or name.
339                Pass ``None`` to clear the document type.
340            storage_path: Storage path to assign, as an ID or name.
341                Pass ``None`` to clear the storage path.
342            tags: Full replacement list of tags (IDs or names).
343            archive_serial_number: Archive serial number to assign.
344                Pass ``None`` to clear the archive serial number.
345            custom_fields: List of ``{"field": <field_id>, "value": ...}`` dicts.
346            owner: Numeric user ID to assign as document owner.
347                Pass ``None`` to clear the owner.
348            set_permissions: Explicit view/change permission sets.
349                Pass ``None`` to clear all permissions (overwrite with empty).
350                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
351                The given sets replace the document's current view and change
352                users and groups.  Together with ``owner`` everything goes out
353                in one PATCH, which paperless-ngx applies as a whole.
354            remove_inbox_tags: When ``True``, removes all inbox tags from the document.
355
356        Returns:
357            The updated :class:`~easypaperless.models.documents.Document`.
358        """
359        return cast(
360            Document,
361            self._run(
362                self._async_documents.update(
363                    id,
364                    title=title,
365                    content=content,
366                    created=created,
367                    correspondent=correspondent,
368                    document_type=document_type,
369                    storage_path=storage_path,
370                    tags=tags,
371                    archive_serial_number=archive_serial_number,
372                    custom_fields=custom_fields,
373                    owner=owner,
374                    set_permissions=set_permissions,
375                    remove_inbox_tags=remove_inbox_tags,
376                )
377            ),
378        )
379
380    def delete(self, id: int) -> None:
381        """Permanently delete a document.
382
383        Args:
384            id: Numeric ID of the document to delete.
385
386        Raises:
387            ~easypaperless.exceptions.NotFoundError: If no document exists
388                with that ID.
389        """
390        self._run(self._async_documents.delete(id))
391
392    def download(self, id: int, *, original: bool = False) -> bytes:
393        """Download the binary content of a document.
394
395        Args:
396            id: Numeric ID of the document to download.
397            original: If ``False`` *(default)*, returns the archived PDF
398                (``GET /documents/{id}/download/``).
399                If ``True``, returns the original uploaded file
400                (``GET /documents/{id}/download/?original=true``).
401
402        Returns:
403            Raw file bytes.
404        """
405        return cast(bytes, self._run(self._async_documents.download(id, original=original)))
406
407    def thumbnail(self, id: int) -> bytes:
408        """Fetch the thumbnail image of a document.
409
410        Args:
411            id: Numeric ID of the document whose thumbnail to retrieve.
412
413        Returns:
414            Raw binary content of the thumbnail image.
415
416        Raises:
417            ~easypaperless.exceptions.NotFoundError: If no document exists
418                with that ID.
419            ~easypaperless.exceptions.ServerResponseError: If the server returns an
420                HTML page (e.g. an auth redirect) instead of the image.
421        """
422        return cast(bytes, self._run(self._async_documents.thumbnail(id)))
423
424    def upload(
425        self,
426        file: str | Path | bytes,
427        *,
428        filename: str | None = None,
429        content_type: str | None = None,
430        request_timeout: float | None = None,
431        title: str | Unset = UNSET,
432        created: date | str | None = None,
433        correspondent: int | str | None | Unset = UNSET,
434        document_type: int | str | None | Unset = UNSET,
435        storage_path: int | str | None | Unset = UNSET,
436        tags: List[int | str] | None = None,
437        archive_serial_number: int | None | Unset = UNSET,
438        custom_fields: List[dict[str, Any]] | None = None,
439        wait: bool = False,
440        poll_interval: float | None = None,
441        poll_timeout: float | None = None,
442    ) -> str | Document:
443        """Upload a document to paperless-ngx.
444
445        The upload request is never retried automatically, whatever the
446        client's ``retry_attempts`` / ``tenacity_retrying`` settings: if the
447        connection fails after paperless-ngx has accepted the file, a retry
448        would create a duplicate.  A failed upload raises (e.g.
449        :exc:`~easypaperless.exceptions.TransportTimeoutError`) so you can
450        decide whether to check for the document and upload again.
451
452        Args:
453            file: Path to the file to upload (``str`` or :class:`~pathlib.Path`),
454                or the file content as ``bytes``.  Bytes are sent directly; no
455                temporary file is written.
456            filename: File name sent to paperless-ngx.  Required when *file* is
457                ``bytes`` (omitting it raises
458                :exc:`~easypaperless.exceptions.ValidationError` before any
459                request).  For a path, overrides the name taken from the path.
460            content_type: MIME type of the file part, sent as given (e.g.
461                ``"application/pdf"``).  When omitted, it is guessed from the
462                file name as before.  paperless-ngx detects the file type from
463                the bytes and does not rely on this value to accept the file.
464            request_timeout: HTTP timeout in seconds for the upload request
465                only, overriding the client's ``timeout`` for this call.  Does
466                not affect task polling (see ``poll_timeout``).  When omitted,
467                the client's ``timeout`` applies.
468            title: Title to assign to the document.
469            created: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``) or a
470                :class:`~datetime.date` object.
471            correspondent: Correspondent to assign, as an ID or name.
472            document_type: Document type to assign, as an ID or name.
473            storage_path: Storage path to assign, as an ID or name.
474            tags: Tags to assign, as IDs or names.
475            archive_serial_number: Archive serial number to assign.
476            custom_fields: List of ``{"field": <field_id>, "value": ...}`` dicts.
477            wait: If ``False`` *(default)*, returns immediately with the task ID.
478                If ``True``, polls until processing completes.
479            poll_interval: Seconds between task-status checks while waiting for
480                processing to complete (requires ``wait=True``). Overrides the
481                client-level default. When omitted, falls back to the client-level
482                ``poll_interval`` (``2.0`` s unless changed at construction).
483            poll_timeout: Maximum seconds to wait before raising
484                :exc:`~easypaperless.exceptions.TaskTimeoutError` (requires
485                ``wait=True``). Overrides the client-level default. When omitted,
486                falls back to the client-level ``poll_timeout`` (``60.0`` s unless
487                changed at construction).
488
489        Returns:
490            The Celery task ID string when ``wait=False``, or the fully
491            processed :class:`~easypaperless.models.documents.Document`
492            when ``wait=True``.
493
494        Raises:
495            ~easypaperless.exceptions.ValidationError: If *file* is ``bytes``
496                and no *filename* is given.
497            ~easypaperless.exceptions.BadRequestError: If paperless-ngx rejects
498                the file before processing starts, e.g. an unsupported file
499                type or an empty file (``err.field_errors["document"]``).
500            ~easypaperless.exceptions.UploadError: If processing fails;
501                ``err.task`` holds the task with paperless-ngx's ``result``
502                unaltered.  For a duplicate, ``err.task.result`` contains
503                ``": It is a duplicate of "`` and ``err.task.related_document``
504                is the existing document's ID (``None`` if that document is
505                in the trash).
506            ~easypaperless.exceptions.TaskTimeoutError: If timeout is exceeded;
507                resume with ``client.tasks.wait(err.task_id)``.
508        """
509        return cast(
510            str | Document,
511            self._run(
512                self._async_documents.upload(
513                    file,
514                    filename=filename,
515                    content_type=content_type,
516                    request_timeout=request_timeout,
517                    title=title,
518                    created=created,
519                    correspondent=correspondent,
520                    document_type=document_type,
521                    storage_path=storage_path,
522                    tags=tags,
523                    archive_serial_number=archive_serial_number,
524                    custom_fields=custom_fields,
525                    wait=wait,
526                    poll_interval=poll_interval,
527                    poll_timeout=poll_timeout,
528                )
529            ),
530        )
531
532    def bulk_add_tag(self, document_ids: List[int], tag: int | str) -> None:
533        """Add a tag to multiple documents in a single request.
534
535        Args:
536            document_ids: List of document IDs to tag.
537            tag: Tag to add, as an ID or name.
538        """
539        self._run(self._async_documents.bulk_add_tag(document_ids, tag))
540
541    def bulk_remove_tag(self, document_ids: List[int], tag: int | str) -> None:
542        """Remove a tag from multiple documents in a single request.
543
544        Args:
545            document_ids: List of document IDs to un-tag.
546            tag: Tag to remove, as an ID or name.
547        """
548        self._run(self._async_documents.bulk_remove_tag(document_ids, tag))
549
550    def bulk_modify_tags(
551        self,
552        document_ids: List[int],
553        *,
554        add_tags: List[int | str] | None = None,
555        remove_tags: List[int | str] | None = None,
556    ) -> None:
557        """Add and/or remove tags on multiple documents atomically.
558
559        Args:
560            document_ids: List of document IDs to modify.
561            add_tags: Tags to add, as IDs or names.
562            remove_tags: Tags to remove, as IDs or names.
563        """
564        self._run(
565            self._async_documents.bulk_modify_tags(
566                document_ids, add_tags=add_tags, remove_tags=remove_tags
567            )
568        )
569
570    def bulk_delete(self, document_ids: List[int]) -> None:
571        """Permanently delete multiple documents in a single request.
572
573        Args:
574            document_ids: List of document IDs to delete.
575        """
576        self._run(self._async_documents.bulk_delete(document_ids))
577
578    def bulk_set_correspondent(
579        self, document_ids: List[int], correspondent: int | str | None
580    ) -> None:
581        """Assign a correspondent to multiple documents in a single request.
582
583        Args:
584            document_ids: List of document IDs to modify.
585            correspondent: Correspondent to assign, as an ID or name.
586                Pass ``None`` to clear.
587        """
588        self._run(self._async_documents.bulk_set_correspondent(document_ids, correspondent))
589
590    def bulk_set_document_type(
591        self, document_ids: List[int], document_type: int | str | None
592    ) -> None:
593        """Assign a document type to multiple documents in a single request.
594
595        Args:
596            document_ids: List of document IDs to modify.
597            document_type: Document type to assign, as an ID or name.
598                Pass ``None`` to clear.
599        """
600        self._run(self._async_documents.bulk_set_document_type(document_ids, document_type))
601
602    def bulk_set_storage_path(
603        self, document_ids: List[int], storage_path: int | str | None
604    ) -> None:
605        """Assign a storage path to multiple documents in a single request.
606
607        Args:
608            document_ids: List of document IDs to modify.
609            storage_path: Storage path to assign, as an ID or name.
610                Pass ``None`` to clear.
611        """
612        self._run(self._async_documents.bulk_set_storage_path(document_ids, storage_path))
613
614    def bulk_modify_custom_fields(
615        self,
616        document_ids: List[int],
617        *,
618        add_fields: List[dict[str, Any]] | None = None,
619        remove_fields: List[int] | None = None,
620    ) -> None:
621        """Add and/or remove custom field values on multiple documents.
622
623        Args:
624            document_ids: List of document IDs to modify.
625            add_fields: Custom-field value dicts to add.
626            remove_fields: Custom-field IDs whose values should be removed.
627        """
628        self._run(
629            self._async_documents.bulk_modify_custom_fields(
630                document_ids, add_fields=add_fields, remove_fields=remove_fields
631            )
632        )
633
634    def bulk_set_permissions(
635        self,
636        document_ids: List[int],
637        *,
638        set_permissions: SetPermissions | Unset = UNSET,
639        owner: int | None | Unset = UNSET,
640        merge: bool = False,
641    ) -> None:
642        """Set permissions and/or owner on multiple documents.
643
644        Args:
645            document_ids: List of document IDs to modify.
646            set_permissions: Explicit view/change permission sets.
647                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
648            owner: Numeric user ID to assign as document owner.
649                Pass ``None`` to clear the owner.
650                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
651            merge: When ``True``, new permissions are merged with existing ones.
652        """
653        self._run(
654            self._async_documents.bulk_set_permissions(
655                document_ids,
656                set_permissions=set_permissions,
657                owner=owner,
658                merge=merge,
659            )
660        )
661
662    def bulk_download(
663        self,
664        document_ids: List[int],
665        *,
666        content: Literal["archive", "originals", "both"] = "archive",
667        compression: Literal["none", "deflated", "bzip2", "lzma"] = "none",
668        follow_formatting: bool = False,
669    ) -> bytes:
670        """Download multiple documents as a single ZIP archive.
671
672        Args:
673            document_ids: List of document IDs to include in the ZIP.
674            content: File variant to include.  One of ``"archive"`` *(default)*,
675                ``"originals"``, or ``"both"``.
676            compression: ZIP compression algorithm.  One of ``"none"`` *(default)*,
677                ``"deflated"``, ``"bzip2"``, or ``"lzma"``.
678            follow_formatting: When ``True``, filenames inside the ZIP follow
679                the storage path formatting configured in paperless-ngx.
680                Default: ``False``.
681
682        Returns:
683            Raw bytes of the ZIP archive.
684        """
685        return cast(
686            bytes,
687            self._run(
688                self._async_documents.bulk_download(
689                    document_ids,
690                    content=content,
691                    compression=compression,
692                    follow_formatting=follow_formatting,
693                )
694            ),
695        )

Sync accessor for documents: client.documents.

SyncDocumentsResource( async_documents: DocumentsResource, run: Any)
26    def __init__(self, async_documents: DocumentsResource, run: Any) -> None:
27        self._async_documents = async_documents
28        self._run = run
29        self.notes = SyncNotesResource(async_documents.notes, run)
notes
def history( self, document_id: int, *, page: int | None = None, page_size: int | None = None) -> easypaperless.PagedResult[AuditLogEntry]:
31    def history(
32        self,
33        document_id: int,
34        *,
35        page: int | None = None,
36        page_size: int | None = None,
37    ) -> PagedResult[AuditLogEntry]:
38        """Fetch the audit log for a document.
39
40        The paperless-ngx ``/api/documents/{id}/history/`` endpoint returns a
41        plain JSON array rather than a paginated envelope.  This method wraps
42        the response into a :class:`~easypaperless.models.paged_result.PagedResult`
43        so callers always receive a consistent return type.
44
45        Args:
46            document_id: Numeric ID of the document whose history to retrieve.
47            page: Forwarded to the API as a query parameter when provided.
48                Effect depends on the paperless-ngx version; the server may
49                ignore this parameter.
50            page_size: Forwarded to the API as a query parameter when provided.
51
52        Returns:
53            :class:`~easypaperless.models.paged_result.PagedResult` of
54            :class:`~easypaperless.models.documents.AuditLogEntry` objects,
55            ordered by timestamp descending.
56
57        Raises:
58            ~easypaperless.exceptions.NotFoundError: If no document exists
59                with that ID.
60        """
61        return cast(
62            PagedResult[AuditLogEntry],
63            self._run(self._async_documents.history(document_id, page=page, page_size=page_size)),
64        )

Fetch the audit log for a document.

The paperless-ngx /api/documents/{id}/history/ endpoint returns a plain JSON array rather than a paginated envelope. This method wraps the response into a ~easypaperless.models.paged_result.PagedResult so callers always receive a consistent return type.

Arguments:
  • document_id: Numeric ID of the document whose history to retrieve.
  • page: Forwarded to the API as a query parameter when provided. Effect depends on the paperless-ngx version; the server may ignore this parameter.
  • page_size: Forwarded to the API as a query parameter when provided.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.documents.AuditLogEntry objects, ordered by timestamp descending.

Raises:
def get( self, id: int, *, include_metadata: bool = False, full_perms: bool = False) -> easypaperless.Document:
66    def get(self, id: int, *, include_metadata: bool = False, full_perms: bool = False) -> Document:
67        """Fetch a single document by its ID.
68
69        Args:
70            id: Numeric paperless-ngx document ID.
71            include_metadata: When ``True``, the extended file-level metadata
72                is fetched concurrently and attached to the document.
73                Default: ``False``.
74            full_perms: When ``True``, paperless-ngx returns the full view/change
75                permissions, available as ``Document.permissions``. paperless-ngx
76                then omits ``user_can_change`` and ``is_shared_by_requester``
77                (both ``None`` on the model). Default: ``False``.
78
79        Returns:
80            The :class:`~easypaperless.models.documents.Document` with the
81            given ID.
82
83        Raises:
84            ~easypaperless.exceptions.NotFoundError: If no document exists
85                with that ID.
86        """
87        return cast(
88            Document,
89            self._run(
90                self._async_documents.get(
91                    id, include_metadata=include_metadata, full_perms=full_perms
92                )
93            ),
94        )

Fetch a single document by its ID.

Arguments:
  • id: Numeric paperless-ngx document ID.
  • include_metadata: When True, the extended file-level metadata is fetched concurrently and attached to the document. Default: False.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as Document.permissions. paperless-ngx then omits user_can_change and is_shared_by_requester (both None on the model). Default: False.
Returns:

The ~easypaperless.models.documents.Document with the given ID.

Raises:
def get_metadata(self, id: int) -> easypaperless.DocumentMetadata:
 96    def get_metadata(self, id: int) -> DocumentMetadata:
 97        """Fetch the extended file-level metadata for a document.
 98
 99        Args:
100            id: Numeric paperless-ngx document ID.
101
102        Returns:
103            A :class:`~easypaperless.models.documents.DocumentMetadata` instance.
104
105        Raises:
106            ~easypaperless.exceptions.NotFoundError: If no document exists
107                with that ID.
108        """
109        return cast(DocumentMetadata, self._run(self._async_documents.get_metadata(id)))

Fetch the extended file-level metadata for a document.

Arguments:
  • id: Numeric paperless-ngx document ID.
Returns:

A ~easypaperless.models.documents.DocumentMetadata instance.

Raises:
def list( self, *, search: str | None = None, search_mode: str = 'title_or_content', ids: Optional[List[int]] = None, tags: Optional[List[Union[str, int]]] = None, any_tags: Optional[List[Union[str, int]]] = None, exclude_tags: Optional[List[Union[str, int]]] = None, correspondent: int | str | None | easypaperless.Unset = UNSET, any_correspondent: Optional[List[Union[str, int]]] = None, exclude_correspondents: Optional[List[Union[str, int]]] = None, document_type: int | str | None | easypaperless.Unset = UNSET, document_type_name_contains: str | None = None, document_type_name_exact: str | None = None, any_document_type: Optional[List[Union[str, int]]] = None, exclude_document_types: Optional[List[Union[str, int]]] = None, storage_path: int | str | None | easypaperless.Unset = UNSET, any_storage_paths: Optional[List[Union[str, int]]] = None, exclude_storage_paths: Optional[List[Union[str, int]]] = None, owner: int | None | easypaperless.Unset = UNSET, exclude_owners: Optional[List[int]] = None, custom_fields: Optional[List[Union[str, int]]] = None, any_custom_fields: Optional[List[Union[str, int]]] = None, exclude_custom_fields: Optional[List[Union[str, int]]] = None, custom_field_query: Optional[List[Any]] = None, archive_serial_number: int | None | easypaperless.Unset = UNSET, archive_serial_number_from: int | None = None, archive_serial_number_till: int | None = None, created_after: datetime.date | str | None = None, created_before: datetime.date | str | None = None, added_after: datetime.date | datetime.datetime | str | None = None, added_from: datetime.date | datetime.datetime | str | None = None, added_before: datetime.date | datetime.datetime | str | None = None, added_until: datetime.date | datetime.datetime | str | None = None, modified_after: datetime.date | datetime.datetime | str | None = None, modified_from: datetime.date | datetime.datetime | str | None = None, modified_before: datetime.date | datetime.datetime | str | None = None, modified_until: datetime.date | datetime.datetime | str | None = None, checksum: str | None = None, full_perms: bool = False, page_size: int = 25, page: int | None = None, ordering: str | None = None, descending: bool = False, max_results: int | None = None, on_page: Callable[[int, int | None], None] | None = None) -> easypaperless.PagedResult[Document]:
111    def list(
112        self,
113        *,
114        search: str | None = None,
115        search_mode: str = "title_or_content",
116        ids: List[int] | None = None,
117        tags: List[int | str] | None = None,
118        any_tags: List[int | str] | None = None,
119        exclude_tags: List[int | str] | None = None,
120        correspondent: int | str | None | Unset = UNSET,
121        any_correspondent: List[int | str] | None = None,
122        exclude_correspondents: List[int | str] | None = None,
123        document_type: int | str | None | Unset = UNSET,
124        document_type_name_contains: str | None = None,
125        document_type_name_exact: str | None = None,
126        any_document_type: List[int | str] | None = None,
127        exclude_document_types: List[int | str] | None = None,
128        storage_path: int | str | None | Unset = UNSET,
129        any_storage_paths: List[int | str] | None = None,
130        exclude_storage_paths: List[int | str] | None = None,
131        owner: int | None | Unset = UNSET,
132        exclude_owners: List[int] | None = None,
133        custom_fields: List[int | str] | None = None,
134        any_custom_fields: List[int | str] | None = None,
135        exclude_custom_fields: List[int | str] | None = None,
136        custom_field_query: List[Any] | None = None,
137        archive_serial_number: int | None | Unset = UNSET,
138        archive_serial_number_from: int | None = None,
139        archive_serial_number_till: int | None = None,
140        created_after: date | str | None = None,
141        created_before: date | str | None = None,
142        added_after: date | datetime | str | None = None,
143        added_from: date | datetime | str | None = None,
144        added_before: date | datetime | str | None = None,
145        added_until: date | datetime | str | None = None,
146        modified_after: date | datetime | str | None = None,
147        modified_from: date | datetime | str | None = None,
148        modified_before: date | datetime | str | None = None,
149        modified_until: date | datetime | str | None = None,
150        checksum: str | None = None,
151        full_perms: bool = False,
152        page_size: int = 25,
153        page: int | None = None,
154        ordering: str | None = None,
155        descending: bool = False,
156        max_results: int | None = None,
157        on_page: Callable[[int, int | None], None] | None = None,
158    ) -> PagedResult[Document]:
159        """Return a filtered list of documents.
160
161        All tag, correspondent, document-type, storage-path, and custom-field
162        parameters accept either integer IDs or string names.
163
164        When ``page`` is ``None`` (the default), all pages are fetched
165        automatically and ``next`` / ``previous`` in the returned
166        :class:`~easypaperless.models.paged_result.PagedResult` are always
167        ``None`` — even if ``max_results`` truncates the final result set.
168        ``count`` always reflects the server total, not the truncated length.
169        When ``page`` is set to a specific integer, only that one page is
170        fetched and ``next`` / ``previous`` contain the raw API values.
171
172        Args:
173            search: Search string.  Behaviour depends on ``search_mode``.
174            search_mode: How ``search`` is applied.  One of:
175                ``"title_or_content"`` *(default)*, ``"title"``, ``"query"``,
176                ``"original_filename"``.
177            ids: Return only documents whose ID is in this list.
178            tags: Documents must have **all** of these tags (AND semantics).
179            any_tags: Documents must have **at least one** of these tags.
180            exclude_tags: Documents must have **none** of these tags.
181            correspondent: Filter to documents assigned to this correspondent.
182                Pass ``None`` to return only documents with no correspondent set.
183            any_correspondent: Filter to documents assigned to any of these.
184            exclude_correspondents: Exclude documents assigned to any of these.
185            document_type: Filter to documents of exactly this type.
186                Pass ``None`` to return only documents with no document type set.
187            document_type_name_contains: Case-insensitive substring filter on document type name.
188            document_type_name_exact: Case-insensitive exact match on document type name.
189            any_document_type: Filter to documents whose type is any of these.
190            exclude_document_types: Exclude documents whose type is any of these.
191            storage_path: Filter to documents assigned to this storage path.
192                Pass ``None`` to return only documents with no storage path set.
193            any_storage_paths: Filter to documents assigned to any of these paths.
194            exclude_storage_paths: Exclude documents assigned to any of these paths.
195            owner: Filter to documents owned by this user ID.
196                Pass ``None`` to return only documents with no owner set.
197            exclude_owners: Exclude documents owned by any of these user IDs.
198            custom_fields: Documents must have **all** of these custom fields set.
199            any_custom_fields: Documents must have **at least one** of these fields.
200            exclude_custom_fields: Documents must have **none** of these fields.
201            custom_field_query: Filter documents by custom field values using a nested
202                query structure. See the `paperless-ngx API docs
203                <https://docs.paperless-ngx.com/api/#filtering-by-custom-fields>`_ for
204                the query format.
205            archive_serial_number: Filter by exact archive serial number.
206                Pass ``None`` to return only documents with no ASN set.
207            archive_serial_number_from: Filter by ASN >= this value.
208            archive_serial_number_till: Filter by ASN <= this value.
209            created_after: Only documents created after this date.
210                String input must be ISO-8601: ``"YYYY-MM-DD"``.
211            created_before: Only documents created before this date.
212                String input must be ISO-8601: ``"YYYY-MM-DD"``.
213            added_after: Only documents added after this date/time.
214                String input must be ISO-8601: ``"YYYY-MM-DD"`` for date precision or
215                ``"YYYY-MM-DDTHH:MM:SS"`` for datetime precision.
216            added_from: Only documents added on or after this date/time.
217                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
218            added_before: Only documents added before this date/time.
219                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
220            added_until: Only documents added on or before this date/time.
221                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
222            modified_after: Only documents modified after this date/time.
223                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
224            modified_from: Only documents modified on or after this date/time.
225                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
226            modified_before: Only documents modified before this date/time.
227                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
228            modified_until: Only documents modified on or before this date/time.
229                String input must be ISO-8601: ``"YYYY-MM-DD"`` or ``"YYYY-MM-DDTHH:MM:SS"``.
230            checksum: MD5 checksum (hex) of the original uploaded file, matched
231                exactly but case-insensitively (sent as ``checksum__iexact``).
232                Documents in the trash are **not** found, yet paperless-ngx
233                still rejects a re-upload of the same file as a duplicate.  To
234                detect that case, catch the
235                :exc:`~easypaperless.exceptions.UploadError` of
236                ``upload(wait=True)`` (or of ``tasks.wait()``): ``err.task.result``
237                contains ``": It is a duplicate of "`` and ends in
238                ``"Note: existing document is in the trash."``, and
239                ``err.task.related_document`` is ``None`` (for a live duplicate
240                it is the existing document's ID).  ``client.trash.list()``
241                shows the trashed document; ``client.trash.restore()`` brings
242                it back.
243            full_perms: When ``True``, paperless-ngx returns the full view/change
244                permissions of every document, available as
245                ``Document.permissions``. paperless-ngx then omits
246                ``user_can_change`` and ``is_shared_by_requester`` (both ``None``
247                on the model). Default: ``False``.
248            page_size: Number of results per API page.  Default: ``25``.
249            page: Return only this specific page (1-based).
250            ordering: Field name to sort by.
251            descending: When ``True``, reverses the sort direction.
252            max_results: Stop after collecting this many documents.
253            on_page: Callback invoked after each page fetch.
254
255        Returns:
256            :class:`~easypaperless.models.paged_result.PagedResult` of
257            :class:`~easypaperless.models.documents.Document` objects.
258        """
259        return cast(
260            PagedResult[Document],
261            self._run(
262                self._async_documents.list(
263                    search=search,
264                    search_mode=search_mode,
265                    ids=ids,
266                    tags=tags,
267                    any_tags=any_tags,
268                    exclude_tags=exclude_tags,
269                    correspondent=correspondent,
270                    any_correspondent=any_correspondent,
271                    exclude_correspondents=exclude_correspondents,
272                    document_type=document_type,
273                    document_type_name_contains=document_type_name_contains,
274                    document_type_name_exact=document_type_name_exact,
275                    any_document_type=any_document_type,
276                    exclude_document_types=exclude_document_types,
277                    storage_path=storage_path,
278                    any_storage_paths=any_storage_paths,
279                    exclude_storage_paths=exclude_storage_paths,
280                    owner=owner,
281                    exclude_owners=exclude_owners,
282                    custom_fields=custom_fields,
283                    any_custom_fields=any_custom_fields,
284                    exclude_custom_fields=exclude_custom_fields,
285                    custom_field_query=custom_field_query,
286                    archive_serial_number=archive_serial_number,
287                    archive_serial_number_from=archive_serial_number_from,
288                    archive_serial_number_till=archive_serial_number_till,
289                    created_after=created_after,
290                    created_before=created_before,
291                    added_after=added_after,
292                    added_from=added_from,
293                    added_before=added_before,
294                    added_until=added_until,
295                    modified_after=modified_after,
296                    modified_from=modified_from,
297                    modified_before=modified_before,
298                    modified_until=modified_until,
299                    checksum=checksum,
300                    full_perms=full_perms,
301                    page_size=page_size,
302                    page=page,
303                    ordering=ordering,
304                    descending=descending,
305                    max_results=max_results,
306                    on_page=on_page,
307                )
308            ),
309        )

Return a filtered list of documents.

All tag, correspondent, document-type, storage-path, and custom-field parameters accept either integer IDs or string names.

When page is None (the default), all pages are fetched automatically and next / previous in the returned ~easypaperless.models.paged_result.PagedResult are always None — even if max_results truncates the final result set. count always reflects the server total, not the truncated length. When page is set to a specific integer, only that one page is fetched and next / previous contain the raw API values.

Arguments:
  • search: Search string. Behaviour depends on search_mode.
  • search_mode: How search is applied. One of: "title_or_content" (default), "title", "query", "original_filename".
  • ids: Return only documents whose ID is in this list.
  • tags: Documents must have all of these tags (AND semantics).
  • any_tags: Documents must have at least one of these tags.
  • exclude_tags: Documents must have none of these tags.
  • correspondent: Filter to documents assigned to this correspondent. Pass None to return only documents with no correspondent set.
  • any_correspondent: Filter to documents assigned to any of these.
  • exclude_correspondents: Exclude documents assigned to any of these.
  • document_type: Filter to documents of exactly this type. Pass None to return only documents with no document type set.
  • document_type_name_contains: Case-insensitive substring filter on document type name.
  • document_type_name_exact: Case-insensitive exact match on document type name.
  • any_document_type: Filter to documents whose type is any of these.
  • exclude_document_types: Exclude documents whose type is any of these.
  • storage_path: Filter to documents assigned to this storage path. Pass None to return only documents with no storage path set.
  • any_storage_paths: Filter to documents assigned to any of these paths.
  • exclude_storage_paths: Exclude documents assigned to any of these paths.
  • owner: Filter to documents owned by this user ID. Pass None to return only documents with no owner set.
  • exclude_owners: Exclude documents owned by any of these user IDs.
  • custom_fields: Documents must have all of these custom fields set.
  • any_custom_fields: Documents must have at least one of these fields.
  • exclude_custom_fields: Documents must have none of these fields.
  • custom_field_query: Filter documents by custom field values using a nested query structure. See the paperless-ngx API docs for the query format.
  • archive_serial_number: Filter by exact archive serial number. Pass None to return only documents with no ASN set.
  • archive_serial_number_from: Filter by ASN >= this value.
  • archive_serial_number_till: Filter by ASN <= this value.
  • created_after: Only documents created after this date. String input must be ISO-8601: "YYYY-MM-DD".
  • created_before: Only documents created before this date. String input must be ISO-8601: "YYYY-MM-DD".
  • added_after: Only documents added after this date/time. String input must be ISO-8601: "YYYY-MM-DD" for date precision or "YYYY-MM-DDTHH:MM:SS" for datetime precision.
  • added_from: Only documents added on or after this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • added_before: Only documents added before this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • added_until: Only documents added on or before this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • modified_after: Only documents modified after this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • modified_from: Only documents modified on or after this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • modified_before: Only documents modified before this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • modified_until: Only documents modified on or before this date/time. String input must be ISO-8601: "YYYY-MM-DD" or "YYYY-MM-DDTHH:MM:SS".
  • checksum: MD5 checksum (hex) of the original uploaded file, matched exactly but case-insensitively (sent as checksum__iexact). Documents in the trash are not found, yet paperless-ngx still rejects a re-upload of the same file as a duplicate. To detect that case, catch the ~easypaperless.exceptions.UploadError of upload(wait=True) (or of tasks.wait()): err.task.result contains ": It is a duplicate of " and ends in "Note: existing document is in the trash.", and err.task.related_document is None (for a live duplicate it is the existing document's ID). client.trash.list() shows the trashed document; client.trash.restore() brings it back.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every document, available as Document.permissions. paperless-ngx then omits user_can_change and is_shared_by_requester (both None on the model). Default: False.
  • page_size: Number of results per API page. Default: 25.
  • page: Return only this specific page (1-based).
  • ordering: Field name to sort by.
  • descending: When True, reverses the sort direction.
  • max_results: Stop after collecting this many documents.
  • on_page: Callback invoked after each page fetch.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.documents.Document objects.

def update( self, id: int, *, title: str | easypaperless.Unset = UNSET, content: str | easypaperless.Unset = UNSET, created: datetime.date | str | None | easypaperless.Unset = UNSET, correspondent: int | str | None | easypaperless.Unset = UNSET, document_type: int | str | None | easypaperless.Unset = UNSET, storage_path: int | str | None | easypaperless.Unset = UNSET, tags: Union[List[Union[str, int]], NoneType, easypaperless.Unset] = UNSET, archive_serial_number: int | None | easypaperless.Unset = UNSET, custom_fields: Union[List[dict[str, Any]], NoneType, easypaperless.Unset] = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET, remove_inbox_tags: bool | None | easypaperless.Unset = UNSET) -> easypaperless.Document:
311    def update(
312        self,
313        id: int,
314        *,
315        title: str | Unset = UNSET,
316        content: str | Unset = UNSET,
317        created: date | str | None | Unset = UNSET,
318        correspondent: int | str | None | Unset = UNSET,
319        document_type: int | str | None | Unset = UNSET,
320        storage_path: int | str | None | Unset = UNSET,
321        tags: List[int | str] | None | Unset = UNSET,
322        archive_serial_number: int | None | Unset = UNSET,
323        custom_fields: List[dict[str, Any]] | None | Unset = UNSET,
324        owner: int | None | Unset = UNSET,
325        set_permissions: SetPermissions | None | Unset = UNSET,
326        remove_inbox_tags: bool | None | Unset = UNSET,
327    ) -> Document:
328        """Partially update a document (PATCH semantics).
329
330        Args:
331            id: Numeric ID of the document to update.
332            title: New document title.
333            content: OCR text content of the document.
334            created: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``) or a
335                :class:`~datetime.date` object.
336            correspondent: Correspondent to assign, as an ID or name.
337                Pass ``None`` to clear the correspondent.
338            document_type: Document type to assign, as an ID or name.
339                Pass ``None`` to clear the document type.
340            storage_path: Storage path to assign, as an ID or name.
341                Pass ``None`` to clear the storage path.
342            tags: Full replacement list of tags (IDs or names).
343            archive_serial_number: Archive serial number to assign.
344                Pass ``None`` to clear the archive serial number.
345            custom_fields: List of ``{"field": <field_id>, "value": ...}`` dicts.
346            owner: Numeric user ID to assign as document owner.
347                Pass ``None`` to clear the owner.
348            set_permissions: Explicit view/change permission sets.
349                Pass ``None`` to clear all permissions (overwrite with empty).
350                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
351                The given sets replace the document's current view and change
352                users and groups.  Together with ``owner`` everything goes out
353                in one PATCH, which paperless-ngx applies as a whole.
354            remove_inbox_tags: When ``True``, removes all inbox tags from the document.
355
356        Returns:
357            The updated :class:`~easypaperless.models.documents.Document`.
358        """
359        return cast(
360            Document,
361            self._run(
362                self._async_documents.update(
363                    id,
364                    title=title,
365                    content=content,
366                    created=created,
367                    correspondent=correspondent,
368                    document_type=document_type,
369                    storage_path=storage_path,
370                    tags=tags,
371                    archive_serial_number=archive_serial_number,
372                    custom_fields=custom_fields,
373                    owner=owner,
374                    set_permissions=set_permissions,
375                    remove_inbox_tags=remove_inbox_tags,
376                )
377            ),
378        )

Partially update a document (PATCH semantics).

Arguments:
  • id: Numeric ID of the document to update.
  • title: New document title.
  • content: OCR text content of the document.
  • created: Creation date as an ISO-8601 string ("YYYY-MM-DD") or a ~datetime.date object.
  • correspondent: Correspondent to assign, as an ID or name. Pass None to clear the correspondent.
  • document_type: Document type to assign, as an ID or name. Pass None to clear the document type.
  • storage_path: Storage path to assign, as an ID or name. Pass None to clear the storage path.
  • tags: Full replacement list of tags (IDs or names).
  • archive_serial_number: Archive serial number to assign. Pass None to clear the archive serial number.
  • custom_fields: List of {"field": <field_id>, "value": ...} dicts.
  • owner: Numeric user ID to assign as document owner. Pass None to clear the owner.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged. The given sets replace the document's current view and change users and groups. Together with owner everything goes out in one PATCH, which paperless-ngx applies as a whole.
  • remove_inbox_tags: When True, removes all inbox tags from the document.
Returns:

The updated ~easypaperless.models.documents.Document.

def delete(self, id: int) -> None:
380    def delete(self, id: int) -> None:
381        """Permanently delete a document.
382
383        Args:
384            id: Numeric ID of the document to delete.
385
386        Raises:
387            ~easypaperless.exceptions.NotFoundError: If no document exists
388                with that ID.
389        """
390        self._run(self._async_documents.delete(id))

Permanently delete a document.

Arguments:
  • id: Numeric ID of the document to delete.
Raises:
def download(self, id: int, *, original: bool = False) -> bytes:
392    def download(self, id: int, *, original: bool = False) -> bytes:
393        """Download the binary content of a document.
394
395        Args:
396            id: Numeric ID of the document to download.
397            original: If ``False`` *(default)*, returns the archived PDF
398                (``GET /documents/{id}/download/``).
399                If ``True``, returns the original uploaded file
400                (``GET /documents/{id}/download/?original=true``).
401
402        Returns:
403            Raw file bytes.
404        """
405        return cast(bytes, self._run(self._async_documents.download(id, original=original)))

Download the binary content of a document.

Arguments:
  • id: Numeric ID of the document to download.
  • original: If False (default), returns the archived PDF (GET /documents/{id}/download/). If True, returns the original uploaded file (GET /documents/{id}/download/?original=true).
Returns:

Raw file bytes.

def thumbnail(self, id: int) -> bytes:
407    def thumbnail(self, id: int) -> bytes:
408        """Fetch the thumbnail image of a document.
409
410        Args:
411            id: Numeric ID of the document whose thumbnail to retrieve.
412
413        Returns:
414            Raw binary content of the thumbnail image.
415
416        Raises:
417            ~easypaperless.exceptions.NotFoundError: If no document exists
418                with that ID.
419            ~easypaperless.exceptions.ServerResponseError: If the server returns an
420                HTML page (e.g. an auth redirect) instead of the image.
421        """
422        return cast(bytes, self._run(self._async_documents.thumbnail(id)))

Fetch the thumbnail image of a document.

Arguments:
  • id: Numeric ID of the document whose thumbnail to retrieve.
Returns:

Raw binary content of the thumbnail image.

Raises:
def upload( self, file: str | pathlib._local.Path | bytes, *, filename: str | None = None, content_type: str | None = None, request_timeout: float | None = None, title: str | easypaperless.Unset = UNSET, created: datetime.date | str | None = None, correspondent: int | str | None | easypaperless.Unset = UNSET, document_type: int | str | None | easypaperless.Unset = UNSET, storage_path: int | str | None | easypaperless.Unset = UNSET, tags: Optional[List[Union[str, int]]] = None, archive_serial_number: int | None | easypaperless.Unset = UNSET, custom_fields: Optional[List[dict[str, Any]]] = None, wait: bool = False, poll_interval: float | None = None, poll_timeout: float | None = None) -> str | easypaperless.Document:
424    def upload(
425        self,
426        file: str | Path | bytes,
427        *,
428        filename: str | None = None,
429        content_type: str | None = None,
430        request_timeout: float | None = None,
431        title: str | Unset = UNSET,
432        created: date | str | None = None,
433        correspondent: int | str | None | Unset = UNSET,
434        document_type: int | str | None | Unset = UNSET,
435        storage_path: int | str | None | Unset = UNSET,
436        tags: List[int | str] | None = None,
437        archive_serial_number: int | None | Unset = UNSET,
438        custom_fields: List[dict[str, Any]] | None = None,
439        wait: bool = False,
440        poll_interval: float | None = None,
441        poll_timeout: float | None = None,
442    ) -> str | Document:
443        """Upload a document to paperless-ngx.
444
445        The upload request is never retried automatically, whatever the
446        client's ``retry_attempts`` / ``tenacity_retrying`` settings: if the
447        connection fails after paperless-ngx has accepted the file, a retry
448        would create a duplicate.  A failed upload raises (e.g.
449        :exc:`~easypaperless.exceptions.TransportTimeoutError`) so you can
450        decide whether to check for the document and upload again.
451
452        Args:
453            file: Path to the file to upload (``str`` or :class:`~pathlib.Path`),
454                or the file content as ``bytes``.  Bytes are sent directly; no
455                temporary file is written.
456            filename: File name sent to paperless-ngx.  Required when *file* is
457                ``bytes`` (omitting it raises
458                :exc:`~easypaperless.exceptions.ValidationError` before any
459                request).  For a path, overrides the name taken from the path.
460            content_type: MIME type of the file part, sent as given (e.g.
461                ``"application/pdf"``).  When omitted, it is guessed from the
462                file name as before.  paperless-ngx detects the file type from
463                the bytes and does not rely on this value to accept the file.
464            request_timeout: HTTP timeout in seconds for the upload request
465                only, overriding the client's ``timeout`` for this call.  Does
466                not affect task polling (see ``poll_timeout``).  When omitted,
467                the client's ``timeout`` applies.
468            title: Title to assign to the document.
469            created: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``) or a
470                :class:`~datetime.date` object.
471            correspondent: Correspondent to assign, as an ID or name.
472            document_type: Document type to assign, as an ID or name.
473            storage_path: Storage path to assign, as an ID or name.
474            tags: Tags to assign, as IDs or names.
475            archive_serial_number: Archive serial number to assign.
476            custom_fields: List of ``{"field": <field_id>, "value": ...}`` dicts.
477            wait: If ``False`` *(default)*, returns immediately with the task ID.
478                If ``True``, polls until processing completes.
479            poll_interval: Seconds between task-status checks while waiting for
480                processing to complete (requires ``wait=True``). Overrides the
481                client-level default. When omitted, falls back to the client-level
482                ``poll_interval`` (``2.0`` s unless changed at construction).
483            poll_timeout: Maximum seconds to wait before raising
484                :exc:`~easypaperless.exceptions.TaskTimeoutError` (requires
485                ``wait=True``). Overrides the client-level default. When omitted,
486                falls back to the client-level ``poll_timeout`` (``60.0`` s unless
487                changed at construction).
488
489        Returns:
490            The Celery task ID string when ``wait=False``, or the fully
491            processed :class:`~easypaperless.models.documents.Document`
492            when ``wait=True``.
493
494        Raises:
495            ~easypaperless.exceptions.ValidationError: If *file* is ``bytes``
496                and no *filename* is given.
497            ~easypaperless.exceptions.BadRequestError: If paperless-ngx rejects
498                the file before processing starts, e.g. an unsupported file
499                type or an empty file (``err.field_errors["document"]``).
500            ~easypaperless.exceptions.UploadError: If processing fails;
501                ``err.task`` holds the task with paperless-ngx's ``result``
502                unaltered.  For a duplicate, ``err.task.result`` contains
503                ``": It is a duplicate of "`` and ``err.task.related_document``
504                is the existing document's ID (``None`` if that document is
505                in the trash).
506            ~easypaperless.exceptions.TaskTimeoutError: If timeout is exceeded;
507                resume with ``client.tasks.wait(err.task_id)``.
508        """
509        return cast(
510            str | Document,
511            self._run(
512                self._async_documents.upload(
513                    file,
514                    filename=filename,
515                    content_type=content_type,
516                    request_timeout=request_timeout,
517                    title=title,
518                    created=created,
519                    correspondent=correspondent,
520                    document_type=document_type,
521                    storage_path=storage_path,
522                    tags=tags,
523                    archive_serial_number=archive_serial_number,
524                    custom_fields=custom_fields,
525                    wait=wait,
526                    poll_interval=poll_interval,
527                    poll_timeout=poll_timeout,
528                )
529            ),
530        )

Upload a document to paperless-ngx.

The upload request is never retried automatically, whatever the client's retry_attempts / tenacity_retrying settings: if the connection fails after paperless-ngx has accepted the file, a retry would create a duplicate. A failed upload raises (e.g. ~easypaperless.exceptions.TransportTimeoutError) so you can decide whether to check for the document and upload again.

Arguments:
  • file: Path to the file to upload (str or ~pathlib.Path), or the file content as bytes. Bytes are sent directly; no temporary file is written.
  • filename: File name sent to paperless-ngx. Required when file is bytes (omitting it raises ~easypaperless.exceptions.ValidationError before any request). For a path, overrides the name taken from the path.
  • content_type: MIME type of the file part, sent as given (e.g. "application/pdf"). When omitted, it is guessed from the file name as before. paperless-ngx detects the file type from the bytes and does not rely on this value to accept the file.
  • request_timeout: HTTP timeout in seconds for the upload request only, overriding the client's timeout for this call. Does not affect task polling (see poll_timeout). When omitted, the client's timeout applies.
  • title: Title to assign to the document.
  • created: Creation date as an ISO-8601 string ("YYYY-MM-DD") or a ~datetime.date object.
  • correspondent: Correspondent to assign, as an ID or name.
  • document_type: Document type to assign, as an ID or name.
  • storage_path: Storage path to assign, as an ID or name.
  • tags: Tags to assign, as IDs or names.
  • archive_serial_number: Archive serial number to assign.
  • custom_fields: List of {"field": <field_id>, "value": ...} dicts.
  • wait: If False (default), returns immediately with the task ID. If True, polls until processing completes.
  • poll_interval: Seconds between task-status checks while waiting for processing to complete (requires wait=True). Overrides the client-level default. When omitted, falls back to the client-level poll_interval (2.0 s unless changed at construction).
  • poll_timeout: Maximum seconds to wait before raising ~easypaperless.exceptions.TaskTimeoutError (requires wait=True). Overrides the client-level default. When omitted, falls back to the client-level poll_timeout (60.0 s unless changed at construction).
Returns:

The Celery task ID string when wait=False, or the fully processed ~easypaperless.models.documents.Document when wait=True.

Raises:
def bulk_add_tag(self, document_ids: List[int], tag: int | str) -> None:
532    def bulk_add_tag(self, document_ids: List[int], tag: int | str) -> None:
533        """Add a tag to multiple documents in a single request.
534
535        Args:
536            document_ids: List of document IDs to tag.
537            tag: Tag to add, as an ID or name.
538        """
539        self._run(self._async_documents.bulk_add_tag(document_ids, tag))

Add a tag to multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to tag.
  • tag: Tag to add, as an ID or name.
def bulk_remove_tag(self, document_ids: List[int], tag: int | str) -> None:
541    def bulk_remove_tag(self, document_ids: List[int], tag: int | str) -> None:
542        """Remove a tag from multiple documents in a single request.
543
544        Args:
545            document_ids: List of document IDs to un-tag.
546            tag: Tag to remove, as an ID or name.
547        """
548        self._run(self._async_documents.bulk_remove_tag(document_ids, tag))

Remove a tag from multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to un-tag.
  • tag: Tag to remove, as an ID or name.
def bulk_modify_tags( self, document_ids: List[int], *, add_tags: Optional[List[Union[str, int]]] = None, remove_tags: Optional[List[Union[str, int]]] = None) -> None:
550    def bulk_modify_tags(
551        self,
552        document_ids: List[int],
553        *,
554        add_tags: List[int | str] | None = None,
555        remove_tags: List[int | str] | None = None,
556    ) -> None:
557        """Add and/or remove tags on multiple documents atomically.
558
559        Args:
560            document_ids: List of document IDs to modify.
561            add_tags: Tags to add, as IDs or names.
562            remove_tags: Tags to remove, as IDs or names.
563        """
564        self._run(
565            self._async_documents.bulk_modify_tags(
566                document_ids, add_tags=add_tags, remove_tags=remove_tags
567            )
568        )

Add and/or remove tags on multiple documents atomically.

Arguments:
  • document_ids: List of document IDs to modify.
  • add_tags: Tags to add, as IDs or names.
  • remove_tags: Tags to remove, as IDs or names.
def bulk_delete(self, document_ids: List[int]) -> None:
570    def bulk_delete(self, document_ids: List[int]) -> None:
571        """Permanently delete multiple documents in a single request.
572
573        Args:
574            document_ids: List of document IDs to delete.
575        """
576        self._run(self._async_documents.bulk_delete(document_ids))

Permanently delete multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to delete.
def bulk_set_correspondent(self, document_ids: List[int], correspondent: int | str | None) -> None:
578    def bulk_set_correspondent(
579        self, document_ids: List[int], correspondent: int | str | None
580    ) -> None:
581        """Assign a correspondent to multiple documents in a single request.
582
583        Args:
584            document_ids: List of document IDs to modify.
585            correspondent: Correspondent to assign, as an ID or name.
586                Pass ``None`` to clear.
587        """
588        self._run(self._async_documents.bulk_set_correspondent(document_ids, correspondent))

Assign a correspondent to multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to modify.
  • correspondent: Correspondent to assign, as an ID or name. Pass None to clear.
def bulk_set_document_type(self, document_ids: List[int], document_type: int | str | None) -> None:
590    def bulk_set_document_type(
591        self, document_ids: List[int], document_type: int | str | None
592    ) -> None:
593        """Assign a document type to multiple documents in a single request.
594
595        Args:
596            document_ids: List of document IDs to modify.
597            document_type: Document type to assign, as an ID or name.
598                Pass ``None`` to clear.
599        """
600        self._run(self._async_documents.bulk_set_document_type(document_ids, document_type))

Assign a document type to multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to modify.
  • document_type: Document type to assign, as an ID or name. Pass None to clear.
def bulk_set_storage_path(self, document_ids: List[int], storage_path: int | str | None) -> None:
602    def bulk_set_storage_path(
603        self, document_ids: List[int], storage_path: int | str | None
604    ) -> None:
605        """Assign a storage path to multiple documents in a single request.
606
607        Args:
608            document_ids: List of document IDs to modify.
609            storage_path: Storage path to assign, as an ID or name.
610                Pass ``None`` to clear.
611        """
612        self._run(self._async_documents.bulk_set_storage_path(document_ids, storage_path))

Assign a storage path to multiple documents in a single request.

Arguments:
  • document_ids: List of document IDs to modify.
  • storage_path: Storage path to assign, as an ID or name. Pass None to clear.
def bulk_modify_custom_fields( self, document_ids: List[int], *, add_fields: Optional[List[dict[str, Any]]] = None, remove_fields: Optional[List[int]] = None) -> None:
614    def bulk_modify_custom_fields(
615        self,
616        document_ids: List[int],
617        *,
618        add_fields: List[dict[str, Any]] | None = None,
619        remove_fields: List[int] | None = None,
620    ) -> None:
621        """Add and/or remove custom field values on multiple documents.
622
623        Args:
624            document_ids: List of document IDs to modify.
625            add_fields: Custom-field value dicts to add.
626            remove_fields: Custom-field IDs whose values should be removed.
627        """
628        self._run(
629            self._async_documents.bulk_modify_custom_fields(
630                document_ids, add_fields=add_fields, remove_fields=remove_fields
631            )
632        )

Add and/or remove custom field values on multiple documents.

Arguments:
  • document_ids: List of document IDs to modify.
  • add_fields: Custom-field value dicts to add.
  • remove_fields: Custom-field IDs whose values should be removed.
def bulk_set_permissions( self, document_ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
634    def bulk_set_permissions(
635        self,
636        document_ids: List[int],
637        *,
638        set_permissions: SetPermissions | Unset = UNSET,
639        owner: int | None | Unset = UNSET,
640        merge: bool = False,
641    ) -> None:
642        """Set permissions and/or owner on multiple documents.
643
644        Args:
645            document_ids: List of document IDs to modify.
646            set_permissions: Explicit view/change permission sets.
647                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
648            owner: Numeric user ID to assign as document owner.
649                Pass ``None`` to clear the owner.
650                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
651            merge: When ``True``, new permissions are merged with existing ones.
652        """
653        self._run(
654            self._async_documents.bulk_set_permissions(
655                document_ids,
656                set_permissions=set_permissions,
657                owner=owner,
658                merge=merge,
659            )
660        )

Set permissions and/or owner on multiple documents.

Arguments:
  • document_ids: List of document IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as document owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
def bulk_download( self, document_ids: List[int], *, content: Literal['archive', 'originals', 'both'] = 'archive', compression: Literal['none', 'deflated', 'bzip2', 'lzma'] = 'none', follow_formatting: bool = False) -> bytes:
662    def bulk_download(
663        self,
664        document_ids: List[int],
665        *,
666        content: Literal["archive", "originals", "both"] = "archive",
667        compression: Literal["none", "deflated", "bzip2", "lzma"] = "none",
668        follow_formatting: bool = False,
669    ) -> bytes:
670        """Download multiple documents as a single ZIP archive.
671
672        Args:
673            document_ids: List of document IDs to include in the ZIP.
674            content: File variant to include.  One of ``"archive"`` *(default)*,
675                ``"originals"``, or ``"both"``.
676            compression: ZIP compression algorithm.  One of ``"none"`` *(default)*,
677                ``"deflated"``, ``"bzip2"``, or ``"lzma"``.
678            follow_formatting: When ``True``, filenames inside the ZIP follow
679                the storage path formatting configured in paperless-ngx.
680                Default: ``False``.
681
682        Returns:
683            Raw bytes of the ZIP archive.
684        """
685        return cast(
686            bytes,
687            self._run(
688                self._async_documents.bulk_download(
689                    document_ids,
690                    content=content,
691                    compression=compression,
692                    follow_formatting=follow_formatting,
693                )
694            ),
695        )

Download multiple documents as a single ZIP archive.

Arguments:
  • document_ids: List of document IDs to include in the ZIP.
  • content: File variant to include. One of "archive" (default), "originals", or "both".
  • compression: ZIP compression algorithm. One of "none" (default), "deflated", "bzip2", or "lzma".
  • follow_formatting: When True, filenames inside the ZIP follow the storage path formatting configured in paperless-ngx. Default: False.
Returns:

Raw bytes of the ZIP archive.

class SyncNotesResource:
 15class SyncNotesResource:
 16    """Sync accessor for document notes: ``client.documents.notes``."""
 17
 18    def __init__(self, async_notes: NotesResource, run: Any) -> None:
 19        self._async_notes = async_notes
 20        self._run = run
 21
 22    def list(
 23        self,
 24        document_id: int,
 25        *,
 26        page: int | None = None,
 27        page_size: int | None = None,
 28    ) -> PagedResult[DocumentNote]:
 29        """Fetch notes attached to a document.
 30
 31        When ``page`` is ``None`` (the default), all pages are fetched
 32        automatically and ``next`` / ``previous`` in the returned
 33        :class:`~easypaperless.models.paged_result.PagedResult` are always
 34        ``None``.  When ``page`` is set to a specific integer, only that one
 35        page is fetched and ``next`` / ``previous`` contain the raw API values.
 36
 37        Args:
 38            document_id: Numeric ID of the document whose notes to retrieve.
 39            page: Return only this specific page (1-based).
 40            page_size: Number of results per page.
 41
 42        Returns:
 43            :class:`~easypaperless.models.paged_result.PagedResult` of
 44            :class:`~easypaperless.models.documents.DocumentNote` objects,
 45            ordered by creation time.
 46
 47        Raises:
 48            ~easypaperless.exceptions.NotFoundError: If no document exists
 49                with that ID.
 50        """
 51        return cast(
 52            PagedResult[DocumentNote],
 53            self._run(self._async_notes.list(document_id, page=page, page_size=page_size)),
 54        )
 55
 56    def create(self, document_id: int, *, note: str) -> DocumentNote:
 57        """Create a new note on a document.
 58
 59        paperless-ngx answers with the document's full note list, not with
 60        the new note alone.  The created note is picked from that list as the
 61        note whose text equals ``note``, so a note another user adds to the
 62        same document at the same moment is not returned by mistake.  Only if
 63        that text occurs more than once does the client look up the token's
 64        user once (``GET /api/ui_settings/``, cached per client) and keep only
 65        that user's notes; of the remaining notes the newest (highest ID) is
 66        returned.
 67
 68        Telling identical texts of different users apart needs the
 69        ``view_uisettings`` permission (or a superuser), because that lookup
 70        uses ``/api/ui_settings/``.  Without it the lookup fails (403), the
 71        failure is cached per client and logged as a warning, no error is
 72        raised (the note already exists), and the newest note with that text
 73        is returned, which may belong to another user.
 74
 75        Ambiguous case: if the token's user already has a note with the same
 76        text on the document, or creates one concurrently, the notes cannot be
 77        told apart and the newest one is returned.  It has the same text, user
 78        and document; only ``id`` and ``created`` may differ from the note this
 79        call created.  If no note in the response has the sent text (not
 80        observed with paperless-ngx 2.18), the newest note is returned and a
 81        warning is logged.
 82
 83        Args:
 84            document_id: Numeric ID of the document to annotate.
 85            note: Text content of the note.
 86
 87        Returns:
 88            The newly created :class:`~easypaperless.models.documents.DocumentNote`.
 89
 90        Raises:
 91            ~easypaperless.exceptions.NotFoundError: If no document exists
 92                with that ID.
 93            ~easypaperless.exceptions.ServerResponseError: If paperless-ngx
 94                answers with an empty note list.
 95        """
 96        return cast(DocumentNote, self._run(self._async_notes.create(document_id, note=note)))
 97
 98    def delete(self, document_id: int, note_id: int) -> None:
 99        """Delete a note from a document.
100
101        Args:
102            document_id: Numeric ID of the document that owns the note.
103            note_id: Numeric ID of the note to delete.
104
105        Raises:
106            ~easypaperless.exceptions.NotFoundError: If no document exists with
107                that ID.
108            ~easypaperless.exceptions.ServerResponseError: If the document has
109                no note with ``note_id``.  paperless-ngx answers an unknown note
110                ID with ``500 Server Error`` instead of 404 (verified against
111                paperless-ngx 2.18.2), so it cannot be told apart from a real
112                server error.  With ``retry_attempts`` set, the 500 is retried
113                like any other and ends in
114                :exc:`~easypaperless.exceptions.RetryExhaustedError`.  Use
115                ``notes.list(document_id)`` first if you need to be sure the
116                note exists.
117        """
118        self._run(self._async_notes.delete(document_id, note_id))

Sync accessor for document notes: client.documents.notes.

SyncNotesResource( async_notes: NotesResource, run: Any)
18    def __init__(self, async_notes: NotesResource, run: Any) -> None:
19        self._async_notes = async_notes
20        self._run = run
def list( self, document_id: int, *, page: int | None = None, page_size: int | None = None) -> easypaperless.PagedResult[DocumentNote]:
22    def list(
23        self,
24        document_id: int,
25        *,
26        page: int | None = None,
27        page_size: int | None = None,
28    ) -> PagedResult[DocumentNote]:
29        """Fetch notes attached to a document.
30
31        When ``page`` is ``None`` (the default), all pages are fetched
32        automatically and ``next`` / ``previous`` in the returned
33        :class:`~easypaperless.models.paged_result.PagedResult` are always
34        ``None``.  When ``page`` is set to a specific integer, only that one
35        page is fetched and ``next`` / ``previous`` contain the raw API values.
36
37        Args:
38            document_id: Numeric ID of the document whose notes to retrieve.
39            page: Return only this specific page (1-based).
40            page_size: Number of results per page.
41
42        Returns:
43            :class:`~easypaperless.models.paged_result.PagedResult` of
44            :class:`~easypaperless.models.documents.DocumentNote` objects,
45            ordered by creation time.
46
47        Raises:
48            ~easypaperless.exceptions.NotFoundError: If no document exists
49                with that ID.
50        """
51        return cast(
52            PagedResult[DocumentNote],
53            self._run(self._async_notes.list(document_id, page=page, page_size=page_size)),
54        )

Fetch notes attached to a document.

When page is None (the default), all pages are fetched automatically and next / previous in the returned ~easypaperless.models.paged_result.PagedResult are always None. When page is set to a specific integer, only that one page is fetched and next / previous contain the raw API values.

Arguments:
  • document_id: Numeric ID of the document whose notes to retrieve.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.documents.DocumentNote objects, ordered by creation time.

Raises:
def create( self, document_id: int, *, note: str) -> easypaperless.DocumentNote:
56    def create(self, document_id: int, *, note: str) -> DocumentNote:
57        """Create a new note on a document.
58
59        paperless-ngx answers with the document's full note list, not with
60        the new note alone.  The created note is picked from that list as the
61        note whose text equals ``note``, so a note another user adds to the
62        same document at the same moment is not returned by mistake.  Only if
63        that text occurs more than once does the client look up the token's
64        user once (``GET /api/ui_settings/``, cached per client) and keep only
65        that user's notes; of the remaining notes the newest (highest ID) is
66        returned.
67
68        Telling identical texts of different users apart needs the
69        ``view_uisettings`` permission (or a superuser), because that lookup
70        uses ``/api/ui_settings/``.  Without it the lookup fails (403), the
71        failure is cached per client and logged as a warning, no error is
72        raised (the note already exists), and the newest note with that text
73        is returned, which may belong to another user.
74
75        Ambiguous case: if the token's user already has a note with the same
76        text on the document, or creates one concurrently, the notes cannot be
77        told apart and the newest one is returned.  It has the same text, user
78        and document; only ``id`` and ``created`` may differ from the note this
79        call created.  If no note in the response has the sent text (not
80        observed with paperless-ngx 2.18), the newest note is returned and a
81        warning is logged.
82
83        Args:
84            document_id: Numeric ID of the document to annotate.
85            note: Text content of the note.
86
87        Returns:
88            The newly created :class:`~easypaperless.models.documents.DocumentNote`.
89
90        Raises:
91            ~easypaperless.exceptions.NotFoundError: If no document exists
92                with that ID.
93            ~easypaperless.exceptions.ServerResponseError: If paperless-ngx
94                answers with an empty note list.
95        """
96        return cast(DocumentNote, self._run(self._async_notes.create(document_id, note=note)))

Create a new note on a document.

paperless-ngx answers with the document's full note list, not with the new note alone. The created note is picked from that list as the note whose text equals note, so a note another user adds to the same document at the same moment is not returned by mistake. Only if that text occurs more than once does the client look up the token's user once (GET /api/ui_settings/, cached per client) and keep only that user's notes; of the remaining notes the newest (highest ID) is returned.

Telling identical texts of different users apart needs the view_uisettings permission (or a superuser), because that lookup uses /api/ui_settings/. Without it the lookup fails (403), the failure is cached per client and logged as a warning, no error is raised (the note already exists), and the newest note with that text is returned, which may belong to another user.

Ambiguous case: if the token's user already has a note with the same text on the document, or creates one concurrently, the notes cannot be told apart and the newest one is returned. It has the same text, user and document; only id and created may differ from the note this call created. If no note in the response has the sent text (not observed with paperless-ngx 2.18), the newest note is returned and a warning is logged.

Arguments:
  • document_id: Numeric ID of the document to annotate.
  • note: Text content of the note.
Returns:

The newly created ~easypaperless.models.documents.DocumentNote.

Raises:
def delete(self, document_id: int, note_id: int) -> None:
 98    def delete(self, document_id: int, note_id: int) -> None:
 99        """Delete a note from a document.
100
101        Args:
102            document_id: Numeric ID of the document that owns the note.
103            note_id: Numeric ID of the note to delete.
104
105        Raises:
106            ~easypaperless.exceptions.NotFoundError: If no document exists with
107                that ID.
108            ~easypaperless.exceptions.ServerResponseError: If the document has
109                no note with ``note_id``.  paperless-ngx answers an unknown note
110                ID with ``500 Server Error`` instead of 404 (verified against
111                paperless-ngx 2.18.2), so it cannot be told apart from a real
112                server error.  With ``retry_attempts`` set, the 500 is retried
113                like any other and ends in
114                :exc:`~easypaperless.exceptions.RetryExhaustedError`.  Use
115                ``notes.list(document_id)`` first if you need to be sure the
116                note exists.
117        """
118        self._run(self._async_notes.delete(document_id, note_id))

Delete a note from a document.

Arguments:
  • document_id: Numeric ID of the document that owns the note.
  • note_id: Numeric ID of the note to delete.
Raises:
class SyncStoragePathsResource:
 18class SyncStoragePathsResource:
 19    """Sync accessor for storage paths: ``client.storage_paths``."""
 20
 21    def __init__(self, async_storage_paths: StoragePathsResource, run: Any) -> None:
 22        self._async_storage_paths = async_storage_paths
 23        self._run = run
 24
 25    def list(
 26        self,
 27        *,
 28        ids: List[int] | None = None,
 29        name_contains: str | None = None,
 30        name_exact: str | None = None,
 31        path_contains: str | None = None,
 32        path_exact: str | None = None,
 33        page: int | None = None,
 34        page_size: int | None = None,
 35        ordering: str | None = None,
 36        descending: bool = False,
 37        full_perms: bool = False,
 38    ) -> PagedResult[StoragePath]:
 39        """Return storage paths defined in paperless-ngx.
 40
 41        When ``page`` is ``None`` (the default), all pages are fetched
 42        automatically and ``next`` / ``previous`` in the result are always
 43        ``None``.  When ``page`` is set, only that page is fetched and
 44        ``next`` / ``previous`` reflect the raw API values.
 45
 46        Args:
 47            ids: Return only storage paths whose ID is in this list.
 48            name_contains: Case-insensitive substring filter on name.
 49            name_exact: Case-insensitive exact match on name.
 50            path_contains: Case-insensitive substring filter on path template.
 51            path_exact: Case-insensitive exact match on path template.
 52            page: Return only this specific page (1-based).
 53            page_size: Number of results per page.
 54            ordering: Field to sort by.
 55            descending: When ``True``, reverses the sort direction.
 56            full_perms: When ``True``, paperless-ngx returns the full view/change
 57                permissions of every object, available as
 58                ``StoragePath.permissions``; ``user_can_change`` is then ``None``.
 59                Default: ``False``.
 60
 61        Returns:
 62            :class:`~easypaperless.models.paged_result.PagedResult` of
 63            :class:`~easypaperless.models.storage_paths.StoragePath` objects.
 64        """
 65        return cast(
 66            PagedResult[StoragePath],
 67            self._run(
 68                self._async_storage_paths.list(
 69                    ids=ids,
 70                    name_contains=name_contains,
 71                    name_exact=name_exact,
 72                    path_contains=path_contains,
 73                    path_exact=path_exact,
 74                    page=page,
 75                    page_size=page_size,
 76                    ordering=ordering,
 77                    descending=descending,
 78                    full_perms=full_perms,
 79                )
 80            ),
 81        )
 82
 83    def get(self, id: int, *, full_perms: bool = False) -> StoragePath:
 84        """Fetch a single storage path by its ID.
 85
 86        Args:
 87            id: Numeric storage-path ID.
 88            full_perms: When ``True``, paperless-ngx returns the full view/change
 89                permissions, available as ``StoragePath.permissions``;
 90                ``user_can_change`` is then ``None``. Default: ``False``.
 91
 92        Returns:
 93            The :class:`~easypaperless.models.storage_paths.StoragePath` with the given ID.
 94
 95        Raises:
 96            ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
 97        """
 98        return cast(
 99            StoragePath, self._run(self._async_storage_paths.get(id, full_perms=full_perms))
100        )
101
102    def create(
103        self,
104        *,
105        name: str,
106        path: str | Unset = UNSET,
107        match: str | Unset = UNSET,
108        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
109        is_insensitive: bool = True,
110        owner: int | None | Unset = UNSET,
111        set_permissions: SetPermissions | None | Unset = UNSET,
112    ) -> StoragePath:
113        """Create a new storage path.
114
115        Args:
116            name: Storage-path name. Must be unique.
117            path: Template string for the archive file path.
118            match: Auto-matching pattern.
119            matching_algorithm: Controls how ``match`` is applied.
120                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
121                regular-expression matching.
122            is_insensitive: When ``True``, ``match`` is case-insensitive.
123                Defaults to ``True``, matching the paperless-ngx API default.
124            owner: Numeric user ID to assign as owner.
125            set_permissions: Explicit view/change permission sets.
126                Pass ``None`` to create with empty permissions.
127
128        Returns:
129            The newly created :class:`~easypaperless.models.storage_paths.StoragePath`.
130        """
131        return cast(
132            StoragePath,
133            self._run(
134                self._async_storage_paths.create(
135                    name=name,
136                    path=path,
137                    match=match,
138                    matching_algorithm=matching_algorithm,
139                    is_insensitive=is_insensitive,
140                    owner=owner,
141                    set_permissions=set_permissions,
142                )
143            ),
144        )
145
146    def update(
147        self,
148        id: int,
149        *,
150        name: str | Unset = UNSET,
151        path: str | Unset = UNSET,
152        match: str | Unset = UNSET,
153        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
154        is_insensitive: bool | Unset = UNSET,
155        owner: int | None | Unset = UNSET,
156        set_permissions: SetPermissions | None | Unset = UNSET,
157    ) -> StoragePath:
158        """Partially update a storage path (PATCH semantics).
159
160        Args:
161            id: Numeric ID of the storage path to update.
162            name: Storage-path name.
163            path: Template string for the archive file path.
164            match: Auto-matching pattern.
165            matching_algorithm: Controls how ``match`` is applied.
166                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
167                regular-expression matching.
168            is_insensitive: When ``True``, ``match`` is case-insensitive.
169            owner: Numeric user ID to assign as owner.
170                Pass ``None`` to clear the owner.
171                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
172            set_permissions: Explicit view/change permission sets.
173                Pass ``None`` to clear all permissions (overwrite with empty).
174                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
175
176        Returns:
177            The updated :class:`~easypaperless.models.storage_paths.StoragePath`.
178        """
179        return cast(
180            StoragePath,
181            self._run(
182                self._async_storage_paths.update(
183                    id,
184                    name=name,
185                    path=path,
186                    match=match,
187                    matching_algorithm=matching_algorithm,
188                    is_insensitive=is_insensitive,
189                    owner=owner,
190                    set_permissions=set_permissions,
191                )
192            ),
193        )
194
195    def delete(self, id: int) -> None:
196        """Delete a storage path.
197
198        Args:
199            id: Numeric ID of the storage path to delete.
200
201        Raises:
202            ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
203        """
204        self._run(self._async_storage_paths.delete(id))
205
206    def bulk_delete(self, ids: List[int]) -> None:
207        """Permanently delete multiple storage paths in a single request.
208
209        Args:
210            ids: List of storage path IDs to delete.
211        """
212        self._run(self._async_storage_paths.bulk_delete(ids))
213
214    def bulk_set_permissions(
215        self,
216        ids: List[int],
217        *,
218        set_permissions: SetPermissions | Unset = UNSET,
219        owner: int | None | Unset = UNSET,
220        merge: bool = False,
221    ) -> None:
222        """Set permissions and/or owner on multiple storage paths.
223
224        Args:
225            ids: List of storage path IDs to modify.
226            set_permissions: Explicit view/change permission sets.
227                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
228            owner: Numeric user ID to assign as owner.
229                Pass ``None`` to clear the owner.
230                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
231            merge: When ``True``, new permissions are merged with existing ones.
232        """
233        self._run(
234            self._async_storage_paths.bulk_set_permissions(
235                ids, set_permissions=set_permissions, owner=owner, merge=merge
236            )
237        )

Sync accessor for storage paths: client.storage_paths.

SyncStoragePathsResource( async_storage_paths: StoragePathsResource, run: Any)
21    def __init__(self, async_storage_paths: StoragePathsResource, run: Any) -> None:
22        self._async_storage_paths = async_storage_paths
23        self._run = run
def list( self, *, ids: Optional[List[int]] = None, name_contains: str | None = None, name_exact: str | None = None, path_contains: str | None = None, path_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False, full_perms: bool = False) -> easypaperless.PagedResult[StoragePath]:
25    def list(
26        self,
27        *,
28        ids: List[int] | None = None,
29        name_contains: str | None = None,
30        name_exact: str | None = None,
31        path_contains: str | None = None,
32        path_exact: str | None = None,
33        page: int | None = None,
34        page_size: int | None = None,
35        ordering: str | None = None,
36        descending: bool = False,
37        full_perms: bool = False,
38    ) -> PagedResult[StoragePath]:
39        """Return storage paths defined in paperless-ngx.
40
41        When ``page`` is ``None`` (the default), all pages are fetched
42        automatically and ``next`` / ``previous`` in the result are always
43        ``None``.  When ``page`` is set, only that page is fetched and
44        ``next`` / ``previous`` reflect the raw API values.
45
46        Args:
47            ids: Return only storage paths whose ID is in this list.
48            name_contains: Case-insensitive substring filter on name.
49            name_exact: Case-insensitive exact match on name.
50            path_contains: Case-insensitive substring filter on path template.
51            path_exact: Case-insensitive exact match on path template.
52            page: Return only this specific page (1-based).
53            page_size: Number of results per page.
54            ordering: Field to sort by.
55            descending: When ``True``, reverses the sort direction.
56            full_perms: When ``True``, paperless-ngx returns the full view/change
57                permissions of every object, available as
58                ``StoragePath.permissions``; ``user_can_change`` is then ``None``.
59                Default: ``False``.
60
61        Returns:
62            :class:`~easypaperless.models.paged_result.PagedResult` of
63            :class:`~easypaperless.models.storage_paths.StoragePath` objects.
64        """
65        return cast(
66            PagedResult[StoragePath],
67            self._run(
68                self._async_storage_paths.list(
69                    ids=ids,
70                    name_contains=name_contains,
71                    name_exact=name_exact,
72                    path_contains=path_contains,
73                    path_exact=path_exact,
74                    page=page,
75                    page_size=page_size,
76                    ordering=ordering,
77                    descending=descending,
78                    full_perms=full_perms,
79                )
80            ),
81        )

Return storage paths defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • ids: Return only storage paths whose ID is in this list.
  • name_contains: Case-insensitive substring filter on name.
  • name_exact: Case-insensitive exact match on name.
  • path_contains: Case-insensitive substring filter on path template.
  • path_exact: Case-insensitive exact match on path template.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every object, available as StoragePath.permissions; user_can_change is then None. Default: False.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.storage_paths.StoragePath objects.

def get( self, id: int, *, full_perms: bool = False) -> easypaperless.StoragePath:
 83    def get(self, id: int, *, full_perms: bool = False) -> StoragePath:
 84        """Fetch a single storage path by its ID.
 85
 86        Args:
 87            id: Numeric storage-path ID.
 88            full_perms: When ``True``, paperless-ngx returns the full view/change
 89                permissions, available as ``StoragePath.permissions``;
 90                ``user_can_change`` is then ``None``. Default: ``False``.
 91
 92        Returns:
 93            The :class:`~easypaperless.models.storage_paths.StoragePath` with the given ID.
 94
 95        Raises:
 96            ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
 97        """
 98        return cast(
 99            StoragePath, self._run(self._async_storage_paths.get(id, full_perms=full_perms))
100        )

Fetch a single storage path by its ID.

Arguments:
  • id: Numeric storage-path ID.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as StoragePath.permissions; user_can_change is then None. Default: False.
Returns:

The ~easypaperless.models.storage_paths.StoragePath with the given ID.

Raises:
def create( self, *, name: str, path: str | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool = True, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.StoragePath:
102    def create(
103        self,
104        *,
105        name: str,
106        path: str | Unset = UNSET,
107        match: str | Unset = UNSET,
108        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
109        is_insensitive: bool = True,
110        owner: int | None | Unset = UNSET,
111        set_permissions: SetPermissions | None | Unset = UNSET,
112    ) -> StoragePath:
113        """Create a new storage path.
114
115        Args:
116            name: Storage-path name. Must be unique.
117            path: Template string for the archive file path.
118            match: Auto-matching pattern.
119            matching_algorithm: Controls how ``match`` is applied.
120                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
121                regular-expression matching.
122            is_insensitive: When ``True``, ``match`` is case-insensitive.
123                Defaults to ``True``, matching the paperless-ngx API default.
124            owner: Numeric user ID to assign as owner.
125            set_permissions: Explicit view/change permission sets.
126                Pass ``None`` to create with empty permissions.
127
128        Returns:
129            The newly created :class:`~easypaperless.models.storage_paths.StoragePath`.
130        """
131        return cast(
132            StoragePath,
133            self._run(
134                self._async_storage_paths.create(
135                    name=name,
136                    path=path,
137                    match=match,
138                    matching_algorithm=matching_algorithm,
139                    is_insensitive=is_insensitive,
140                    owner=owner,
141                    set_permissions=set_permissions,
142                )
143            ),
144        )

Create a new storage path.

Arguments:
  • name: Storage-path name. Must be unique.
  • path: Template string for the archive file path.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive. Defaults to True, matching the paperless-ngx API default.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.storage_paths.StoragePath.

def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, path: str | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.StoragePath:
146    def update(
147        self,
148        id: int,
149        *,
150        name: str | Unset = UNSET,
151        path: str | Unset = UNSET,
152        match: str | Unset = UNSET,
153        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
154        is_insensitive: bool | Unset = UNSET,
155        owner: int | None | Unset = UNSET,
156        set_permissions: SetPermissions | None | Unset = UNSET,
157    ) -> StoragePath:
158        """Partially update a storage path (PATCH semantics).
159
160        Args:
161            id: Numeric ID of the storage path to update.
162            name: Storage-path name.
163            path: Template string for the archive file path.
164            match: Auto-matching pattern.
165            matching_algorithm: Controls how ``match`` is applied.
166                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
167                regular-expression matching.
168            is_insensitive: When ``True``, ``match`` is case-insensitive.
169            owner: Numeric user ID to assign as owner.
170                Pass ``None`` to clear the owner.
171                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
172            set_permissions: Explicit view/change permission sets.
173                Pass ``None`` to clear all permissions (overwrite with empty).
174                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
175
176        Returns:
177            The updated :class:`~easypaperless.models.storage_paths.StoragePath`.
178        """
179        return cast(
180            StoragePath,
181            self._run(
182                self._async_storage_paths.update(
183                    id,
184                    name=name,
185                    path=path,
186                    match=match,
187                    matching_algorithm=matching_algorithm,
188                    is_insensitive=is_insensitive,
189                    owner=owner,
190                    set_permissions=set_permissions,
191                )
192            ),
193        )

Partially update a storage path (PATCH semantics).

Arguments:
  • id: Numeric ID of the storage path to update.
  • name: Storage-path name.
  • path: Template string for the archive file path.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.storage_paths.StoragePath.

def delete(self, id: int) -> None:
195    def delete(self, id: int) -> None:
196        """Delete a storage path.
197
198        Args:
199            id: Numeric ID of the storage path to delete.
200
201        Raises:
202            ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
203        """
204        self._run(self._async_storage_paths.delete(id))

Delete a storage path.

Arguments:
  • id: Numeric ID of the storage path to delete.
Raises:
def bulk_delete(self, ids: List[int]) -> None:
206    def bulk_delete(self, ids: List[int]) -> None:
207        """Permanently delete multiple storage paths in a single request.
208
209        Args:
210            ids: List of storage path IDs to delete.
211        """
212        self._run(self._async_storage_paths.bulk_delete(ids))

Permanently delete multiple storage paths in a single request.

Arguments:
  • ids: List of storage path IDs to delete.
def bulk_set_permissions( self, ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
214    def bulk_set_permissions(
215        self,
216        ids: List[int],
217        *,
218        set_permissions: SetPermissions | Unset = UNSET,
219        owner: int | None | Unset = UNSET,
220        merge: bool = False,
221    ) -> None:
222        """Set permissions and/or owner on multiple storage paths.
223
224        Args:
225            ids: List of storage path IDs to modify.
226            set_permissions: Explicit view/change permission sets.
227                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
228            owner: Numeric user ID to assign as owner.
229                Pass ``None`` to clear the owner.
230                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
231            merge: When ``True``, new permissions are merged with existing ones.
232        """
233        self._run(
234            self._async_storage_paths.bulk_set_permissions(
235                ids, set_permissions=set_permissions, owner=owner, merge=merge
236            )
237        )

Set permissions and/or owner on multiple storage paths.

Arguments:
  • ids: List of storage path IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
class SyncTagsResource:
 18class SyncTagsResource:
 19    """Sync accessor for tags: ``client.tags``."""
 20
 21    def __init__(self, async_tags: TagsResource, run: Any) -> None:
 22        self._async_tags = async_tags
 23        self._run = run
 24
 25    def list(
 26        self,
 27        *,
 28        ids: List[int] | None = None,
 29        name_contains: str | None = None,
 30        name_exact: str | None = None,
 31        page: int | None = None,
 32        page_size: int | None = None,
 33        ordering: str | None = None,
 34        descending: bool = False,
 35        full_perms: bool = False,
 36    ) -> PagedResult[Tag]:
 37        """Return tags defined in paperless-ngx.
 38
 39        When ``page`` is ``None`` (the default), all pages are fetched
 40        automatically and ``next`` / ``previous`` in the result are always
 41        ``None``.  When ``page`` is set, only that page is fetched and
 42        ``next`` / ``previous`` reflect the raw API values.
 43
 44        Args:
 45            ids: Return only tags whose ID is in this list.
 46            name_contains: Case-insensitive substring filter on tag name.
 47            name_exact: Case-insensitive exact match on tag name.
 48            page: Return only this specific page (1-based).
 49            page_size: Number of results per page.
 50            ordering: Field to sort by.
 51            descending: When ``True``, reverses the sort direction.
 52            full_perms: When ``True``, paperless-ngx returns the full view/change
 53                permissions of every object, available as
 54                ``Tag.permissions``; ``user_can_change`` is then ``None``.
 55                Default: ``False``.
 56
 57        Returns:
 58            :class:`~easypaperless.models.paged_result.PagedResult` of
 59            :class:`~easypaperless.models.tags.Tag` objects.
 60        """
 61        return cast(
 62            PagedResult[Tag],
 63            self._run(
 64                self._async_tags.list(
 65                    ids=ids,
 66                    name_contains=name_contains,
 67                    name_exact=name_exact,
 68                    page=page,
 69                    page_size=page_size,
 70                    ordering=ordering,
 71                    descending=descending,
 72                    full_perms=full_perms,
 73                )
 74            ),
 75        )
 76
 77    def get(self, id: int, *, full_perms: bool = False) -> Tag:
 78        """Fetch a single tag by its ID.
 79
 80        Args:
 81            id: Numeric tag ID.
 82            full_perms: When ``True``, paperless-ngx returns the full view/change
 83                permissions, available as ``Tag.permissions``;
 84                ``user_can_change`` is then ``None``. Default: ``False``.
 85
 86        Returns:
 87            The :class:`~easypaperless.models.tags.Tag` with the given ID.
 88
 89        Raises:
 90            ~easypaperless.exceptions.NotFoundError: If no tag exists with
 91                that ID.
 92        """
 93        return cast(Tag, self._run(self._async_tags.get(id, full_perms=full_perms)))
 94
 95    def create(
 96        self,
 97        *,
 98        name: str,
 99        color: str | Unset = UNSET,
100        is_inbox_tag: bool | Unset = UNSET,
101        match: str | Unset = UNSET,
102        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
103        is_insensitive: bool = True,
104        parent: int | None | Unset = UNSET,
105        owner: int | None | Unset = UNSET,
106        set_permissions: SetPermissions | None | Unset = UNSET,
107    ) -> Tag:
108        """Create a new tag.
109
110        Args:
111            name: Tag name. Must be unique.
112            color: Background colour as a CSS hex string.
113            is_inbox_tag: When ``True``, newly ingested documents get this tag.
114            match: Auto-matching pattern.
115            matching_algorithm: Controls how ``match`` is applied.
116                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
117                regular-expression matching.
118            is_insensitive: When ``True``, ``match`` is case-insensitive.
119                Defaults to ``True``, matching the paperless-ngx API default.
120            parent: ID of parent tag for hierarchical trees.
121            owner: Numeric user ID to assign as owner.
122            set_permissions: Explicit view/change permission sets.
123                Pass ``None`` to create with empty permissions.
124
125        Returns:
126            The newly created :class:`~easypaperless.models.tags.Tag`.
127        """
128        return cast(
129            Tag,
130            self._run(
131                self._async_tags.create(
132                    name=name,
133                    color=color,
134                    is_inbox_tag=is_inbox_tag,
135                    match=match,
136                    matching_algorithm=matching_algorithm,
137                    is_insensitive=is_insensitive,
138                    parent=parent,
139                    owner=owner,
140                    set_permissions=set_permissions,
141                )
142            ),
143        )
144
145    def update(
146        self,
147        id: int,
148        *,
149        name: str | Unset = UNSET,
150        color: str | Unset = UNSET,
151        is_inbox_tag: bool | Unset = UNSET,
152        match: str | Unset = UNSET,
153        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
154        is_insensitive: bool | Unset = UNSET,
155        parent: int | None | Unset = UNSET,
156        owner: int | None | Unset = UNSET,
157        set_permissions: SetPermissions | None | Unset = UNSET,
158    ) -> Tag:
159        """Partially update a tag (PATCH semantics).
160
161        Args:
162            id: Numeric ID of the tag to update.
163            name: Tag name.
164            color: Background colour as a CSS hex string.
165            is_inbox_tag: When ``True``, newly ingested documents get this tag.
166            match: Auto-matching pattern.
167            matching_algorithm: Controls how ``match`` is applied.
168                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
169                regular-expression matching.
170            is_insensitive: When ``True``, ``match`` is case-insensitive.
171            parent: ID of parent tag.
172                Pass ``None`` to clear (make root tag).
173                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
174            owner: Numeric user ID to assign as owner.
175                Pass ``None`` to clear the owner.
176                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
177            set_permissions: Explicit view/change permission sets.
178                Pass ``None`` to clear all permissions (overwrite with empty).
179                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
180
181        Returns:
182            The updated :class:`~easypaperless.models.tags.Tag`.
183        """
184        return cast(
185            Tag,
186            self._run(
187                self._async_tags.update(
188                    id,
189                    name=name,
190                    color=color,
191                    is_inbox_tag=is_inbox_tag,
192                    match=match,
193                    matching_algorithm=matching_algorithm,
194                    is_insensitive=is_insensitive,
195                    parent=parent,
196                    owner=owner,
197                    set_permissions=set_permissions,
198                )
199            ),
200        )
201
202    def delete(self, id: int) -> None:
203        """Delete a tag.
204
205        Args:
206            id: Numeric ID of the tag to delete.
207
208        Raises:
209            ~easypaperless.exceptions.NotFoundError: If no tag exists with
210                that ID.
211        """
212        self._run(self._async_tags.delete(id))
213
214    def bulk_delete(self, ids: List[int]) -> None:
215        """Permanently delete multiple tags in a single request.
216
217        Args:
218            ids: List of tag IDs to delete.
219        """
220        self._run(self._async_tags.bulk_delete(ids))
221
222    def bulk_set_permissions(
223        self,
224        ids: List[int],
225        *,
226        set_permissions: SetPermissions | Unset = UNSET,
227        owner: int | None | Unset = UNSET,
228        merge: bool = False,
229    ) -> None:
230        """Set permissions and/or owner on multiple tags.
231
232        Args:
233            ids: List of tag IDs to modify.
234            set_permissions: Explicit view/change permission sets.
235                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
236            owner: Numeric user ID to assign as owner.
237                Pass ``None`` to clear the owner.
238                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
239            merge: When ``True``, new permissions are merged with existing ones.
240        """
241        self._run(
242            self._async_tags.bulk_set_permissions(
243                ids, set_permissions=set_permissions, owner=owner, merge=merge
244            )
245        )

Sync accessor for tags: client.tags.

SyncTagsResource( async_tags: TagsResource, run: Any)
21    def __init__(self, async_tags: TagsResource, run: Any) -> None:
22        self._async_tags = async_tags
23        self._run = run
def list( self, *, ids: Optional[List[int]] = None, name_contains: str | None = None, name_exact: str | None = None, page: int | None = None, page_size: int | None = None, ordering: str | None = None, descending: bool = False, full_perms: bool = False) -> easypaperless.PagedResult[Tag]:
25    def list(
26        self,
27        *,
28        ids: List[int] | None = None,
29        name_contains: str | None = None,
30        name_exact: str | None = None,
31        page: int | None = None,
32        page_size: int | None = None,
33        ordering: str | None = None,
34        descending: bool = False,
35        full_perms: bool = False,
36    ) -> PagedResult[Tag]:
37        """Return tags defined in paperless-ngx.
38
39        When ``page`` is ``None`` (the default), all pages are fetched
40        automatically and ``next`` / ``previous`` in the result are always
41        ``None``.  When ``page`` is set, only that page is fetched and
42        ``next`` / ``previous`` reflect the raw API values.
43
44        Args:
45            ids: Return only tags whose ID is in this list.
46            name_contains: Case-insensitive substring filter on tag name.
47            name_exact: Case-insensitive exact match on tag name.
48            page: Return only this specific page (1-based).
49            page_size: Number of results per page.
50            ordering: Field to sort by.
51            descending: When ``True``, reverses the sort direction.
52            full_perms: When ``True``, paperless-ngx returns the full view/change
53                permissions of every object, available as
54                ``Tag.permissions``; ``user_can_change`` is then ``None``.
55                Default: ``False``.
56
57        Returns:
58            :class:`~easypaperless.models.paged_result.PagedResult` of
59            :class:`~easypaperless.models.tags.Tag` objects.
60        """
61        return cast(
62            PagedResult[Tag],
63            self._run(
64                self._async_tags.list(
65                    ids=ids,
66                    name_contains=name_contains,
67                    name_exact=name_exact,
68                    page=page,
69                    page_size=page_size,
70                    ordering=ordering,
71                    descending=descending,
72                    full_perms=full_perms,
73                )
74            ),
75        )

Return tags defined in paperless-ngx.

When page is None (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • ids: Return only tags whose ID is in this list.
  • name_contains: Case-insensitive substring filter on tag name.
  • name_exact: Case-insensitive exact match on tag name.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
  • ordering: Field to sort by.
  • descending: When True, reverses the sort direction.
  • full_perms: When True, paperless-ngx returns the full view/change permissions of every object, available as Tag.permissions; user_can_change is then None. Default: False.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.tags.Tag objects.

def get( self, id: int, *, full_perms: bool = False) -> easypaperless.Tag:
77    def get(self, id: int, *, full_perms: bool = False) -> Tag:
78        """Fetch a single tag by its ID.
79
80        Args:
81            id: Numeric tag ID.
82            full_perms: When ``True``, paperless-ngx returns the full view/change
83                permissions, available as ``Tag.permissions``;
84                ``user_can_change`` is then ``None``. Default: ``False``.
85
86        Returns:
87            The :class:`~easypaperless.models.tags.Tag` with the given ID.
88
89        Raises:
90            ~easypaperless.exceptions.NotFoundError: If no tag exists with
91                that ID.
92        """
93        return cast(Tag, self._run(self._async_tags.get(id, full_perms=full_perms)))

Fetch a single tag by its ID.

Arguments:
  • id: Numeric tag ID.
  • full_perms: When True, paperless-ngx returns the full view/change permissions, available as Tag.permissions; user_can_change is then None. Default: False.
Returns:

The ~easypaperless.models.tags.Tag with the given ID.

Raises:
def create( self, *, name: str, color: str | easypaperless.Unset = UNSET, is_inbox_tag: bool | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool = True, parent: int | None | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.Tag:
 95    def create(
 96        self,
 97        *,
 98        name: str,
 99        color: str | Unset = UNSET,
100        is_inbox_tag: bool | Unset = UNSET,
101        match: str | Unset = UNSET,
102        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
103        is_insensitive: bool = True,
104        parent: int | None | Unset = UNSET,
105        owner: int | None | Unset = UNSET,
106        set_permissions: SetPermissions | None | Unset = UNSET,
107    ) -> Tag:
108        """Create a new tag.
109
110        Args:
111            name: Tag name. Must be unique.
112            color: Background colour as a CSS hex string.
113            is_inbox_tag: When ``True``, newly ingested documents get this tag.
114            match: Auto-matching pattern.
115            matching_algorithm: Controls how ``match`` is applied.
116                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
117                regular-expression matching.
118            is_insensitive: When ``True``, ``match`` is case-insensitive.
119                Defaults to ``True``, matching the paperless-ngx API default.
120            parent: ID of parent tag for hierarchical trees.
121            owner: Numeric user ID to assign as owner.
122            set_permissions: Explicit view/change permission sets.
123                Pass ``None`` to create with empty permissions.
124
125        Returns:
126            The newly created :class:`~easypaperless.models.tags.Tag`.
127        """
128        return cast(
129            Tag,
130            self._run(
131                self._async_tags.create(
132                    name=name,
133                    color=color,
134                    is_inbox_tag=is_inbox_tag,
135                    match=match,
136                    matching_algorithm=matching_algorithm,
137                    is_insensitive=is_insensitive,
138                    parent=parent,
139                    owner=owner,
140                    set_permissions=set_permissions,
141                )
142            ),
143        )

Create a new tag.

Arguments:
  • name: Tag name. Must be unique.
  • color: Background colour as a CSS hex string.
  • is_inbox_tag: When True, newly ingested documents get this tag.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive. Defaults to True, matching the paperless-ngx API default.
  • parent: ID of parent tag for hierarchical trees.
  • owner: Numeric user ID to assign as owner.
  • set_permissions: Explicit view/change permission sets. Pass None to create with empty permissions.
Returns:

The newly created ~easypaperless.models.tags.Tag.

def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, color: str | easypaperless.Unset = UNSET, is_inbox_tag: bool | easypaperless.Unset = UNSET, match: str | easypaperless.Unset = UNSET, matching_algorithm: easypaperless.MatchingAlgorithm | easypaperless.Unset = UNSET, is_insensitive: bool | easypaperless.Unset = UNSET, parent: int | None | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, set_permissions: easypaperless.SetPermissions | None | easypaperless.Unset = UNSET) -> easypaperless.Tag:
145    def update(
146        self,
147        id: int,
148        *,
149        name: str | Unset = UNSET,
150        color: str | Unset = UNSET,
151        is_inbox_tag: bool | Unset = UNSET,
152        match: str | Unset = UNSET,
153        matching_algorithm: MatchingAlgorithm | Unset = UNSET,
154        is_insensitive: bool | Unset = UNSET,
155        parent: int | None | Unset = UNSET,
156        owner: int | None | Unset = UNSET,
157        set_permissions: SetPermissions | None | Unset = UNSET,
158    ) -> Tag:
159        """Partially update a tag (PATCH semantics).
160
161        Args:
162            id: Numeric ID of the tag to update.
163            name: Tag name.
164            color: Background colour as a CSS hex string.
165            is_inbox_tag: When ``True``, newly ingested documents get this tag.
166            match: Auto-matching pattern.
167            matching_algorithm: Controls how ``match`` is applied.
168                E.g. ``matching_algorithm=MatchingAlgorithm.REGEX`` for
169                regular-expression matching.
170            is_insensitive: When ``True``, ``match`` is case-insensitive.
171            parent: ID of parent tag.
172                Pass ``None`` to clear (make root tag).
173                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
174            owner: Numeric user ID to assign as owner.
175                Pass ``None`` to clear the owner.
176                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
177            set_permissions: Explicit view/change permission sets.
178                Pass ``None`` to clear all permissions (overwrite with empty).
179                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
180
181        Returns:
182            The updated :class:`~easypaperless.models.tags.Tag`.
183        """
184        return cast(
185            Tag,
186            self._run(
187                self._async_tags.update(
188                    id,
189                    name=name,
190                    color=color,
191                    is_inbox_tag=is_inbox_tag,
192                    match=match,
193                    matching_algorithm=matching_algorithm,
194                    is_insensitive=is_insensitive,
195                    parent=parent,
196                    owner=owner,
197                    set_permissions=set_permissions,
198                )
199            ),
200        )

Partially update a tag (PATCH semantics).

Arguments:
  • id: Numeric ID of the tag to update.
  • name: Tag name.
  • color: Background colour as a CSS hex string.
  • is_inbox_tag: When True, newly ingested documents get this tag.
  • match: Auto-matching pattern.
  • matching_algorithm: Controls how match is applied. E.g. matching_algorithm=MatchingAlgorithm.REGEX for regular-expression matching.
  • is_insensitive: When True, match is case-insensitive.
  • parent: ID of parent tag. Pass None to clear (make root tag). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • set_permissions: Explicit view/change permission sets. Pass None to clear all permissions (overwrite with empty). Omit (or pass ~easypaperless.UNSET) to leave unchanged.
Returns:

The updated ~easypaperless.models.tags.Tag.

def delete(self, id: int) -> None:
202    def delete(self, id: int) -> None:
203        """Delete a tag.
204
205        Args:
206            id: Numeric ID of the tag to delete.
207
208        Raises:
209            ~easypaperless.exceptions.NotFoundError: If no tag exists with
210                that ID.
211        """
212        self._run(self._async_tags.delete(id))

Delete a tag.

Arguments:
  • id: Numeric ID of the tag to delete.
Raises:
def bulk_delete(self, ids: List[int]) -> None:
214    def bulk_delete(self, ids: List[int]) -> None:
215        """Permanently delete multiple tags in a single request.
216
217        Args:
218            ids: List of tag IDs to delete.
219        """
220        self._run(self._async_tags.bulk_delete(ids))

Permanently delete multiple tags in a single request.

Arguments:
  • ids: List of tag IDs to delete.
def bulk_set_permissions( self, ids: List[int], *, set_permissions: easypaperless.SetPermissions | easypaperless.Unset = UNSET, owner: int | None | easypaperless.Unset = UNSET, merge: bool = False) -> None:
222    def bulk_set_permissions(
223        self,
224        ids: List[int],
225        *,
226        set_permissions: SetPermissions | Unset = UNSET,
227        owner: int | None | Unset = UNSET,
228        merge: bool = False,
229    ) -> None:
230        """Set permissions and/or owner on multiple tags.
231
232        Args:
233            ids: List of tag IDs to modify.
234            set_permissions: Explicit view/change permission sets.
235                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
236            owner: Numeric user ID to assign as owner.
237                Pass ``None`` to clear the owner.
238                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
239            merge: When ``True``, new permissions are merged with existing ones.
240        """
241        self._run(
242            self._async_tags.bulk_set_permissions(
243                ids, set_permissions=set_permissions, owner=owner, merge=merge
244            )
245        )

Set permissions and/or owner on multiple tags.

Arguments:
  • ids: List of tag IDs to modify.
  • set_permissions: Explicit view/change permission sets. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • owner: Numeric user ID to assign as owner. Pass None to clear the owner. Omit (or pass ~easypaperless.UNSET) to leave unchanged.
  • merge: When True, new permissions are merged with existing ones.
class UsersResource:
 20class UsersResource:
 21    """Accessor for users: ``client.users``."""
 22
 23    def __init__(self, core: _ClientCore) -> None:
 24        self._core = core
 25
 26    async def list(
 27        self,
 28        *,
 29        username_contains: str | Unset = UNSET,
 30        username_exact: str | Unset = UNSET,
 31        ordering: str | Unset = UNSET,
 32        page: int | Unset = UNSET,
 33        page_size: int | Unset = UNSET,
 34    ) -> PagedResult[User]:
 35        """Return users defined in paperless-ngx.
 36
 37        When ``page`` is ``UNSET`` (the default), all pages are fetched
 38        automatically and ``next`` / ``previous`` in the result are always
 39        ``None``.  When ``page`` is set, only that page is fetched and
 40        ``next`` / ``previous`` reflect the raw API values.
 41
 42        Args:
 43            username_contains: Case-insensitive substring filter on username.
 44            username_exact: Case-insensitive exact match on username.
 45            ordering: Field to sort by.
 46            page: Return only this specific page (1-based).
 47            page_size: Number of results per page.
 48
 49        Returns:
 50            :class:`~easypaperless.models.paged_result.PagedResult` of
 51            :class:`~easypaperless.models.users.User` objects.
 52        """
 53        logger.info("Listing users")
 54        params: dict[str, Any] = {}
 55        if not isinstance(username_contains, Unset):
 56            params["username__icontains"] = username_contains
 57        if not isinstance(username_exact, Unset):
 58            params["username__iexact"] = username_exact
 59        if not isinstance(ordering, Unset):
 60            params["ordering"] = ordering
 61        if not isinstance(page, Unset):
 62            params["page"] = page
 63        if not isinstance(page_size, Unset):
 64            params["page_size"] = page_size
 65        return cast(
 66            PagedResult[User],
 67            await self._core._list_resource("users", User, params or None),
 68        )
 69
 70    async def get(self, id: int) -> User:
 71        """Fetch a single user by their ID.
 72
 73        Args:
 74            id: Numeric user ID.
 75
 76        Returns:
 77            The :class:`~easypaperless.models.users.User` with the given ID.
 78
 79        Raises:
 80            ~easypaperless.exceptions.NotFoundError: If no user exists with
 81                that ID.
 82        """
 83        logger.info("Getting user id=%d", id)
 84        return cast(User, await self._core._get_resource("users", id, User))
 85
 86    async def create(
 87        self,
 88        *,
 89        username: str,
 90        email: str | Unset = UNSET,
 91        password: str | Unset = UNSET,
 92        first_name: str | Unset = UNSET,
 93        last_name: str | Unset = UNSET,
 94        date_joined: datetime | Unset = UNSET,
 95        is_staff: bool | Unset = UNSET,
 96        is_active: bool | Unset = UNSET,
 97        is_superuser: bool | Unset = UNSET,
 98        groups: List[int] | Unset = UNSET,
 99        user_permissions: List[str] | Unset = UNSET,
100    ) -> User:
101        """Create a new user.
102
103        Args:
104            username: Login username. Must be unique.
105            email: Email address.
106            password: Password for the new account.
107            first_name: Given name.
108            last_name: Family name.
109            date_joined: Account creation timestamp.
110            is_staff: Grant staff (admin UI) access.
111            is_active: Whether the account is active.
112            is_superuser: Grant unrestricted superuser access.
113            groups: IDs of groups to assign the user to.
114            user_permissions: Directly assigned permission codenames, without
115                the app label (e.g. ``["view_document"]``).  The app-labelled
116                form ``"documents.view_document"`` is rejected by paperless-ngx
117                with a :exc:`~easypaperless.exceptions.BadRequestError`.
118
119        Returns:
120            The newly created :class:`~easypaperless.models.users.User`.
121        """
122        logger.info("Creating user username=%r", username)
123        return cast(
124            User,
125            await self._core._create_resource(
126                "users",
127                User,
128                username=username,
129                email=email,
130                password=password,
131                first_name=first_name,
132                last_name=last_name,
133                date_joined=date_joined,
134                is_staff=is_staff,
135                is_active=is_active,
136                is_superuser=is_superuser,
137                groups=groups,
138                user_permissions=user_permissions,
139            ),
140        )
141
142    async def update(
143        self,
144        id: int,
145        *,
146        username: str | Unset = UNSET,
147        email: str | Unset = UNSET,
148        password: str | Unset = UNSET,
149        first_name: str | Unset = UNSET,
150        last_name: str | Unset = UNSET,
151        date_joined: datetime | Unset = UNSET,
152        is_staff: bool | Unset = UNSET,
153        is_active: bool | Unset = UNSET,
154        is_superuser: bool | Unset = UNSET,
155        groups: List[int] | Unset = UNSET,
156        user_permissions: List[str] | Unset = UNSET,
157    ) -> User:
158        """Partially update a user (PATCH semantics).
159
160        Only fields with a non-:data:`~easypaperless.UNSET` value are included
161        in the request body.  Omit a parameter (or pass
162        :data:`~easypaperless.UNSET`) to leave it unchanged.
163
164        Args:
165            id: Numeric ID of the user to update.
166            username: Login username.
167            email: Email address.
168            password: New password.
169            first_name: Given name.
170            last_name: Family name.
171            date_joined: Account creation timestamp.
172            is_staff: Grant or revoke staff access.
173            is_active: Activate or deactivate the account.
174            is_superuser: Grant or revoke superuser access.
175            groups: IDs of groups to assign the user to.
176            user_permissions: Directly assigned permission codenames, without
177                the app label (e.g. ``["view_document"]``).  The app-labelled
178                form ``"documents.view_document"`` is rejected by paperless-ngx
179                with a :exc:`~easypaperless.exceptions.BadRequestError`.
180
181        Returns:
182            The updated :class:`~easypaperless.models.users.User`.
183        """
184        logger.info("Updating user id=%d", id)
185        return cast(
186            User,
187            await self._core._update_resource(
188                "users",
189                id,
190                User,
191                username=username,
192                email=email,
193                password=password,
194                first_name=first_name,
195                last_name=last_name,
196                date_joined=date_joined,
197                is_staff=is_staff,
198                is_active=is_active,
199                is_superuser=is_superuser,
200                groups=groups,
201                user_permissions=user_permissions,
202            ),
203        )
204
205    async def delete(self, id: int) -> None:
206        """Delete a user.
207
208        Args:
209            id: Numeric ID of the user to delete.
210
211        Raises:
212            ~easypaperless.exceptions.NotFoundError: If no user exists with
213                that ID.
214        """
215        logger.info("Deleting user id=%d", id)
216        await self._core._delete_resource("users", id)

Accessor for users: client.users.

UsersResource(core: easypaperless.client._ClientCore)
23    def __init__(self, core: _ClientCore) -> None:
24        self._core = core
async def list( self, *, username_contains: str | easypaperless.Unset = UNSET, username_exact: str | easypaperless.Unset = UNSET, ordering: str | easypaperless.Unset = UNSET, page: int | easypaperless.Unset = UNSET, page_size: int | easypaperless.Unset = UNSET) -> easypaperless.PagedResult[User]:
26    async def list(
27        self,
28        *,
29        username_contains: str | Unset = UNSET,
30        username_exact: str | Unset = UNSET,
31        ordering: str | Unset = UNSET,
32        page: int | Unset = UNSET,
33        page_size: int | Unset = UNSET,
34    ) -> PagedResult[User]:
35        """Return users defined in paperless-ngx.
36
37        When ``page`` is ``UNSET`` (the default), all pages are fetched
38        automatically and ``next`` / ``previous`` in the result are always
39        ``None``.  When ``page`` is set, only that page is fetched and
40        ``next`` / ``previous`` reflect the raw API values.
41
42        Args:
43            username_contains: Case-insensitive substring filter on username.
44            username_exact: Case-insensitive exact match on username.
45            ordering: Field to sort by.
46            page: Return only this specific page (1-based).
47            page_size: Number of results per page.
48
49        Returns:
50            :class:`~easypaperless.models.paged_result.PagedResult` of
51            :class:`~easypaperless.models.users.User` objects.
52        """
53        logger.info("Listing users")
54        params: dict[str, Any] = {}
55        if not isinstance(username_contains, Unset):
56            params["username__icontains"] = username_contains
57        if not isinstance(username_exact, Unset):
58            params["username__iexact"] = username_exact
59        if not isinstance(ordering, Unset):
60            params["ordering"] = ordering
61        if not isinstance(page, Unset):
62            params["page"] = page
63        if not isinstance(page_size, Unset):
64            params["page_size"] = page_size
65        return cast(
66            PagedResult[User],
67            await self._core._list_resource("users", User, params or None),
68        )

Return users defined in paperless-ngx.

When page is UNSET (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • username_contains: Case-insensitive substring filter on username.
  • username_exact: Case-insensitive exact match on username.
  • ordering: Field to sort by.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.users.User objects.

async def get(self, id: int) -> easypaperless.User:
70    async def get(self, id: int) -> User:
71        """Fetch a single user by their ID.
72
73        Args:
74            id: Numeric user ID.
75
76        Returns:
77            The :class:`~easypaperless.models.users.User` with the given ID.
78
79        Raises:
80            ~easypaperless.exceptions.NotFoundError: If no user exists with
81                that ID.
82        """
83        logger.info("Getting user id=%d", id)
84        return cast(User, await self._core._get_resource("users", id, User))

Fetch a single user by their ID.

Arguments:
  • id: Numeric user ID.
Returns:

The ~easypaperless.models.users.User with the given ID.

Raises:
async def create( self, *, username: str, email: str | easypaperless.Unset = UNSET, password: str | easypaperless.Unset = UNSET, first_name: str | easypaperless.Unset = UNSET, last_name: str | easypaperless.Unset = UNSET, date_joined: datetime.datetime | easypaperless.Unset = UNSET, is_staff: bool | easypaperless.Unset = UNSET, is_active: bool | easypaperless.Unset = UNSET, is_superuser: bool | easypaperless.Unset = UNSET, groups: Union[List[int], easypaperless.Unset] = UNSET, user_permissions: Union[List[str], easypaperless.Unset] = UNSET) -> easypaperless.User:
 86    async def create(
 87        self,
 88        *,
 89        username: str,
 90        email: str | Unset = UNSET,
 91        password: str | Unset = UNSET,
 92        first_name: str | Unset = UNSET,
 93        last_name: str | Unset = UNSET,
 94        date_joined: datetime | Unset = UNSET,
 95        is_staff: bool | Unset = UNSET,
 96        is_active: bool | Unset = UNSET,
 97        is_superuser: bool | Unset = UNSET,
 98        groups: List[int] | Unset = UNSET,
 99        user_permissions: List[str] | Unset = UNSET,
100    ) -> User:
101        """Create a new user.
102
103        Args:
104            username: Login username. Must be unique.
105            email: Email address.
106            password: Password for the new account.
107            first_name: Given name.
108            last_name: Family name.
109            date_joined: Account creation timestamp.
110            is_staff: Grant staff (admin UI) access.
111            is_active: Whether the account is active.
112            is_superuser: Grant unrestricted superuser access.
113            groups: IDs of groups to assign the user to.
114            user_permissions: Directly assigned permission codenames, without
115                the app label (e.g. ``["view_document"]``).  The app-labelled
116                form ``"documents.view_document"`` is rejected by paperless-ngx
117                with a :exc:`~easypaperless.exceptions.BadRequestError`.
118
119        Returns:
120            The newly created :class:`~easypaperless.models.users.User`.
121        """
122        logger.info("Creating user username=%r", username)
123        return cast(
124            User,
125            await self._core._create_resource(
126                "users",
127                User,
128                username=username,
129                email=email,
130                password=password,
131                first_name=first_name,
132                last_name=last_name,
133                date_joined=date_joined,
134                is_staff=is_staff,
135                is_active=is_active,
136                is_superuser=is_superuser,
137                groups=groups,
138                user_permissions=user_permissions,
139            ),
140        )

Create a new user.

Arguments:
  • username: Login username. Must be unique.
  • email: Email address.
  • password: Password for the new account.
  • first_name: Given name.
  • last_name: Family name.
  • date_joined: Account creation timestamp.
  • is_staff: Grant staff (admin UI) access.
  • is_active: Whether the account is active.
  • is_superuser: Grant unrestricted superuser access.
  • groups: IDs of groups to assign the user to.
  • user_permissions: Directly assigned permission codenames, without the app label (e.g. ["view_document"]). The app-labelled form "documents.view_document" is rejected by paperless-ngx with a ~easypaperless.exceptions.BadRequestError.
Returns:

The newly created ~easypaperless.models.users.User.

async def update( self, id: int, *, username: str | easypaperless.Unset = UNSET, email: str | easypaperless.Unset = UNSET, password: str | easypaperless.Unset = UNSET, first_name: str | easypaperless.Unset = UNSET, last_name: str | easypaperless.Unset = UNSET, date_joined: datetime.datetime | easypaperless.Unset = UNSET, is_staff: bool | easypaperless.Unset = UNSET, is_active: bool | easypaperless.Unset = UNSET, is_superuser: bool | easypaperless.Unset = UNSET, groups: Union[List[int], easypaperless.Unset] = UNSET, user_permissions: Union[List[str], easypaperless.Unset] = UNSET) -> easypaperless.User:
142    async def update(
143        self,
144        id: int,
145        *,
146        username: str | Unset = UNSET,
147        email: str | Unset = UNSET,
148        password: str | Unset = UNSET,
149        first_name: str | Unset = UNSET,
150        last_name: str | Unset = UNSET,
151        date_joined: datetime | Unset = UNSET,
152        is_staff: bool | Unset = UNSET,
153        is_active: bool | Unset = UNSET,
154        is_superuser: bool | Unset = UNSET,
155        groups: List[int] | Unset = UNSET,
156        user_permissions: List[str] | Unset = UNSET,
157    ) -> User:
158        """Partially update a user (PATCH semantics).
159
160        Only fields with a non-:data:`~easypaperless.UNSET` value are included
161        in the request body.  Omit a parameter (or pass
162        :data:`~easypaperless.UNSET`) to leave it unchanged.
163
164        Args:
165            id: Numeric ID of the user to update.
166            username: Login username.
167            email: Email address.
168            password: New password.
169            first_name: Given name.
170            last_name: Family name.
171            date_joined: Account creation timestamp.
172            is_staff: Grant or revoke staff access.
173            is_active: Activate or deactivate the account.
174            is_superuser: Grant or revoke superuser access.
175            groups: IDs of groups to assign the user to.
176            user_permissions: Directly assigned permission codenames, without
177                the app label (e.g. ``["view_document"]``).  The app-labelled
178                form ``"documents.view_document"`` is rejected by paperless-ngx
179                with a :exc:`~easypaperless.exceptions.BadRequestError`.
180
181        Returns:
182            The updated :class:`~easypaperless.models.users.User`.
183        """
184        logger.info("Updating user id=%d", id)
185        return cast(
186            User,
187            await self._core._update_resource(
188                "users",
189                id,
190                User,
191                username=username,
192                email=email,
193                password=password,
194                first_name=first_name,
195                last_name=last_name,
196                date_joined=date_joined,
197                is_staff=is_staff,
198                is_active=is_active,
199                is_superuser=is_superuser,
200                groups=groups,
201                user_permissions=user_permissions,
202            ),
203        )

Partially update a user (PATCH semantics).

Only fields with a non-~easypaperless.UNSET value are included in the request body. Omit a parameter (or pass ~easypaperless.UNSET) to leave it unchanged.

Arguments:
  • id: Numeric ID of the user to update.
  • username: Login username.
  • email: Email address.
  • password: New password.
  • first_name: Given name.
  • last_name: Family name.
  • date_joined: Account creation timestamp.
  • is_staff: Grant or revoke staff access.
  • is_active: Activate or deactivate the account.
  • is_superuser: Grant or revoke superuser access.
  • groups: IDs of groups to assign the user to.
  • user_permissions: Directly assigned permission codenames, without the app label (e.g. ["view_document"]). The app-labelled form "documents.view_document" is rejected by paperless-ngx with a ~easypaperless.exceptions.BadRequestError.
Returns:

The updated ~easypaperless.models.users.User.

async def delete(self, id: int) -> None:
205    async def delete(self, id: int) -> None:
206        """Delete a user.
207
208        Args:
209            id: Numeric ID of the user to delete.
210
211        Raises:
212            ~easypaperless.exceptions.NotFoundError: If no user exists with
213                that ID.
214        """
215        logger.info("Deleting user id=%d", id)
216        await self._core._delete_resource("users", id)

Delete a user.

Arguments:
  • id: Numeric ID of the user to delete.
Raises:
class SyncUsersResource:
 17class SyncUsersResource:
 18    """Sync accessor for users: ``client.users``."""
 19
 20    def __init__(self, async_users: UsersResource, run: Any) -> None:
 21        self._async_users = async_users
 22        self._run = run
 23
 24    def list(
 25        self,
 26        *,
 27        username_contains: str | Unset = UNSET,
 28        username_exact: str | Unset = UNSET,
 29        ordering: str | Unset = UNSET,
 30        page: int | Unset = UNSET,
 31        page_size: int | Unset = UNSET,
 32    ) -> PagedResult[User]:
 33        """Return users defined in paperless-ngx.
 34
 35        When ``page`` is ``UNSET`` (the default), all pages are fetched
 36        automatically and ``next`` / ``previous`` in the result are always
 37        ``None``.  When ``page`` is set, only that page is fetched and
 38        ``next`` / ``previous`` reflect the raw API values.
 39
 40        Args:
 41            username_contains: Case-insensitive substring filter on username.
 42            username_exact: Case-insensitive exact match on username.
 43            ordering: Field to sort by.
 44            page: Return only this specific page (1-based).
 45            page_size: Number of results per page.
 46
 47        Returns:
 48            :class:`~easypaperless.models.paged_result.PagedResult` of
 49            :class:`~easypaperless.models.users.User` objects.
 50        """
 51        return cast(
 52            PagedResult[User],
 53            self._run(
 54                self._async_users.list(
 55                    username_contains=username_contains,
 56                    username_exact=username_exact,
 57                    ordering=ordering,
 58                    page=page,
 59                    page_size=page_size,
 60                )
 61            ),
 62        )
 63
 64    def get(self, id: int) -> User:
 65        """Fetch a single user by their ID.
 66
 67        Args:
 68            id: Numeric user ID.
 69
 70        Returns:
 71            The :class:`~easypaperless.models.users.User` with the given ID.
 72
 73        Raises:
 74            ~easypaperless.exceptions.NotFoundError: If no user exists with
 75                that ID.
 76        """
 77        return cast(User, self._run(self._async_users.get(id)))
 78
 79    def create(
 80        self,
 81        *,
 82        username: str,
 83        email: str | Unset = UNSET,
 84        password: str | Unset = UNSET,
 85        first_name: str | Unset = UNSET,
 86        last_name: str | Unset = UNSET,
 87        date_joined: datetime | Unset = UNSET,
 88        is_staff: bool | Unset = UNSET,
 89        is_active: bool | Unset = UNSET,
 90        is_superuser: bool | Unset = UNSET,
 91        groups: List[int] | Unset = UNSET,
 92        user_permissions: List[str] | Unset = UNSET,
 93    ) -> User:
 94        """Create a new user.
 95
 96        Args:
 97            username: Login username. Must be unique.
 98            email: Email address.
 99            password: Password for the new account.
100            first_name: Given name.
101            last_name: Family name.
102            date_joined: Account creation timestamp.
103            is_staff: Grant staff (admin UI) access.
104            is_active: Whether the account is active.
105            is_superuser: Grant unrestricted superuser access.
106            groups: IDs of groups to assign the user to.
107            user_permissions: Directly assigned permission codenames, without
108                the app label (e.g. ``["view_document"]``).  The app-labelled
109                form ``"documents.view_document"`` is rejected by paperless-ngx
110                with a :exc:`~easypaperless.exceptions.BadRequestError`.
111
112        Returns:
113            The newly created :class:`~easypaperless.models.users.User`.
114        """
115        return cast(
116            User,
117            self._run(
118                self._async_users.create(
119                    username=username,
120                    email=email,
121                    password=password,
122                    first_name=first_name,
123                    last_name=last_name,
124                    date_joined=date_joined,
125                    is_staff=is_staff,
126                    is_active=is_active,
127                    is_superuser=is_superuser,
128                    groups=groups,
129                    user_permissions=user_permissions,
130                )
131            ),
132        )
133
134    def update(
135        self,
136        id: int,
137        *,
138        username: str | Unset = UNSET,
139        email: str | Unset = UNSET,
140        password: str | Unset = UNSET,
141        first_name: str | Unset = UNSET,
142        last_name: str | Unset = UNSET,
143        date_joined: datetime | Unset = UNSET,
144        is_staff: bool | Unset = UNSET,
145        is_active: bool | Unset = UNSET,
146        is_superuser: bool | Unset = UNSET,
147        groups: List[int] | Unset = UNSET,
148        user_permissions: List[str] | Unset = UNSET,
149    ) -> User:
150        """Partially update a user (PATCH semantics).
151
152        Only fields with a non-:data:`~easypaperless.UNSET` value are included
153        in the request body.  Omit a parameter (or pass
154        :data:`~easypaperless.UNSET`) to leave it unchanged.
155
156        Args:
157            id: Numeric ID of the user to update.
158            username: Login username.
159            email: Email address.
160            password: New password.
161            first_name: Given name.
162            last_name: Family name.
163            date_joined: Account creation timestamp.
164            is_staff: Grant or revoke staff access.
165            is_active: Activate or deactivate the account.
166            is_superuser: Grant or revoke superuser access.
167            groups: IDs of groups to assign the user to.
168            user_permissions: Directly assigned permission codenames, without
169                the app label (e.g. ``["view_document"]``).  The app-labelled
170                form ``"documents.view_document"`` is rejected by paperless-ngx
171                with a :exc:`~easypaperless.exceptions.BadRequestError`.
172
173        Returns:
174            The updated :class:`~easypaperless.models.users.User`.
175        """
176        return cast(
177            User,
178            self._run(
179                self._async_users.update(
180                    id,
181                    username=username,
182                    email=email,
183                    password=password,
184                    first_name=first_name,
185                    last_name=last_name,
186                    date_joined=date_joined,
187                    is_staff=is_staff,
188                    is_active=is_active,
189                    is_superuser=is_superuser,
190                    groups=groups,
191                    user_permissions=user_permissions,
192                )
193            ),
194        )
195
196    def delete(self, id: int) -> None:
197        """Delete a user.
198
199        Args:
200            id: Numeric ID of the user to delete.
201
202        Raises:
203            ~easypaperless.exceptions.NotFoundError: If no user exists with
204                that ID.
205        """
206        self._run(self._async_users.delete(id))

Sync accessor for users: client.users.

SyncUsersResource( async_users: UsersResource, run: Any)
20    def __init__(self, async_users: UsersResource, run: Any) -> None:
21        self._async_users = async_users
22        self._run = run
def list( self, *, username_contains: str | easypaperless.Unset = UNSET, username_exact: str | easypaperless.Unset = UNSET, ordering: str | easypaperless.Unset = UNSET, page: int | easypaperless.Unset = UNSET, page_size: int | easypaperless.Unset = UNSET) -> easypaperless.PagedResult[User]:
24    def list(
25        self,
26        *,
27        username_contains: str | Unset = UNSET,
28        username_exact: str | Unset = UNSET,
29        ordering: str | Unset = UNSET,
30        page: int | Unset = UNSET,
31        page_size: int | Unset = UNSET,
32    ) -> PagedResult[User]:
33        """Return users defined in paperless-ngx.
34
35        When ``page`` is ``UNSET`` (the default), all pages are fetched
36        automatically and ``next`` / ``previous`` in the result are always
37        ``None``.  When ``page`` is set, only that page is fetched and
38        ``next`` / ``previous`` reflect the raw API values.
39
40        Args:
41            username_contains: Case-insensitive substring filter on username.
42            username_exact: Case-insensitive exact match on username.
43            ordering: Field to sort by.
44            page: Return only this specific page (1-based).
45            page_size: Number of results per page.
46
47        Returns:
48            :class:`~easypaperless.models.paged_result.PagedResult` of
49            :class:`~easypaperless.models.users.User` objects.
50        """
51        return cast(
52            PagedResult[User],
53            self._run(
54                self._async_users.list(
55                    username_contains=username_contains,
56                    username_exact=username_exact,
57                    ordering=ordering,
58                    page=page,
59                    page_size=page_size,
60                )
61            ),
62        )

Return users defined in paperless-ngx.

When page is UNSET (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • username_contains: Case-insensitive substring filter on username.
  • username_exact: Case-insensitive exact match on username.
  • ordering: Field to sort by.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.users.User objects.

def get(self, id: int) -> easypaperless.User:
64    def get(self, id: int) -> User:
65        """Fetch a single user by their ID.
66
67        Args:
68            id: Numeric user ID.
69
70        Returns:
71            The :class:`~easypaperless.models.users.User` with the given ID.
72
73        Raises:
74            ~easypaperless.exceptions.NotFoundError: If no user exists with
75                that ID.
76        """
77        return cast(User, self._run(self._async_users.get(id)))

Fetch a single user by their ID.

Arguments:
  • id: Numeric user ID.
Returns:

The ~easypaperless.models.users.User with the given ID.

Raises:
def create( self, *, username: str, email: str | easypaperless.Unset = UNSET, password: str | easypaperless.Unset = UNSET, first_name: str | easypaperless.Unset = UNSET, last_name: str | easypaperless.Unset = UNSET, date_joined: datetime.datetime | easypaperless.Unset = UNSET, is_staff: bool | easypaperless.Unset = UNSET, is_active: bool | easypaperless.Unset = UNSET, is_superuser: bool | easypaperless.Unset = UNSET, groups: Union[List[int], easypaperless.Unset] = UNSET, user_permissions: Union[List[str], easypaperless.Unset] = UNSET) -> easypaperless.User:
 79    def create(
 80        self,
 81        *,
 82        username: str,
 83        email: str | Unset = UNSET,
 84        password: str | Unset = UNSET,
 85        first_name: str | Unset = UNSET,
 86        last_name: str | Unset = UNSET,
 87        date_joined: datetime | Unset = UNSET,
 88        is_staff: bool | Unset = UNSET,
 89        is_active: bool | Unset = UNSET,
 90        is_superuser: bool | Unset = UNSET,
 91        groups: List[int] | Unset = UNSET,
 92        user_permissions: List[str] | Unset = UNSET,
 93    ) -> User:
 94        """Create a new user.
 95
 96        Args:
 97            username: Login username. Must be unique.
 98            email: Email address.
 99            password: Password for the new account.
100            first_name: Given name.
101            last_name: Family name.
102            date_joined: Account creation timestamp.
103            is_staff: Grant staff (admin UI) access.
104            is_active: Whether the account is active.
105            is_superuser: Grant unrestricted superuser access.
106            groups: IDs of groups to assign the user to.
107            user_permissions: Directly assigned permission codenames, without
108                the app label (e.g. ``["view_document"]``).  The app-labelled
109                form ``"documents.view_document"`` is rejected by paperless-ngx
110                with a :exc:`~easypaperless.exceptions.BadRequestError`.
111
112        Returns:
113            The newly created :class:`~easypaperless.models.users.User`.
114        """
115        return cast(
116            User,
117            self._run(
118                self._async_users.create(
119                    username=username,
120                    email=email,
121                    password=password,
122                    first_name=first_name,
123                    last_name=last_name,
124                    date_joined=date_joined,
125                    is_staff=is_staff,
126                    is_active=is_active,
127                    is_superuser=is_superuser,
128                    groups=groups,
129                    user_permissions=user_permissions,
130                )
131            ),
132        )

Create a new user.

Arguments:
  • username: Login username. Must be unique.
  • email: Email address.
  • password: Password for the new account.
  • first_name: Given name.
  • last_name: Family name.
  • date_joined: Account creation timestamp.
  • is_staff: Grant staff (admin UI) access.
  • is_active: Whether the account is active.
  • is_superuser: Grant unrestricted superuser access.
  • groups: IDs of groups to assign the user to.
  • user_permissions: Directly assigned permission codenames, without the app label (e.g. ["view_document"]). The app-labelled form "documents.view_document" is rejected by paperless-ngx with a ~easypaperless.exceptions.BadRequestError.
Returns:

The newly created ~easypaperless.models.users.User.

def update( self, id: int, *, username: str | easypaperless.Unset = UNSET, email: str | easypaperless.Unset = UNSET, password: str | easypaperless.Unset = UNSET, first_name: str | easypaperless.Unset = UNSET, last_name: str | easypaperless.Unset = UNSET, date_joined: datetime.datetime | easypaperless.Unset = UNSET, is_staff: bool | easypaperless.Unset = UNSET, is_active: bool | easypaperless.Unset = UNSET, is_superuser: bool | easypaperless.Unset = UNSET, groups: Union[List[int], easypaperless.Unset] = UNSET, user_permissions: Union[List[str], easypaperless.Unset] = UNSET) -> easypaperless.User:
134    def update(
135        self,
136        id: int,
137        *,
138        username: str | Unset = UNSET,
139        email: str | Unset = UNSET,
140        password: str | Unset = UNSET,
141        first_name: str | Unset = UNSET,
142        last_name: str | Unset = UNSET,
143        date_joined: datetime | Unset = UNSET,
144        is_staff: bool | Unset = UNSET,
145        is_active: bool | Unset = UNSET,
146        is_superuser: bool | Unset = UNSET,
147        groups: List[int] | Unset = UNSET,
148        user_permissions: List[str] | Unset = UNSET,
149    ) -> User:
150        """Partially update a user (PATCH semantics).
151
152        Only fields with a non-:data:`~easypaperless.UNSET` value are included
153        in the request body.  Omit a parameter (or pass
154        :data:`~easypaperless.UNSET`) to leave it unchanged.
155
156        Args:
157            id: Numeric ID of the user to update.
158            username: Login username.
159            email: Email address.
160            password: New password.
161            first_name: Given name.
162            last_name: Family name.
163            date_joined: Account creation timestamp.
164            is_staff: Grant or revoke staff access.
165            is_active: Activate or deactivate the account.
166            is_superuser: Grant or revoke superuser access.
167            groups: IDs of groups to assign the user to.
168            user_permissions: Directly assigned permission codenames, without
169                the app label (e.g. ``["view_document"]``).  The app-labelled
170                form ``"documents.view_document"`` is rejected by paperless-ngx
171                with a :exc:`~easypaperless.exceptions.BadRequestError`.
172
173        Returns:
174            The updated :class:`~easypaperless.models.users.User`.
175        """
176        return cast(
177            User,
178            self._run(
179                self._async_users.update(
180                    id,
181                    username=username,
182                    email=email,
183                    password=password,
184                    first_name=first_name,
185                    last_name=last_name,
186                    date_joined=date_joined,
187                    is_staff=is_staff,
188                    is_active=is_active,
189                    is_superuser=is_superuser,
190                    groups=groups,
191                    user_permissions=user_permissions,
192                )
193            ),
194        )

Partially update a user (PATCH semantics).

Only fields with a non-~easypaperless.UNSET value are included in the request body. Omit a parameter (or pass ~easypaperless.UNSET) to leave it unchanged.

Arguments:
  • id: Numeric ID of the user to update.
  • username: Login username.
  • email: Email address.
  • password: New password.
  • first_name: Given name.
  • last_name: Family name.
  • date_joined: Account creation timestamp.
  • is_staff: Grant or revoke staff access.
  • is_active: Activate or deactivate the account.
  • is_superuser: Grant or revoke superuser access.
  • groups: IDs of groups to assign the user to.
  • user_permissions: Directly assigned permission codenames, without the app label (e.g. ["view_document"]). The app-labelled form "documents.view_document" is rejected by paperless-ngx with a ~easypaperless.exceptions.BadRequestError.
Returns:

The updated ~easypaperless.models.users.User.

def delete(self, id: int) -> None:
196    def delete(self, id: int) -> None:
197        """Delete a user.
198
199        Args:
200            id: Numeric ID of the user to delete.
201
202        Raises:
203            ~easypaperless.exceptions.NotFoundError: If no user exists with
204                that ID.
205        """
206        self._run(self._async_users.delete(id))

Delete a user.

Arguments:
  • id: Numeric ID of the user to delete.
Raises:
class GroupsResource:
 20class GroupsResource:
 21    """Accessor for groups: ``client.groups``."""
 22
 23    def __init__(self, core: _ClientCore) -> None:
 24        self._core = core
 25
 26    async def list(
 27        self,
 28        *,
 29        name_contains: str | Unset = UNSET,
 30        name_exact: str | Unset = UNSET,
 31        ordering: str | Unset = UNSET,
 32        page: int | Unset = UNSET,
 33        page_size: int | Unset = UNSET,
 34    ) -> PagedResult[Group]:
 35        """Return groups defined in paperless-ngx.
 36
 37        When ``page`` is ``UNSET`` (the default), all pages are fetched
 38        automatically and ``next`` / ``previous`` in the result are always
 39        ``None``.  When ``page`` is set, only that page is fetched and
 40        ``next`` / ``previous`` reflect the raw API values.
 41
 42        Args:
 43            name_contains: Case-insensitive substring filter on the group name.
 44            name_exact: Case-insensitive exact match on the group name.
 45            ordering: Field to sort by.
 46            page: Return only this specific page (1-based).
 47            page_size: Number of results per page.
 48
 49        Returns:
 50            :class:`~easypaperless.models.paged_result.PagedResult` of
 51            :class:`~easypaperless.models.groups.Group` objects.
 52        """
 53        logger.info("Listing groups")
 54        params: dict[str, Any] = {}
 55        if not isinstance(name_contains, Unset):
 56            params["name__icontains"] = name_contains
 57        if not isinstance(name_exact, Unset):
 58            params["name__iexact"] = name_exact
 59        if not isinstance(ordering, Unset):
 60            params["ordering"] = ordering
 61        if not isinstance(page, Unset):
 62            params["page"] = page
 63        if not isinstance(page_size, Unset):
 64            params["page_size"] = page_size
 65        return cast(
 66            PagedResult[Group],
 67            await self._core._list_resource("groups", Group, params or None),
 68        )
 69
 70    async def get(self, id: int) -> Group:
 71        """Fetch a single group by its ID.
 72
 73        Args:
 74            id: Numeric group ID.
 75
 76        Returns:
 77            The :class:`~easypaperless.models.groups.Group` with the given ID.
 78
 79        Raises:
 80            ~easypaperless.exceptions.NotFoundError: If no group exists with
 81                that ID.
 82        """
 83        logger.info("Getting group id=%d", id)
 84        return cast(Group, await self._core._get_resource("groups", id, Group))
 85
 86    async def create(
 87        self,
 88        *,
 89        name: str,
 90        permissions: builtins.list[str] | Unset = UNSET,
 91    ) -> Group:
 92        """Create a new group.
 93
 94        Args:
 95            name: Group name. Must be unique.
 96            permissions: Permission codenames to grant the group, without
 97                the app label (e.g. ``["view_document", "add_note"]``).
 98                paperless-ngx rejects the app-labelled form
 99                ``"documents.view_document"`` with a
100                :exc:`~easypaperless.exceptions.BadRequestError`.  When
101                omitted, ``[]`` is sent (paperless-ngx requires the field),
102                so the group starts without permissions.
103
104        Returns:
105            The newly created :class:`~easypaperless.models.groups.Group`.
106        """
107        logger.info("Creating group name=%r", name)
108        return cast(
109            Group,
110            await self._core._create_resource(
111                "groups",
112                Group,
113                name=name,
114                # paperless-ngx answers 400 "This field is required." without it.
115                permissions=[] if isinstance(permissions, Unset) else permissions,
116            ),
117        )
118
119    async def update(
120        self,
121        id: int,
122        *,
123        name: str | Unset = UNSET,
124        permissions: builtins.list[str] | Unset = UNSET,
125    ) -> Group:
126        """Partially update a group (PATCH semantics).
127
128        Only fields with a non-:data:`~easypaperless.UNSET` value are included
129        in the request body.  Omit a parameter (or pass
130        :data:`~easypaperless.UNSET`) to leave it unchanged.
131
132        Args:
133            id: Numeric ID of the group to update.
134            name: New group name.
135            permissions: Replacement list of permission codenames, without
136                the app label (e.g. ``["view_document"]``).  Pass ``[]`` to
137                remove all permissions.
138
139        Returns:
140            The updated :class:`~easypaperless.models.groups.Group`.
141        """
142        logger.info("Updating group id=%d", id)
143        return cast(
144            Group,
145            await self._core._update_resource(
146                "groups",
147                id,
148                Group,
149                name=name,
150                permissions=permissions,
151            ),
152        )
153
154    async def delete(self, id: int) -> None:
155        """Delete a group.
156
157        Args:
158            id: Numeric ID of the group to delete.
159
160        Raises:
161            ~easypaperless.exceptions.NotFoundError: If no group exists with
162                that ID.
163        """
164        logger.info("Deleting group id=%d", id)
165        await self._core._delete_resource("groups", id)

Accessor for groups: client.groups.

GroupsResource(core: easypaperless.client._ClientCore)
23    def __init__(self, core: _ClientCore) -> None:
24        self._core = core
async def list( self, *, name_contains: str | easypaperless.Unset = UNSET, name_exact: str | easypaperless.Unset = UNSET, ordering: str | easypaperless.Unset = UNSET, page: int | easypaperless.Unset = UNSET, page_size: int | easypaperless.Unset = UNSET) -> easypaperless.PagedResult[Group]:
26    async def list(
27        self,
28        *,
29        name_contains: str | Unset = UNSET,
30        name_exact: str | Unset = UNSET,
31        ordering: str | Unset = UNSET,
32        page: int | Unset = UNSET,
33        page_size: int | Unset = UNSET,
34    ) -> PagedResult[Group]:
35        """Return groups defined in paperless-ngx.
36
37        When ``page`` is ``UNSET`` (the default), all pages are fetched
38        automatically and ``next`` / ``previous`` in the result are always
39        ``None``.  When ``page`` is set, only that page is fetched and
40        ``next`` / ``previous`` reflect the raw API values.
41
42        Args:
43            name_contains: Case-insensitive substring filter on the group name.
44            name_exact: Case-insensitive exact match on the group name.
45            ordering: Field to sort by.
46            page: Return only this specific page (1-based).
47            page_size: Number of results per page.
48
49        Returns:
50            :class:`~easypaperless.models.paged_result.PagedResult` of
51            :class:`~easypaperless.models.groups.Group` objects.
52        """
53        logger.info("Listing groups")
54        params: dict[str, Any] = {}
55        if not isinstance(name_contains, Unset):
56            params["name__icontains"] = name_contains
57        if not isinstance(name_exact, Unset):
58            params["name__iexact"] = name_exact
59        if not isinstance(ordering, Unset):
60            params["ordering"] = ordering
61        if not isinstance(page, Unset):
62            params["page"] = page
63        if not isinstance(page_size, Unset):
64            params["page_size"] = page_size
65        return cast(
66            PagedResult[Group],
67            await self._core._list_resource("groups", Group, params or None),
68        )

Return groups defined in paperless-ngx.

When page is UNSET (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • name_contains: Case-insensitive substring filter on the group name.
  • name_exact: Case-insensitive exact match on the group name.
  • ordering: Field to sort by.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.groups.Group objects.

async def get(self, id: int) -> easypaperless.Group:
70    async def get(self, id: int) -> Group:
71        """Fetch a single group by its ID.
72
73        Args:
74            id: Numeric group ID.
75
76        Returns:
77            The :class:`~easypaperless.models.groups.Group` with the given ID.
78
79        Raises:
80            ~easypaperless.exceptions.NotFoundError: If no group exists with
81                that ID.
82        """
83        logger.info("Getting group id=%d", id)
84        return cast(Group, await self._core._get_resource("groups", id, Group))

Fetch a single group by its ID.

Arguments:
  • id: Numeric group ID.
Returns:

The ~easypaperless.models.groups.Group with the given ID.

Raises:
async def create( self, *, name: str, permissions: list[str] | easypaperless.Unset = UNSET) -> easypaperless.Group:
 86    async def create(
 87        self,
 88        *,
 89        name: str,
 90        permissions: builtins.list[str] | Unset = UNSET,
 91    ) -> Group:
 92        """Create a new group.
 93
 94        Args:
 95            name: Group name. Must be unique.
 96            permissions: Permission codenames to grant the group, without
 97                the app label (e.g. ``["view_document", "add_note"]``).
 98                paperless-ngx rejects the app-labelled form
 99                ``"documents.view_document"`` with a
100                :exc:`~easypaperless.exceptions.BadRequestError`.  When
101                omitted, ``[]`` is sent (paperless-ngx requires the field),
102                so the group starts without permissions.
103
104        Returns:
105            The newly created :class:`~easypaperless.models.groups.Group`.
106        """
107        logger.info("Creating group name=%r", name)
108        return cast(
109            Group,
110            await self._core._create_resource(
111                "groups",
112                Group,
113                name=name,
114                # paperless-ngx answers 400 "This field is required." without it.
115                permissions=[] if isinstance(permissions, Unset) else permissions,
116            ),
117        )

Create a new group.

Arguments:
  • name: Group name. Must be unique.
  • permissions: Permission codenames to grant the group, without the app label (e.g. ["view_document", "add_note"]). paperless-ngx rejects the app-labelled form "documents.view_document" with a ~easypaperless.exceptions.BadRequestError. When omitted, [] is sent (paperless-ngx requires the field), so the group starts without permissions.
Returns:

The newly created ~easypaperless.models.groups.Group.

async def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, permissions: list[str] | easypaperless.Unset = UNSET) -> easypaperless.Group:
119    async def update(
120        self,
121        id: int,
122        *,
123        name: str | Unset = UNSET,
124        permissions: builtins.list[str] | Unset = UNSET,
125    ) -> Group:
126        """Partially update a group (PATCH semantics).
127
128        Only fields with a non-:data:`~easypaperless.UNSET` value are included
129        in the request body.  Omit a parameter (or pass
130        :data:`~easypaperless.UNSET`) to leave it unchanged.
131
132        Args:
133            id: Numeric ID of the group to update.
134            name: New group name.
135            permissions: Replacement list of permission codenames, without
136                the app label (e.g. ``["view_document"]``).  Pass ``[]`` to
137                remove all permissions.
138
139        Returns:
140            The updated :class:`~easypaperless.models.groups.Group`.
141        """
142        logger.info("Updating group id=%d", id)
143        return cast(
144            Group,
145            await self._core._update_resource(
146                "groups",
147                id,
148                Group,
149                name=name,
150                permissions=permissions,
151            ),
152        )

Partially update a group (PATCH semantics).

Only fields with a non-~easypaperless.UNSET value are included in the request body. Omit a parameter (or pass ~easypaperless.UNSET) to leave it unchanged.

Arguments:
  • id: Numeric ID of the group to update.
  • name: New group name.
  • permissions: Replacement list of permission codenames, without the app label (e.g. ["view_document"]). Pass [] to remove all permissions.
Returns:

The updated ~easypaperless.models.groups.Group.

async def delete(self, id: int) -> None:
154    async def delete(self, id: int) -> None:
155        """Delete a group.
156
157        Args:
158            id: Numeric ID of the group to delete.
159
160        Raises:
161            ~easypaperless.exceptions.NotFoundError: If no group exists with
162                that ID.
163        """
164        logger.info("Deleting group id=%d", id)
165        await self._core._delete_resource("groups", id)

Delete a group.

Arguments:
  • id: Numeric ID of the group to delete.
Raises:
class SyncGroupsResource:
 17class SyncGroupsResource:
 18    """Sync accessor for groups: ``client.groups``."""
 19
 20    def __init__(self, async_groups: GroupsResource, run: Any) -> None:
 21        self._async_groups = async_groups
 22        self._run = run
 23
 24    def list(
 25        self,
 26        *,
 27        name_contains: str | Unset = UNSET,
 28        name_exact: str | Unset = UNSET,
 29        ordering: str | Unset = UNSET,
 30        page: int | Unset = UNSET,
 31        page_size: int | Unset = UNSET,
 32    ) -> PagedResult[Group]:
 33        """Return groups defined in paperless-ngx.
 34
 35        When ``page`` is ``UNSET`` (the default), all pages are fetched
 36        automatically and ``next`` / ``previous`` in the result are always
 37        ``None``.  When ``page`` is set, only that page is fetched and
 38        ``next`` / ``previous`` reflect the raw API values.
 39
 40        Args:
 41            name_contains: Case-insensitive substring filter on the group name.
 42            name_exact: Case-insensitive exact match on the group name.
 43            ordering: Field to sort by.
 44            page: Return only this specific page (1-based).
 45            page_size: Number of results per page.
 46
 47        Returns:
 48            :class:`~easypaperless.models.paged_result.PagedResult` of
 49            :class:`~easypaperless.models.groups.Group` objects.
 50        """
 51        return cast(
 52            PagedResult[Group],
 53            self._run(
 54                self._async_groups.list(
 55                    name_contains=name_contains,
 56                    name_exact=name_exact,
 57                    ordering=ordering,
 58                    page=page,
 59                    page_size=page_size,
 60                )
 61            ),
 62        )
 63
 64    def get(self, id: int) -> Group:
 65        """Fetch a single group by its ID.
 66
 67        Args:
 68            id: Numeric group ID.
 69
 70        Returns:
 71            The :class:`~easypaperless.models.groups.Group` with the given ID.
 72
 73        Raises:
 74            ~easypaperless.exceptions.NotFoundError: If no group exists with
 75                that ID.
 76        """
 77        return cast(Group, self._run(self._async_groups.get(id)))
 78
 79    def create(
 80        self,
 81        *,
 82        name: str,
 83        permissions: builtins.list[str] | Unset = UNSET,
 84    ) -> Group:
 85        """Create a new group.
 86
 87        Args:
 88            name: Group name. Must be unique.
 89            permissions: Permission codenames to grant the group, without
 90                the app label (e.g. ``["view_document", "add_note"]``).
 91                paperless-ngx rejects the app-labelled form
 92                ``"documents.view_document"`` with a
 93                :exc:`~easypaperless.exceptions.BadRequestError`.  When
 94                omitted, ``[]`` is sent (paperless-ngx requires the field),
 95                so the group starts without permissions.
 96
 97        Returns:
 98            The newly created :class:`~easypaperless.models.groups.Group`.
 99        """
100        return cast(
101            Group,
102            self._run(self._async_groups.create(name=name, permissions=permissions)),
103        )
104
105    def update(
106        self,
107        id: int,
108        *,
109        name: str | Unset = UNSET,
110        permissions: builtins.list[str] | Unset = UNSET,
111    ) -> Group:
112        """Partially update a group (PATCH semantics).
113
114        Only fields with a non-:data:`~easypaperless.UNSET` value are included
115        in the request body.  Omit a parameter (or pass
116        :data:`~easypaperless.UNSET`) to leave it unchanged.
117
118        Args:
119            id: Numeric ID of the group to update.
120            name: New group name.
121            permissions: Replacement list of permission codenames, without
122                the app label (e.g. ``["view_document"]``).  Pass ``[]`` to
123                remove all permissions.
124
125        Returns:
126            The updated :class:`~easypaperless.models.groups.Group`.
127        """
128        return cast(
129            Group,
130            self._run(self._async_groups.update(id, name=name, permissions=permissions)),
131        )
132
133    def delete(self, id: int) -> None:
134        """Delete a group.
135
136        Args:
137            id: Numeric ID of the group to delete.
138
139        Raises:
140            ~easypaperless.exceptions.NotFoundError: If no group exists with
141                that ID.
142        """
143        self._run(self._async_groups.delete(id))

Sync accessor for groups: client.groups.

SyncGroupsResource( async_groups: GroupsResource, run: Any)
20    def __init__(self, async_groups: GroupsResource, run: Any) -> None:
21        self._async_groups = async_groups
22        self._run = run
def list( self, *, name_contains: str | easypaperless.Unset = UNSET, name_exact: str | easypaperless.Unset = UNSET, ordering: str | easypaperless.Unset = UNSET, page: int | easypaperless.Unset = UNSET, page_size: int | easypaperless.Unset = UNSET) -> easypaperless.PagedResult[Group]:
24    def list(
25        self,
26        *,
27        name_contains: str | Unset = UNSET,
28        name_exact: str | Unset = UNSET,
29        ordering: str | Unset = UNSET,
30        page: int | Unset = UNSET,
31        page_size: int | Unset = UNSET,
32    ) -> PagedResult[Group]:
33        """Return groups defined in paperless-ngx.
34
35        When ``page`` is ``UNSET`` (the default), all pages are fetched
36        automatically and ``next`` / ``previous`` in the result are always
37        ``None``.  When ``page`` is set, only that page is fetched and
38        ``next`` / ``previous`` reflect the raw API values.
39
40        Args:
41            name_contains: Case-insensitive substring filter on the group name.
42            name_exact: Case-insensitive exact match on the group name.
43            ordering: Field to sort by.
44            page: Return only this specific page (1-based).
45            page_size: Number of results per page.
46
47        Returns:
48            :class:`~easypaperless.models.paged_result.PagedResult` of
49            :class:`~easypaperless.models.groups.Group` objects.
50        """
51        return cast(
52            PagedResult[Group],
53            self._run(
54                self._async_groups.list(
55                    name_contains=name_contains,
56                    name_exact=name_exact,
57                    ordering=ordering,
58                    page=page,
59                    page_size=page_size,
60                )
61            ),
62        )

Return groups defined in paperless-ngx.

When page is UNSET (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • name_contains: Case-insensitive substring filter on the group name.
  • name_exact: Case-insensitive exact match on the group name.
  • ordering: Field to sort by.
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.groups.Group objects.

def get(self, id: int) -> easypaperless.Group:
64    def get(self, id: int) -> Group:
65        """Fetch a single group by its ID.
66
67        Args:
68            id: Numeric group ID.
69
70        Returns:
71            The :class:`~easypaperless.models.groups.Group` with the given ID.
72
73        Raises:
74            ~easypaperless.exceptions.NotFoundError: If no group exists with
75                that ID.
76        """
77        return cast(Group, self._run(self._async_groups.get(id)))

Fetch a single group by its ID.

Arguments:
  • id: Numeric group ID.
Returns:

The ~easypaperless.models.groups.Group with the given ID.

Raises:
def create( self, *, name: str, permissions: list[str] | easypaperless.Unset = UNSET) -> easypaperless.Group:
 79    def create(
 80        self,
 81        *,
 82        name: str,
 83        permissions: builtins.list[str] | Unset = UNSET,
 84    ) -> Group:
 85        """Create a new group.
 86
 87        Args:
 88            name: Group name. Must be unique.
 89            permissions: Permission codenames to grant the group, without
 90                the app label (e.g. ``["view_document", "add_note"]``).
 91                paperless-ngx rejects the app-labelled form
 92                ``"documents.view_document"`` with a
 93                :exc:`~easypaperless.exceptions.BadRequestError`.  When
 94                omitted, ``[]`` is sent (paperless-ngx requires the field),
 95                so the group starts without permissions.
 96
 97        Returns:
 98            The newly created :class:`~easypaperless.models.groups.Group`.
 99        """
100        return cast(
101            Group,
102            self._run(self._async_groups.create(name=name, permissions=permissions)),
103        )

Create a new group.

Arguments:
  • name: Group name. Must be unique.
  • permissions: Permission codenames to grant the group, without the app label (e.g. ["view_document", "add_note"]). paperless-ngx rejects the app-labelled form "documents.view_document" with a ~easypaperless.exceptions.BadRequestError. When omitted, [] is sent (paperless-ngx requires the field), so the group starts without permissions.
Returns:

The newly created ~easypaperless.models.groups.Group.

def update( self, id: int, *, name: str | easypaperless.Unset = UNSET, permissions: list[str] | easypaperless.Unset = UNSET) -> easypaperless.Group:
105    def update(
106        self,
107        id: int,
108        *,
109        name: str | Unset = UNSET,
110        permissions: builtins.list[str] | Unset = UNSET,
111    ) -> Group:
112        """Partially update a group (PATCH semantics).
113
114        Only fields with a non-:data:`~easypaperless.UNSET` value are included
115        in the request body.  Omit a parameter (or pass
116        :data:`~easypaperless.UNSET`) to leave it unchanged.
117
118        Args:
119            id: Numeric ID of the group to update.
120            name: New group name.
121            permissions: Replacement list of permission codenames, without
122                the app label (e.g. ``["view_document"]``).  Pass ``[]`` to
123                remove all permissions.
124
125        Returns:
126            The updated :class:`~easypaperless.models.groups.Group`.
127        """
128        return cast(
129            Group,
130            self._run(self._async_groups.update(id, name=name, permissions=permissions)),
131        )

Partially update a group (PATCH semantics).

Only fields with a non-~easypaperless.UNSET value are included in the request body. Omit a parameter (or pass ~easypaperless.UNSET) to leave it unchanged.

Arguments:
  • id: Numeric ID of the group to update.
  • name: New group name.
  • permissions: Replacement list of permission codenames, without the app label (e.g. ["view_document"]). Pass [] to remove all permissions.
Returns:

The updated ~easypaperless.models.groups.Group.

def delete(self, id: int) -> None:
133    def delete(self, id: int) -> None:
134        """Delete a group.
135
136        Args:
137            id: Numeric ID of the group to delete.
138
139        Raises:
140            ~easypaperless.exceptions.NotFoundError: If no group exists with
141                that ID.
142        """
143        self._run(self._async_groups.delete(id))

Delete a group.

Arguments:
  • id: Numeric ID of the group to delete.
Raises:
class TrashResource:
19class TrashResource:
20    """Accessor for the trash bin: ``client.trash``."""
21
22    def __init__(self, core: _ClientCore) -> None:
23        self._core = core
24
25    async def list(
26        self,
27        *,
28        page: int | Unset = UNSET,
29        page_size: int | Unset = UNSET,
30    ) -> PagedResult[Document]:
31        """Return all documents currently in the trash.
32
33        When ``page`` is ``UNSET`` (the default), all pages are fetched
34        automatically and ``next`` / ``previous`` in the result are always
35        ``None``.  When ``page`` is set, only that page is fetched and
36        ``next`` / ``previous`` reflect the raw API values.
37
38        Args:
39            page: Return only this specific page (1-based).
40            page_size: Number of results per page.
41
42        Returns:
43            :class:`~easypaperless.models.paged_result.PagedResult` of
44            :class:`~easypaperless.models.documents.Document` objects currently
45            in the trash.
46        """
47        logger.info("Listing trashed documents")
48        params: dict[str, Any] = {}
49        if not isinstance(page, Unset):
50            params["page"] = page
51        if not isinstance(page_size, Unset):
52            params["page_size"] = page_size
53        return cast(
54            PagedResult[Document],
55            await self._core._list_resource("trash", Document, params or None),
56        )
57
58    async def restore(self, document_ids: List[int]) -> None:
59        """Restore trashed documents back to active status.
60
61        Args:
62            document_ids: List of numeric document IDs to restore.
63        """
64        logger.info("Restoring %d trashed document(s)", len(document_ids))
65        await self._core._session.post(
66            "/trash/",
67            json={"documents": document_ids, "action": "restore"},
68        )
69
70    async def empty(self, document_ids: List[int]) -> None:
71        """Permanently delete trashed documents.
72
73        .. warning::
74            **This operation is irreversible and cannot be undone.**
75            The documents will be permanently removed and cannot be recovered.
76
77        Args:
78            document_ids: List of numeric document IDs to permanently delete.
79        """
80        logger.info("Permanently deleting %d trashed document(s)", len(document_ids))
81        await self._core._session.post(
82            "/trash/",
83            json={"documents": document_ids, "action": "empty"},
84        )

Accessor for the trash bin: client.trash.

TrashResource(core: easypaperless.client._ClientCore)
22    def __init__(self, core: _ClientCore) -> None:
23        self._core = core
async def list( self, *, page: int | easypaperless.Unset = UNSET, page_size: int | easypaperless.Unset = UNSET) -> easypaperless.PagedResult[Document]:
25    async def list(
26        self,
27        *,
28        page: int | Unset = UNSET,
29        page_size: int | Unset = UNSET,
30    ) -> PagedResult[Document]:
31        """Return all documents currently in the trash.
32
33        When ``page`` is ``UNSET`` (the default), all pages are fetched
34        automatically and ``next`` / ``previous`` in the result are always
35        ``None``.  When ``page`` is set, only that page is fetched and
36        ``next`` / ``previous`` reflect the raw API values.
37
38        Args:
39            page: Return only this specific page (1-based).
40            page_size: Number of results per page.
41
42        Returns:
43            :class:`~easypaperless.models.paged_result.PagedResult` of
44            :class:`~easypaperless.models.documents.Document` objects currently
45            in the trash.
46        """
47        logger.info("Listing trashed documents")
48        params: dict[str, Any] = {}
49        if not isinstance(page, Unset):
50            params["page"] = page
51        if not isinstance(page_size, Unset):
52            params["page_size"] = page_size
53        return cast(
54            PagedResult[Document],
55            await self._core._list_resource("trash", Document, params or None),
56        )

Return all documents currently in the trash.

When page is UNSET (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.documents.Document objects currently in the trash.

async def restore(self, document_ids: List[int]) -> None:
58    async def restore(self, document_ids: List[int]) -> None:
59        """Restore trashed documents back to active status.
60
61        Args:
62            document_ids: List of numeric document IDs to restore.
63        """
64        logger.info("Restoring %d trashed document(s)", len(document_ids))
65        await self._core._session.post(
66            "/trash/",
67            json={"documents": document_ids, "action": "restore"},
68        )

Restore trashed documents back to active status.

Arguments:
  • document_ids: List of numeric document IDs to restore.
async def empty(self, document_ids: List[int]) -> None:
70    async def empty(self, document_ids: List[int]) -> None:
71        """Permanently delete trashed documents.
72
73        .. warning::
74            **This operation is irreversible and cannot be undone.**
75            The documents will be permanently removed and cannot be recovered.
76
77        Args:
78            document_ids: List of numeric document IDs to permanently delete.
79        """
80        logger.info("Permanently deleting %d trashed document(s)", len(document_ids))
81        await self._core._session.post(
82            "/trash/",
83            json={"documents": document_ids, "action": "empty"},
84        )

Permanently delete trashed documents.

This operation is irreversible and cannot be undone. The documents will be permanently removed and cannot be recovered.

Arguments:
  • document_ids: List of numeric document IDs to permanently delete.
class SyncTrashResource:
16class SyncTrashResource:
17    """Sync accessor for the trash bin: ``client.trash``."""
18
19    def __init__(self, async_trash: TrashResource, run: Any) -> None:
20        self._async_trash = async_trash
21        self._run = run
22
23    def list(
24        self,
25        *,
26        page: int | Unset = UNSET,
27        page_size: int | Unset = UNSET,
28    ) -> PagedResult[Document]:
29        """Return all documents currently in the trash.
30
31        When ``page`` is ``UNSET`` (the default), all pages are fetched
32        automatically and ``next`` / ``previous`` in the result are always
33        ``None``.  When ``page`` is set, only that page is fetched and
34        ``next`` / ``previous`` reflect the raw API values.
35
36        Args:
37            page: Return only this specific page (1-based).
38            page_size: Number of results per page.
39
40        Returns:
41            :class:`~easypaperless.models.paged_result.PagedResult` of
42            :class:`~easypaperless.models.documents.Document` objects currently
43            in the trash.
44        """
45        return cast(
46            PagedResult[Document],
47            self._run(self._async_trash.list(page=page, page_size=page_size)),
48        )
49
50    def restore(self, document_ids: List[int]) -> None:
51        """Restore trashed documents back to active status.
52
53        Args:
54            document_ids: List of numeric document IDs to restore.
55        """
56        self._run(self._async_trash.restore(document_ids))
57
58    def empty(self, document_ids: List[int]) -> None:
59        """Permanently delete trashed documents.
60
61        .. warning::
62            **This operation is irreversible and cannot be undone.**
63            The documents will be permanently removed and cannot be recovered.
64
65        Args:
66            document_ids: List of numeric document IDs to permanently delete.
67        """
68        self._run(self._async_trash.empty(document_ids))

Sync accessor for the trash bin: client.trash.

SyncTrashResource( async_trash: TrashResource, run: Any)
19    def __init__(self, async_trash: TrashResource, run: Any) -> None:
20        self._async_trash = async_trash
21        self._run = run
def list( self, *, page: int | easypaperless.Unset = UNSET, page_size: int | easypaperless.Unset = UNSET) -> easypaperless.PagedResult[Document]:
23    def list(
24        self,
25        *,
26        page: int | Unset = UNSET,
27        page_size: int | Unset = UNSET,
28    ) -> PagedResult[Document]:
29        """Return all documents currently in the trash.
30
31        When ``page`` is ``UNSET`` (the default), all pages are fetched
32        automatically and ``next`` / ``previous`` in the result are always
33        ``None``.  When ``page`` is set, only that page is fetched and
34        ``next`` / ``previous`` reflect the raw API values.
35
36        Args:
37            page: Return only this specific page (1-based).
38            page_size: Number of results per page.
39
40        Returns:
41            :class:`~easypaperless.models.paged_result.PagedResult` of
42            :class:`~easypaperless.models.documents.Document` objects currently
43            in the trash.
44        """
45        return cast(
46            PagedResult[Document],
47            self._run(self._async_trash.list(page=page, page_size=page_size)),
48        )

Return all documents currently in the trash.

When page is UNSET (the default), all pages are fetched automatically and next / previous in the result are always None. When page is set, only that page is fetched and next / previous reflect the raw API values.

Arguments:
  • page: Return only this specific page (1-based).
  • page_size: Number of results per page.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.documents.Document objects currently in the trash.

def restore(self, document_ids: List[int]) -> None:
50    def restore(self, document_ids: List[int]) -> None:
51        """Restore trashed documents back to active status.
52
53        Args:
54            document_ids: List of numeric document IDs to restore.
55        """
56        self._run(self._async_trash.restore(document_ids))

Restore trashed documents back to active status.

Arguments:
  • document_ids: List of numeric document IDs to restore.
def empty(self, document_ids: List[int]) -> None:
58    def empty(self, document_ids: List[int]) -> None:
59        """Permanently delete trashed documents.
60
61        .. warning::
62            **This operation is irreversible and cannot be undone.**
63            The documents will be permanently removed and cannot be recovered.
64
65        Args:
66            document_ids: List of numeric document IDs to permanently delete.
67        """
68        self._run(self._async_trash.empty(document_ids))

Permanently delete trashed documents.

This operation is irreversible and cannot be undone. The documents will be permanently removed and cannot be recovered.

Arguments:
  • document_ids: List of numeric document IDs to permanently delete.
class TasksResource:
 23class TasksResource:
 24    """Accessor for paperless-ngx background tasks: ``client.tasks``."""
 25
 26    def __init__(self, core: _ClientCore) -> None:
 27        self._core = core
 28
 29    async def list(
 30        self,
 31        *,
 32        task_id: str | Unset = UNSET,
 33        status: TaskStatus | str | Unset = UNSET,
 34        task_name: str | Unset = UNSET,
 35        type: str | Unset = UNSET,
 36        acknowledged: bool | Unset = UNSET,
 37    ) -> PagedResult[Task]:
 38        """Return background tasks, optionally filtered.
 39
 40        paperless-ngx returns the task list as a plain JSON array (not
 41        paginated); it is wrapped into a
 42        :class:`~easypaperless.models.paged_result.PagedResult` with
 43        ``next`` / ``previous`` set to ``None``.  A paginated response is
 44        accepted as well, and all its pages are fetched.
 45
 46        Args:
 47            task_id: Only the task with this Celery task ID (UUID string).
 48            status: Only tasks with this status, e.g. ``TaskStatus.FAILURE``
 49                or ``"FAILURE"``.
 50            task_name: Only tasks with this name: ``"consume_file"``,
 51                ``"train_classifier"``, ``"check_sanity"`` or
 52                ``"index_optimize"``.
 53            type: Only tasks of this type: ``"auto_task"``,
 54                ``"scheduled_task"`` or ``"manual_task"``.
 55            acknowledged: ``False`` for tasks not yet acknowledged (as shown
 56                in the paperless-ngx UI), ``True`` for acknowledged ones.
 57
 58        Returns:
 59            :class:`~easypaperless.models.paged_result.PagedResult` of
 60            :class:`~easypaperless.models.tasks.Task` objects.
 61
 62        Raises:
 63            ~easypaperless.exceptions.BadRequestError: If ``status``,
 64                ``task_name`` or ``type`` is not one of paperless-ngx's values.
 65                These filters are case-sensitive (``"success"`` is rejected).
 66        """
 67        logger.info("Listing tasks")
 68        filters = {
 69            "task_id": task_id,
 70            "status": status,
 71            "task_name": task_name,
 72            "type": type,
 73            "acknowledged": acknowledged,
 74        }
 75        params: dict[str, Any] = {k: v for k, v in filters.items() if not isinstance(v, Unset)}
 76        raw = await self._core._session.get_list("/tasks/", params=params or None)
 77        return PagedResult(
 78            count=raw.count,
 79            all=raw.all_ids,
 80            results=[Task.model_validate(item) for item in raw.items],
 81        )
 82
 83    async def get(self, task_id: str) -> Task:
 84        """Fetch a single task by its Celery task ID.
 85
 86        Args:
 87            task_id: The task's UUID string, e.g. as returned by
 88                ``documents.upload(wait=False)``.
 89
 90        Returns:
 91            The :class:`~easypaperless.models.tasks.Task`.
 92
 93        Raises:
 94            ~easypaperless.exceptions.NotFoundError: If paperless-ngx does not
 95                know a task with this ID.
 96        """
 97        logger.info("Getting task task_id=%r", task_id)
 98        task = await self._fetch(task_id)
 99        if task is None:
100            raise NotFoundError(f"Task {task_id!r} not found")
101        return task
102
103    async def wait(
104        self,
105        task_id: str,
106        *,
107        poll_interval: float | None = None,
108        poll_timeout: float | None = None,
109    ) -> Task:
110        """Poll a task until it reaches a terminal state and return it.
111
112        Use this to resume waiting for an upload started with
113        ``documents.upload(wait=False)``, or after a
114        :exc:`~easypaperless.exceptions.TaskTimeoutError`.  A task that
115        paperless-ngx does not list yet (right after an upload) is polled
116        again rather than treated as missing.  The task is checked at least
117        once, even with ``poll_timeout=0``.  A status this library does not
118        know is treated as not finished yet.  An unknown ``task_id`` therefore
119        keeps being polled until ``poll_timeout`` and then raises
120        :exc:`~easypaperless.exceptions.TaskTimeoutError`.
121
122        Args:
123            task_id: The task's UUID string, e.g. as returned by
124                ``documents.upload(wait=False)``.
125            poll_interval: Seconds between status checks.  When omitted, falls
126                back to the client-level ``poll_interval`` (``2.0`` s unless
127                changed at construction).
128            poll_timeout: Maximum seconds to wait.  When omitted, falls back to
129                the client-level ``poll_timeout`` (``60.0`` s unless changed at
130                construction).
131
132        Returns:
133            The final :class:`~easypaperless.models.tasks.Task` with status
134            ``SUCCESS``.
135
136        Raises:
137            ~easypaperless.exceptions.UploadError: If the task reports
138                ``FAILURE`` or ``REVOKED``; ``err.task`` holds the task with
139                paperless-ngx's ``status`` and ``result`` unaltered.
140            ~easypaperless.exceptions.TaskTimeoutError: If the task does not
141                finish within ``poll_timeout`` seconds; ``err.task_id`` and
142                ``err.timeout`` are set so the caller can wait again.
143        """
144        interval = poll_interval if poll_interval is not None else self._core._poll_interval
145        timeout = poll_timeout if poll_timeout is not None else self._core._poll_timeout
146        logger.info("Waiting for task task_id=%r (timeout=%.1fs)", task_id, timeout)
147        start = time.monotonic()
148        deadline = start + timeout
149        while True:
150            task = await self._fetch(task_id)
151            elapsed = time.monotonic() - start
152            status = task.status if task is not None else None
153            logger.debug(
154                "Polling task %r (status=%s, elapsed=%.1fs)",
155                task_id,
156                status if status is not None else "unknown",
157                elapsed,
158            )
159            if task is not None and status == TaskStatus.SUCCESS:
160                logger.info("Task %r succeeded", task_id)
161                return task
162            if task is not None and status == TaskStatus.FAILURE:
163                logger.warning("Task %r failed: %s", task_id, task.result)
164                raise UploadError(f"Document processing failed: {task.result}", task=task)
165            if task is not None and status == TaskStatus.REVOKED:
166                logger.warning("Task %r was revoked", task_id)
167                raise UploadError(f"Task {task_id!r} was revoked", task=task)
168            if time.monotonic() >= deadline:
169                break
170            await asyncio.sleep(interval)
171
172        logger.warning("Task %r timed out after %.1fs", task_id, time.monotonic() - start)
173        raise TaskTimeoutError(
174            f"Task {task_id!r} did not complete within {timeout}s",
175            task_id=task_id,
176            timeout=timeout,
177        )
178
179    async def acknowledge(self, ids: builtins.list[int]) -> int:
180        """Mark tasks as acknowledged, as the paperless-ngx UI's "Dismiss" does.
181
182        Args:
183            ids: Numeric task IDs (:attr:`Task.id
184                <easypaperless.models.tasks.Task.id>`, not the UUID
185                ``task_id``).
186
187        Returns:
188            The number of tasks paperless-ngx acknowledged.
189        """
190        logger.info("Acknowledging %d task(s)", len(ids))
191        resp = await self._core._session.post("/tasks/acknowledge/", json={"tasks": ids})
192        body = resp.json()
193        result = body.get("result") if isinstance(body, dict) else None
194        return result if isinstance(result, int) else len(ids)
195
196    async def _fetch(self, task_id: str) -> Task | None:
197        """Return the task with ``task_id``, or ``None`` if paperless has none."""
198        raw = await self._core._session.get_list(
199            "/tasks/", params={"task_id": task_id}, all_pages=False
200        )
201        if not raw.items:
202            return None
203        return Task.model_validate(raw.items[0])

Accessor for paperless-ngx background tasks: client.tasks.

TasksResource(core: easypaperless.client._ClientCore)
26    def __init__(self, core: _ClientCore) -> None:
27        self._core = core
async def list( self, *, task_id: str | easypaperless.Unset = UNSET, status: easypaperless.TaskStatus | str | easypaperless.Unset = UNSET, task_name: str | easypaperless.Unset = UNSET, type: str | easypaperless.Unset = UNSET, acknowledged: bool | easypaperless.Unset = UNSET) -> easypaperless.PagedResult[Task]:
29    async def list(
30        self,
31        *,
32        task_id: str | Unset = UNSET,
33        status: TaskStatus | str | Unset = UNSET,
34        task_name: str | Unset = UNSET,
35        type: str | Unset = UNSET,
36        acknowledged: bool | Unset = UNSET,
37    ) -> PagedResult[Task]:
38        """Return background tasks, optionally filtered.
39
40        paperless-ngx returns the task list as a plain JSON array (not
41        paginated); it is wrapped into a
42        :class:`~easypaperless.models.paged_result.PagedResult` with
43        ``next`` / ``previous`` set to ``None``.  A paginated response is
44        accepted as well, and all its pages are fetched.
45
46        Args:
47            task_id: Only the task with this Celery task ID (UUID string).
48            status: Only tasks with this status, e.g. ``TaskStatus.FAILURE``
49                or ``"FAILURE"``.
50            task_name: Only tasks with this name: ``"consume_file"``,
51                ``"train_classifier"``, ``"check_sanity"`` or
52                ``"index_optimize"``.
53            type: Only tasks of this type: ``"auto_task"``,
54                ``"scheduled_task"`` or ``"manual_task"``.
55            acknowledged: ``False`` for tasks not yet acknowledged (as shown
56                in the paperless-ngx UI), ``True`` for acknowledged ones.
57
58        Returns:
59            :class:`~easypaperless.models.paged_result.PagedResult` of
60            :class:`~easypaperless.models.tasks.Task` objects.
61
62        Raises:
63            ~easypaperless.exceptions.BadRequestError: If ``status``,
64                ``task_name`` or ``type`` is not one of paperless-ngx's values.
65                These filters are case-sensitive (``"success"`` is rejected).
66        """
67        logger.info("Listing tasks")
68        filters = {
69            "task_id": task_id,
70            "status": status,
71            "task_name": task_name,
72            "type": type,
73            "acknowledged": acknowledged,
74        }
75        params: dict[str, Any] = {k: v for k, v in filters.items() if not isinstance(v, Unset)}
76        raw = await self._core._session.get_list("/tasks/", params=params or None)
77        return PagedResult(
78            count=raw.count,
79            all=raw.all_ids,
80            results=[Task.model_validate(item) for item in raw.items],
81        )

Return background tasks, optionally filtered.

paperless-ngx returns the task list as a plain JSON array (not paginated); it is wrapped into a ~easypaperless.models.paged_result.PagedResult with next / previous set to None. A paginated response is accepted as well, and all its pages are fetched.

Arguments:
  • task_id: Only the task with this Celery task ID (UUID string).
  • status: Only tasks with this status, e.g. TaskStatus.FAILURE or "FAILURE".
  • task_name: Only tasks with this name: "consume_file", "train_classifier", "check_sanity" or "index_optimize".
  • type: Only tasks of this type: "auto_task", "scheduled_task" or "manual_task".
  • acknowledged: False for tasks not yet acknowledged (as shown in the paperless-ngx UI), True for acknowledged ones.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.tasks.Task objects.

Raises:
async def get(self, task_id: str) -> easypaperless.Task:
 83    async def get(self, task_id: str) -> Task:
 84        """Fetch a single task by its Celery task ID.
 85
 86        Args:
 87            task_id: The task's UUID string, e.g. as returned by
 88                ``documents.upload(wait=False)``.
 89
 90        Returns:
 91            The :class:`~easypaperless.models.tasks.Task`.
 92
 93        Raises:
 94            ~easypaperless.exceptions.NotFoundError: If paperless-ngx does not
 95                know a task with this ID.
 96        """
 97        logger.info("Getting task task_id=%r", task_id)
 98        task = await self._fetch(task_id)
 99        if task is None:
100            raise NotFoundError(f"Task {task_id!r} not found")
101        return task

Fetch a single task by its Celery task ID.

Arguments:
  • task_id: The task's UUID string, e.g. as returned by documents.upload(wait=False).
Returns:

The ~easypaperless.models.tasks.Task.

Raises:
async def wait( self, task_id: str, *, poll_interval: float | None = None, poll_timeout: float | None = None) -> easypaperless.Task:
103    async def wait(
104        self,
105        task_id: str,
106        *,
107        poll_interval: float | None = None,
108        poll_timeout: float | None = None,
109    ) -> Task:
110        """Poll a task until it reaches a terminal state and return it.
111
112        Use this to resume waiting for an upload started with
113        ``documents.upload(wait=False)``, or after a
114        :exc:`~easypaperless.exceptions.TaskTimeoutError`.  A task that
115        paperless-ngx does not list yet (right after an upload) is polled
116        again rather than treated as missing.  The task is checked at least
117        once, even with ``poll_timeout=0``.  A status this library does not
118        know is treated as not finished yet.  An unknown ``task_id`` therefore
119        keeps being polled until ``poll_timeout`` and then raises
120        :exc:`~easypaperless.exceptions.TaskTimeoutError`.
121
122        Args:
123            task_id: The task's UUID string, e.g. as returned by
124                ``documents.upload(wait=False)``.
125            poll_interval: Seconds between status checks.  When omitted, falls
126                back to the client-level ``poll_interval`` (``2.0`` s unless
127                changed at construction).
128            poll_timeout: Maximum seconds to wait.  When omitted, falls back to
129                the client-level ``poll_timeout`` (``60.0`` s unless changed at
130                construction).
131
132        Returns:
133            The final :class:`~easypaperless.models.tasks.Task` with status
134            ``SUCCESS``.
135
136        Raises:
137            ~easypaperless.exceptions.UploadError: If the task reports
138                ``FAILURE`` or ``REVOKED``; ``err.task`` holds the task with
139                paperless-ngx's ``status`` and ``result`` unaltered.
140            ~easypaperless.exceptions.TaskTimeoutError: If the task does not
141                finish within ``poll_timeout`` seconds; ``err.task_id`` and
142                ``err.timeout`` are set so the caller can wait again.
143        """
144        interval = poll_interval if poll_interval is not None else self._core._poll_interval
145        timeout = poll_timeout if poll_timeout is not None else self._core._poll_timeout
146        logger.info("Waiting for task task_id=%r (timeout=%.1fs)", task_id, timeout)
147        start = time.monotonic()
148        deadline = start + timeout
149        while True:
150            task = await self._fetch(task_id)
151            elapsed = time.monotonic() - start
152            status = task.status if task is not None else None
153            logger.debug(
154                "Polling task %r (status=%s, elapsed=%.1fs)",
155                task_id,
156                status if status is not None else "unknown",
157                elapsed,
158            )
159            if task is not None and status == TaskStatus.SUCCESS:
160                logger.info("Task %r succeeded", task_id)
161                return task
162            if task is not None and status == TaskStatus.FAILURE:
163                logger.warning("Task %r failed: %s", task_id, task.result)
164                raise UploadError(f"Document processing failed: {task.result}", task=task)
165            if task is not None and status == TaskStatus.REVOKED:
166                logger.warning("Task %r was revoked", task_id)
167                raise UploadError(f"Task {task_id!r} was revoked", task=task)
168            if time.monotonic() >= deadline:
169                break
170            await asyncio.sleep(interval)
171
172        logger.warning("Task %r timed out after %.1fs", task_id, time.monotonic() - start)
173        raise TaskTimeoutError(
174            f"Task {task_id!r} did not complete within {timeout}s",
175            task_id=task_id,
176            timeout=timeout,
177        )

Poll a task until it reaches a terminal state and return it.

Use this to resume waiting for an upload started with documents.upload(wait=False), or after a ~easypaperless.exceptions.TaskTimeoutError. A task that paperless-ngx does not list yet (right after an upload) is polled again rather than treated as missing. The task is checked at least once, even with poll_timeout=0. A status this library does not know is treated as not finished yet. An unknown task_id therefore keeps being polled until poll_timeout and then raises ~easypaperless.exceptions.TaskTimeoutError.

Arguments:
  • task_id: The task's UUID string, e.g. as returned by documents.upload(wait=False).
  • poll_interval: Seconds between status checks. When omitted, falls back to the client-level poll_interval (2.0 s unless changed at construction).
  • poll_timeout: Maximum seconds to wait. When omitted, falls back to the client-level poll_timeout (60.0 s unless changed at construction).
Returns:

The final ~easypaperless.models.tasks.Task with status SUCCESS.

Raises:
async def acknowledge(self, ids: list[int]) -> int:
179    async def acknowledge(self, ids: builtins.list[int]) -> int:
180        """Mark tasks as acknowledged, as the paperless-ngx UI's "Dismiss" does.
181
182        Args:
183            ids: Numeric task IDs (:attr:`Task.id
184                <easypaperless.models.tasks.Task.id>`, not the UUID
185                ``task_id``).
186
187        Returns:
188            The number of tasks paperless-ngx acknowledged.
189        """
190        logger.info("Acknowledging %d task(s)", len(ids))
191        resp = await self._core._session.post("/tasks/acknowledge/", json={"tasks": ids})
192        body = resp.json()
193        result = body.get("result") if isinstance(body, dict) else None
194        return result if isinstance(result, int) else len(ids)

Mark tasks as acknowledged, as the paperless-ngx UI's "Dismiss" does.

Arguments:
Returns:

The number of tasks paperless-ngx acknowledged.

class SyncTasksResource:
 17class SyncTasksResource:
 18    """Sync accessor for paperless-ngx background tasks: ``client.tasks``."""
 19
 20    def __init__(self, async_tasks: TasksResource, run: Any) -> None:
 21        self._async_tasks = async_tasks
 22        self._run = run
 23
 24    def list(
 25        self,
 26        *,
 27        task_id: str | Unset = UNSET,
 28        status: TaskStatus | str | Unset = UNSET,
 29        task_name: str | Unset = UNSET,
 30        type: str | Unset = UNSET,
 31        acknowledged: bool | Unset = UNSET,
 32    ) -> PagedResult[Task]:
 33        """Return background tasks, optionally filtered.
 34
 35        paperless-ngx returns the task list as a plain JSON array (not
 36        paginated); it is wrapped into a
 37        :class:`~easypaperless.models.paged_result.PagedResult` with
 38        ``next`` / ``previous`` set to ``None``.  A paginated response is
 39        accepted as well, and all its pages are fetched.
 40
 41        Args:
 42            task_id: Only the task with this Celery task ID (UUID string).
 43            status: Only tasks with this status, e.g. ``TaskStatus.FAILURE``
 44                or ``"FAILURE"``.
 45            task_name: Only tasks with this name: ``"consume_file"``,
 46                ``"train_classifier"``, ``"check_sanity"`` or
 47                ``"index_optimize"``.
 48            type: Only tasks of this type: ``"auto_task"``,
 49                ``"scheduled_task"`` or ``"manual_task"``.
 50            acknowledged: ``False`` for tasks not yet acknowledged (as shown
 51                in the paperless-ngx UI), ``True`` for acknowledged ones.
 52
 53        Returns:
 54            :class:`~easypaperless.models.paged_result.PagedResult` of
 55            :class:`~easypaperless.models.tasks.Task` objects.
 56
 57        Raises:
 58            ~easypaperless.exceptions.BadRequestError: If ``status``,
 59                ``task_name`` or ``type`` is not one of paperless-ngx's values.
 60                These filters are case-sensitive (``"success"`` is rejected).
 61        """
 62        return cast(
 63            PagedResult[Task],
 64            self._run(
 65                self._async_tasks.list(
 66                    task_id=task_id,
 67                    status=status,
 68                    task_name=task_name,
 69                    type=type,
 70                    acknowledged=acknowledged,
 71                )
 72            ),
 73        )
 74
 75    def get(self, task_id: str) -> Task:
 76        """Fetch a single task by its Celery task ID.
 77
 78        Args:
 79            task_id: The task's UUID string, e.g. as returned by
 80                ``documents.upload(wait=False)``.
 81
 82        Returns:
 83            The :class:`~easypaperless.models.tasks.Task`.
 84
 85        Raises:
 86            ~easypaperless.exceptions.NotFoundError: If paperless-ngx does not
 87                know a task with this ID.
 88        """
 89        return cast(Task, self._run(self._async_tasks.get(task_id)))
 90
 91    def wait(
 92        self,
 93        task_id: str,
 94        *,
 95        poll_interval: float | None = None,
 96        poll_timeout: float | None = None,
 97    ) -> Task:
 98        """Poll a task until it reaches a terminal state and return it.
 99
100        Use this to resume waiting for an upload started with
101        ``documents.upload(wait=False)``, or after a
102        :exc:`~easypaperless.exceptions.TaskTimeoutError`.  A task that
103        paperless-ngx does not list yet (right after an upload) is polled
104        again rather than treated as missing.  The task is checked at least
105        once, even with ``poll_timeout=0``.  A status this library does not
106        know is treated as not finished yet.  An unknown ``task_id`` therefore
107        keeps being polled until ``poll_timeout`` and then raises
108        :exc:`~easypaperless.exceptions.TaskTimeoutError`.
109
110        Args:
111            task_id: The task's UUID string, e.g. as returned by
112                ``documents.upload(wait=False)``.
113            poll_interval: Seconds between status checks.  When omitted, falls
114                back to the client-level ``poll_interval`` (``2.0`` s unless
115                changed at construction).
116            poll_timeout: Maximum seconds to wait.  When omitted, falls back to
117                the client-level ``poll_timeout`` (``60.0`` s unless changed at
118                construction).
119
120        Returns:
121            The final :class:`~easypaperless.models.tasks.Task` with status
122            ``SUCCESS``.
123
124        Raises:
125            ~easypaperless.exceptions.UploadError: If the task reports
126                ``FAILURE`` or ``REVOKED``; ``err.task`` holds the task with
127                paperless-ngx's ``status`` and ``result`` unaltered.
128            ~easypaperless.exceptions.TaskTimeoutError: If the task does not
129                finish within ``poll_timeout`` seconds; ``err.task_id`` and
130                ``err.timeout`` are set so the caller can wait again.
131        """
132        return cast(
133            Task,
134            self._run(
135                self._async_tasks.wait(
136                    task_id, poll_interval=poll_interval, poll_timeout=poll_timeout
137                )
138            ),
139        )
140
141    def acknowledge(self, ids: builtins.list[int]) -> int:
142        """Mark tasks as acknowledged, as the paperless-ngx UI's "Dismiss" does.
143
144        Args:
145            ids: Numeric task IDs (:attr:`Task.id
146                <easypaperless.models.tasks.Task.id>`, not the UUID
147                ``task_id``).
148
149        Returns:
150            The number of tasks paperless-ngx acknowledged.
151        """
152        return cast(int, self._run(self._async_tasks.acknowledge(ids)))

Sync accessor for paperless-ngx background tasks: client.tasks.

SyncTasksResource( async_tasks: TasksResource, run: Any)
20    def __init__(self, async_tasks: TasksResource, run: Any) -> None:
21        self._async_tasks = async_tasks
22        self._run = run
def list( self, *, task_id: str | easypaperless.Unset = UNSET, status: easypaperless.TaskStatus | str | easypaperless.Unset = UNSET, task_name: str | easypaperless.Unset = UNSET, type: str | easypaperless.Unset = UNSET, acknowledged: bool | easypaperless.Unset = UNSET) -> easypaperless.PagedResult[Task]:
24    def list(
25        self,
26        *,
27        task_id: str | Unset = UNSET,
28        status: TaskStatus | str | Unset = UNSET,
29        task_name: str | Unset = UNSET,
30        type: str | Unset = UNSET,
31        acknowledged: bool | Unset = UNSET,
32    ) -> PagedResult[Task]:
33        """Return background tasks, optionally filtered.
34
35        paperless-ngx returns the task list as a plain JSON array (not
36        paginated); it is wrapped into a
37        :class:`~easypaperless.models.paged_result.PagedResult` with
38        ``next`` / ``previous`` set to ``None``.  A paginated response is
39        accepted as well, and all its pages are fetched.
40
41        Args:
42            task_id: Only the task with this Celery task ID (UUID string).
43            status: Only tasks with this status, e.g. ``TaskStatus.FAILURE``
44                or ``"FAILURE"``.
45            task_name: Only tasks with this name: ``"consume_file"``,
46                ``"train_classifier"``, ``"check_sanity"`` or
47                ``"index_optimize"``.
48            type: Only tasks of this type: ``"auto_task"``,
49                ``"scheduled_task"`` or ``"manual_task"``.
50            acknowledged: ``False`` for tasks not yet acknowledged (as shown
51                in the paperless-ngx UI), ``True`` for acknowledged ones.
52
53        Returns:
54            :class:`~easypaperless.models.paged_result.PagedResult` of
55            :class:`~easypaperless.models.tasks.Task` objects.
56
57        Raises:
58            ~easypaperless.exceptions.BadRequestError: If ``status``,
59                ``task_name`` or ``type`` is not one of paperless-ngx's values.
60                These filters are case-sensitive (``"success"`` is rejected).
61        """
62        return cast(
63            PagedResult[Task],
64            self._run(
65                self._async_tasks.list(
66                    task_id=task_id,
67                    status=status,
68                    task_name=task_name,
69                    type=type,
70                    acknowledged=acknowledged,
71                )
72            ),
73        )

Return background tasks, optionally filtered.

paperless-ngx returns the task list as a plain JSON array (not paginated); it is wrapped into a ~easypaperless.models.paged_result.PagedResult with next / previous set to None. A paginated response is accepted as well, and all its pages are fetched.

Arguments:
  • task_id: Only the task with this Celery task ID (UUID string).
  • status: Only tasks with this status, e.g. TaskStatus.FAILURE or "FAILURE".
  • task_name: Only tasks with this name: "consume_file", "train_classifier", "check_sanity" or "index_optimize".
  • type: Only tasks of this type: "auto_task", "scheduled_task" or "manual_task".
  • acknowledged: False for tasks not yet acknowledged (as shown in the paperless-ngx UI), True for acknowledged ones.
Returns:

~easypaperless.models.paged_result.PagedResult of ~easypaperless.models.tasks.Task objects.

Raises:
def get(self, task_id: str) -> easypaperless.Task:
75    def get(self, task_id: str) -> Task:
76        """Fetch a single task by its Celery task ID.
77
78        Args:
79            task_id: The task's UUID string, e.g. as returned by
80                ``documents.upload(wait=False)``.
81
82        Returns:
83            The :class:`~easypaperless.models.tasks.Task`.
84
85        Raises:
86            ~easypaperless.exceptions.NotFoundError: If paperless-ngx does not
87                know a task with this ID.
88        """
89        return cast(Task, self._run(self._async_tasks.get(task_id)))

Fetch a single task by its Celery task ID.

Arguments:
  • task_id: The task's UUID string, e.g. as returned by documents.upload(wait=False).
Returns:

The ~easypaperless.models.tasks.Task.

Raises:
def wait( self, task_id: str, *, poll_interval: float | None = None, poll_timeout: float | None = None) -> easypaperless.Task:
 91    def wait(
 92        self,
 93        task_id: str,
 94        *,
 95        poll_interval: float | None = None,
 96        poll_timeout: float | None = None,
 97    ) -> Task:
 98        """Poll a task until it reaches a terminal state and return it.
 99
100        Use this to resume waiting for an upload started with
101        ``documents.upload(wait=False)``, or after a
102        :exc:`~easypaperless.exceptions.TaskTimeoutError`.  A task that
103        paperless-ngx does not list yet (right after an upload) is polled
104        again rather than treated as missing.  The task is checked at least
105        once, even with ``poll_timeout=0``.  A status this library does not
106        know is treated as not finished yet.  An unknown ``task_id`` therefore
107        keeps being polled until ``poll_timeout`` and then raises
108        :exc:`~easypaperless.exceptions.TaskTimeoutError`.
109
110        Args:
111            task_id: The task's UUID string, e.g. as returned by
112                ``documents.upload(wait=False)``.
113            poll_interval: Seconds between status checks.  When omitted, falls
114                back to the client-level ``poll_interval`` (``2.0`` s unless
115                changed at construction).
116            poll_timeout: Maximum seconds to wait.  When omitted, falls back to
117                the client-level ``poll_timeout`` (``60.0`` s unless changed at
118                construction).
119
120        Returns:
121            The final :class:`~easypaperless.models.tasks.Task` with status
122            ``SUCCESS``.
123
124        Raises:
125            ~easypaperless.exceptions.UploadError: If the task reports
126                ``FAILURE`` or ``REVOKED``; ``err.task`` holds the task with
127                paperless-ngx's ``status`` and ``result`` unaltered.
128            ~easypaperless.exceptions.TaskTimeoutError: If the task does not
129                finish within ``poll_timeout`` seconds; ``err.task_id`` and
130                ``err.timeout`` are set so the caller can wait again.
131        """
132        return cast(
133            Task,
134            self._run(
135                self._async_tasks.wait(
136                    task_id, poll_interval=poll_interval, poll_timeout=poll_timeout
137                )
138            ),
139        )

Poll a task until it reaches a terminal state and return it.

Use this to resume waiting for an upload started with documents.upload(wait=False), or after a ~easypaperless.exceptions.TaskTimeoutError. A task that paperless-ngx does not list yet (right after an upload) is polled again rather than treated as missing. The task is checked at least once, even with poll_timeout=0. A status this library does not know is treated as not finished yet. An unknown task_id therefore keeps being polled until poll_timeout and then raises ~easypaperless.exceptions.TaskTimeoutError.

Arguments:
  • task_id: The task's UUID string, e.g. as returned by documents.upload(wait=False).
  • poll_interval: Seconds between status checks. When omitted, falls back to the client-level poll_interval (2.0 s unless changed at construction).
  • poll_timeout: Maximum seconds to wait. When omitted, falls back to the client-level poll_timeout (60.0 s unless changed at construction).
Returns:

The final ~easypaperless.models.tasks.Task with status SUCCESS.

Raises:
def acknowledge(self, ids: list[int]) -> int:
141    def acknowledge(self, ids: builtins.list[int]) -> int:
142        """Mark tasks as acknowledged, as the paperless-ngx UI's "Dismiss" does.
143
144        Args:
145            ids: Numeric task IDs (:attr:`Task.id
146                <easypaperless.models.tasks.Task.id>`, not the UUID
147                ``task_id``).
148
149        Returns:
150            The number of tasks paperless-ngx acknowledged.
151        """
152        return cast(int, self._run(self._async_tasks.acknowledge(ids)))

Mark tasks as acknowledged, as the paperless-ngx UI's "Dismiss" does.

Arguments:
Returns:

The number of tasks paperless-ngx acknowledged.