docs: add contract-oriented docstrings across core, html, and pdf layers

- docs(core): document Content and ContentType canonical models
- docs(core): define BaseParser contract and parsing semantics
- docs(core): define BaseScraper contract and acquisition semantics
- docs(html): document HTML package purpose and scope
- docs(html): add HTMLParser base with DOM helpers and contracts
- docs(html): add HTTP-based HTMLScraper with content-type enforcement
- docs(pdf): document PDF package structure and public pipeline
- docs(pdf): add BasePDFClient abstraction and filesystem implementation
- docs(pdf): add PDFParser base contract for binary parsing
- docs(pdf): add PDFScraper coordinating client and Content normalization
- docs(api): expand top-level omniread module with install instructions and examples
This commit is contained in:
2026-01-09 15:51:22 +05:30
parent b2173f3ef0
commit 7f1b0d9c10
12 changed files with 566 additions and 4 deletions

View File

@@ -1,3 +1,19 @@
"""
PDF client abstractions for OmniRead.
This module defines the **client layer** responsible for retrieving raw PDF
bytes from a concrete backing store.
Clients provide low-level access to PDF binaries and are intentionally
decoupled from scraping and parsing logic. They do not perform validation,
interpretation, or content extraction.
Typical backing stores include:
- Local filesystems
- Object storage (S3, GCS, etc.)
- Network file systems
"""
from abc import ABC, abstractmethod
from pathlib import Path
@@ -5,13 +21,28 @@ from pathlib import Path
class BasePDFClient(ABC):
"""
Abstract client responsible for retrieving PDF bytes
from a specific backing store (filesystem, S3, FTP, etc).
from a specific backing store (filesystem, S3, FTP, etc.).
Implementations must:
- Accept a source identifier appropriate to the backing store
- Return the full PDF binary payload
- Raise retrieval-specific errors on failure
"""
@abstractmethod
def fetch(self, source: str) -> bytes:
"""
Fetch raw PDF bytes from the given source.
Args:
source: Identifier of the PDF location, such as a file path,
object storage key, or remote reference.
Returns:
Raw PDF bytes.
Raises:
Exception: Retrieval-specific errors defined by the implementation.
"""
raise NotImplementedError
@@ -19,9 +50,25 @@ class BasePDFClient(ABC):
class FileSystemPDFClient(BasePDFClient):
"""
PDF client that reads from the local filesystem.
This client reads PDF files directly from the disk and returns their raw
binary contents.
"""
def fetch(self, path: Path) -> bytes:
"""
Read a PDF file from the local filesystem.
Args:
path: Filesystem path to the PDF file.
Returns:
Raw PDF bytes.
Raises:
FileNotFoundError: If the path does not exist.
ValueError: If the path exists but is not a file.
"""
if not path.exists():
raise FileNotFoundError(f"PDF not found: {path}")