easypaperless.resources

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

 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)

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