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]
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.
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 asCorrespondent.permissions;user_can_changeis thenNone. Default:False.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.correspondents.Correspondentobjects.
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 asCorrespondent.permissions;user_can_changeis thenNone. Default:False.
Returns:
The
~easypaperless.models.correspondents.Correspondentwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. Defaults toTrue, matching the paperless-ngx API default. - owner: Numeric user ID to assign as owner.
- set_permissions: Explicit view/change permission sets.
Pass
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.correspondents.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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. - owner: Numeric user ID to assign as owner.
Pass
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.correspondents.Correspondent.
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:
- ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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.PagedResultof~easypaperless.models.custom_fields.CustomFieldobjects.
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.CustomFieldwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
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
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.custom_fields.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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.custom_fields.CustomField.
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:
- ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
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.
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 asDocumentType.permissions;user_can_changeis thenNone. Default:False.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.document_types.DocumentTypeobjects.
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 asDocumentType.permissions;user_can_changeis thenNone. Default:False.
Returns:
The
~easypaperless.models.document_types.DocumentTypewith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. Defaults toTrue, matching the paperless-ngx API default. - owner: Numeric user ID to assign as owner.
- set_permissions: Explicit view/change permission sets.
Pass
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.document_types.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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. - owner: Numeric user ID to assign as owner.
Pass
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.document_types.DocumentType.
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:
- ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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.PagedResultof~easypaperless.models.documents.AuditLogEntryobjects, ordered by timestamp descending.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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 asDocument.permissions. paperless-ngx then omitsuser_can_changeandis_shared_by_requester(bothNoneon the model). Default:False.
Returns:
The
~easypaperless.models.documents.Documentwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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.DocumentMetadatainstance.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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
searchis 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
Noneto 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
Noneto 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
Noneto 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
Noneto 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
Noneto 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.UploadErrorofupload(wait=True)(or oftasks.wait()):err.task.resultcontains": It is a duplicate of "and ends in"Note: existing document is in the trash.", anderr.task.related_documentisNone(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 asDocument.permissions. paperless-ngx then omitsuser_can_changeandis_shared_by_requester(bothNoneon 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.PagedResultof~easypaperless.models.documents.Documentobjects.
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.dateobject. - correspondent: Correspondent to assign, as an ID or name.
Pass
Noneto clear the correspondent. - document_type: Document type to assign, as an ID or name.
Pass
Noneto clear the document type. - storage_path: Storage path to assign, as an ID or name.
Pass
Noneto clear the storage path. - tags: Full replacement list of tags (IDs or names).
- archive_serial_number: Archive serial number to assign.
Pass
Noneto clear the archive serial number. - custom_fields: List of
{"field": <field_id>, "value": ...}dicts. - owner: Numeric user ID to assign as document owner.
Pass
Noneto clear the owner. - set_permissions: Explicit view/change permission sets.
Pass
Noneto 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 withownereverything 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.
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:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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/). IfTrue, returns the original uploaded file (GET /documents/{id}/download/?original=true).
Returns:
Raw file 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:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
- ~easypaperless.exceptions.ServerResponseError: If the server returns an HTML page (e.g. an auth redirect) instead of the image.
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 (
stror~pathlib.Path), or the file content asbytes. 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.ValidationErrorbefore 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
timeoutfor this call. Does not affect task polling (seepoll_timeout). When omitted, the client'stimeoutapplies. - title: Title to assign to the document.
- created: Creation date as an ISO-8601 string (
"YYYY-MM-DD") or a~datetime.dateobject. - 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. IfTrue, 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-levelpoll_interval(2.0s unless changed at construction). - poll_timeout: Maximum seconds to wait before raising
~easypaperless.exceptions.TaskTimeoutError(requireswait=True). Overrides the client-level default. When omitted, falls back to the client-levelpoll_timeout(60.0s unless changed at construction).
Returns:
The Celery task ID string when
wait=False, or the fully processed~easypaperless.models.documents.Documentwhenwait=True.
Raises:
- ~easypaperless.exceptions.ValidationError: If file is
bytesand no filename is given. - ~easypaperless.exceptions.BadRequestError: If paperless-ngx rejects
the file before processing starts, e.g. an unsupported file
type or an empty file (
err.field_errors["document"]). - ~easypaperless.exceptions.UploadError: If processing fails;
err.taskholds the task with paperless-ngx'sresultunaltered. For a duplicate,err.task.resultcontains": It is a duplicate of "anderr.task.related_documentis the existing document's ID (Noneif that document is in the trash). - ~easypaperless.exceptions.TaskTimeoutError: If timeout is exceeded;
resume with
client.tasks.wait(err.task_id).
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.
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.
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.
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
Noneto clear.
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
Noneto clear.
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
Noneto clear.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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.
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.PagedResultof~easypaperless.models.documents.DocumentNoteobjects, ordered by creation time.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
- ~easypaperless.exceptions.ServerResponseError: If paperless-ngx answers with an empty note list.
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:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
- ~easypaperless.exceptions.ServerResponseError: If the document has
no note with
note_id. paperless-ngx answers an unknown note ID with500 Server Errorinstead of 404 (verified against paperless-ngx 2.18.2), so it cannot be told apart from a real server error. Withretry_attemptsset, the 500 is retried like any other and ends in~easypaperless.exceptions.RetryExhaustedError. Usenotes.list(document_id)first if you need to be sure the note exists.
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.
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 asStoragePath.permissions;user_can_changeis thenNone. Default:False.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.storage_paths.StoragePathobjects.
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 asStoragePath.permissions;user_can_changeis thenNone. Default:False.
Returns:
The
~easypaperless.models.storage_paths.StoragePathwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. Defaults toTrue, matching the paperless-ngx API default. - owner: Numeric user ID to assign as owner.
- set_permissions: Explicit view/change permission sets.
Pass
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.storage_paths.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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. - owner: Numeric user ID to assign as owner.
Pass
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.storage_paths.StoragePath.
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:
- ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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 asTag.permissions;user_can_changeis thenNone. Default:False.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.tags.Tagobjects.
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 asTag.permissions;user_can_changeis thenNone. Default:False.
Returns:
The
~easypaperless.models.tags.Tagwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no tag exists with that ID.
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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. Defaults toTrue, 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
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.tags.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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. - parent: ID of parent tag.
Pass
Noneto clear (make root tag). Omit (or pass~easypaperless.UNSET) to leave unchanged. - owner: Numeric user ID to assign as owner.
Pass
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.tags.Tag.
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:
- ~easypaperless.exceptions.NotFoundError: If no tag exists with that ID.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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 asCorrespondent.permissions;user_can_changeis thenNone. Default:False.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.correspondents.Correspondentobjects.
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 asCorrespondent.permissions;user_can_changeis thenNone. Default:False.
Returns:
The
~easypaperless.models.correspondents.Correspondentwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. Defaults toTrue, matching the paperless-ngx API default. - owner: Numeric user ID to assign as owner.
- set_permissions: Explicit view/change permission sets.
Pass
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.correspondents.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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. - owner: Numeric user ID to assign as owner.
Pass
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.correspondents.Correspondent.
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:
- ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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.PagedResultof~easypaperless.models.custom_fields.CustomFieldobjects.
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.CustomFieldwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
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
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.custom_fields.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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.custom_fields.CustomField.
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:
- ~easypaperless.exceptions.NotFoundError: If no custom field exists with that ID.
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.
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 asDocumentType.permissions;user_can_changeis thenNone. Default:False.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.document_types.DocumentTypeobjects.
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 asDocumentType.permissions;user_can_changeis thenNone. Default:False.
Returns:
The
~easypaperless.models.document_types.DocumentTypewith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. Defaults toTrue, matching the paperless-ngx API default. - owner: Numeric user ID to assign as owner.
- set_permissions: Explicit view/change permission sets.
Pass
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.document_types.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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. - owner: Numeric user ID to assign as owner.
Pass
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.document_types.DocumentType.
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:
- ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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.PagedResultof~easypaperless.models.documents.AuditLogEntryobjects, ordered by timestamp descending.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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 asDocument.permissions. paperless-ngx then omitsuser_can_changeandis_shared_by_requester(bothNoneon the model). Default:False.
Returns:
The
~easypaperless.models.documents.Documentwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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.DocumentMetadatainstance.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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
searchis 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
Noneto 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
Noneto 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
Noneto 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
Noneto 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
Noneto 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.UploadErrorofupload(wait=True)(or oftasks.wait()):err.task.resultcontains": It is a duplicate of "and ends in"Note: existing document is in the trash.", anderr.task.related_documentisNone(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 asDocument.permissions. paperless-ngx then omitsuser_can_changeandis_shared_by_requester(bothNoneon 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.PagedResultof~easypaperless.models.documents.Documentobjects.
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.dateobject. - correspondent: Correspondent to assign, as an ID or name.
Pass
Noneto clear the correspondent. - document_type: Document type to assign, as an ID or name.
Pass
Noneto clear the document type. - storage_path: Storage path to assign, as an ID or name.
Pass
Noneto clear the storage path. - tags: Full replacement list of tags (IDs or names).
- archive_serial_number: Archive serial number to assign.
Pass
Noneto clear the archive serial number. - custom_fields: List of
{"field": <field_id>, "value": ...}dicts. - owner: Numeric user ID to assign as document owner.
Pass
Noneto clear the owner. - set_permissions: Explicit view/change permission sets.
Pass
Noneto 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 withownereverything 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.
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:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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/). IfTrue, returns the original uploaded file (GET /documents/{id}/download/?original=true).
Returns:
Raw file 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:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
- ~easypaperless.exceptions.ServerResponseError: If the server returns an HTML page (e.g. an auth redirect) instead of the image.
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 (
stror~pathlib.Path), or the file content asbytes. 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.ValidationErrorbefore 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
timeoutfor this call. Does not affect task polling (seepoll_timeout). When omitted, the client'stimeoutapplies. - title: Title to assign to the document.
- created: Creation date as an ISO-8601 string (
"YYYY-MM-DD") or a~datetime.dateobject. - 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. IfTrue, 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-levelpoll_interval(2.0s unless changed at construction). - poll_timeout: Maximum seconds to wait before raising
~easypaperless.exceptions.TaskTimeoutError(requireswait=True). Overrides the client-level default. When omitted, falls back to the client-levelpoll_timeout(60.0s unless changed at construction).
Returns:
The Celery task ID string when
wait=False, or the fully processed~easypaperless.models.documents.Documentwhenwait=True.
Raises:
- ~easypaperless.exceptions.ValidationError: If file is
bytesand no filename is given. - ~easypaperless.exceptions.BadRequestError: If paperless-ngx rejects
the file before processing starts, e.g. an unsupported file
type or an empty file (
err.field_errors["document"]). - ~easypaperless.exceptions.UploadError: If processing fails;
err.taskholds the task with paperless-ngx'sresultunaltered. For a duplicate,err.task.resultcontains": It is a duplicate of "anderr.task.related_documentis the existing document's ID (Noneif that document is in the trash). - ~easypaperless.exceptions.TaskTimeoutError: If timeout is exceeded;
resume with
client.tasks.wait(err.task_id).
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.
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.
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.
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
Noneto clear.
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
Noneto clear.
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
Noneto clear.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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.
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.PagedResultof~easypaperless.models.documents.DocumentNoteobjects, ordered by creation time.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
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:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
- ~easypaperless.exceptions.ServerResponseError: If paperless-ngx answers with an empty note list.
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:
- ~easypaperless.exceptions.NotFoundError: If no document exists with that ID.
- ~easypaperless.exceptions.ServerResponseError: If the document has
no note with
note_id. paperless-ngx answers an unknown note ID with500 Server Errorinstead of 404 (verified against paperless-ngx 2.18.2), so it cannot be told apart from a real server error. Withretry_attemptsset, the 500 is retried like any other and ends in~easypaperless.exceptions.RetryExhaustedError. Usenotes.list(document_id)first if you need to be sure the note exists.
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.
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 asStoragePath.permissions;user_can_changeis thenNone. Default:False.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.storage_paths.StoragePathobjects.
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 asStoragePath.permissions;user_can_changeis thenNone. Default:False.
Returns:
The
~easypaperless.models.storage_paths.StoragePathwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. Defaults toTrue, matching the paperless-ngx API default. - owner: Numeric user ID to assign as owner.
- set_permissions: Explicit view/change permission sets.
Pass
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.storage_paths.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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. - owner: Numeric user ID to assign as owner.
Pass
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.storage_paths.StoragePath.
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:
- ~easypaperless.exceptions.NotFoundError: If no storage path exists with that ID.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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 asTag.permissions;user_can_changeis thenNone. Default:False.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.tags.Tagobjects.
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 asTag.permissions;user_can_changeis thenNone. Default:False.
Returns:
The
~easypaperless.models.tags.Tagwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no tag exists with that ID.
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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. Defaults toTrue, 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
Noneto create with empty permissions.
Returns:
The newly created
~easypaperless.models.tags.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
matchis applied. E.g.matching_algorithm=MatchingAlgorithm.REGEXfor regular-expression matching. - is_insensitive: When
True,matchis case-insensitive. - parent: ID of parent tag.
Pass
Noneto clear (make root tag). Omit (or pass~easypaperless.UNSET) to leave unchanged. - owner: Numeric user ID to assign as owner.
Pass
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - set_permissions: Explicit view/change permission sets.
Pass
Noneto clear all permissions (overwrite with empty). Omit (or pass~easypaperless.UNSET) to leave unchanged.
Returns:
The updated
~easypaperless.models.tags.Tag.
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:
- ~easypaperless.exceptions.NotFoundError: If no tag exists with that ID.
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.
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
Noneto clear the owner. Omit (or pass~easypaperless.UNSET) to leave unchanged. - merge: When
True, new permissions are merged with existing ones.
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.
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.PagedResultof~easypaperless.models.users.Userobjects.
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.Userwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no user exists with that ID.
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.
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.
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:
- ~easypaperless.exceptions.NotFoundError: If no user exists with that ID.
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.
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.PagedResultof~easypaperless.models.users.Userobjects.
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.Userwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no user exists with that ID.
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.
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.
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:
- ~easypaperless.exceptions.NotFoundError: If no user exists with that ID.
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.
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.PagedResultof~easypaperless.models.groups.Groupobjects.
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.Groupwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no group exists with that ID.
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.
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.
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:
- ~easypaperless.exceptions.NotFoundError: If no group exists with that ID.
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.
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.PagedResultof~easypaperless.models.groups.Groupobjects.
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.Groupwith the given ID.
Raises:
- ~easypaperless.exceptions.NotFoundError: If no group exists with that ID.
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.
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.
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:
- ~easypaperless.exceptions.NotFoundError: If no group exists with that ID.
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.
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.PagedResultof~easypaperless.models.documents.Documentobjects currently in the trash.
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.
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.
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.
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.PagedResultof~easypaperless.models.documents.Documentobjects currently in the trash.
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.
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.
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.
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.FAILUREor"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:
Falsefor tasks not yet acknowledged (as shown in the paperless-ngx UI),Truefor acknowledged ones.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.tasks.Taskobjects.
Raises:
- ~easypaperless.exceptions.BadRequestError: If
status,task_nameortypeis not one of paperless-ngx's values. These filters are case-sensitive ("success"is rejected).
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:
Raises:
- ~easypaperless.exceptions.NotFoundError: If paperless-ngx does not know a task with this ID.
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.0s unless changed at construction). - poll_timeout: Maximum seconds to wait. When omitted, falls back to
the client-level
poll_timeout(60.0s unless changed at construction).
Returns:
The final
~easypaperless.models.tasks.Taskwith statusSUCCESS.
Raises:
- ~easypaperless.exceptions.UploadError: If the task reports
FAILUREorREVOKED;err.taskholds the task with paperless-ngx'sstatusandresultunaltered. - ~easypaperless.exceptions.TaskTimeoutError: If the task does not
finish within
poll_timeoutseconds;err.task_idanderr.timeoutare set so the caller can wait again.
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:
- ids: Numeric task IDs (
Task.id <easypaperless.models.tasks.Task.id>, not the UUIDtask_id).
Returns:
The number of tasks paperless-ngx acknowledged.
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.
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.FAILUREor"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:
Falsefor tasks not yet acknowledged (as shown in the paperless-ngx UI),Truefor acknowledged ones.
Returns:
~easypaperless.models.paged_result.PagedResultof~easypaperless.models.tasks.Taskobjects.
Raises:
- ~easypaperless.exceptions.BadRequestError: If
status,task_nameortypeis not one of paperless-ngx's values. These filters are case-sensitive ("success"is rejected).
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:
Raises:
- ~easypaperless.exceptions.NotFoundError: If paperless-ngx does not know a task with this ID.
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.0s unless changed at construction). - poll_timeout: Maximum seconds to wait. When omitted, falls back to
the client-level
poll_timeout(60.0s unless changed at construction).
Returns:
The final
~easypaperless.models.tasks.Taskwith statusSUCCESS.
Raises:
- ~easypaperless.exceptions.UploadError: If the task reports
FAILUREorREVOKED;err.taskholds the task with paperless-ngx'sstatusandresultunaltered. - ~easypaperless.exceptions.TaskTimeoutError: If the task does not
finish within
poll_timeoutseconds;err.task_idanderr.timeoutare set so the caller can wait again.
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:
- ids: Numeric task IDs (
Task.id <easypaperless.models.tasks.Task.id>, not the UUIDtask_id).
Returns:
The number of tasks paperless-ngx acknowledged.