client: Enhance docstrings for consistency and clarity

- Revised docstrings across `PdfRestClient`, `AsyncPdfRestFilesClient`, and
  exception classes to follow Google-style formatting.
- Improved descriptions and added missing sections like `Args`, `Returns`, and
  `Raises` for better usability and readability.
- Updated models and types with refined docstrings to clearly explain usage,
  structure, and expected behaviors.

Assisted-by: Codex

Author: datalogics-kam

src/pdfrest/client.py

@@ -1500,9 +1500,10 @@ async def __aexit__(self, exc_type: Any, exc: Any, traceback: Any) -> None:
 
 
 class PdfRestFilesClient(Protocol):
-    """Public interface for file operations returned by
-    [`PdfRestClient.files`][pdfrest.PdfRestClient.files].
+    """Public interface for file operations returned by files helpers.
 
+    This protocol describes the object returned by
+    [`PdfRestClient.files`][pdfrest.PdfRestClient.files].
     Retrieve this helper from `client.files`; do not instantiate it directly.
     """
 
@@ -1727,9 +1728,10 @@ def stream(
 
 
 class AsyncPdfRestFilesClient(Protocol):
-    """Public interface for file operations returned by
-    [`AsyncPdfRestClient.files`][pdfrest.AsyncPdfRestClient.files].
+    """Public interface for async file operations returned by files helpers.
 
+    This protocol describes the object returned by
+    [`AsyncPdfRestClient.files`][pdfrest.AsyncPdfRestClient.files].
     Retrieve this helper from `client.files`; do not instantiate it directly.
     """
 

src/pdfrest/exceptions.py

@@ -68,6 +68,14 @@ def __init__(
         *,
         retry_after: float | None = None,
     ) -> None:
+        """Initialize an API error with HTTP status and response details.
+
+        Args:
+            status_code: HTTP status code returned by pdfRest.
+            message: Optional human-readable error message.
+            response_content: Parsed or raw error payload from the API response.
+            retry_after: Optional retry delay in seconds parsed from headers.
+        """
         self.status_code = status_code
         self.response_content = response_content
         self.retry_after = retry_after
@@ -90,6 +98,12 @@ class PdfRestDeleteError(PdfRestError):
     """Raised when an individual file cannot be deleted."""
 
     def __init__(self, file_id: PdfRestFileID | str, message: str) -> None:
+        """Initialize a delete failure for one uploaded file.
+
+        Args:
+            file_id: Identifier of the file that failed to delete.
+            message: Error detail returned for the deletion attempt.
+        """
         self.file_id = str(file_id)
         self.detail = message
         super().__init__(f"Failed to delete file {self.file_id}: {message}")
@@ -99,6 +113,15 @@ class PdfRestErrorGroup(ExceptionGroup):
     """Group of PdfRestError exceptions produced by the PDF REST library."""
 
     def __init__(self, message: str, exceptions: Sequence[Exception], /) -> None:
+        """Initialize a grouped pdfRest failure.
+
+        Args:
+            message: Summary message for the grouped error.
+            exceptions: Collection of `PdfRestError` instances.
+
+        Raises:
+            TypeError: If any item in `exceptions` is not a `PdfRestError`.
+        """
         # enforce that everything inside is from your library
         for e in exceptions:
             if not isinstance(e, PdfRestError):

src/pdfrest/models/__init__.py

@@ -1,3 +1,5 @@
+"""Public model exports for the `pdfrest.models` package."""
+
 from .public import (
     ExtractedTextDocument,
     ExtractedTextFullText,

src/pdfrest/models/_internal.py

@@ -2577,8 +2577,10 @@ class TiffPdfRestPayload(
 
 
 class PdfRestRawUploadedFile(BaseModel):
-    """The response sent by /upload is a list of these. /unzip returns files like this
-    with outputUrl
+    """Raw uploaded-file entry returned by pdfRest upload-style endpoints.
+
+    The `/upload` response is a list of these objects. The `/unzip` response
+    also uses this shape and may include `outputUrl` entries.
     """
 
     name: Annotated[str, Field(description="The name of the file")]

src/pdfrest/models/public.py

@@ -46,7 +46,9 @@
 
 
 class PdfRestFileID(str):
-    """A str-like type representing:
+    """Str-like identifier for pdfRest files.
+
+    Format:
       [optional '1' or '2' prefix] + [UUIDv4 with hyphens]
 
     Examples:
@@ -71,6 +73,17 @@ class PdfRestFileID(str):
     )
 
     def __new__(cls, value: str) -> PdfRestFileID:
+        """Create a normalized file identifier from a validated string.
+
+        Args:
+            value: Candidate pdfRest file id string.
+
+        Returns:
+            Lower-cased, validated file id value.
+
+        Raises:
+            ValueError: If `value` is not a valid prefixed UUIDv4 identifier.
+        """
         if not cls._PY_PATTERN.fullmatch(value):
             msg = (
                 "Invalid PdfRestPrefixedUUID4. Expected: "
@@ -116,8 +129,14 @@ def is_valid(cls, value: str) -> bool:
     def from_parts(
         cls, u: str | _uuid.UUID, prefix: int | str | None = None
     ) -> PdfRestFileID:
-        """Build from a UUIDv4 (str or uuid.UUID) and an optional prefix (1 or 2).
-        Raises ValueError if not a v4 UUID or bad prefix.
+        """Build a file id from a UUIDv4 and optional prefix.
+
+        Args:
+            u: UUID value as string or `uuid.UUID`.
+            prefix: Optional leading prefix (`1` or `2`).
+
+        Raises:
+            ValueError: If the UUID is not version 4 or the prefix is invalid.
         """
         if isinstance(prefix, int):
             prefix = str(prefix)  # allow 1/2 as int
@@ -156,9 +175,11 @@ def generate(cls, prefix: int | str | None = None) -> PdfRestFileID:
     # -------------------------
     @classmethod
     def __get_pydantic_core_schema__(cls, source_type: Any, handler: Any) -> CoreSchema:
-        """Build a Pydantic v2 core schema that accepts:
-        - a UUID (validated as v4) -> converted to this type (no prefix)
-        - a string matching our pattern
+        """Build a Pydantic v2 core schema for `PdfRestFileID`.
+
+        Accepted inputs:
+        - a UUID (validated as v4) converted to this type with no prefix
+        - a string matching the `PdfRestFileID` pattern
         """
         from pydantic_core import core_schema
 
@@ -272,8 +293,10 @@ class PdfRestFile(BaseModel):
 
 
 class PdfRestFileBasedResponse(BaseModel):
-    """Represents a response from a pdfRest API operation that is file-based, allowing
-    handling of input and output files along with additional warnings.
+    """Response model for file-based pdfRest operations.
+
+    Includes input file identifiers, output files, and optional warnings from
+    the API response payload.
     """
 
     # Allow all extra fields to be stored and serialized
@@ -678,35 +701,43 @@ class ExtractedTextFullTextPages(BaseModel):
 
 
 class ExtractedTextFullText(RootModel[str | ExtractedTextFullTextPages]):
-    """Represents full-text extraction in either "document" (str) or "page" (object)
-    modes while providing convenience accessors for both forms.
+    """Full-text extraction payload in document or per-page mode.
+
+    Wraps either a single document-level string or a per-page text object and
+    provides convenience accessors for both shapes.
     """
 
     root: str | ExtractedTextFullTextPages
     """Raw payload in document-text or per-page form."""
 
     @property
     def document_text(self) -> str | None:
-        """Return the document-level string. Falls back to space-joining per-page text
-        when only the page-structured payload is available.
+        """Return document-level text for either payload shape.
+
+        Falls back to joining per-page text when only the page-structured
+        payload is available.
         """
         if isinstance(self.root, str):
             return self.root
         return " ".join(page.text for page in self.root.pages)
 
     @property
     def pages(self) -> list[ExtractedTextFullTextPage]:
-        """Return page entries when pdfRest emits per-page text.
-        Raises ValueError when the payload is in document-string mode.
+        """Return per-page text entries when page mode is available.
+
+        Raises:
+            ValueError: If the payload is in document-string mode.
         """
         if isinstance(self.root, ExtractedTextFullTextPages):
             return self.root.pages
         msg = "full text payload was emitted in document mode; page data unavailable"
         raise ValueError(msg)
 
     def iter_pages(self) -> list[ExtractedTextFullTextPage]:
-        """Convenience helper that provides a stable iterable without requiring
-        callers to guard against the document-only representation.
+        """Return per-page text entries or an empty list in document mode.
+
+        This helper avoids forcing callers to catch mode errors when they only
+        need an iterable.
         """
         try:
             return self.pages

src/pdfrest/types/public.py

@@ -145,7 +145,7 @@ class PdfAddTextObject(TypedDict, total=False):
         font: Font family name used to render text.
         max_width: Maximum text box width in PDF points.
         opacity: Opacity value from 0.0 (transparent) to 1.0 (opaque).
-        page: One-based page number or ``\"all\"`` for every page.
+        page: One-based page number or ``"all"`` for every page.
         rotation: Rotation angle in degrees.
         text: Text content to draw.
         text_color_rgb: Optional RGB text color tuple.