Vishesh 'ironeagle' Bangotra
650d3a19e8
Squash-merge lib-standardisation: adopt repo standards across packaging, tooling, docs, and CI. - standardize pyproject.toml (canonical packaging, lint config, extras, GSDFC pydoclint) - add py.typed marker, modernize type hints and Google-style docstrings - nest generated docs under docs/lib and docs/mcp; add hand-written wiki - adopt standard Type A PyPI CI pipeline (tag==version guard + quality gate) - promote generated CHANGELOG.md; bump version to 0.0.3
98 lines
2.5 KiB
Python
98 lines
2.5 KiB
Python
"""
|
|
# Summary
|
|
|
|
XLSX client abstractions for OmniRead.
|
|
|
|
This module defines the **client layer** responsible for retrieving raw
|
|
Office Open XML spreadsheet bytes from a concrete backing store.
|
|
|
|
Clients provide low-level access to xlsx 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
|
|
from typing import Any
|
|
|
|
|
|
class BaseXlsxClient(ABC):
|
|
"""
|
|
Abstract client responsible for retrieving spreadsheet bytes.
|
|
|
|
Retrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).
|
|
|
|
Notes:
|
|
**Responsibilities:**
|
|
|
|
- Implementations must accept a source identifier appropriate to
|
|
the backing store.
|
|
- Return the full xlsx binary payload.
|
|
- Raise retrieval-specific errors on failure.
|
|
"""
|
|
|
|
@abstractmethod
|
|
def fetch(self, source: Any) -> bytes:
|
|
"""
|
|
Fetch raw xlsx bytes from the given source.
|
|
|
|
Args:
|
|
source (Any):
|
|
Identifier of the spreadsheet location, such as a file path,
|
|
object storage key, or remote reference.
|
|
|
|
Returns:
|
|
bytes:
|
|
Raw xlsx bytes.
|
|
|
|
Raises:
|
|
Exception:
|
|
Retrieval-specific errors defined by the implementation.
|
|
"""
|
|
raise NotImplementedError
|
|
|
|
|
|
class FileSystemXlsxClient(BaseXlsxClient):
|
|
"""
|
|
XLSX client that reads from the local filesystem.
|
|
|
|
Notes:
|
|
**Guarantees:**
|
|
|
|
- This client reads spreadsheet files directly from the disk and
|
|
returns their raw binary contents.
|
|
"""
|
|
|
|
def fetch(self, path: Path) -> bytes:
|
|
"""
|
|
Read an xlsx file from the local filesystem.
|
|
|
|
Args:
|
|
path (Path):
|
|
Filesystem path to the spreadsheet file.
|
|
|
|
Returns:
|
|
bytes:
|
|
Raw xlsx 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"XLSX not found: {path}")
|
|
|
|
if not path.is_file():
|
|
raise ValueError(f"Path is not a file: {path}")
|
|
|
|
return path.read_bytes()
|