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:
@@ -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}")
|
||||
|
||||
Reference in New Issue
Block a user