easypaperless.resources

 17class CorrespondentsResource:
 18    """Accessor for correspondents: ``client.correspondents``."""
 19
 20    def __init__(self, core: _ClientCore) -> None:
 21        self._core = core
 22
 23    async def list(
 24        self,
 25        *,
 26        ids: List[int] | None = None,
 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    ) -> List[Correspondent]:
 34        """Return correspondents defined in paperless-ngx.
 35
 36        Args:
 37            ids: Return only correspondents whose ID is in this list.
 38            name_contains: Case-insensitive substring filter on name.
 39            name_exact: Case-insensitive exact match on name.
 40            page: Return only this specific page (1-based).
 41            page_size: Number of results per page.
 42            ordering: Field to sort by.
 43            descending: When ``True``, reverses the sort direction.
 44
 45        Returns:
 46            List of :class:`~easypaperless.models.correspondents.Correspondent` objects.
 47        """
 48        params: dict[str, Any] = {}
 49        if ids is not None:
 50            params["id__in"] = ",".join(str(i) for i in ids)
 51        if name_contains is not None:
 52            params["name__icontains"] = name_contains
 53        if name_exact is not None:
 54            params["name__iexact"] = name_exact
 55        if page is not None:
 56            params["page"] = page
 57        if page_size is not None:
 58            params["page_size"] = page_size
 59        if ordering is not None:
 60            params["ordering"] = f"-{ordering}" if descending else ordering
 61        return cast(
 62            List[Correspondent],
 63            await self._core._list_resource("correspondents", Correspondent, params or None),
 64        )
 65
 66    async def get(self, id: int) -> Correspondent:
 67        """Fetch a single correspondent by its ID.
 68
 69        Args:
 70            id: Numeric correspondent ID.
 71
 72        Returns:
 73            The :class:`~easypaperless.models.correspondents.Correspondent` with the given ID.
 74
 75        Raises:
 76            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
 77        """
 78        return cast(
 79            Correspondent, await self._core._get_resource("correspondents", id, Correspondent)
 80        )
 81
 82    async def create(
 83        self,
 84        *,
 85        name: str,
 86        match: str | None | _Unset = UNSET,
 87        matching_algorithm: MatchingAlgorithm | None | _Unset = UNSET,
 88        is_insensitive: bool = True,
 89        owner: int | None | _Unset = UNSET,
 90        set_permissions: SetPermissions | None = None,
 91    ) -> Correspondent:
 92        """Create a new correspondent.
 93
 94        Args:
 95            name: Correspondent name. Must be unique.
 96            match: Auto-matching pattern.
 97            matching_algorithm: Controls how ``match`` is applied.
 98            is_insensitive: When ``True``, ``match`` is case-insensitive.
 99                Defaults to ``True``, matching the paperless-ngx API default.
100            owner: Numeric user ID to assign as owner.
101            set_permissions: Explicit view/change permission sets.
102
103        Returns:
104            The newly created :class:`~easypaperless.models.correspondents.Correspondent`.
105        """
106        return cast(
107            Correspondent,
108            await self._core._create_resource(
109                "correspondents",
110                Correspondent,
111                owner=owner,
112                set_permissions=set_permissions,
113                name=name,
114                match=match,
115                matching_algorithm=matching_algorithm,
116                is_insensitive=is_insensitive,
117            ),
118        )
119
120    async def update(
121        self,
122        id: int,
123        *,
124        name: str | None | _Unset = UNSET,
125        match: str | None | _Unset = UNSET,
126        matching_algorithm: MatchingAlgorithm | None | _Unset = UNSET,
127        is_insensitive: bool | None | _Unset = UNSET,
128        owner: int | None | _Unset = UNSET,
129        set_permissions: SetPermissions | None | _Unset = UNSET,
130    ) -> Correspondent:
131        """Partially update a correspondent (PATCH semantics).
132
133        Args:
134            id: Numeric ID of the correspondent to update.
135            name: Correspondent name.
136            match: Auto-matching pattern.
137            matching_algorithm: Controls how ``match`` is applied.
138            is_insensitive: When ``True``, ``match`` is case-insensitive.
139            owner: Numeric user ID to assign as owner.
140                Pass ``None`` to clear the owner.
141                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
142            set_permissions: Explicit view/change permission sets.
143                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
144
145        Returns:
146            The updated :class:`~easypaperless.models.correspondents.Correspondent`.
147        """
148        _set_perms: dict[str, Any] | _Unset = (
149            UNSET
150            if isinstance(set_permissions, _Unset)
151            else (set_permissions or SetPermissions()).model_dump()
152        )
153        return cast(
154            Correspondent,
155            await self._core._update_resource(
156                "correspondents",
157                id,
158                Correspondent,
159                name=name,
160                match=match,
161                matching_algorithm=matching_algorithm,
162                is_insensitive=is_insensitive,
163                owner=owner,
164                set_permissions=_set_perms,
165            ),
166        )
167
168    async def delete(self, id: int) -> None:
169        """Delete a correspondent.
170
171        Args:
172            id: Numeric ID of the correspondent to delete.
173
174        Raises:
175            ~easypaperless.exceptions.NotFoundError: If no correspondent exists with that ID.
176        """
177        await self._core._delete_resource("correspondents", id)
178
179    async def bulk_delete(self, ids: List[int]) -> None:
180        """Permanently delete multiple correspondents in a single request.
181
182        Args:
183            ids: List of correspondent IDs to delete.
184        """
185        await self._core._bulk_edit_objects("correspondents", ids, "delete")
186
187    async def bulk_set_permissions(
188        self,
189        ids: List[int],
190        *,
191        set_permissions: SetPermissions | None = None,
192        owner: int | None = None,
193        merge: bool = False,
194    ) -> None:
195        """Set permissions and/or owner on multiple correspondents.
196
197        Args:
198            ids: List of correspondent IDs to modify.
199            set_permissions: Explicit view/change permission sets.
200            owner: Numeric user ID to assign as owner.
201            merge: When ``True``, new permissions are merged with existing ones.
202        """
203        params: dict[str, Any] = {"merge": merge}
204        if set_permissions is not None:
205            params["permissions"] = set_permissions.model_dump()
206        if owner is not None:
207            params["owner"] = owner
208        await self._core._bulk_edit_objects("correspondents", ids, "set_permissions", **params)

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

 17class DocumentTypesResource:
 18    """Accessor for document types: ``client.document_types``."""
 19
 20    def __init__(self, core: _ClientCore) -> None:
 21        self._core = core
 22
 23    async def list(
 24        self,
 25        *,
 26        ids: List[int] | None = None,
 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    ) -> List[DocumentType]:
 34        """Return document types defined in paperless-ngx.
 35
 36        Args:
 37            ids: Return only document types whose ID is in this list.
 38            name_contains: Case-insensitive substring filter on name.
 39            name_exact: Case-insensitive exact match on name.
 40            page: Return only this specific page (1-based).
 41            page_size: Number of results per page.
 42            ordering: Field to sort by.
 43            descending: When ``True``, reverses the sort direction.
 44
 45        Returns:
 46            List of :class:`~easypaperless.models.document_types.DocumentType` objects.
 47        """
 48        params: dict[str, Any] = {}
 49        if ids is not None:
 50            params["id__in"] = ",".join(str(i) for i in ids)
 51        if name_contains is not None:
 52            params["name__icontains"] = name_contains
 53        if name_exact is not None:
 54            params["name__iexact"] = name_exact
 55        if page is not None:
 56            params["page"] = page
 57        if page_size is not None:
 58            params["page_size"] = page_size
 59        if ordering is not None:
 60            params["ordering"] = f"-{ordering}" if descending else ordering
 61        return cast(
 62            List[DocumentType],
 63            await self._core._list_resource("document_types", DocumentType, params or None),
 64        )
 65
 66    async def get(self, id: int) -> DocumentType:
 67        """Fetch a single document type by its ID.
 68
 69        Args:
 70            id: Numeric document-type ID.
 71
 72        Returns:
 73            The :class:`~easypaperless.models.document_types.DocumentType` with the given ID.
 74
 75        Raises:
 76            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
 77        """
 78        return cast(
 79            DocumentType, await self._core._get_resource("document_types", id, DocumentType)
 80        )
 81
 82    async def create(
 83        self,
 84        *,
 85        name: str,
 86        match: str | None | _Unset = UNSET,
 87        matching_algorithm: MatchingAlgorithm | None | _Unset = UNSET,
 88        is_insensitive: bool = True,
 89        owner: int | None | _Unset = UNSET,
 90        set_permissions: SetPermissions | None = None,
 91    ) -> DocumentType:
 92        """Create a new document type.
 93
 94        Args:
 95            name: Document-type name. Must be unique.
 96            match: Auto-matching pattern.
 97            matching_algorithm: Controls how ``match`` is applied.
 98            is_insensitive: When ``True``, ``match`` is case-insensitive.
 99                Defaults to ``True``, matching the paperless-ngx API default.
100            owner: Numeric user ID to assign as owner.
101            set_permissions: Explicit view/change permission sets.
102
103        Returns:
104            The newly created :class:`~easypaperless.models.document_types.DocumentType`.
105        """
106        return cast(
107            DocumentType,
108            await self._core._create_resource(
109                "document_types",
110                DocumentType,
111                owner=owner,
112                set_permissions=set_permissions,
113                name=name,
114                match=match,
115                matching_algorithm=matching_algorithm,
116                is_insensitive=is_insensitive,
117            ),
118        )
119
120    async def update(
121        self,
122        id: int,
123        *,
124        name: str | None | _Unset = UNSET,
125        match: str | None | _Unset = UNSET,
126        matching_algorithm: MatchingAlgorithm | None | _Unset = UNSET,
127        is_insensitive: bool | None | _Unset = UNSET,
128        owner: int | None | _Unset = UNSET,
129        set_permissions: SetPermissions | None | _Unset = UNSET,
130    ) -> DocumentType:
131        """Partially update a document type (PATCH semantics).
132
133        Args:
134            id: Numeric ID of the document type to update.
135            name: Document-type name.
136            match: Auto-matching pattern.
137            matching_algorithm: Controls how ``match`` is applied.
138            is_insensitive: When ``True``, ``match`` is case-insensitive.
139            owner: Numeric user ID to assign as owner.
140                Pass ``None`` to clear the owner.
141                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
142            set_permissions: Explicit view/change permission sets.
143                Omit (or pass :data:`~easypaperless.UNSET`) to leave unchanged.
144
145        Returns:
146            The updated :class:`~easypaperless.models.document_types.DocumentType`.
147        """
148        _set_perms: dict[str, Any] | _Unset = (
149            UNSET
150            if isinstance(set_permissions, _Unset)
151            else (set_permissions or SetPermissions()).model_dump()
152        )
153        return cast(
154            DocumentType,
155            await self._core._update_resource(
156                "document_types",
157                id,
158                DocumentType,
159                name=name,
160                match=match,
161                matching_algorithm=matching_algorithm,
162                is_insensitive=is_insensitive,
163                owner=owner,
164                set_permissions=_set_perms,
165            ),
166        )
167
168    async def delete(self, id: int) -> None:
169        """Delete a document type.
170
171        Args:
172            id: Numeric ID of the document type to delete.
173
174        Raises:
175            ~easypaperless.exceptions.NotFoundError: If no document type exists with that ID.
176        """
177        await self._core._delete_resource("document_types", id)
178
179    async def bulk_delete(self, ids: List[int]) -> None:
180        """Permanently delete multiple document types in a single request.
181
182        Args:
183            ids: List of document type IDs to delete.
184        """
185        await self._core._bulk_edit_objects("document_types", ids, "delete")
186
187    async def bulk_set_permissions(
188        self,
189        ids: List[int],
190        *,
191        set_permissions: SetPermissions | None = None,
192        owner: int | None = None,
193        merge: bool = False,
194    ) -> None:
195        """Set permissions and/or owner on multiple document types.
196
197        Args:
198            ids: List of document type IDs to modify.
199            set_permissions: Explicit view/change permission sets.
200            owner: Numeric user ID to assign as owner.
201            merge: When ``True``, new permissions are merged with existing ones.
202        """
203        params: dict[str, Any] = {"merge": merge}
204        if set_permissions is not None:
205            params["permissions"] = set_permissions.model_dump()
206        if owner is not None:
207            params["owner"] = owner
208        await self._core._bulk_edit_objects("document_types", ids, "set_permissions", **params)