standardize packaging, tooling, docs, CI, and licensing

omniread/__init__.py

@@ -132,23 +132,19 @@ __all__ = [
     # core
     "Content",
     "ContentType",
-
     # html
     "HTMLScraper",
     "HTMLParser",
-
     # pdf
     "FileSystemPDFClient",
     "PDFScraper",
     "PDFParser",
-
     # csv
     "BaseCsvClient",
     "FileSystemCsvClient",
     "CsvScraper",
     "CsvParser",
     "CsvParserBase",
-
     # xlsx
     "BaseXlsxClient",
     "FileSystemXlsxClient",

omniread/__init__.pyi

@@ -1,6 +1,6 @@
 from .core import Content, ContentType
-from .html import HTMLScraper, HTMLParser
-from .pdf import FileSystemPDFClient, PDFScraper, PDFParser
+from .html import HTMLParser, HTMLScraper
+from .pdf import FileSystemPDFClient, PDFParser, PDFScraper
 
 __all__ = [
     "Content",

omniread/core/content.py

@@ -11,9 +11,10 @@ retrieved or parsed. Format-specific behavior and metadata must not alter
 the semantic meaning of these models.
 """
 
-from enum import Enum
+from collections.abc import Mapping
 from dataclasses import dataclass
-from typing import Any, Mapping, Optional
+from enum import Enum
+from typing import Any
 
 
 class ContentType(str, Enum):
@@ -72,12 +73,12 @@ class Content:
     Identifier of the content origin (URL, file path, or logical name).
     """
 
-    content_type: Optional[ContentType] = None
+    content_type: ContentType | None = None
     """
     Optional MIME type of the content, if known.
     """
 
-    metadata: Optional[Mapping[str, Any]] = None
+    metadata: Mapping[str, Any] | None = None
     """
     Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes).
     """

omniread/core/content.pyi

@@ -1,15 +1,24 @@
+from collections.abc import Mapping
 from enum import Enum
-from typing import Any, Mapping, Optional
+from typing import Any
 
 class ContentType(str, Enum):
     HTML = "text/html"
     PDF = "application/pdf"
+    XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+    CSV = "text/csv"
     JSON = "application/json"
     XML = "application/xml"
 
 class Content:
     raw: bytes
     source: str
-    content_type: Optional[ContentType]
-    metadata: Optional[Mapping[str, Any]]
-    def __init__(self, raw: bytes, source: str, content_type: Optional[ContentType] = ..., metadata: Optional[Mapping[str, Any]] = ...) -> None: ...
+    content_type: ContentType | None
+    metadata: Mapping[str, Any] | None
+    def __init__(
+        self,
+        raw: bytes,
+        source: str,
+        content_type: ContentType | None = ...,
+        metadata: Mapping[str, Any] | None = ...,
+    ) -> None: ...

omniread/core/parser.py

@@ -20,7 +20,7 @@ Parsers are not responsible for:
 """
 
 from abc import ABC, abstractmethod
-from typing import Generic, TypeVar, Set
+from typing import Generic, TypeVar
 
 from .content import Content, ContentType
 
@@ -46,7 +46,7 @@ class BaseParser(ABC, Generic[T]):
             - Implementations must remain deterministic for a given input.
     """
 
-    supported_types: Set[ContentType] = set()
+    supported_types: set[ContentType] = set()
     """
     Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic.
     """

omniread/core/parser.pyi

@@ -1,11 +1,12 @@
 from abc import ABC, abstractmethod
-from typing import Generic, TypeVar, Set
+from typing import Generic, TypeVar
+
 from .content import Content, ContentType
 
 T = TypeVar("T")
 
 class BaseParser(ABC, Generic[T]):
-    supported_types: Set[ContentType]
+    supported_types: set[ContentType]
     content: Content
     def __init__(self, content: Content) -> None: ...
     @abstractmethod

omniread/core/scraper.py

@@ -22,7 +22,8 @@ All interpretation must be delegated to parsers.
 """
 
 from abc import ABC, abstractmethod
-from typing import Any, Mapping, Optional
+from collections.abc import Mapping
+from typing import Any
 
 from .content import Content
 
@@ -53,7 +54,7 @@ class BaseScraper(ABC):
         self,
         source: str,
         *,
-        metadata: Optional[Mapping[str, Any]] = None,
+        metadata: Mapping[str, Any] | None = None,
     ) -> Content:
         """
         Fetch raw content from the given source.

omniread/core/scraper.pyi

@@ -1,7 +1,11 @@
 from abc import ABC, abstractmethod
-from typing import Any, Mapping, Optional
+from collections.abc import Mapping
+from typing import Any
+
 from .content import Content
 
 class BaseScraper(ABC):
     @abstractmethod
-    def fetch(self, source: str, *, metadata: Optional[Mapping[str, Any]] = ...) -> Content: ...
+    def fetch(
+        self, source: str, *, metadata: Mapping[str, Any] | None = ...
+    ) -> Content: ...

omniread/csv/client.py

@@ -17,9 +17,9 @@ Typical backing stores include:
 - Network file systems
 """
 
-from typing import Any
 from abc import ABC, abstractmethod
 from pathlib import Path
+from typing import Any
 
 
 class BaseCsvClient(ABC):

omniread/csv/parser.py

@@ -13,15 +13,15 @@ detection or column interpretation beyond basic cell normalization and
 delimiter detection.
 """
 
-from io import StringIO
 from csv import Sniffer, reader
-from typing import List
+from io import StringIO
 
 from omniread.core.content import Content
+
 from .parser_base import CsvParserBase
 
 
-class CsvParser(CsvParserBase):
+class CsvParser(CsvParserBase[list[list[str]]]):
     """
     Generic csv parser producing string rows from the document.
 
@@ -54,7 +54,7 @@ class CsvParser(CsvParserBase):
         """
         super().__init__(content)
 
-    def parse(self) -> List[List[str]]:
+    def parse(self) -> list[list[str]]:
         """
         Parse the document into normalized string rows.
 
@@ -64,7 +64,7 @@ class CsvParser(CsvParserBase):
         """
         return self.rows()
 
-    def rows(self, *, skip_empty: bool = True) -> List[List[str]]:
+    def rows(self, *, skip_empty: bool = True) -> list[list[str]]:
         """
         Extract normalized string rows from the document.
 
@@ -84,7 +84,7 @@ class CsvParser(CsvParserBase):
             delimiter = dialect.delimiter
         except Exception:
             delimiter = ","
-        out: List[List[str]] = []
+        out: list[list[str]] = []
         for row in reader(StringIO(text), delimiter=delimiter):
             cells = [c.strip() for c in row]
             while cells and not cells[-1]:

omniread/csv/parser_base.py

@@ -8,8 +8,8 @@ format-agnostic `BaseParser` with constraints appropriate for
 comma-separated-value documents.
 """
 
-from typing import Generic, TypeVar
 from abc import abstractmethod
+from typing import Generic, TypeVar
 
 from omniread.core.content import ContentType
 from omniread.core.parser import BaseParser

omniread/csv/scraper.py

@@ -11,9 +11,11 @@ The scraper does not interpret or parse the acquired bytes; it wraps them in
 the canonical `Content` model.
 """
 
-from typing import Any, Mapping, Optional
+from collections.abc import Mapping
+from typing import Any
 
 from omniread.core.content import Content, ContentType
+
 from .client import BaseCsvClient
 
 
@@ -48,7 +50,7 @@ class CsvScraper:
         self,
         source: Any,
         *,
-        metadata: Optional[Mapping[str, Any]] = None,
+        metadata: Mapping[str, Any] | None = None,
     ) -> Content:
         """
         Fetch a csv document from the given source.

omniread/html/__init__.py

@@ -30,7 +30,6 @@ use this package only when HTML-specific behavior is required.
 ---
 """
 
-
 from .scraper import HTMLScraper
 from .parser import HTMLParser
 

omniread/html/__init__.pyi

@@ -1,4 +1,4 @@
-from .scraper import HTMLScraper
 from .parser import HTMLParser
+from .scraper import HTMLScraper
 
 __all__ = ["HTMLScraper", "HTMLParser"]

omniread/html/parser.py

@@ -16,12 +16,12 @@ Concrete parsers must subclass `HTMLParser` and implement the `parse()` method
 to return a structured representation appropriate for their use case.
 """
 
-from typing import Any, Generic, TypeVar, Optional
 from abc import abstractmethod
+from typing import Any, Generic, TypeVar
 
 from bs4 import BeautifulSoup, Tag
 
-from omniread.core.content import ContentType, Content
+from omniread.core.content import Content, ContentType
 from omniread.core.parser import BaseParser
 
 T = TypeVar("T")
@@ -117,7 +117,7 @@ class HTMLParser(BaseParser[T], Generic[T]):
         return div.get_text(separator=separator, strip=True)
 
     @staticmethod
-    def parse_link(a: Tag) -> Optional[str]:
+    def parse_link(a: Tag) -> str | None:
         """
         Extract the hyperlink reference from an `<a>` element.
 
@@ -146,10 +146,7 @@ class HTMLParser(BaseParser[T], Generic[T]):
         """
         rows: list[list[str]] = []
         for tr in table.find_all("tr"):
-            cells = [
-                cell.get_text(strip=True)
-                for cell in tr.find_all(["td", "th"])
-            ]
+            cells = [cell.get_text(strip=True) for cell in tr.find_all(["td", "th"])]
             if cells:
                 rows.append(cells)
         return rows

omniread/html/parser.pyi

@@ -1,6 +1,8 @@
-from typing import Any, Generic, TypeVar, Optional, list, dict
-from bs4 import BeautifulSoup, Tag
-from omniread.core.content import ContentType, Content
+from typing import Any, Generic, TypeVar
+
+from bs4 import Tag
+
+from omniread.core.content import Content, ContentType
 from omniread.core.parser import BaseParser
 
 T = TypeVar("T")
@@ -12,7 +14,7 @@ class HTMLParser(BaseParser[T], Generic[T]):
     @staticmethod
     def parse_div(div: Tag, *, separator: str = ...) -> str: ...
     @staticmethod
-    def parse_link(a: Tag) -> Optional[str]: ...
+    def parse_link(a: Tag) -> str | None: ...
     @staticmethod
     def parse_table(table: Tag) -> list[list[str]]: ...
     def parse_meta(self) -> dict[str, Any]: ...

omniread/html/scraper.py

@@ -20,8 +20,10 @@ This scraper is not responsible for:
 - Managing crawl policies or rate limiting
 """
 
+from collections.abc import Mapping
+from typing import Any
+
 import httpx
-from typing import Any, Mapping, Optional
 
 from omniread.core.content import Content, ContentType
 from omniread.core.scraper import BaseScraper
@@ -51,7 +53,7 @@ class HTMLScraper(BaseScraper):
         *,
         client: httpx.Client | None = None,
         timeout: float = 15.0,
-        headers: Optional[Mapping[str, str]] = None,
+        headers: Mapping[str, str] | None = None,
         follow_redirects: bool = True,
     ):
         """
@@ -97,15 +99,13 @@ class HTMLScraper(BaseScraper):
 
         base_ct = raw_ct.split(";", 1)[0].strip().lower()
         if base_ct != self.content_type.value:
-            raise ValueError(
-                f"Expected HTML content, got '{raw_ct}'"
-            )
+            raise ValueError(f"Expected HTML content, got '{raw_ct}'")
 
     def fetch(
         self,
         source: str,
         *,
-        metadata: Optional[Mapping[str, Any]] = None,
+        metadata: Mapping[str, Any] | None = None,
     ) -> Content:
         """
         Fetch an HTML document from the given source.

omniread/html/scraper.pyi

@@ -1,10 +1,22 @@
+from collections.abc import Mapping
+from typing import Any
+
 import httpx
-from typing import Any, Mapping, Optional
+
 from omniread.core.content import Content, ContentType
 from omniread.core.scraper import BaseScraper
 
 class HTMLScraper(BaseScraper):
     content_type: ContentType
-    def __init__(self, *, client: Optional[httpx.Client] = ..., timeout: float = ..., headers: Optional[Mapping[str, str]] = ..., follow_redirects: bool = ...) -> None: ...
+    def __init__(
+        self,
+        *,
+        client: httpx.Client | None = ...,
+        timeout: float = ...,
+        headers: Mapping[str, str] | None = ...,
+        follow_redirects: bool = ...,
+    ) -> None: ...
     def validate_content_type(self, response: httpx.Response) -> None: ...
-    def fetch(self, source: str, *, metadata: Optional[Mapping[str, Any]] = ...) -> Content: ...
+    def fetch(
+        self, source: str, *, metadata: Mapping[str, Any] | None = ...
+    ) -> Content: ...

omniread/pdf/__init__.pyi

@@ -1,5 +1,5 @@
 from .client import FileSystemPDFClient
-from .scraper import PDFScraper
 from .parser import PDFParser
+from .scraper import PDFScraper
 
 __all__ = ["FileSystemPDFClient", "PDFScraper", "PDFParser"]

omniread/pdf/client.py

@@ -17,9 +17,9 @@ Typical backing stores include:
 - Network file systems
 """
 
-from typing import Any
 from abc import ABC, abstractmethod
 from pathlib import Path
+from typing import Any
 
 
 class BasePDFClient(ABC):

omniread/pdf/parser.py

@@ -10,8 +10,8 @@ PDF parsers are responsible for interpreting binary PDF data and producing
 structured representations suitable for downstream consumption.
 """
 
-from typing import Generic, TypeVar
 from abc import abstractmethod
+from typing import Generic, TypeVar
 
 from omniread.core.content import ContentType
 from omniread.core.parser import BaseParser

omniread/pdf/parser.pyi

@@ -1,5 +1,6 @@
 from abc import abstractmethod
 from typing import Generic, TypeVar
+
 from omniread.core.content import ContentType
 from omniread.core.parser import BaseParser
 

omniread/pdf/scraper.py

@@ -10,7 +10,8 @@ The scraper implements the core `BaseScraper` contract while delegating
 all storage and access concerns to a `BasePDFClient` implementation.
 """
 
-from typing import Any, Mapping, Optional
+from collections.abc import Mapping
+from typing import Any
 
 from omniread.core.content import Content, ContentType
 from omniread.core.scraper import BaseScraper
@@ -48,7 +49,7 @@ class PDFScraper(BaseScraper):
         self,
         source: Any,
         *,
-        metadata: Optional[Mapping[str, Any]] = None,
+        metadata: Mapping[str, Any] | None = None,
     ) -> Content:
         """
         Fetch a PDF document from the given source.

omniread/pdf/scraper.pyi

@@ -1,8 +1,13 @@
-from typing import Any, Mapping, Optional
-from omniread.core.content import Content, ContentType
+from collections.abc import Mapping
+from typing import Any
+
+from omniread.core.content import Content
 from omniread.core.scraper import BaseScraper
+
 from .client import BasePDFClient
 
 class PDFScraper(BaseScraper):
     def __init__(self, *, client: BasePDFClient) -> None: ...
-    def fetch(self, source: Any, *, metadata: Optional[Mapping[str, Any]] = ...) -> Content: ...
+    def fetch(
+        self, source: Any, *, metadata: Mapping[str, Any] | None = ...
+    ) -> Content: ...

omniread/xlsx/client.py

@@ -17,9 +17,9 @@ Typical backing stores include:
 - Network file systems
 """
 
-from typing import Any
 from abc import ABC, abstractmethod
 from pathlib import Path
+from typing import Any
 
 
 class BaseXlsxClient(ABC):

omniread/xlsx/parser.py

@@ -14,15 +14,16 @@ detection or column interpretation beyond basic cell normalization.
 
 import datetime
 from io import BytesIO
-from typing import List, Optional, Union
+from typing import Any
 
 import openpyxl
 
 from omniread.core.content import Content
+
 from .parser_base import XlsxParserBase
 
 
-class XlsxParser(XlsxParserBase):
+class XlsxParser(XlsxParserBase[list[list[str]]]):
     """
     Generic xlsx parser producing string rows from a worksheet.
 
@@ -41,7 +42,9 @@ class XlsxParser(XlsxParserBase):
               locale-specific formatting must convert on their side.
     """
 
-    def __init__(self, content: Content, *, data_only: bool = True, read_only: bool = True):
+    def __init__(
+        self, content: Content, *, data_only: bool = True, read_only: bool = True
+    ):
         """
         Initialize the parser.
 
@@ -57,7 +60,7 @@ class XlsxParser(XlsxParserBase):
         super().__init__(content)
         self._data_only = data_only
         self._read_only = read_only
-        self._workbook: Optional[openpyxl.Workbook] = None
+        self._workbook: openpyxl.Workbook | None = None
 
     @property
     def workbook(self) -> openpyxl.Workbook:
@@ -73,13 +76,13 @@ class XlsxParser(XlsxParserBase):
         return self._workbook
 
     @property
-    def sheet_names(self) -> List[str]:
+    def sheet_names(self) -> list[str]:
         """
         Names of all worksheets contained in the workbook.
         """
         return list(self.workbook.sheetnames)
 
-    def parse(self) -> List[List[str]]:
+    def parse(self) -> list[list[str]]:
         """
         Parse the first worksheet into normalized string rows.
 
@@ -91,10 +94,10 @@ class XlsxParser(XlsxParserBase):
 
     def rows(
         self,
-        sheet: Optional[Union[int, str]] = None,
+        sheet: int | str | None = None,
         *,
         skip_empty: bool = True,
-    ) -> List[List[str]]:
+    ) -> list[list[str]]:
         """
         Extract normalized string rows from a worksheet.
 
@@ -113,7 +116,7 @@ class XlsxParser(XlsxParserBase):
                 If the requested sheet does not exist.
         """
         ws = self._resolve_sheet(sheet)
-        out: List[List[str]] = []
+        out: list[list[str]] = []
         for row in ws.iter_rows(values_only=True):
             cells = [self._cell_str(v) for v in row]
             while cells and not cells[-1].strip():
@@ -123,7 +126,7 @@ class XlsxParser(XlsxParserBase):
             out.append(cells)
         return out
 
-    def _resolve_sheet(self, sheet: Optional[Union[int, str]]):
+    def _resolve_sheet(self, sheet: int | str | None) -> Any:
         names = self.workbook.sheetnames
         if not names:
             raise ValueError("Workbook contains no worksheets")
@@ -138,7 +141,7 @@ class XlsxParser(XlsxParserBase):
         return self.workbook[names[index]]
 
     @staticmethod
-    def _cell_str(value) -> str:
+    def _cell_str(value: Any) -> str:
         if value is None:
             return ""
         if isinstance(value, (datetime.datetime, datetime.date)):

omniread/xlsx/parser_base.py

@@ -8,8 +8,8 @@ format-agnostic `BaseParser` with constraints appropriate for Office Open
 XML spreadsheet content.
 """
 
-from typing import Generic, TypeVar
 from abc import abstractmethod
+from typing import Generic, TypeVar
 
 from omniread.core.content import ContentType
 from omniread.core.parser import BaseParser

omniread/xlsx/scraper.py

@@ -10,9 +10,11 @@ The scraper does not interpret or parse the acquired bytes; it wraps them in
 the canonical `Content` model.
 """
 
-from typing import Any, Mapping, Optional
+from collections.abc import Mapping
+from typing import Any
 
 from omniread.core.content import Content, ContentType
+
 from .client import BaseXlsxClient
 
 
@@ -47,7 +49,7 @@ class XlsxScraper:
         self,
         source: Any,
         *,
-        metadata: Optional[Mapping[str, Any]] = None,
+        metadata: Mapping[str, Any] | None = None,
     ) -> Content:
         """
         Fetch an xlsx document from the given source.