Source code for paperap.resources.document_metadata
"""
Provide resources for interacting with document metadata in the Paperless-NgX API.
The document metadata endpoints expose additional information about documents
that isn't included in standard document responses, such as detailed OCR text,
archive metadata, and system-level information.
Classes:
DocumentMetadataResource: Resource for retrieving and managing document metadata.
Exceptions:
ResourceNotFoundError: Raised when requested metadata is not found.
APIError: Raised when the API returns an error response.
BadResponseError: Raised when the API response cannot be parsed.
"""
from __future__ import annotations
from typing import Any
from typing_extensions import TypeVar
from paperap.const import URLS
from paperap.exceptions import APIError, BadResponseError, ResourceNotFoundError
from paperap.models.document.metadata import DocumentMetadata, DocumentMetadataQuerySet
from paperap.resources.base import BaseResource, StandardResource
[docs]
class DocumentMetadataResource(StandardResource[DocumentMetadata, DocumentMetadataQuerySet]):
"""
Manage document metadata in Paperless-NgX.
Provides methods to interact with document metadata API endpoints,
allowing retrieval of extended metadata associated with documents. Document metadata
includes information such as OCR text, archive metadata, and system-level details
that aren't included in standard document responses.
Unlike most resources, DocumentMetadataResource uses a specialized endpoint
structure that retrieves metadata for a specific document by ID.
Attributes:
model_class (Type[DocumentMetadata]): The model class for document metadata.
queryset_class (Type[DocumentMetadataQuerySet]): The queryset class for metadata queries.
name (str): The resource name identifier.
endpoints (dict): Mapping of endpoint names to their URL patterns.
Example:
>>> client = PaperlessClient()
>>> metadata_resource = client.document_metadata
>>> # or directly
>>> metadata_resource = DocumentMetadataResource(client)
"""
model_class = DocumentMetadata
queryset_class = DocumentMetadataQuerySet
name: str = "document_metadata"
endpoints = {
# Override the detail endpoint to point to metadata
"detail": URLS.meta,
}
[docs]
def get_metadata(self, document_id: int) -> DocumentMetadata:
"""
Retrieve metadata for a specific document.
Fetches extended metadata for a document that isn't included
in the standard document response, such as detailed OCR text, archive
metadata, and system-level information.
Args:
document_id (int): The ID of the document for which to retrieve metadata.
Returns:
DocumentMetadata: A model containing the document's metadata.
Raises:
ResourceNotFoundError: If the document or its metadata doesn't exist.
APIError: If the API returns an error response.
BadResponseError: If the API response cannot be parsed.
Example:
>>> client = PaperlessClient()
>>> metadata = client.document_metadata.get_metadata(123)
>>> print(f"Original filename: {metadata.original_filename}")
>>> print(f"Archive Size: {metadata.archive_size} bytes")
"""
url = self.get_endpoint("detail", pk=document_id)
response = self.client.request("GET", url)
if not response:
raise ResourceNotFoundError(f"Metadata for document {document_id} not found", self.name)
return self.parse_to_model(response)