easypaperless

200    def __init__(
201        self,
202        url: str,
203        api_key: str,
204        *,
205        timeout: float = 30.0,
206        poll_interval: float = 2.0,
207        poll_timeout: float = 60.0,
208    ) -> None:
209        """Create an async paperless-ngx client.
210
211        Args:
212            url: Base URL of the paperless-ngx instance
213                (e.g. ``"http://localhost:8000"``).
214            api_key: API token.  Generate one in paperless-ngx under
215                *Settings → API → Generate Token*.
216            timeout: Default request timeout in seconds.  Individual
217                operations (e.g. uploads) may override this per-call.
218                Default: ``30.0``.
219            poll_interval: Seconds between status checks when ``wait=True``
220                is passed to :meth:`upload_document`.  Default: ``2.0``.
221            poll_timeout: Maximum seconds to wait for a document to finish
222                processing before raising
223                :exc:`~easypaperless.exceptions.TaskTimeoutError`.
224                Default: ``60.0``.
225        """
226        super().__init__(
227            url, api_key, timeout=timeout, poll_interval=poll_interval, poll_timeout=poll_timeout
228        )

115    async def list_documents(
116        self,
117        *,
118        search: str | None = None,
119        search_mode: str = "title_or_text",
120        ids: list[int] | None = None,
121        tags: list[int | str] | None = None,
122        any_tags: list[int | str] | None = None,
123        exclude_tags: list[int | str] | None = None,
124        correspondent: int | str | None = None,
125        any_correspondent: list[int | str] | None = None,
126        exclude_correspondents: list[int | str] | None = None,
127        document_type: int | str | None = None,
128        any_document_type: list[int | str] | None = None,
129        exclude_document_types: list[int | str] | None = None,
130        storage_path: int | str | None = None,
131        any_storage_paths: list[int | str] | None = None,
132        exclude_storage_paths: list[int | str] | None = None,
133        owner: int | None = None,
134        exclude_owners: list[int] | None = None,
135        custom_fields: list[int | str] | None = None,
136        any_custom_fields: list[int | str] | None = None,
137        exclude_custom_fields: list[int | str] | None = None,
138        custom_field_query: list[Any] | None = None,
139        archive_serial_number: int | None = None,
140        archive_serial_number_from: int | None = None,
141        archive_serial_number_till: int | None = None,
142        created_after: date | str | None = None,
143        created_before: date | str | None = None,
144        added_after: date | datetime | str | None = None,
145        added_from: date | datetime | str | None = None,
146        added_before: date | datetime | str | None = None,
147        added_until: date | datetime | str | None = None,
148        modified_after: date | datetime | str | None = None,
149        modified_from: date | datetime | str | None = None,
150        modified_before: date | datetime | str | None = None,
151        modified_until: date | datetime | str | None = None,
152        checksum: str | None = None,
153        page_size: int = 25,
154        page: int | None = None,
155        ordering: str | None = None,
156        descending: bool = False,
157        max_results: int | None = None,
158        on_page: Callable[[int, int | None], None] | None = None,
159    ) -> list[Document]:
160        """Return a filtered list of documents.
161
162        All tag, correspondent, document-type, storage-path, and custom-field
163        parameters accept either integer IDs or string names — names are
164        resolved to IDs transparently.
165
166        Args:
167            search: Search string.  Behaviour depends on ``search_mode``.
168            search_mode: How ``search`` is applied.  One of:
169
170                * ``"title_or_text"`` *(default)* — full-text search across
171                  title and OCR content (Whoosh FTS, raw API ``search``
172                  parameter).
173                * ``"title"`` — case-insensitive substring match on title
174                  only (raw API ``title__icontains``).
175                * ``"query"`` — paperless query language, e.g.
176                  ``"tag:invoice date:[2024 TO *]"`` (raw API ``query``).
177                * ``"original_filename"`` — case-insensitive substring match
178                  on the original file name (raw API
179                  ``original_filename__icontains``).
180
181            ids: Return only documents whose ID is in this list.
182            tags: Documents must have **all** of these tags (AND semantics).
183                Accepts tag IDs or tag names.
184            any_tags: Documents must have **at least one** of these tags
185                (OR semantics).  Accepts tag IDs or tag names.
186            exclude_tags: Documents must have **none** of these tags.
187                Accepts tag IDs or tag names.
188            correspondent: Filter to documents assigned to exactly this
189                correspondent.  Accepts a correspondent ID or name.
190            any_correspondent: Filter to documents assigned to **any** of
191                these correspondents (OR semantics).  Accepts IDs or names.
192                Takes precedence over ``correspondent`` when both are given.
193            exclude_correspondents: Exclude documents assigned to any of
194                these correspondents.  Accepts IDs or names.
195            document_type: Filter to documents of exactly this type.
196                Accepts a document-type ID or name.
197            any_document_type: Filter to documents whose type is **any** of
198                these (OR semantics).  Accepts IDs or names.  Takes
199                precedence over ``document_type`` when both are given.
200            exclude_document_types: Exclude documents whose type is any of
201                these.  Accepts IDs or names.
202            storage_path: Filter to documents assigned to exactly this
203                storage path.  Accepts a storage path ID or name.
204            any_storage_paths: Filter to documents assigned to **any** of
205                these storage paths (OR semantics).  Accepts IDs or names.
206                Takes precedence over ``storage_path`` when both are given.
207            exclude_storage_paths: Exclude documents assigned to any of
208                these storage paths.  Accepts IDs or names.
209            owner: Filter to documents owned by this user ID.
210            exclude_owners: Exclude documents owned by any of these user IDs.
211            custom_fields: Documents must have **all** of these custom fields
212                set (AND semantics).  Accepts custom field IDs or names.
213            any_custom_fields: Documents must have **at least one** of these
214                custom fields set (OR semantics).  Accepts IDs or names.
215            exclude_custom_fields: Documents must have **none** of these
216                custom fields set.  Accepts IDs or names.
217            custom_field_query: Filter documents by custom field values using
218                a structured query.  Simple form:
219                ``["Invoice Amount", "gt", 100]``.  Compound form:
220                ``["AND", [["Amount", "gt", 100], ["Status", "exact", "paid"]]]``.
221                Field references accept integer IDs or string names (resolved
222                server-side, not by the client).
223            archive_serial_number: Filter by exact archive serial number.
224            archive_serial_number_from: Filter by archive serial number
225                greater than or equal to this value.
226            archive_serial_number_till: Filter by archive serial number
227                less than or equal to this value.
228            created_after: ISO-8601 date string or ``date`` object.  Only
229                documents created **after** this date are returned.
230            created_before: ISO-8601 date string or ``date`` object.  Only
231                documents created **before** this date are returned.
232            added_after: Date, datetime, or ISO-8601 string.  Only
233                documents **added** (ingested) after this date/time.
234            added_from: Date, datetime, or ISO-8601 string.  Only
235                documents **added** on or after this date/time.
236            added_before: Date, datetime, or ISO-8601 string.  Only
237                documents **added** before this date/time.
238            added_until: Date, datetime, or ISO-8601 string.  Only
239                documents **added** on or before this date/time.
240            modified_after: Date, datetime, or ISO-8601 string.  Only
241                documents **modified** after this date/time.
242            modified_from: Date, datetime, or ISO-8601 string.  Only
243                documents **modified** on or after this date/time.
244            modified_before: Date, datetime, or ISO-8601 string.  Only
245                documents **modified** before this date/time.
246            modified_until: Date, datetime, or ISO-8601 string.  Only
247                documents **modified** on or before this date/time.
248            checksum: MD5 checksum of the original file (exact match).
249            page_size: Number of results per API page.  Default: ``25``.
250            page: Return only this specific page of results (1-based). When
251                set, auto-pagination is disabled. Default: ``None``.
252            ordering: Field name to sort by. Default: ``None``.
253            descending: When ``True``, reverses the sort direction.
254                Default: ``False``.
255            max_results: Stop after collecting this many documents.
256                Default: ``None``.
257            on_page: Callback invoked after each page fetch.  Receives
258                ``(fetched_so_far, total)``.  Ignored when ``page`` is set.
259
260        Returns:
261            List of :class:`~easypaperless.models.documents.Document`
262            objects.
263        """
264        params: dict[str, Any] = {"page_size": page_size}
265
266        if search is not None:
267            api_param = _SEARCH_MODE_MAP.get(search_mode, "search")
268            params[api_param] = search
269
270        if ids is not None:
271            params["id__in"] = ",".join(str(i) for i in ids)
272
273        if tags is not None:
274            resolved = await self._resolver.resolve_list("tags", tags)
275            params["tags__id__all"] = ",".join(str(t) for t in resolved)
276
277        if any_tags is not None:
278            resolved = await self._resolver.resolve_list("tags", any_tags)
279            params["tags__id__in"] = ",".join(str(t) for t in resolved)
280
281        if exclude_tags is not None:
282            resolved = await self._resolver.resolve_list("tags", exclude_tags)
283            params["tags__id__none"] = ",".join(str(t) for t in resolved)
284
285        if any_correspondent is not None:
286            resolved = await self._resolver.resolve_list("correspondents", any_correspondent)
287            params["correspondent__id__in"] = ",".join(str(c) for c in resolved)
288        elif correspondent is not None:
289            resolved_id = await self._resolver.resolve("correspondents", correspondent)
290            params["correspondent__id__in"] = resolved_id
291
292        if exclude_correspondents is not None:
293            resolved = await self._resolver.resolve_list("correspondents", exclude_correspondents)
294            params["correspondent__id__none"] = ",".join(str(c) for c in resolved)
295
296        if any_document_type is not None:
297            resolved = await self._resolver.resolve_list("document_types", any_document_type)
298            params["document_type__id__in"] = ",".join(str(d) for d in resolved)
299        elif document_type is not None:
300            resolved_id = await self._resolver.resolve("document_types", document_type)
301            params["document_type"] = resolved_id
302
303        if exclude_document_types is not None:
304            resolved = await self._resolver.resolve_list("document_types", exclude_document_types)
305            params["document_type__id__none"] = ",".join(str(d) for d in resolved)
306
307        # Storage path filters
308        if any_storage_paths is not None:
309            resolved = await self._resolver.resolve_list("storage_paths", any_storage_paths)
310            params["storage_path__id__in"] = ",".join(str(s) for s in resolved)
311        elif storage_path is not None:
312            resolved_id = await self._resolver.resolve("storage_paths", storage_path)
313            params["storage_path__id__in"] = resolved_id
314
315        if exclude_storage_paths is not None:
316            resolved = await self._resolver.resolve_list("storage_paths", exclude_storage_paths)
317            params["storage_path__id__none"] = ",".join(str(s) for s in resolved)
318
319        # Owner filters
320        if owner is not None:
321            params["owner__id__in"] = owner
322
323        if exclude_owners is not None:
324            params["owner__id__none"] = ",".join(str(o) for o in exclude_owners)
325
326        # Custom field existence filters
327        if custom_fields is not None:
328            resolved = await self._resolver.resolve_list("custom_fields", custom_fields)
329            params["custom_fields__id__all"] = ",".join(str(f) for f in resolved)
330
331        if any_custom_fields is not None:
332            resolved = await self._resolver.resolve_list("custom_fields", any_custom_fields)
333            params["custom_fields__id__in"] = ",".join(str(f) for f in resolved)
334
335        if exclude_custom_fields is not None:
336            resolved = await self._resolver.resolve_list("custom_fields", exclude_custom_fields)
337            params["custom_fields__id__none"] = ",".join(str(f) for f in resolved)
338
339        # Custom field value query
340        if custom_field_query is not None:
341            params["custom_field_query"] = json.dumps(custom_field_query)
342
343        # Archive serial number filters
344        if archive_serial_number is not None:
345            params["archive_serial_number"] = archive_serial_number
346
347        if archive_serial_number_from is not None:
348            params["archive_serial_number__gte"] = archive_serial_number_from
349
350        if archive_serial_number_till is not None:
351            params["archive_serial_number__lte"] = archive_serial_number_till
352
353        # Date filters — created (date only)
354        if created_after is not None:
355            params["created__date__gt"] = self._format_date_value(created_after)
356
357        if created_before is not None:
358            params["created__date__lt"] = self._format_date_value(created_before)
359
360        # Date filters — added (date or datetime)
361        if added_after is not None:
362            key = "added__gt" if self._is_datetime(added_after) else "added__date__gt"
363            params[key] = self._format_date_value(added_after)
364
365        if added_from is not None:
366            key = "added__gte" if self._is_datetime(added_from) else "added__date__gte"
367            params[key] = self._format_date_value(added_from)
368
369        if added_before is not None:
370            key = "added__lt" if self._is_datetime(added_before) else "added__date__lt"
371            params[key] = self._format_date_value(added_before)
372
373        if added_until is not None:
374            key = "added__lte" if self._is_datetime(added_until) else "added__date__lte"
375            params[key] = self._format_date_value(added_until)
376
377        # Date filters — modified (date or datetime)
378        if modified_after is not None:
379            key = "modified__gt" if self._is_datetime(modified_after) else "modified__date__gt"
380            params[key] = self._format_date_value(modified_after)
381
382        if modified_from is not None:
383            key = "modified__gte" if self._is_datetime(modified_from) else "modified__date__gte"
384            params[key] = self._format_date_value(modified_from)
385
386        if modified_before is not None:
387            key = "modified__lt" if self._is_datetime(modified_before) else "modified__date__lt"
388            params[key] = self._format_date_value(modified_before)
389
390        if modified_until is not None:
391            key = "modified__lte" if self._is_datetime(modified_until) else "modified__date__lte"
392            params[key] = self._format_date_value(modified_until)
393
394        if checksum is not None:
395            params["checksum__iexact"] = checksum
396
397        if ordering is not None:
398            params["ordering"] = f"-{ordering}" if descending else ordering
399
400        if page is not None:
401            params["page"] = page
402            resp = await self._session.get("/documents/", params=params)
403            items = resp.json().get("results", [])
404            if max_results is not None:
405                items = items[:max_results]
406            return [Document.model_validate(item) for item in items]
407
408        items = await self._session.get_all_pages(
409            "/documents/", params, max_results=max_results, on_page=on_page
410        )
411        return [Document.model_validate(item) for item in items]

38    async def get_document(self, id: int, *, include_metadata: bool = False) -> Document:
39        """Fetch a single document by its ID.
40
41        Args:
42            id: Numeric paperless-ngx document ID.
43            include_metadata: When ``True``, the extended file-level metadata
44                (checksums, sizes, MIME type) is fetched concurrently from
45                ``/documents/{id}/metadata/`` and attached to
46                :attr:`~easypaperless.models.documents.Document.metadata`.
47                Default: ``False``.
48
49        Returns:
50            The :class:`~easypaperless.models.documents.Document` with the
51            given ID.  When ``include_metadata=True`` the ``metadata``
52            attribute is populated; otherwise it is ``None``.
53
54        Raises:
55            ~easypaperless.exceptions.NotFoundError: If no document exists
56                with that ID.
57        """
58        if include_metadata:
59            doc_resp, meta_resp = await asyncio.gather(
60                self._session.get(f"/documents/{id}/"),
61                self._session.get(f"/documents/{id}/metadata/"),
62            )
63            data = doc_resp.json()
64            data["metadata"] = meta_resp.json()
65        else:
66            resp = await self._session.get(f"/documents/{id}/")
67            data = resp.json()
68        return Document.model_validate(data)

70    async def get_document_metadata(self, id: int) -> DocumentMetadata:
71        """Fetch the extended file-level metadata for a document.
72
73        This is a lower-overhead alternative to
74        ``get_document(id, include_metadata=True)`` when you only need the
75        metadata and not the full document object.
76
77        Args:
78            id: Numeric paperless-ngx document ID.
79
80        Returns:
81            A :class:`~easypaperless.models.documents.DocumentMetadata`
82            instance containing checksums, sizes, MIME type, and embedded
83            file metadata.
84
85        Raises:
86            ~easypaperless.exceptions.NotFoundError: If no document exists
87                with that ID.
88        """
89        resp = await self._session.get(f"/documents/{id}/metadata/")
90        return DocumentMetadata.model_validate(resp.json())

413    async def update_document(
414        self,
415        id: int,
416        *,
417        title: str | None = None,
418        content: str | None = None,
419        date: str | None = None,
420        correspondent: int | str | None = None,
421        document_type: int | str | None = None,
422        storage_path: int | str | None = None,
423        tags: list[int | str] | None = None,
424        asn: int | None = None,
425        custom_fields: list[dict[str, Any]] | None = None,
426        owner: int | None = None,
427        set_permissions: SetPermissions | None = None,
428    ) -> Document:
429        """Partially update a document (PATCH semantics — only passed fields change).
430
431        Args:
432            id: Numeric ID of the document to update.
433            title: New document title.
434            content: OCR text content of the document.
435            date: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``).
436            correspondent: Correspondent to assign, as an ID or name.
437                Pass ``0`` to clear.
438            document_type: Document type to assign, as an ID or name.
439                Pass ``0`` to clear.
440            storage_path: Storage path to assign, as an ID or name.
441                Pass ``0`` to clear.
442            tags: Full replacement list of tags (IDs or names).  The existing
443                tag list is replaced, not merged.
444            asn: Archive serial number to assign.
445            custom_fields: List of ``{"field": <field_id>, "value": ...}``
446                dicts.  Replaces the existing custom-field values.
447            owner: Numeric user ID to assign as document owner.
448            set_permissions: Explicit view/change permission sets.
449
450        Returns:
451            The updated :class:`~easypaperless.models.documents.Document`.
452        """
453        logger.debug("Updating document id=%d", id)
454        payload: dict[str, Any] = {}
455
456        if title is not None:
457            payload["title"] = title
458        if content is not None:
459            payload["content"] = content
460        if date is not None:
461            payload["created"] = date
462        if correspondent is not None:
463            payload["correspondent"] = await self._resolver.resolve("correspondents", correspondent)
464        if document_type is not None:
465            payload["document_type"] = await self._resolver.resolve("document_types", document_type)
466        if storage_path is not None:
467            payload["storage_path"] = await self._resolver.resolve("storage_paths", storage_path)
468        if tags is not None:
469            payload["tags"] = await self._resolver.resolve_list("tags", tags)
470        if asn is not None:
471            payload["archive_serial_number"] = asn
472        if custom_fields is not None:
473            payload["custom_fields"] = custom_fields
474        if owner is not None:
475            payload["owner"] = owner
476        if set_permissions is not None:
477            payload["set_permissions"] = set_permissions.model_dump()
478
479        resp = await self._session.patch(f"/documents/{id}/", json=payload)
480        return Document.model_validate(resp.json())

482    async def delete_document(self, id: int) -> None:
483        """Permanently delete a document.
484
485        Args:
486            id: Numeric ID of the document to delete.
487
488        Raises:
489            ~easypaperless.exceptions.NotFoundError: If no document exists
490                with that ID.
491        """
492        logger.debug("Deleting document id=%d", id)
493        await self._session.delete(f"/documents/{id}/")

495    async def download_document(self, id: int, *, original: bool = False) -> bytes:
496        """Download the binary content of a document.
497
498        Args:
499            id: Numeric ID of the document to download.
500            original: If ``False`` *(default)*, returns the archived
501                (post-processed) PDF.  If ``True``, returns the original
502                file that was uploaded.
503
504        Returns:
505            Raw file bytes.
506        """
507        endpoint = "download" if original else "archive"
508        resp = await self._session.get_download(f"/documents/{id}/{endpoint}/")
509        content_type = resp.headers.get("content-type", "")
510        if "text/html" in content_type or resp.content[:9].lower().startswith(b"<!doctype"):
511            raise ServerError(
512                f"Download returned an HTML page (content-type: {content_type!r}). "
513                "The server redirected to a login page even after re-attaching auth. "
514                "Run with --verbose to see redirect details.",
515                status_code=None,
516            )
517        return resp.content

21    async def get_notes(self, document_id: int) -> list[DocumentNote]:
22        """Fetch all notes attached to a document.
23
24        Args:
25            document_id: Numeric ID of the document whose notes to retrieve.
26
27        Returns:
28            List of :class:`~easypaperless.models.documents.DocumentNote` objects,
29            ordered by creation time.
30
31        Raises:
32            ~easypaperless.exceptions.NotFoundError: If no document exists
33                with that ID.
34        """
35        logger.debug("Fetching notes for document id=%d", document_id)
36        resp = await self._session.get(f"/documents/{document_id}/notes/")
37        return [DocumentNote.model_validate(item) for item in resp.json()]

39    async def create_note(self, document_id: int, *, note: str) -> DocumentNote:
40        """Create a new note on a document.
41
42        Args:
43            document_id: Numeric ID of the document to annotate.
44            note: Text content of the note.
45
46        Returns:
47            The newly created :class:`~easypaperless.models.documents.DocumentNote`.
48
49        Raises:
50            ~easypaperless.exceptions.NotFoundError: If no document exists
51                with that ID.
52        """
53        logger.debug("Creating note for document id=%d", document_id)
54        resp = await self._session.post(
55            f"/documents/{document_id}/notes/",
56            json={"note": note},
57        )
58        # paperless-ngx returns the full list of notes after creation;
59        # the newly created note is the last item in the list.
60        data = resp.json()
61        if isinstance(data, list):
62            return DocumentNote.model_validate(data[-1])
63        return DocumentNote.model_validate(data)

65    async def delete_note(self, document_id: int, note_id: int) -> None:
66        """Delete a note from a document.
67
68        Args:
69            document_id: Numeric ID of the document that owns the note.
70            note_id: Numeric ID of the note to delete.
71
72        Raises:
73            ~easypaperless.exceptions.NotFoundError: If no document or note
74                exists with the given IDs.
75        """
76        logger.debug("Deleting note id=%d from document id=%d", note_id, document_id)
77        await self._session.delete(f"/documents/{document_id}/notes/", params={"id": note_id})

 31    async def upload_document(
 32        self,
 33        file: str | Path,
 34        *,
 35        title: str | None = None,
 36        created: str | None = None,
 37        correspondent: int | str | None = None,
 38        document_type: int | str | None = None,
 39        storage_path: int | str | None = None,
 40        tags: list[int | str] | None = None,
 41        asn: int | None = None,
 42        wait: bool = False,
 43        poll_interval: float | None = None,
 44        poll_timeout: float | None = None,
 45    ) -> str | Document:
 46        """Upload a document to paperless-ngx.
 47
 48        Args:
 49            file: Path to the file to upload (``str`` or
 50                :class:`~pathlib.Path`).
 51            title: Title to assign to the document.  Paperless-ngx derives
 52                one from the file name if omitted.
 53            created: Creation date as an ISO-8601 string (``"YYYY-MM-DD"``).
 54            correspondent: Correspondent to assign, as an ID or name.
 55            document_type: Document type to assign, as an ID or name.
 56            storage_path: Storage path to assign, as an ID or name.
 57            tags: Tags to assign, as IDs or names.
 58            asn: Archive serial number to assign.
 59            wait: If ``False`` *(default)*, returns immediately with the
 60                task ID string.  If ``True``, polls the task-status endpoint
 61                until processing completes and returns the resulting
 62                :class:`~easypaperless.models.documents.Document`.
 63            poll_interval: Override the client-level ``poll_interval`` for
 64                this upload.  Only used when ``wait=True``.
 65            poll_timeout: Override the client-level ``poll_timeout`` for
 66                this upload.  Only used when ``wait=True``.
 67
 68        Returns:
 69            The Celery task ID string when ``wait=False``, or the fully
 70            processed :class:`~easypaperless.models.documents.Document`
 71            when ``wait=True``.
 72
 73        Raises:
 74            ~easypaperless.exceptions.UploadError: If paperless-ngx reports
 75                that the processing task failed.
 76            ~easypaperless.exceptions.TaskTimeoutError: If ``wait=True`` and
 77                processing does not complete within the timeout.
 78        """
 79        file_path = Path(file)
 80        file_bytes = file_path.read_bytes()
 81        logger.info("Uploading %r (%d bytes)", file_path.name, len(file_bytes))
 82
 83        data: dict[str, Any] = {}
 84        if title is not None:
 85            data["title"] = title
 86        if created is not None:
 87            data["created"] = created
 88        if correspondent is not None:
 89            data["correspondent"] = await self._resolver.resolve("correspondents", correspondent)
 90        if document_type is not None:
 91            data["document_type"] = await self._resolver.resolve("document_types", document_type)
 92        if storage_path is not None:
 93            data["storage_path"] = await self._resolver.resolve("storage_paths", storage_path)
 94        if tags is not None:
 95            resolved = await self._resolver.resolve_list("tags", tags)
 96            data["tags"] = resolved
 97        if asn is not None:
 98            data["archive_serial_number"] = asn
 99
100        files = {"document": (file_path.name, file_bytes)}
101        resp = await self._session.post("/documents/post_document/", data=data, files=files)
102        task_id: str = resp.text.strip('"')
103        logger.debug("Upload accepted, task_id=%r", task_id)
104
105        if not wait:
106            return task_id
107
108        interval = poll_interval if poll_interval is not None else self._poll_interval
109        timeout = poll_timeout if poll_timeout is not None else self._poll_timeout
110        return await self._poll_task(task_id, poll_interval=interval, poll_timeout=timeout)

20    async def bulk_edit(
21        self, document_ids: list[int], method: str, **parameters: Any
22    ) -> None:
23        """Execute a bulk-edit operation on a list of documents.
24
25        This is a low-level method; prefer the higher-level helpers such as
26        :meth:`bulk_add_tag`, :meth:`bulk_remove_tag`, and
27        :meth:`bulk_modify_tags`.
28
29        Args:
30            document_ids: List of document IDs to operate on.
31            method: Bulk-edit method name as recognised by paperless-ngx
32                (e.g. ``"add_tag"``, ``"remove_tag"``, ``"delete"``).
33            **parameters: Additional keyword arguments forwarded to the API as
34                the ``parameters`` object.
35        """
36        payload = {"documents": document_ids, "method": method, "parameters": parameters}
37        # Use a longer timeout for bulk operations — large batches can take
38        # considerably more than the default 30 s on the paperless-ngx side.
39        await self._session.post("/documents/bulk_edit/", json=payload, timeout=120.0)

41    async def bulk_add_tag(self, document_ids: list[int], tag: int | str) -> None:
42        """Add a tag to multiple documents in a single request.
43
44        Args:
45            document_ids: List of document IDs to tag.
46            tag: Tag to add, as an ID or name.
47        """
48        tag_id = await self._resolver.resolve("tags", tag)
49        await self.bulk_edit(document_ids, "add_tag", tag=tag_id)

51    async def bulk_remove_tag(self, document_ids: list[int], tag: int | str) -> None:
52        """Remove a tag from multiple documents in a single request.
53
54        Args:
55            document_ids: List of document IDs to un-tag.
56            tag: Tag to remove, as an ID or name.
57        """
58        tag_id = await self._resolver.resolve("tags", tag)
59        await self.bulk_edit(document_ids, "remove_tag", tag=tag_id)

61    async def bulk_modify_tags(
62        self,
63        document_ids: list[int],
64        *,
65        add_tags: list[int | str] | None = None,
66        remove_tags: list[int | str] | None = None,
67    ) -> None:
68        """Add and/or remove tags on multiple documents atomically.
69
70        Args:
71            document_ids: List of document IDs to modify.
72            add_tags: Tags to add, as IDs or names.
73            remove_tags: Tags to remove, as IDs or names.
74        """
75        add_ids = await self._resolver.resolve_list("tags", add_tags or [])
76        remove_ids = await self._resolver.resolve_list("tags", remove_tags or [])
77        await self.bulk_edit(document_ids, "modify_tags", add_tags=add_ids, remove_tags=remove_ids)

79    async def bulk_delete(self, document_ids: list[int]) -> None:
80        """Permanently delete multiple documents in a single request.
81
82        Args:
83            document_ids: List of document IDs to delete.
84        """
85        await self.bulk_edit(document_ids, "delete")

 87    async def bulk_set_correspondent(
 88        self, document_ids: list[int], correspondent: int | str | None
 89    ) -> None:
 90        """Assign a correspondent to multiple documents in a single request.
 91
 92        Args:
 93            document_ids: List of document IDs to modify.
 94            correspondent: Correspondent to assign, as an ID or name.
 95                Pass ``None`` to clear the assignment.
 96        """
 97        cor_id: int | None = None
 98        if correspondent is not None:
 99            cor_id = await self._resolver.resolve("correspondents", correspondent)
100        await self.bulk_edit(document_ids, "set_correspondent", correspondent=cor_id)