diff --git a/docforge.nav.yml b/docforge.nav.yml index 02d6c12..2532b93 100644 --- a/docforge.nav.yml +++ b/docforge.nav.yml @@ -14,6 +14,18 @@ groups: - lib/pdf/client.md - lib/pdf/parser.md - lib/pdf/scraper.md + CSV Handling: + - lib/csv/index.md + - lib/csv/client.md + - lib/csv/parser_base.md + - lib/csv/parser.md + - lib/csv/scraper.md + XLSX Handling: + - lib/xlsx/index.md + - lib/xlsx/client.md + - lib/xlsx/parser_base.md + - lib/xlsx/parser.md + - lib/xlsx/scraper.md icon: logo: material/book-open-page-variant repo: fontawesome/brands/github \ No newline at end of file diff --git a/docs/mcp/index.json b/docs/mcp/index.json index 88b932a..c73df60 100644 --- a/docs/mcp/index.json +++ b/docs/mcp/index.json @@ -1,5 +1,5 @@ { - "project": "omniread", + "project": "OmniRead", "type": "docforge-model", "modules_count": 22, "source": "docforge" diff --git a/docs/mcp/modules/omniread.core.content.json b/docs/mcp/modules/omniread.core.content.json index b88d924..a71ec4f 100644 --- a/docs/mcp/modules/omniread.core.content.json +++ b/docs/mcp/modules/omniread.core.content.json @@ -4,39 +4,11 @@ "path": "omniread.core.content", "docstring": "# Summary\n\nCanonical content models for OmniRead.\n\nThis module defines the **format-agnostic content representation** used across\nall parsers and scrapers in OmniRead.\n\nThe models defined here represent *what* was extracted, not *how* it was\nretrieved or parsed. Format-specific behavior and metadata must not alter\nthe semantic meaning of these models.", "objects": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.core.content.Mapping", - "signature": "", - "docstring": null - }, - "dataclass": { - "name": "dataclass", - "kind": "alias", - "path": "omniread.core.content.dataclass", - "signature": "", - "docstring": null - }, - "Enum": { - "name": "Enum", - "kind": "alias", - "path": "omniread.core.content.Enum", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.core.content.Any", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.core.content.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { @@ -87,7 +59,7 @@ "name": "Content", "kind": "class", "path": "omniread.core.content.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { diff --git a/docs/mcp/modules/omniread.core.json b/docs/mcp/modules/omniread.core.json index 8d60ecf..fd51d72 100644 --- a/docs/mcp/modules/omniread.core.json +++ b/docs/mcp/modules/omniread.core.json @@ -8,35 +8,35 @@ "name": "Content", "kind": "class", "path": "omniread.core.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.core.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.core.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.core.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.core.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -45,49 +45,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.core.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.core.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.core.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.core.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.core.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.core.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.core.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -96,35 +96,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.core.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.core.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.core.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.core.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.core.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -133,14 +133,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.core.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.core.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } @@ -152,39 +152,11 @@ "signature": null, "docstring": "# Summary\n\nCanonical content models for OmniRead.\n\nThis module defines the **format-agnostic content representation** used across\nall parsers and scrapers in OmniRead.\n\nThe models defined here represent *what* was extracted, not *how* it was\nretrieved or parsed. Format-specific behavior and metadata must not alter\nthe semantic meaning of these models.", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.core.content.Mapping", - "signature": "", - "docstring": null - }, - "dataclass": { - "name": "dataclass", - "kind": "alias", - "path": "omniread.core.content.dataclass", - "signature": "", - "docstring": null - }, - "Enum": { - "name": "Enum", - "kind": "alias", - "path": "omniread.core.content.Enum", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.core.content.Any", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.core.content.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { @@ -235,7 +207,7 @@ "name": "Content", "kind": "class", "path": "omniread.core.content.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { @@ -277,67 +249,39 @@ "signature": null, "docstring": "# Summary\n\nAbstract parsing contracts for OmniRead.\n\nThis module defines the **format-agnostic parser interface** used to transform\nraw content into structured, typed representations.\n\nParsers are responsible for:\n\n- Interpreting a single `Content` instance\n- Validating compatibility with the content type\n- Producing a structured output suitable for downstream consumers\n\nParsers are not responsible for:\n\n- Fetching or acquiring content\n- Performing retries or error recovery\n- Managing multiple content sources", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.core.parser.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.core.parser.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.core.parser.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.core.parser.TypeVar", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.core.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.core.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.core.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.core.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.core.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -346,49 +290,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.core.parser.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.core.parser.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.core.parser.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.core.parser.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.core.parser.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.core.parser.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.core.parser.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -404,7 +348,7 @@ "name": "BaseParser", "kind": "class", "path": "omniread.core.parser.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { @@ -425,14 +369,14 @@ "name": "parse", "kind": "function", "path": "omniread.core.parser.BaseParser.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.core.parser.BaseParser.supports", - "signature": "", + "signature": "supports() -> bool", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -446,67 +390,39 @@ "signature": null, "docstring": "# Summary\n\nAbstract scraping contracts for OmniRead.\n\nThis module defines the **format-agnostic scraper interface** responsible for\nacquiring raw content from external sources.\n\nScrapers are responsible for:\n\n- Locating and retrieving raw content bytes\n- Attaching minimal contextual metadata\n- Returning normalized `Content` objects\n\nScrapers are explicitly NOT responsible for:\n\n- Parsing or interpreting content\n- Inferring structure or semantics\n- Performing content-type specific processing\n\nAll interpretation must be delegated to parsers.", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.core.scraper.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.core.scraper.abstractmethod", - "signature": "", - "docstring": null - }, - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.core.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.core.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.core.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.core.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.core.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.core.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.core.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -515,14 +431,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.core.scraper.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.core.scraper.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } diff --git a/docs/mcp/modules/omniread.core.parser.json b/docs/mcp/modules/omniread.core.parser.json index c10e259..88c67ce 100644 --- a/docs/mcp/modules/omniread.core.parser.json +++ b/docs/mcp/modules/omniread.core.parser.json @@ -4,67 +4,39 @@ "path": "omniread.core.parser", "docstring": "# Summary\n\nAbstract parsing contracts for OmniRead.\n\nThis module defines the **format-agnostic parser interface** used to transform\nraw content into structured, typed representations.\n\nParsers are responsible for:\n\n- Interpreting a single `Content` instance\n- Validating compatibility with the content type\n- Producing a structured output suitable for downstream consumers\n\nParsers are not responsible for:\n\n- Fetching or acquiring content\n- Performing retries or error recovery\n- Managing multiple content sources", "objects": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.core.parser.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.core.parser.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.core.parser.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.core.parser.TypeVar", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.core.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.core.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.core.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.core.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.core.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -73,49 +45,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.core.parser.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.core.parser.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.core.parser.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.core.parser.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.core.parser.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.core.parser.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.core.parser.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -131,7 +103,7 @@ "name": "BaseParser", "kind": "class", "path": "omniread.core.parser.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { @@ -152,14 +124,14 @@ "name": "parse", "kind": "function", "path": "omniread.core.parser.BaseParser.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.core.parser.BaseParser.supports", - "signature": "", + "signature": "supports() -> bool", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } diff --git a/docs/mcp/modules/omniread.core.scraper.json b/docs/mcp/modules/omniread.core.scraper.json index 7945331..5bb6bde 100644 --- a/docs/mcp/modules/omniread.core.scraper.json +++ b/docs/mcp/modules/omniread.core.scraper.json @@ -4,67 +4,39 @@ "path": "omniread.core.scraper", "docstring": "# Summary\n\nAbstract scraping contracts for OmniRead.\n\nThis module defines the **format-agnostic scraper interface** responsible for\nacquiring raw content from external sources.\n\nScrapers are responsible for:\n\n- Locating and retrieving raw content bytes\n- Attaching minimal contextual metadata\n- Returning normalized `Content` objects\n\nScrapers are explicitly NOT responsible for:\n\n- Parsing or interpreting content\n- Inferring structure or semantics\n- Performing content-type specific processing\n\nAll interpretation must be delegated to parsers.", "objects": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.core.scraper.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.core.scraper.abstractmethod", - "signature": "", - "docstring": null - }, - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.core.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.core.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.core.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.core.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.core.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.core.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.core.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -73,14 +45,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.core.scraper.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.core.scraper.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } diff --git a/docs/mcp/modules/omniread.csv.client.json b/docs/mcp/modules/omniread.csv.client.json index af0c03e..7d36d79 100644 --- a/docs/mcp/modules/omniread.csv.client.json +++ b/docs/mcp/modules/omniread.csv.client.json @@ -4,46 +4,18 @@ "path": "omniread.csv.client", "docstring": "# Summary\n\nCSV client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw\ncomma-separated-value document bytes from a concrete backing store.\n\nClients provide low-level access to csv binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems", "objects": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.csv.client.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.csv.client.abstractmethod", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "omniread.csv.client.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.csv.client.Any", - "signature": "", - "docstring": null - }, "BaseCsvClient": { "name": "BaseCsvClient", "kind": "class", "path": "omniread.csv.client.BaseCsvClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving csv bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full csv binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.client.BaseCsvClient.fetch", - "signature": "", + "signature": "fetch(source: Any) -> bytes", "docstring": "Fetch raw csv bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -52,14 +24,14 @@ "name": "FileSystemCsvClient", "kind": "class", "path": "omniread.csv.client.FileSystemCsvClient", - "signature": "", + "signature": null, "docstring": "CSV client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads csv files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.client.FileSystemCsvClient.fetch", - "signature": "", + "signature": "fetch(path: Path) -> bytes", "docstring": "Read a csv file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the csv file.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } diff --git a/docs/mcp/modules/omniread.csv.json b/docs/mcp/modules/omniread.csv.json index 46215e9..0dfa9aa 100644 --- a/docs/mcp/modules/omniread.csv.json +++ b/docs/mcp/modules/omniread.csv.json @@ -8,14 +8,14 @@ "name": "BaseCsvClient", "kind": "class", "path": "omniread.csv.BaseCsvClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving csv bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full csv binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.BaseCsvClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw csv bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -24,14 +24,14 @@ "name": "FileSystemCsvClient", "kind": "class", "path": "omniread.csv.FileSystemCsvClient", - "signature": "", + "signature": null, "docstring": "CSV client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads csv files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.FileSystemCsvClient.fetch", - "signature": "", + "signature": "fetch(path: Path)", "docstring": "Read a csv file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the csv file.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -40,21 +40,21 @@ "name": "CsvParser", "kind": "class", "path": "omniread.csv.CsvParser", - "signature": "", + "signature": "CsvParser(content: Content)", "docstring": "Generic csv parser producing string rows from the document.\n\nNotes:\n **Responsibilities:**\n\n - Decode the payload (UTF-8 with BOM support, Latin-1 fallback).\n - Detect the delimiter from a leading sample (`,` `;` tab `|`),\n defaulting to `,`.\n - Normalize cells into deterministic stripped string values.\n - Expose row extraction helpers mirroring `XlsxParser.rows`.\n\n **Constraints:**\n\n - All values are strings; consumers requiring typed values must\n convert on their side.\n - Quoted fields containing delimiters/newlines are handled by\n the standard ``csv`` module.", "members": { "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.CsvParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the document into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the document." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.csv.CsvParser.rows", - "signature": "", + "signature": "rows(*, skip_empty: bool = True)", "docstring": "Extract normalized string rows from the document.\n\nArgs:\n skip_empty (bool):\n When True (default), rows whose cells are all blank are\n omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row." } } @@ -63,21 +63,21 @@ "name": "CsvParserBase", "kind": "class", "path": "omniread.csv.CsvParserBase", - "signature": "", + "signature": null, "docstring": "Base csv parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces csv content-type compatibility and provides\n the extension point for implementing concrete csv parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.csv.CsvParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (CSV only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.CsvParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse csv content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -86,14 +86,14 @@ "name": "CsvScraper", "kind": "class", "path": "omniread.csv.CsvScraper", - "signature": "", + "signature": "CsvScraper(*, client: BaseCsvClient)", "docstring": "Scraper for csv documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw csv bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n CSV content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.CsvScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch a csv document from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw csv bytes, source\n identifier, CSV content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } @@ -105,46 +105,18 @@ "signature": null, "docstring": "# Summary\n\nCSV client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw\ncomma-separated-value document bytes from a concrete backing store.\n\nClients provide low-level access to csv binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.csv.client.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.csv.client.abstractmethod", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "omniread.csv.client.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.csv.client.Any", - "signature": "", - "docstring": null - }, "BaseCsvClient": { "name": "BaseCsvClient", "kind": "class", "path": "omniread.csv.client.BaseCsvClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving csv bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full csv binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.client.BaseCsvClient.fetch", - "signature": "", + "signature": "fetch(source: Any) -> bytes", "docstring": "Fetch raw csv bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -153,14 +125,14 @@ "name": "FileSystemCsvClient", "kind": "class", "path": "omniread.csv.client.FileSystemCsvClient", - "signature": "", + "signature": null, "docstring": "CSV client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads csv files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.client.FileSystemCsvClient.fetch", - "signature": "", + "signature": "fetch(path: Path) -> bytes", "docstring": "Read a csv file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the csv file.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -174,60 +146,39 @@ "signature": null, "docstring": "# Summary\n\nCSV parser implementations for OmniRead.\n\nThis module provides a concrete, generic parser for comma-separated-value\ndocuments. It exposes records as lists of string cells so downstream\nconsumers can interpret tabular content without depending on the ``csv``\nmodule directly.\n\nThe parser is intentionally statement-agnostic: it performs no header\ndetection or column interpretation beyond basic cell normalization and\ndelimiter detection.", "members": { - "Sniffer": { - "name": "Sniffer", - "kind": "alias", - "path": "omniread.csv.parser.Sniffer", - "signature": "", - "docstring": null - }, - "reader": { - "name": "reader", - "kind": "alias", - "path": "omniread.csv.parser.reader", - "signature": "", - "docstring": null - }, - "StringIO": { - "name": "StringIO", - "kind": "alias", - "path": "omniread.csv.parser.StringIO", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.csv.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.csv.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.csv.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.csv.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.csv.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -236,21 +187,21 @@ "name": "CsvParserBase", "kind": "class", "path": "omniread.csv.parser.CsvParserBase", - "signature": "", + "signature": null, "docstring": "Base csv parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces csv content-type compatibility and provides\n the extension point for implementing concrete csv parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.csv.parser.CsvParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (CSV only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.parser.CsvParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse csv content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -259,21 +210,21 @@ "name": "CsvParser", "kind": "class", "path": "omniread.csv.parser.CsvParser", - "signature": "", + "signature": "CsvParser(content: Content)", "docstring": "Generic csv parser producing string rows from the document.\n\nNotes:\n **Responsibilities:**\n\n - Decode the payload (UTF-8 with BOM support, Latin-1 fallback).\n - Detect the delimiter from a leading sample (`,` `;` tab `|`),\n defaulting to `,`.\n - Normalize cells into deterministic stripped string values.\n - Expose row extraction helpers mirroring `XlsxParser.rows`.\n\n **Constraints:**\n\n - All values are strings; consumers requiring typed values must\n convert on their side.\n - Quoted fields containing delimiters/newlines are handled by\n the standard ``csv`` module.", "members": { "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.parser.CsvParser.parse", - "signature": "", + "signature": "parse() -> list[list[str]]", "docstring": "Parse the document into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the document." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.csv.parser.CsvParser.rows", - "signature": "", + "signature": "rows(*, skip_empty: bool = True) -> list[list[str]]", "docstring": "Extract normalized string rows from the document.\n\nArgs:\n skip_empty (bool):\n When True (default), rows whose cells are all blank are\n omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row." } } @@ -287,74 +238,53 @@ "signature": null, "docstring": "# Summary\n\nCSV parser base implementation for OmniRead.\n\nThis module defines the **CSV-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for\ncomma-separated-value documents.", "members": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.csv.parser_base.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.csv.parser_base.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.csv.parser_base.TypeVar", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.csv.parser_base.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -363,35 +293,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.csv.parser_base.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.csv.parser_base.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.csv.parser_base.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.parser_base.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.csv.parser_base.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -407,7 +337,7 @@ "name": "CsvParserBase", "kind": "class", "path": "omniread.csv.parser_base.CsvParserBase", - "signature": "", + "signature": null, "docstring": "Base csv parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces csv content-type compatibility and provides\n the extension point for implementing concrete csv parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { @@ -421,7 +351,7 @@ "name": "parse", "kind": "function", "path": "omniread.csv.parser_base.CsvParserBase.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse csv content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -435,53 +365,39 @@ "signature": null, "docstring": "# Summary\n\nCSV scraper for OmniRead.\n\nThis module defines the scraper responsible for acquiring raw\ncomma-separated-value document content from a backing store via a\nconfigured client.\n\nThe scraper does not interpret or parse the acquired bytes; it wraps them in\nthe canonical `Content` model.", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.csv.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.csv.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.csv.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.csv.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.csv.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.csv.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.csv.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -490,49 +406,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.csv.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -541,14 +457,14 @@ "name": "BaseCsvClient", "kind": "class", "path": "omniread.csv.scraper.BaseCsvClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving csv bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full csv binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.scraper.BaseCsvClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw csv bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -557,14 +473,14 @@ "name": "CsvScraper", "kind": "class", "path": "omniread.csv.scraper.CsvScraper", - "signature": "", + "signature": "CsvScraper(*, client: BaseCsvClient)", "docstring": "Scraper for csv documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw csv bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n CSV content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.scraper.CsvScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch a csv document from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw csv bytes, source\n identifier, CSV content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } diff --git a/docs/mcp/modules/omniread.csv.parser.json b/docs/mcp/modules/omniread.csv.parser.json index 1ee8959..50a0fe5 100644 --- a/docs/mcp/modules/omniread.csv.parser.json +++ b/docs/mcp/modules/omniread.csv.parser.json @@ -4,60 +4,39 @@ "path": "omniread.csv.parser", "docstring": "# Summary\n\nCSV parser implementations for OmniRead.\n\nThis module provides a concrete, generic parser for comma-separated-value\ndocuments. It exposes records as lists of string cells so downstream\nconsumers can interpret tabular content without depending on the ``csv``\nmodule directly.\n\nThe parser is intentionally statement-agnostic: it performs no header\ndetection or column interpretation beyond basic cell normalization and\ndelimiter detection.", "objects": { - "Sniffer": { - "name": "Sniffer", - "kind": "alias", - "path": "omniread.csv.parser.Sniffer", - "signature": "", - "docstring": null - }, - "reader": { - "name": "reader", - "kind": "alias", - "path": "omniread.csv.parser.reader", - "signature": "", - "docstring": null - }, - "StringIO": { - "name": "StringIO", - "kind": "alias", - "path": "omniread.csv.parser.StringIO", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.csv.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.csv.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.csv.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.csv.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.csv.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -66,21 +45,21 @@ "name": "CsvParserBase", "kind": "class", "path": "omniread.csv.parser.CsvParserBase", - "signature": "", + "signature": null, "docstring": "Base csv parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces csv content-type compatibility and provides\n the extension point for implementing concrete csv parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.csv.parser.CsvParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (CSV only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.parser.CsvParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse csv content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -89,21 +68,21 @@ "name": "CsvParser", "kind": "class", "path": "omniread.csv.parser.CsvParser", - "signature": "", + "signature": "CsvParser(content: Content)", "docstring": "Generic csv parser producing string rows from the document.\n\nNotes:\n **Responsibilities:**\n\n - Decode the payload (UTF-8 with BOM support, Latin-1 fallback).\n - Detect the delimiter from a leading sample (`,` `;` tab `|`),\n defaulting to `,`.\n - Normalize cells into deterministic stripped string values.\n - Expose row extraction helpers mirroring `XlsxParser.rows`.\n\n **Constraints:**\n\n - All values are strings; consumers requiring typed values must\n convert on their side.\n - Quoted fields containing delimiters/newlines are handled by\n the standard ``csv`` module.", "members": { "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.parser.CsvParser.parse", - "signature": "", + "signature": "parse() -> list[list[str]]", "docstring": "Parse the document into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the document." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.csv.parser.CsvParser.rows", - "signature": "", + "signature": "rows(*, skip_empty: bool = True) -> list[list[str]]", "docstring": "Extract normalized string rows from the document.\n\nArgs:\n skip_empty (bool):\n When True (default), rows whose cells are all blank are\n omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row." } } diff --git a/docs/mcp/modules/omniread.csv.parser_base.json b/docs/mcp/modules/omniread.csv.parser_base.json index a0f7802..4c15183 100644 --- a/docs/mcp/modules/omniread.csv.parser_base.json +++ b/docs/mcp/modules/omniread.csv.parser_base.json @@ -4,74 +4,53 @@ "path": "omniread.csv.parser_base", "docstring": "# Summary\n\nCSV parser base implementation for OmniRead.\n\nThis module defines the **CSV-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for\ncomma-separated-value documents.", "objects": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.csv.parser_base.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.csv.parser_base.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.csv.parser_base.TypeVar", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.csv.parser_base.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -80,35 +59,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.csv.parser_base.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.csv.parser_base.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.csv.parser_base.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.parser_base.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.csv.parser_base.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -124,7 +103,7 @@ "name": "CsvParserBase", "kind": "class", "path": "omniread.csv.parser_base.CsvParserBase", - "signature": "", + "signature": null, "docstring": "Base csv parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces csv content-type compatibility and provides\n the extension point for implementing concrete csv parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { @@ -138,7 +117,7 @@ "name": "parse", "kind": "function", "path": "omniread.csv.parser_base.CsvParserBase.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse csv content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } diff --git a/docs/mcp/modules/omniread.csv.scraper.json b/docs/mcp/modules/omniread.csv.scraper.json index f1910e9..be51654 100644 --- a/docs/mcp/modules/omniread.csv.scraper.json +++ b/docs/mcp/modules/omniread.csv.scraper.json @@ -4,53 +4,39 @@ "path": "omniread.csv.scraper", "docstring": "# Summary\n\nCSV scraper for OmniRead.\n\nThis module defines the scraper responsible for acquiring raw\ncomma-separated-value document content from a backing store via a\nconfigured client.\n\nThe scraper does not interpret or parse the acquired bytes; it wraps them in\nthe canonical `Content` model.", "objects": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.csv.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.csv.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.csv.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.csv.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.csv.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.csv.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.csv.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -59,49 +45,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.csv.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -110,14 +96,14 @@ "name": "BaseCsvClient", "kind": "class", "path": "omniread.csv.scraper.BaseCsvClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving csv bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full csv binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.scraper.BaseCsvClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw csv bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -126,14 +112,14 @@ "name": "CsvScraper", "kind": "class", "path": "omniread.csv.scraper.CsvScraper", - "signature": "", + "signature": "CsvScraper(*, client: BaseCsvClient)", "docstring": "Scraper for csv documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw csv bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n CSV content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.scraper.CsvScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch a csv document from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw csv bytes, source\n identifier, CSV content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } diff --git a/docs/mcp/modules/omniread.html.json b/docs/mcp/modules/omniread.html.json index d6ba1d8..3ffb5b5 100644 --- a/docs/mcp/modules/omniread.html.json +++ b/docs/mcp/modules/omniread.html.json @@ -8,28 +8,28 @@ "name": "HTMLScraper", "kind": "class", "path": "omniread.html.HTMLScraper", - "signature": "", + "signature": "HTMLScraper(*, client: httpx.Client | None = None, timeout: float = 15.0, headers: Mapping[str, str] | None = None, follow_redirects: bool = True)", "docstring": "Base HTML scraper using `httpx`.\n\nNotes:\n **Responsibilities:**\n\n - This scraper retrieves HTML documents over HTTP(S) and returns\n them as raw content wrapped in a `Content` object.\n - Fetches raw bytes and metadata only.\n - The scraper uses `httpx.Client` for HTTP requests, enforces an\n HTML content type, and preserves HTTP response metadata.\n\n **Constraints:**\n\n - The scraper does not: Parse HTML, perform retries or backoff,\n handle non-HTML responses.", "members": { "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.html.HTMLScraper.content_type", - "signature": "", + "signature": null, "docstring": null }, "validate_content_type": { "name": "validate_content_type", "kind": "function", "path": "omniread.html.HTMLScraper.validate_content_type", - "signature": "", + "signature": "validate_content_type(response: httpx.Response)", "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n response (httpx.Response):\n HTTP response returned by `httpx`.\n\nRaises:\n ValueError:\n If the `Content-Type` header is missing or does not indicate HTML content." }, "fetch": { "name": "fetch", "kind": "function", "path": "omniread.html.HTMLScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n source (str):\n URL of the HTML document.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to be merged into the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.\n\nRaises:\n httpx.HTTPError:\n If the HTTP request fails.\n ValueError:\n If the response is not valid HTML." } } @@ -38,49 +38,49 @@ "name": "HTMLParser", "kind": "class", "path": "omniread.html.HTMLParser", - "signature": "", + "signature": "HTMLParser(content: Content, features: str = 'html.parser')", "docstring": "Base HTML parser.\n\nNotes:\n **Responsibilities:**\n\n - This class extends the core `BaseParser` with HTML-specific behavior,\n including DOM parsing via BeautifulSoup and reusable extraction helpers.\n - Provides reusable helpers for HTML extraction. Concrete parsers must\n explicitly define the return type.\n\n **Guarantees:**\n\n - Accepts only HTML content.\n - Owns a parsed BeautifulSoup DOM tree.\n - Provides pure helper utilities for common HTML structures.\n\n **Constraints:**\n\n - Concrete subclasses must define the output type `T` and implement\n the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.html.HTMLParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (HTML only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.html.HTMLParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Fully parse the HTML content into structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the HTML DOM and return a\n deterministic, structured output." }, "parse_div": { "name": "parse_div", "kind": "function", "path": "omniread.html.HTMLParser.parse_div", - "signature": "", + "signature": "parse_div(div: Tag, *, separator: str = ' ')", "docstring": "Extract normalized text from a `
` element.\n\nArgs:\n div (Tag):\n BeautifulSoup tag representing a `
`.\n separator (str, optional):\n String used to separate text nodes.\n\nReturns:\n str:\n Flattened, whitespace-normalized text content." }, "parse_link": { "name": "parse_link", "kind": "function", "path": "omniread.html.HTMLParser.parse_link", - "signature": "", + "signature": "parse_link(a: Tag)", "docstring": "Extract the hyperlink reference from an `` element.\n\nArgs:\n a (Tag):\n BeautifulSoup tag representing an anchor.\n\nReturns:\n str | None:\n The value of the `href` attribute, or None if absent." }, "parse_table": { "name": "parse_table", "kind": "function", "path": "omniread.html.HTMLParser.parse_table", - "signature": "", + "signature": "parse_table(table: Tag)", "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n table (Tag):\n BeautifulSoup tag representing a ``.\n\nReturns:\n list[list[str]]:\n A list of rows, where each row is a list of cell text values." }, "parse_meta": { "name": "parse_meta", "kind": "function", "path": "omniread.html.HTMLParser.parse_meta", - "signature": "", + "signature": "parse_meta()", "docstring": "Extract high-level metadata from the HTML document.\n\nReturns:\n dict[str, Any]:\n Dictionary containing extracted metadata.\n\nNotes:\n **Responsibilities:**\n\n - Extract high-level metadata from the HTML document.\n - This includes: Document title, `` tag name/property to\n content mappings." } } @@ -92,81 +92,39 @@ "signature": null, "docstring": "# Summary\n\nHTML parser base implementations for OmniRead.\n\nThis module provides reusable HTML parsing utilities built on top of\nthe abstract parser contracts defined in `omniread.core.parser`.\n\nIt supplies:\n\n- Content-type enforcement for HTML inputs\n- BeautifulSoup initialization and lifecycle management\n- Common helper methods for extracting structured data from HTML elements\n\nConcrete parsers must subclass `HTMLParser` and implement the `parse()` method\nto return a structured representation appropriate for their use case.", "members": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.html.parser.abstractmethod", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.html.parser.Any", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.html.parser.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.html.parser.TypeVar", - "signature": "", - "docstring": null - }, - "BeautifulSoup": { - "name": "BeautifulSoup", - "kind": "alias", - "path": "omniread.html.parser.BeautifulSoup", - "signature": "", - "docstring": null - }, - "Tag": { - "name": "Tag", - "kind": "alias", - "path": "omniread.html.parser.Tag", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.html.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.html.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.html.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.html.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.html.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -175,49 +133,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.html.parser.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.html.parser.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.html.parser.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.html.parser.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.html.parser.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.html.parser.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.html.parser.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -226,35 +184,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.html.parser.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.html.parser.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.html.parser.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.html.parser.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.html.parser.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -270,7 +228,7 @@ "name": "HTMLParser", "kind": "class", "path": "omniread.html.parser.HTMLParser", - "signature": "", + "signature": "HTMLParser(content: Content, features: str = 'html.parser')", "docstring": "Base HTML parser.\n\nNotes:\n **Responsibilities:**\n\n - This class extends the core `BaseParser` with HTML-specific behavior,\n including DOM parsing via BeautifulSoup and reusable extraction helpers.\n - Provides reusable helpers for HTML extraction. Concrete parsers must\n explicitly define the return type.\n\n **Guarantees:**\n\n - Accepts only HTML content.\n - Owns a parsed BeautifulSoup DOM tree.\n - Provides pure helper utilities for common HTML structures.\n\n **Constraints:**\n\n - Concrete subclasses must define the output type `T` and implement\n the `parse()` method.", "members": { "supported_types": { @@ -284,35 +242,35 @@ "name": "parse", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Fully parse the HTML content into structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the HTML DOM and return a\n deterministic, structured output." }, "parse_div": { "name": "parse_div", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_div", - "signature": "", + "signature": "parse_div(div: Tag, *, separator: str = ' ') -> str", "docstring": "Extract normalized text from a `
` element.\n\nArgs:\n div (Tag):\n BeautifulSoup tag representing a `
`.\n separator (str, optional):\n String used to separate text nodes.\n\nReturns:\n str:\n Flattened, whitespace-normalized text content." }, "parse_link": { "name": "parse_link", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_link", - "signature": "", + "signature": "parse_link(a: Tag) -> str | None", "docstring": "Extract the hyperlink reference from an `` element.\n\nArgs:\n a (Tag):\n BeautifulSoup tag representing an anchor.\n\nReturns:\n str | None:\n The value of the `href` attribute, or None if absent." }, "parse_table": { "name": "parse_table", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_table", - "signature": "", + "signature": "parse_table(table: Tag) -> list[list[str]]", "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n table (Tag):\n BeautifulSoup tag representing a `
`.\n\nReturns:\n list[list[str]]:\n A list of rows, where each row is a list of cell text values." }, "parse_meta": { "name": "parse_meta", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_meta", - "signature": "", + "signature": "parse_meta() -> dict[str, Any]", "docstring": "Extract high-level metadata from the HTML document.\n\nReturns:\n dict[str, Any]:\n Dictionary containing extracted metadata.\n\nNotes:\n **Responsibilities:**\n\n - Extract high-level metadata from the HTML document.\n - This includes: Document title, `` tag name/property to\n content mappings." } } @@ -326,60 +284,39 @@ "signature": null, "docstring": "# Summary\n\nHTML scraping implementation for OmniRead.\n\nThis module provides an HTTP-based scraper for retrieving HTML documents.\nIt implements the core `BaseScraper` contract using `httpx` as the transport\nlayer.\n\nThis scraper is responsible for:\n\n- Fetching raw HTML bytes over HTTP(S)\n- Validating response content type\n- Attaching HTTP metadata to the returned content\n\nThis scraper is not responsible for:\n\n- Parsing or interpreting HTML\n- Retrying failed requests\n- Managing crawl policies or rate limiting", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.html.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.html.scraper.Any", - "signature": "", - "docstring": null - }, - "httpx": { - "name": "httpx", - "kind": "alias", - "path": "omniread.html.scraper.httpx", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.html.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.html.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.html.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.html.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.html.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -388,49 +325,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.html.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.html.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.html.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.html.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.html.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.html.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.html.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -439,14 +376,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.html.scraper.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.html.scraper.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } @@ -455,7 +392,7 @@ "name": "HTMLScraper", "kind": "class", "path": "omniread.html.scraper.HTMLScraper", - "signature": "", + "signature": "HTMLScraper(*, client: httpx.Client | None = None, timeout: float = 15.0, headers: Mapping[str, str] | None = None, follow_redirects: bool = True)", "docstring": "Base HTML scraper using `httpx`.\n\nNotes:\n **Responsibilities:**\n\n - This scraper retrieves HTML documents over HTTP(S) and returns\n them as raw content wrapped in a `Content` object.\n - Fetches raw bytes and metadata only.\n - The scraper uses `httpx.Client` for HTTP requests, enforces an\n HTML content type, and preserves HTTP response metadata.\n\n **Constraints:**\n\n - The scraper does not: Parse HTML, perform retries or backoff,\n handle non-HTML responses.", "members": { "content_type": { @@ -469,14 +406,14 @@ "name": "validate_content_type", "kind": "function", "path": "omniread.html.scraper.HTMLScraper.validate_content_type", - "signature": "", + "signature": "validate_content_type(response: httpx.Response) -> None", "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n response (httpx.Response):\n HTTP response returned by `httpx`.\n\nRaises:\n ValueError:\n If the `Content-Type` header is missing or does not indicate HTML content." }, "fetch": { "name": "fetch", "kind": "function", "path": "omniread.html.scraper.HTMLScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n source (str):\n URL of the HTML document.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to be merged into the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.\n\nRaises:\n httpx.HTTPError:\n If the HTTP request fails.\n ValueError:\n If the response is not valid HTML." } } diff --git a/docs/mcp/modules/omniread.html.parser.json b/docs/mcp/modules/omniread.html.parser.json index 15ca5c5..31c9c59 100644 --- a/docs/mcp/modules/omniread.html.parser.json +++ b/docs/mcp/modules/omniread.html.parser.json @@ -4,81 +4,39 @@ "path": "omniread.html.parser", "docstring": "# Summary\n\nHTML parser base implementations for OmniRead.\n\nThis module provides reusable HTML parsing utilities built on top of\nthe abstract parser contracts defined in `omniread.core.parser`.\n\nIt supplies:\n\n- Content-type enforcement for HTML inputs\n- BeautifulSoup initialization and lifecycle management\n- Common helper methods for extracting structured data from HTML elements\n\nConcrete parsers must subclass `HTMLParser` and implement the `parse()` method\nto return a structured representation appropriate for their use case.", "objects": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.html.parser.abstractmethod", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.html.parser.Any", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.html.parser.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.html.parser.TypeVar", - "signature": "", - "docstring": null - }, - "BeautifulSoup": { - "name": "BeautifulSoup", - "kind": "alias", - "path": "omniread.html.parser.BeautifulSoup", - "signature": "", - "docstring": null - }, - "Tag": { - "name": "Tag", - "kind": "alias", - "path": "omniread.html.parser.Tag", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.html.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.html.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.html.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.html.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.html.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -87,49 +45,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.html.parser.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.html.parser.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.html.parser.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.html.parser.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.html.parser.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.html.parser.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.html.parser.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -138,35 +96,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.html.parser.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.html.parser.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.html.parser.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.html.parser.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.html.parser.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -182,7 +140,7 @@ "name": "HTMLParser", "kind": "class", "path": "omniread.html.parser.HTMLParser", - "signature": "", + "signature": "HTMLParser(content: Content, features: str = 'html.parser')", "docstring": "Base HTML parser.\n\nNotes:\n **Responsibilities:**\n\n - This class extends the core `BaseParser` with HTML-specific behavior,\n including DOM parsing via BeautifulSoup and reusable extraction helpers.\n - Provides reusable helpers for HTML extraction. Concrete parsers must\n explicitly define the return type.\n\n **Guarantees:**\n\n - Accepts only HTML content.\n - Owns a parsed BeautifulSoup DOM tree.\n - Provides pure helper utilities for common HTML structures.\n\n **Constraints:**\n\n - Concrete subclasses must define the output type `T` and implement\n the `parse()` method.", "members": { "supported_types": { @@ -196,35 +154,35 @@ "name": "parse", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Fully parse the HTML content into structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the HTML DOM and return a\n deterministic, structured output." }, "parse_div": { "name": "parse_div", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_div", - "signature": "", + "signature": "parse_div(div: Tag, *, separator: str = ' ') -> str", "docstring": "Extract normalized text from a `
` element.\n\nArgs:\n div (Tag):\n BeautifulSoup tag representing a `
`.\n separator (str, optional):\n String used to separate text nodes.\n\nReturns:\n str:\n Flattened, whitespace-normalized text content." }, "parse_link": { "name": "parse_link", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_link", - "signature": "", + "signature": "parse_link(a: Tag) -> str | None", "docstring": "Extract the hyperlink reference from an `` element.\n\nArgs:\n a (Tag):\n BeautifulSoup tag representing an anchor.\n\nReturns:\n str | None:\n The value of the `href` attribute, or None if absent." }, "parse_table": { "name": "parse_table", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_table", - "signature": "", + "signature": "parse_table(table: Tag) -> list[list[str]]", "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n table (Tag):\n BeautifulSoup tag representing a `
`.\n\nReturns:\n list[list[str]]:\n A list of rows, where each row is a list of cell text values." }, "parse_meta": { "name": "parse_meta", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_meta", - "signature": "", + "signature": "parse_meta() -> dict[str, Any]", "docstring": "Extract high-level metadata from the HTML document.\n\nReturns:\n dict[str, Any]:\n Dictionary containing extracted metadata.\n\nNotes:\n **Responsibilities:**\n\n - Extract high-level metadata from the HTML document.\n - This includes: Document title, `` tag name/property to\n content mappings." } } diff --git a/docs/mcp/modules/omniread.html.scraper.json b/docs/mcp/modules/omniread.html.scraper.json index 7f15d29..2eda9e9 100644 --- a/docs/mcp/modules/omniread.html.scraper.json +++ b/docs/mcp/modules/omniread.html.scraper.json @@ -4,60 +4,39 @@ "path": "omniread.html.scraper", "docstring": "# Summary\n\nHTML scraping implementation for OmniRead.\n\nThis module provides an HTTP-based scraper for retrieving HTML documents.\nIt implements the core `BaseScraper` contract using `httpx` as the transport\nlayer.\n\nThis scraper is responsible for:\n\n- Fetching raw HTML bytes over HTTP(S)\n- Validating response content type\n- Attaching HTTP metadata to the returned content\n\nThis scraper is not responsible for:\n\n- Parsing or interpreting HTML\n- Retrying failed requests\n- Managing crawl policies or rate limiting", "objects": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.html.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.html.scraper.Any", - "signature": "", - "docstring": null - }, - "httpx": { - "name": "httpx", - "kind": "alias", - "path": "omniread.html.scraper.httpx", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.html.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.html.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.html.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.html.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.html.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -66,49 +45,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.html.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.html.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.html.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.html.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.html.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.html.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.html.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -117,14 +96,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.html.scraper.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.html.scraper.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } @@ -133,7 +112,7 @@ "name": "HTMLScraper", "kind": "class", "path": "omniread.html.scraper.HTMLScraper", - "signature": "", + "signature": "HTMLScraper(*, client: httpx.Client | None = None, timeout: float = 15.0, headers: Mapping[str, str] | None = None, follow_redirects: bool = True)", "docstring": "Base HTML scraper using `httpx`.\n\nNotes:\n **Responsibilities:**\n\n - This scraper retrieves HTML documents over HTTP(S) and returns\n them as raw content wrapped in a `Content` object.\n - Fetches raw bytes and metadata only.\n - The scraper uses `httpx.Client` for HTTP requests, enforces an\n HTML content type, and preserves HTTP response metadata.\n\n **Constraints:**\n\n - The scraper does not: Parse HTML, perform retries or backoff,\n handle non-HTML responses.", "members": { "content_type": { @@ -147,14 +126,14 @@ "name": "validate_content_type", "kind": "function", "path": "omniread.html.scraper.HTMLScraper.validate_content_type", - "signature": "", + "signature": "validate_content_type(response: httpx.Response) -> None", "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n response (httpx.Response):\n HTTP response returned by `httpx`.\n\nRaises:\n ValueError:\n If the `Content-Type` header is missing or does not indicate HTML content." }, "fetch": { "name": "fetch", "kind": "function", "path": "omniread.html.scraper.HTMLScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n source (str):\n URL of the HTML document.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to be merged into the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.\n\nRaises:\n httpx.HTTPError:\n If the HTTP request fails.\n ValueError:\n If the response is not valid HTML." } } diff --git a/docs/mcp/modules/omniread.json b/docs/mcp/modules/omniread.json index 9c17528..69dbd9a 100644 --- a/docs/mcp/modules/omniread.json +++ b/docs/mcp/modules/omniread.json @@ -8,35 +8,35 @@ "name": "Content", "kind": "class", "path": "omniread.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -45,49 +45,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -96,14 +96,14 @@ "name": "BaseCsvClient", "kind": "class", "path": "omniread.BaseCsvClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving csv bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full csv binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.BaseCsvClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw csv bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -112,21 +112,21 @@ "name": "CsvParser", "kind": "class", "path": "omniread.CsvParser", - "signature": "", + "signature": "CsvParser(content: Content)", "docstring": "Generic csv parser producing string rows from the document.\n\nNotes:\n **Responsibilities:**\n\n - Decode the payload (UTF-8 with BOM support, Latin-1 fallback).\n - Detect the delimiter from a leading sample (`,` `;` tab `|`),\n defaulting to `,`.\n - Normalize cells into deterministic stripped string values.\n - Expose row extraction helpers mirroring `XlsxParser.rows`.\n\n **Constraints:**\n\n - All values are strings; consumers requiring typed values must\n convert on their side.\n - Quoted fields containing delimiters/newlines are handled by\n the standard ``csv`` module.", "members": { "parse": { "name": "parse", "kind": "function", "path": "omniread.CsvParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the document into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the document." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.CsvParser.rows", - "signature": "", + "signature": "rows(*, skip_empty: bool = True)", "docstring": "Extract normalized string rows from the document.\n\nArgs:\n skip_empty (bool):\n When True (default), rows whose cells are all blank are\n omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row." } } @@ -135,21 +135,21 @@ "name": "CsvParserBase", "kind": "class", "path": "omniread.CsvParserBase", - "signature": "", + "signature": null, "docstring": "Base csv parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces csv content-type compatibility and provides\n the extension point for implementing concrete csv parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.CsvParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (CSV only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.CsvParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse csv content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -158,14 +158,14 @@ "name": "CsvScraper", "kind": "class", "path": "omniread.CsvScraper", - "signature": "", + "signature": "CsvScraper(*, client: BaseCsvClient)", "docstring": "Scraper for csv documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw csv bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n CSV content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.CsvScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch a csv document from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw csv bytes, source\n identifier, CSV content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } @@ -174,14 +174,14 @@ "name": "FileSystemCsvClient", "kind": "class", "path": "omniread.FileSystemCsvClient", - "signature": "", + "signature": null, "docstring": "CSV client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads csv files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.FileSystemCsvClient.fetch", - "signature": "", + "signature": "fetch(path: Path)", "docstring": "Read a csv file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the csv file.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -190,28 +190,28 @@ "name": "HTMLScraper", "kind": "class", "path": "omniread.HTMLScraper", - "signature": "", + "signature": "HTMLScraper(*, client: httpx.Client | None = None, timeout: float = 15.0, headers: Mapping[str, str] | None = None, follow_redirects: bool = True)", "docstring": "Base HTML scraper using `httpx`.\n\nNotes:\n **Responsibilities:**\n\n - This scraper retrieves HTML documents over HTTP(S) and returns\n them as raw content wrapped in a `Content` object.\n - Fetches raw bytes and metadata only.\n - The scraper uses `httpx.Client` for HTTP requests, enforces an\n HTML content type, and preserves HTTP response metadata.\n\n **Constraints:**\n\n - The scraper does not: Parse HTML, perform retries or backoff,\n handle non-HTML responses.", "members": { "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.HTMLScraper.content_type", - "signature": "", + "signature": null, "docstring": null }, "validate_content_type": { "name": "validate_content_type", "kind": "function", "path": "omniread.HTMLScraper.validate_content_type", - "signature": "", + "signature": "validate_content_type(response: httpx.Response)", "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n response (httpx.Response):\n HTTP response returned by `httpx`.\n\nRaises:\n ValueError:\n If the `Content-Type` header is missing or does not indicate HTML content." }, "fetch": { "name": "fetch", "kind": "function", "path": "omniread.HTMLScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n source (str):\n URL of the HTML document.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to be merged into the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.\n\nRaises:\n httpx.HTTPError:\n If the HTTP request fails.\n ValueError:\n If the response is not valid HTML." } } @@ -220,49 +220,49 @@ "name": "HTMLParser", "kind": "class", "path": "omniread.HTMLParser", - "signature": "", + "signature": "HTMLParser(content: Content, features: str = 'html.parser')", "docstring": "Base HTML parser.\n\nNotes:\n **Responsibilities:**\n\n - This class extends the core `BaseParser` with HTML-specific behavior,\n including DOM parsing via BeautifulSoup and reusable extraction helpers.\n - Provides reusable helpers for HTML extraction. Concrete parsers must\n explicitly define the return type.\n\n **Guarantees:**\n\n - Accepts only HTML content.\n - Owns a parsed BeautifulSoup DOM tree.\n - Provides pure helper utilities for common HTML structures.\n\n **Constraints:**\n\n - Concrete subclasses must define the output type `T` and implement\n the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.HTMLParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (HTML only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.HTMLParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Fully parse the HTML content into structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the HTML DOM and return a\n deterministic, structured output." }, "parse_div": { "name": "parse_div", "kind": "function", "path": "omniread.HTMLParser.parse_div", - "signature": "", + "signature": "parse_div(div: Tag, *, separator: str = ' ')", "docstring": "Extract normalized text from a `
` element.\n\nArgs:\n div (Tag):\n BeautifulSoup tag representing a `
`.\n\nReturns:\n list[list[str]]:\n A list of rows, where each row is a list of cell text values." }, "parse_meta": { "name": "parse_meta", "kind": "function", "path": "omniread.HTMLParser.parse_meta", - "signature": "", + "signature": "parse_meta()", "docstring": "Extract high-level metadata from the HTML document.\n\nReturns:\n dict[str, Any]:\n Dictionary containing extracted metadata.\n\nNotes:\n **Responsibilities:**\n\n - Extract high-level metadata from the HTML document.\n - This includes: Document title, `` tag name/property to\n content mappings." } } @@ -271,14 +271,14 @@ "name": "FileSystemPDFClient", "kind": "class", "path": "omniread.FileSystemPDFClient", - "signature": "", + "signature": null, "docstring": "PDF client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads PDF files directly from the disk and returns\n their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.FileSystemPDFClient.fetch", - "signature": "", + "signature": "fetch(path: Path)", "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the PDF file.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -287,14 +287,14 @@ "name": "PDFScraper", "kind": "class", "path": "omniread.PDFScraper", - "signature": "", + "signature": "PDFScraper(*, client: BasePDFClient)", "docstring": "Scraper for PDF sources.\n\nNotes:\n **Responsibilities:**\n\n - Delegates byte retrieval to a PDF client and normalizes output\n into `Content`.\n - Preserves caller-provided metadata.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.PDFScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF source as understood by the configured PDF client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the PDF client." } } @@ -303,21 +303,21 @@ "name": "PDFParser", "kind": "class", "path": "omniread.PDFParser", - "signature": "", + "signature": null, "docstring": "Base PDF parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces PDF content-type compatibility and provides\n the extension point for implementing concrete PDF parsing strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.PDFParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (PDF only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.PDFParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse PDF content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the PDF binary payload and\n return a deterministic, structured output." } } @@ -326,14 +326,14 @@ "name": "BaseXlsxClient", "kind": "class", "path": "omniread.BaseXlsxClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving spreadsheet bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full xlsx binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.BaseXlsxClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw xlsx bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -342,14 +342,14 @@ "name": "FileSystemXlsxClient", "kind": "class", "path": "omniread.FileSystemXlsxClient", - "signature": "", + "signature": null, "docstring": "XLSX client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads spreadsheet files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.FileSystemXlsxClient.fetch", - "signature": "", + "signature": "fetch(path: Path)", "docstring": "Read an xlsx file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the spreadsheet file.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -358,35 +358,35 @@ "name": "XlsxParser", "kind": "class", "path": "omniread.XlsxParser", - "signature": "", + "signature": "XlsxParser(content: Content, *, data_only: bool = True, read_only: bool = True)", "docstring": "Generic xlsx parser producing string rows from a worksheet.\n\nNotes:\n **Responsibilities:**\n\n - Lazily load the workbook owned by the parser's content.\n - Normalize cells (including dates and numeric values) into\n deterministic string representations.\n - Expose sheet discovery and row extraction helpers.\n\n **Constraints:**\n\n - Cells are rendered with ``str(value)`` after trimming; date and\n datetime values are rendered in ISO format. Consumers requiring\n locale-specific formatting must convert on their side.", "members": { "workbook": { "name": "workbook", "kind": "attribute", "path": "omniread.XlsxParser.workbook", - "signature": "", + "signature": null, "docstring": "The lazily loaded workbook backing this parser's content." }, "sheet_names": { "name": "sheet_names", "kind": "attribute", "path": "omniread.XlsxParser.sheet_names", - "signature": "", + "signature": null, "docstring": "Names of all worksheets contained in the workbook." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.XlsxParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the first worksheet into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the default (first) worksheet." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.XlsxParser.rows", - "signature": "", + "signature": "rows(sheet: int | str | None = None, *, skip_empty: bool = True)", "docstring": "Extract normalized string rows from a worksheet.\n\nArgs:\n sheet (int | str | None):\n Worksheet index or title; defaults to the first worksheet.\n skip_empty (bool):\n When True (default), rows whose cells are all blank are omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row.\n\nRaises:\n ValueError:\n If the requested sheet does not exist." } } @@ -395,21 +395,21 @@ "name": "XlsxParserBase", "kind": "class", "path": "omniread.XlsxParserBase", - "signature": "", + "signature": null, "docstring": "Base xlsx parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces xlsx content-type compatibility and provides\n the extension point for implementing concrete xlsx parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.XlsxParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (XLSX only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.XlsxParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse xlsx content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -418,14 +418,14 @@ "name": "XlsxScraper", "kind": "class", "path": "omniread.XlsxScraper", - "signature": "", + "signature": "XlsxScraper(*, client: BaseXlsxClient)", "docstring": "Scraper for xlsx spreadsheet documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw xlsx bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n XLSX content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.XlsxScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch an xlsx document from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw xlsx bytes, source\n identifier, XLSX content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } @@ -441,35 +441,35 @@ "name": "Content", "kind": "class", "path": "omniread.core.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.core.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.core.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.core.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.core.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -478,49 +478,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.core.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.core.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.core.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.core.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.core.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.core.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.core.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -529,35 +529,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.core.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.core.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.core.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.core.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.core.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -566,14 +566,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.core.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.core.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } @@ -585,39 +585,11 @@ "signature": null, "docstring": "# Summary\n\nCanonical content models for OmniRead.\n\nThis module defines the **format-agnostic content representation** used across\nall parsers and scrapers in OmniRead.\n\nThe models defined here represent *what* was extracted, not *how* it was\nretrieved or parsed. Format-specific behavior and metadata must not alter\nthe semantic meaning of these models.", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.core.content.Mapping", - "signature": "", - "docstring": null - }, - "dataclass": { - "name": "dataclass", - "kind": "alias", - "path": "omniread.core.content.dataclass", - "signature": "", - "docstring": null - }, - "Enum": { - "name": "Enum", - "kind": "alias", - "path": "omniread.core.content.Enum", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.core.content.Any", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.core.content.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { @@ -668,7 +640,7 @@ "name": "Content", "kind": "class", "path": "omniread.core.content.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { @@ -710,67 +682,39 @@ "signature": null, "docstring": "# Summary\n\nAbstract parsing contracts for OmniRead.\n\nThis module defines the **format-agnostic parser interface** used to transform\nraw content into structured, typed representations.\n\nParsers are responsible for:\n\n- Interpreting a single `Content` instance\n- Validating compatibility with the content type\n- Producing a structured output suitable for downstream consumers\n\nParsers are not responsible for:\n\n- Fetching or acquiring content\n- Performing retries or error recovery\n- Managing multiple content sources", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.core.parser.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.core.parser.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.core.parser.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.core.parser.TypeVar", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.core.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.core.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.core.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.core.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.core.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -779,49 +723,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.core.parser.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.core.parser.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.core.parser.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.core.parser.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.core.parser.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.core.parser.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.core.parser.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -837,7 +781,7 @@ "name": "BaseParser", "kind": "class", "path": "omniread.core.parser.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { @@ -858,14 +802,14 @@ "name": "parse", "kind": "function", "path": "omniread.core.parser.BaseParser.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.core.parser.BaseParser.supports", - "signature": "", + "signature": "supports() -> bool", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -879,67 +823,39 @@ "signature": null, "docstring": "# Summary\n\nAbstract scraping contracts for OmniRead.\n\nThis module defines the **format-agnostic scraper interface** responsible for\nacquiring raw content from external sources.\n\nScrapers are responsible for:\n\n- Locating and retrieving raw content bytes\n- Attaching minimal contextual metadata\n- Returning normalized `Content` objects\n\nScrapers are explicitly NOT responsible for:\n\n- Parsing or interpreting content\n- Inferring structure or semantics\n- Performing content-type specific processing\n\nAll interpretation must be delegated to parsers.", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.core.scraper.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.core.scraper.abstractmethod", - "signature": "", - "docstring": null - }, - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.core.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.core.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.core.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.core.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.core.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.core.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.core.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -948,14 +864,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.core.scraper.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.core.scraper.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } @@ -975,14 +891,14 @@ "name": "BaseCsvClient", "kind": "class", "path": "omniread.csv.BaseCsvClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving csv bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full csv binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.BaseCsvClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw csv bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -991,14 +907,14 @@ "name": "FileSystemCsvClient", "kind": "class", "path": "omniread.csv.FileSystemCsvClient", - "signature": "", + "signature": null, "docstring": "CSV client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads csv files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.FileSystemCsvClient.fetch", - "signature": "", + "signature": "fetch(path: Path)", "docstring": "Read a csv file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the csv file.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -1007,21 +923,21 @@ "name": "CsvParser", "kind": "class", "path": "omniread.csv.CsvParser", - "signature": "", + "signature": "CsvParser(content: Content)", "docstring": "Generic csv parser producing string rows from the document.\n\nNotes:\n **Responsibilities:**\n\n - Decode the payload (UTF-8 with BOM support, Latin-1 fallback).\n - Detect the delimiter from a leading sample (`,` `;` tab `|`),\n defaulting to `,`.\n - Normalize cells into deterministic stripped string values.\n - Expose row extraction helpers mirroring `XlsxParser.rows`.\n\n **Constraints:**\n\n - All values are strings; consumers requiring typed values must\n convert on their side.\n - Quoted fields containing delimiters/newlines are handled by\n the standard ``csv`` module.", "members": { "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.CsvParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the document into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the document." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.csv.CsvParser.rows", - "signature": "", + "signature": "rows(*, skip_empty: bool = True)", "docstring": "Extract normalized string rows from the document.\n\nArgs:\n skip_empty (bool):\n When True (default), rows whose cells are all blank are\n omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row." } } @@ -1030,21 +946,21 @@ "name": "CsvParserBase", "kind": "class", "path": "omniread.csv.CsvParserBase", - "signature": "", + "signature": null, "docstring": "Base csv parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces csv content-type compatibility and provides\n the extension point for implementing concrete csv parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.csv.CsvParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (CSV only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.CsvParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse csv content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -1053,14 +969,14 @@ "name": "CsvScraper", "kind": "class", "path": "omniread.csv.CsvScraper", - "signature": "", + "signature": "CsvScraper(*, client: BaseCsvClient)", "docstring": "Scraper for csv documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw csv bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n CSV content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.CsvScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch a csv document from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw csv bytes, source\n identifier, CSV content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } @@ -1072,46 +988,18 @@ "signature": null, "docstring": "# Summary\n\nCSV client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw\ncomma-separated-value document bytes from a concrete backing store.\n\nClients provide low-level access to csv binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.csv.client.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.csv.client.abstractmethod", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "omniread.csv.client.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.csv.client.Any", - "signature": "", - "docstring": null - }, "BaseCsvClient": { "name": "BaseCsvClient", "kind": "class", "path": "omniread.csv.client.BaseCsvClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving csv bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full csv binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.client.BaseCsvClient.fetch", - "signature": "", + "signature": "fetch(source: Any) -> bytes", "docstring": "Fetch raw csv bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -1120,14 +1008,14 @@ "name": "FileSystemCsvClient", "kind": "class", "path": "omniread.csv.client.FileSystemCsvClient", - "signature": "", + "signature": null, "docstring": "CSV client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads csv files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.client.FileSystemCsvClient.fetch", - "signature": "", + "signature": "fetch(path: Path) -> bytes", "docstring": "Read a csv file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the csv file.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -1141,60 +1029,39 @@ "signature": null, "docstring": "# Summary\n\nCSV parser implementations for OmniRead.\n\nThis module provides a concrete, generic parser for comma-separated-value\ndocuments. It exposes records as lists of string cells so downstream\nconsumers can interpret tabular content without depending on the ``csv``\nmodule directly.\n\nThe parser is intentionally statement-agnostic: it performs no header\ndetection or column interpretation beyond basic cell normalization and\ndelimiter detection.", "members": { - "Sniffer": { - "name": "Sniffer", - "kind": "alias", - "path": "omniread.csv.parser.Sniffer", - "signature": "", - "docstring": null - }, - "reader": { - "name": "reader", - "kind": "alias", - "path": "omniread.csv.parser.reader", - "signature": "", - "docstring": null - }, - "StringIO": { - "name": "StringIO", - "kind": "alias", - "path": "omniread.csv.parser.StringIO", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.csv.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.csv.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.csv.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.csv.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.csv.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -1203,21 +1070,21 @@ "name": "CsvParserBase", "kind": "class", "path": "omniread.csv.parser.CsvParserBase", - "signature": "", + "signature": null, "docstring": "Base csv parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces csv content-type compatibility and provides\n the extension point for implementing concrete csv parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.csv.parser.CsvParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (CSV only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.parser.CsvParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse csv content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -1226,21 +1093,21 @@ "name": "CsvParser", "kind": "class", "path": "omniread.csv.parser.CsvParser", - "signature": "", + "signature": "CsvParser(content: Content)", "docstring": "Generic csv parser producing string rows from the document.\n\nNotes:\n **Responsibilities:**\n\n - Decode the payload (UTF-8 with BOM support, Latin-1 fallback).\n - Detect the delimiter from a leading sample (`,` `;` tab `|`),\n defaulting to `,`.\n - Normalize cells into deterministic stripped string values.\n - Expose row extraction helpers mirroring `XlsxParser.rows`.\n\n **Constraints:**\n\n - All values are strings; consumers requiring typed values must\n convert on their side.\n - Quoted fields containing delimiters/newlines are handled by\n the standard ``csv`` module.", "members": { "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.parser.CsvParser.parse", - "signature": "", + "signature": "parse() -> list[list[str]]", "docstring": "Parse the document into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the document." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.csv.parser.CsvParser.rows", - "signature": "", + "signature": "rows(*, skip_empty: bool = True) -> list[list[str]]", "docstring": "Extract normalized string rows from the document.\n\nArgs:\n skip_empty (bool):\n When True (default), rows whose cells are all blank are\n omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row." } } @@ -1254,74 +1121,53 @@ "signature": null, "docstring": "# Summary\n\nCSV parser base implementation for OmniRead.\n\nThis module defines the **CSV-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for\ncomma-separated-value documents.", "members": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.csv.parser_base.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.csv.parser_base.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.csv.parser_base.TypeVar", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.csv.parser_base.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.csv.parser_base.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -1330,35 +1176,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.csv.parser_base.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.csv.parser_base.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.csv.parser_base.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.csv.parser_base.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.csv.parser_base.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -1374,7 +1220,7 @@ "name": "CsvParserBase", "kind": "class", "path": "omniread.csv.parser_base.CsvParserBase", - "signature": "", + "signature": null, "docstring": "Base csv parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces csv content-type compatibility and provides\n the extension point for implementing concrete csv parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { @@ -1388,7 +1234,7 @@ "name": "parse", "kind": "function", "path": "omniread.csv.parser_base.CsvParserBase.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse csv content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -1402,53 +1248,39 @@ "signature": null, "docstring": "# Summary\n\nCSV scraper for OmniRead.\n\nThis module defines the scraper responsible for acquiring raw\ncomma-separated-value document content from a backing store via a\nconfigured client.\n\nThe scraper does not interpret or parse the acquired bytes; it wraps them in\nthe canonical `Content` model.", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.csv.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.csv.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.csv.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.csv.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.csv.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.csv.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.csv.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -1457,49 +1289,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.csv.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.csv.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -1508,14 +1340,14 @@ "name": "BaseCsvClient", "kind": "class", "path": "omniread.csv.scraper.BaseCsvClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving csv bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full csv binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.scraper.BaseCsvClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw csv bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw csv bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -1524,14 +1356,14 @@ "name": "CsvScraper", "kind": "class", "path": "omniread.csv.scraper.CsvScraper", - "signature": "", + "signature": "CsvScraper(*, client: BaseCsvClient)", "docstring": "Scraper for csv documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw csv bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n CSV content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.csv.scraper.CsvScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch a csv document from the given source.\n\nArgs:\n source (Any):\n Identifier of the csv source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw csv bytes, source\n identifier, CSV content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } @@ -1551,28 +1383,28 @@ "name": "HTMLScraper", "kind": "class", "path": "omniread.html.HTMLScraper", - "signature": "", + "signature": "HTMLScraper(*, client: httpx.Client | None = None, timeout: float = 15.0, headers: Mapping[str, str] | None = None, follow_redirects: bool = True)", "docstring": "Base HTML scraper using `httpx`.\n\nNotes:\n **Responsibilities:**\n\n - This scraper retrieves HTML documents over HTTP(S) and returns\n them as raw content wrapped in a `Content` object.\n - Fetches raw bytes and metadata only.\n - The scraper uses `httpx.Client` for HTTP requests, enforces an\n HTML content type, and preserves HTTP response metadata.\n\n **Constraints:**\n\n - The scraper does not: Parse HTML, perform retries or backoff,\n handle non-HTML responses.", "members": { "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.html.HTMLScraper.content_type", - "signature": "", + "signature": null, "docstring": null }, "validate_content_type": { "name": "validate_content_type", "kind": "function", "path": "omniread.html.HTMLScraper.validate_content_type", - "signature": "", + "signature": "validate_content_type(response: httpx.Response)", "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n response (httpx.Response):\n HTTP response returned by `httpx`.\n\nRaises:\n ValueError:\n If the `Content-Type` header is missing or does not indicate HTML content." }, "fetch": { "name": "fetch", "kind": "function", "path": "omniread.html.HTMLScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n source (str):\n URL of the HTML document.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to be merged into the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.\n\nRaises:\n httpx.HTTPError:\n If the HTTP request fails.\n ValueError:\n If the response is not valid HTML." } } @@ -1581,49 +1413,49 @@ "name": "HTMLParser", "kind": "class", "path": "omniread.html.HTMLParser", - "signature": "", + "signature": "HTMLParser(content: Content, features: str = 'html.parser')", "docstring": "Base HTML parser.\n\nNotes:\n **Responsibilities:**\n\n - This class extends the core `BaseParser` with HTML-specific behavior,\n including DOM parsing via BeautifulSoup and reusable extraction helpers.\n - Provides reusable helpers for HTML extraction. Concrete parsers must\n explicitly define the return type.\n\n **Guarantees:**\n\n - Accepts only HTML content.\n - Owns a parsed BeautifulSoup DOM tree.\n - Provides pure helper utilities for common HTML structures.\n\n **Constraints:**\n\n - Concrete subclasses must define the output type `T` and implement\n the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.html.HTMLParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (HTML only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.html.HTMLParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Fully parse the HTML content into structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the HTML DOM and return a\n deterministic, structured output." }, "parse_div": { "name": "parse_div", "kind": "function", "path": "omniread.html.HTMLParser.parse_div", - "signature": "", + "signature": "parse_div(div: Tag, *, separator: str = ' ')", "docstring": "Extract normalized text from a `
` element.\n\nArgs:\n div (Tag):\n BeautifulSoup tag representing a `
`.\n separator (str, optional):\n String used to separate text nodes.\n\nReturns:\n str:\n Flattened, whitespace-normalized text content." }, "parse_link": { "name": "parse_link", "kind": "function", "path": "omniread.html.HTMLParser.parse_link", - "signature": "", + "signature": "parse_link(a: Tag)", "docstring": "Extract the hyperlink reference from an `` element.\n\nArgs:\n a (Tag):\n BeautifulSoup tag representing an anchor.\n\nReturns:\n str | None:\n The value of the `href` attribute, or None if absent." }, "parse_table": { "name": "parse_table", "kind": "function", "path": "omniread.html.HTMLParser.parse_table", - "signature": "", + "signature": "parse_table(table: Tag)", "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n table (Tag):\n BeautifulSoup tag representing a `
`.\n\nReturns:\n list[list[str]]:\n A list of rows, where each row is a list of cell text values." }, "parse_meta": { "name": "parse_meta", "kind": "function", "path": "omniread.html.HTMLParser.parse_meta", - "signature": "", + "signature": "parse_meta()", "docstring": "Extract high-level metadata from the HTML document.\n\nReturns:\n dict[str, Any]:\n Dictionary containing extracted metadata.\n\nNotes:\n **Responsibilities:**\n\n - Extract high-level metadata from the HTML document.\n - This includes: Document title, `` tag name/property to\n content mappings." } } @@ -1635,81 +1467,39 @@ "signature": null, "docstring": "# Summary\n\nHTML parser base implementations for OmniRead.\n\nThis module provides reusable HTML parsing utilities built on top of\nthe abstract parser contracts defined in `omniread.core.parser`.\n\nIt supplies:\n\n- Content-type enforcement for HTML inputs\n- BeautifulSoup initialization and lifecycle management\n- Common helper methods for extracting structured data from HTML elements\n\nConcrete parsers must subclass `HTMLParser` and implement the `parse()` method\nto return a structured representation appropriate for their use case.", "members": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.html.parser.abstractmethod", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.html.parser.Any", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.html.parser.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.html.parser.TypeVar", - "signature": "", - "docstring": null - }, - "BeautifulSoup": { - "name": "BeautifulSoup", - "kind": "alias", - "path": "omniread.html.parser.BeautifulSoup", - "signature": "", - "docstring": null - }, - "Tag": { - "name": "Tag", - "kind": "alias", - "path": "omniread.html.parser.Tag", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.html.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.html.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.html.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.html.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.html.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -1718,49 +1508,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.html.parser.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.html.parser.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.html.parser.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.html.parser.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.html.parser.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.html.parser.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.html.parser.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -1769,35 +1559,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.html.parser.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.html.parser.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.html.parser.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.html.parser.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.html.parser.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -1813,7 +1603,7 @@ "name": "HTMLParser", "kind": "class", "path": "omniread.html.parser.HTMLParser", - "signature": "", + "signature": "HTMLParser(content: Content, features: str = 'html.parser')", "docstring": "Base HTML parser.\n\nNotes:\n **Responsibilities:**\n\n - This class extends the core `BaseParser` with HTML-specific behavior,\n including DOM parsing via BeautifulSoup and reusable extraction helpers.\n - Provides reusable helpers for HTML extraction. Concrete parsers must\n explicitly define the return type.\n\n **Guarantees:**\n\n - Accepts only HTML content.\n - Owns a parsed BeautifulSoup DOM tree.\n - Provides pure helper utilities for common HTML structures.\n\n **Constraints:**\n\n - Concrete subclasses must define the output type `T` and implement\n the `parse()` method.", "members": { "supported_types": { @@ -1827,35 +1617,35 @@ "name": "parse", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Fully parse the HTML content into structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the HTML DOM and return a\n deterministic, structured output." }, "parse_div": { "name": "parse_div", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_div", - "signature": "", + "signature": "parse_div(div: Tag, *, separator: str = ' ') -> str", "docstring": "Extract normalized text from a `
` element.\n\nArgs:\n div (Tag):\n BeautifulSoup tag representing a `
`.\n separator (str, optional):\n String used to separate text nodes.\n\nReturns:\n str:\n Flattened, whitespace-normalized text content." }, "parse_link": { "name": "parse_link", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_link", - "signature": "", + "signature": "parse_link(a: Tag) -> str | None", "docstring": "Extract the hyperlink reference from an `` element.\n\nArgs:\n a (Tag):\n BeautifulSoup tag representing an anchor.\n\nReturns:\n str | None:\n The value of the `href` attribute, or None if absent." }, "parse_table": { "name": "parse_table", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_table", - "signature": "", + "signature": "parse_table(table: Tag) -> list[list[str]]", "docstring": "Parse an HTML table into a 2D list of strings.\n\nArgs:\n table (Tag):\n BeautifulSoup tag representing a `
`.\n\nReturns:\n list[list[str]]:\n A list of rows, where each row is a list of cell text values." }, "parse_meta": { "name": "parse_meta", "kind": "function", "path": "omniread.html.parser.HTMLParser.parse_meta", - "signature": "", + "signature": "parse_meta() -> dict[str, Any]", "docstring": "Extract high-level metadata from the HTML document.\n\nReturns:\n dict[str, Any]:\n Dictionary containing extracted metadata.\n\nNotes:\n **Responsibilities:**\n\n - Extract high-level metadata from the HTML document.\n - This includes: Document title, `` tag name/property to\n content mappings." } } @@ -1869,60 +1659,39 @@ "signature": null, "docstring": "# Summary\n\nHTML scraping implementation for OmniRead.\n\nThis module provides an HTTP-based scraper for retrieving HTML documents.\nIt implements the core `BaseScraper` contract using `httpx` as the transport\nlayer.\n\nThis scraper is responsible for:\n\n- Fetching raw HTML bytes over HTTP(S)\n- Validating response content type\n- Attaching HTTP metadata to the returned content\n\nThis scraper is not responsible for:\n\n- Parsing or interpreting HTML\n- Retrying failed requests\n- Managing crawl policies or rate limiting", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.html.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.html.scraper.Any", - "signature": "", - "docstring": null - }, - "httpx": { - "name": "httpx", - "kind": "alias", - "path": "omniread.html.scraper.httpx", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.html.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.html.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.html.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.html.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.html.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -1931,49 +1700,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.html.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.html.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.html.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.html.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.html.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.html.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.html.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -1982,14 +1751,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.html.scraper.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.html.scraper.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } @@ -1998,7 +1767,7 @@ "name": "HTMLScraper", "kind": "class", "path": "omniread.html.scraper.HTMLScraper", - "signature": "", + "signature": "HTMLScraper(*, client: httpx.Client | None = None, timeout: float = 15.0, headers: Mapping[str, str] | None = None, follow_redirects: bool = True)", "docstring": "Base HTML scraper using `httpx`.\n\nNotes:\n **Responsibilities:**\n\n - This scraper retrieves HTML documents over HTTP(S) and returns\n them as raw content wrapped in a `Content` object.\n - Fetches raw bytes and metadata only.\n - The scraper uses `httpx.Client` for HTTP requests, enforces an\n HTML content type, and preserves HTTP response metadata.\n\n **Constraints:**\n\n - The scraper does not: Parse HTML, perform retries or backoff,\n handle non-HTML responses.", "members": { "content_type": { @@ -2012,14 +1781,14 @@ "name": "validate_content_type", "kind": "function", "path": "omniread.html.scraper.HTMLScraper.validate_content_type", - "signature": "", + "signature": "validate_content_type(response: httpx.Response) -> None", "docstring": "Validate that the HTTP response contains HTML content.\n\nArgs:\n response (httpx.Response):\n HTTP response returned by `httpx`.\n\nRaises:\n ValueError:\n If the `Content-Type` header is missing or does not indicate HTML content." }, "fetch": { "name": "fetch", "kind": "function", "path": "omniread.html.scraper.HTMLScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch an HTML document from the given source.\n\nArgs:\n source (str):\n URL of the HTML document.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to be merged into the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw HTML bytes, source URL, HTML content type, and HTTP response metadata.\n\nRaises:\n httpx.HTTPError:\n If the HTTP request fails.\n ValueError:\n If the response is not valid HTML." } } @@ -2039,14 +1808,14 @@ "name": "FileSystemPDFClient", "kind": "class", "path": "omniread.pdf.FileSystemPDFClient", - "signature": "", + "signature": null, "docstring": "PDF client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads PDF files directly from the disk and returns\n their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.FileSystemPDFClient.fetch", - "signature": "", + "signature": "fetch(path: Path)", "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the PDF file.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -2055,14 +1824,14 @@ "name": "PDFScraper", "kind": "class", "path": "omniread.pdf.PDFScraper", - "signature": "", + "signature": "PDFScraper(*, client: BasePDFClient)", "docstring": "Scraper for PDF sources.\n\nNotes:\n **Responsibilities:**\n\n - Delegates byte retrieval to a PDF client and normalizes output\n into `Content`.\n - Preserves caller-provided metadata.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.PDFScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF source as understood by the configured PDF client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the PDF client." } } @@ -2071,21 +1840,21 @@ "name": "PDFParser", "kind": "class", "path": "omniread.pdf.PDFParser", - "signature": "", + "signature": null, "docstring": "Base PDF parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces PDF content-type compatibility and provides\n the extension point for implementing concrete PDF parsing strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.pdf.PDFParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (PDF only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.pdf.PDFParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse PDF content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the PDF binary payload and\n return a deterministic, structured output." } } @@ -2097,46 +1866,18 @@ "signature": null, "docstring": "# Summary\n\nPDF client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw PDF\nbytes from a concrete backing store.\n\nClients provide low-level access to PDF binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.pdf.client.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.pdf.client.abstractmethod", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "omniread.pdf.client.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.pdf.client.Any", - "signature": "", - "docstring": null - }, "BasePDFClient": { "name": "BasePDFClient", "kind": "class", "path": "omniread.pdf.client.BasePDFClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving PDF bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full PDF binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.client.BasePDFClient.fetch", - "signature": "", + "signature": "fetch(source: Any) -> bytes", "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -2145,14 +1886,14 @@ "name": "FileSystemPDFClient", "kind": "class", "path": "omniread.pdf.client.FileSystemPDFClient", - "signature": "", + "signature": null, "docstring": "PDF client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads PDF files directly from the disk and returns\n their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.client.FileSystemPDFClient.fetch", - "signature": "", + "signature": "fetch(path: Path) -> bytes", "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the PDF file.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -2166,74 +1907,53 @@ "signature": null, "docstring": "# Summary\n\nPDF parser base implementations for OmniRead.\n\nThis module defines the **PDF-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for PDF content.\n\nPDF parsers are responsible for interpreting binary PDF data and producing\nstructured representations suitable for downstream consumption.", "members": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.pdf.parser.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.pdf.parser.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.pdf.parser.TypeVar", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.pdf.parser.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -2242,35 +1962,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.pdf.parser.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.pdf.parser.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.pdf.parser.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.pdf.parser.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.pdf.parser.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -2286,7 +2006,7 @@ "name": "PDFParser", "kind": "class", "path": "omniread.pdf.parser.PDFParser", - "signature": "", + "signature": null, "docstring": "Base PDF parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces PDF content-type compatibility and provides\n the extension point for implementing concrete PDF parsing strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { @@ -2300,7 +2020,7 @@ "name": "parse", "kind": "function", "path": "omniread.pdf.parser.PDFParser.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse PDF content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the PDF binary payload and\n return a deterministic, structured output." } } @@ -2314,53 +2034,39 @@ "signature": null, "docstring": "# Summary\n\nPDF scraping implementation for OmniRead.\n\nThis module provides a PDF-specific scraper that coordinates PDF byte\nretrieval via a client and normalizes the result into a `Content` object.\n\nThe scraper implements the core `BaseScraper` contract while delegating\nall storage and access concerns to a `BasePDFClient` implementation.", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.pdf.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.pdf.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.pdf.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.pdf.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.pdf.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.pdf.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.pdf.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -2369,49 +2075,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.pdf.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -2420,14 +2126,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.pdf.scraper.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.scraper.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } @@ -2436,14 +2142,14 @@ "name": "BasePDFClient", "kind": "class", "path": "omniread.pdf.scraper.BasePDFClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving PDF bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full PDF binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.scraper.BasePDFClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -2452,14 +2158,14 @@ "name": "PDFScraper", "kind": "class", "path": "omniread.pdf.scraper.PDFScraper", - "signature": "", + "signature": "PDFScraper(*, client: BasePDFClient)", "docstring": "Scraper for PDF sources.\n\nNotes:\n **Responsibilities:**\n\n - Delegates byte retrieval to a PDF client and normalizes output\n into `Content`.\n - Preserves caller-provided metadata.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.scraper.PDFScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF source as understood by the configured PDF client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the PDF client." } } @@ -2479,14 +2185,14 @@ "name": "BaseXlsxClient", "kind": "class", "path": "omniread.xlsx.BaseXlsxClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving spreadsheet bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full xlsx binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.BaseXlsxClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw xlsx bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -2495,14 +2201,14 @@ "name": "FileSystemXlsxClient", "kind": "class", "path": "omniread.xlsx.FileSystemXlsxClient", - "signature": "", + "signature": null, "docstring": "XLSX client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads spreadsheet files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.FileSystemXlsxClient.fetch", - "signature": "", + "signature": "fetch(path: Path)", "docstring": "Read an xlsx file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the spreadsheet file.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -2511,35 +2217,35 @@ "name": "XlsxParser", "kind": "class", "path": "omniread.xlsx.XlsxParser", - "signature": "", + "signature": "XlsxParser(content: Content, *, data_only: bool = True, read_only: bool = True)", "docstring": "Generic xlsx parser producing string rows from a worksheet.\n\nNotes:\n **Responsibilities:**\n\n - Lazily load the workbook owned by the parser's content.\n - Normalize cells (including dates and numeric values) into\n deterministic string representations.\n - Expose sheet discovery and row extraction helpers.\n\n **Constraints:**\n\n - Cells are rendered with ``str(value)`` after trimming; date and\n datetime values are rendered in ISO format. Consumers requiring\n locale-specific formatting must convert on their side.", "members": { "workbook": { "name": "workbook", "kind": "attribute", "path": "omniread.xlsx.XlsxParser.workbook", - "signature": "", + "signature": null, "docstring": "The lazily loaded workbook backing this parser's content." }, "sheet_names": { "name": "sheet_names", "kind": "attribute", "path": "omniread.xlsx.XlsxParser.sheet_names", - "signature": "", + "signature": null, "docstring": "Names of all worksheets contained in the workbook." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.XlsxParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the first worksheet into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the default (first) worksheet." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.xlsx.XlsxParser.rows", - "signature": "", + "signature": "rows(sheet: int | str | None = None, *, skip_empty: bool = True)", "docstring": "Extract normalized string rows from a worksheet.\n\nArgs:\n sheet (int | str | None):\n Worksheet index or title; defaults to the first worksheet.\n skip_empty (bool):\n When True (default), rows whose cells are all blank are omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row.\n\nRaises:\n ValueError:\n If the requested sheet does not exist." } } @@ -2548,21 +2254,21 @@ "name": "XlsxParserBase", "kind": "class", "path": "omniread.xlsx.XlsxParserBase", - "signature": "", + "signature": null, "docstring": "Base xlsx parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces xlsx content-type compatibility and provides\n the extension point for implementing concrete xlsx parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.xlsx.XlsxParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (XLSX only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.XlsxParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse xlsx content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -2571,14 +2277,14 @@ "name": "XlsxScraper", "kind": "class", "path": "omniread.xlsx.XlsxScraper", - "signature": "", + "signature": "XlsxScraper(*, client: BaseXlsxClient)", "docstring": "Scraper for xlsx spreadsheet documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw xlsx bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n XLSX content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.XlsxScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch an xlsx document from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw xlsx bytes, source\n identifier, XLSX content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } @@ -2590,46 +2296,18 @@ "signature": null, "docstring": "# Summary\n\nXLSX client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw\nOffice Open XML spreadsheet bytes from a concrete backing store.\n\nClients provide low-level access to xlsx binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.xlsx.client.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.xlsx.client.abstractmethod", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "omniread.xlsx.client.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.xlsx.client.Any", - "signature": "", - "docstring": null - }, "BaseXlsxClient": { "name": "BaseXlsxClient", "kind": "class", "path": "omniread.xlsx.client.BaseXlsxClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving spreadsheet bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full xlsx binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.client.BaseXlsxClient.fetch", - "signature": "", + "signature": "fetch(source: Any) -> bytes", "docstring": "Fetch raw xlsx bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -2638,14 +2316,14 @@ "name": "FileSystemXlsxClient", "kind": "class", "path": "omniread.xlsx.client.FileSystemXlsxClient", - "signature": "", + "signature": null, "docstring": "XLSX client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads spreadsheet files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.client.FileSystemXlsxClient.fetch", - "signature": "", + "signature": "fetch(path: Path) -> bytes", "docstring": "Read an xlsx file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the spreadsheet file.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -2659,67 +2337,39 @@ "signature": null, "docstring": "# Summary\n\nXLSX parser implementations for OmniRead.\n\nThis module provides a concrete, generic parser for Office Open XML\nspreadsheets. It exposes workbook sheets as lists of string rows so\ndownstream consumers can interpret tabular content without depending on\nopenpyxl directly.\n\nThe parser is intentionally statement-agnostic: it performs no header\ndetection or column interpretation beyond basic cell normalization.", "members": { - "datetime": { - "name": "datetime", - "kind": "alias", - "path": "omniread.xlsx.parser.datetime", - "signature": "", - "docstring": null - }, - "BytesIO": { - "name": "BytesIO", - "kind": "alias", - "path": "omniread.xlsx.parser.BytesIO", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.xlsx.parser.Any", - "signature": "", - "docstring": null - }, - "openpyxl": { - "name": "openpyxl", - "kind": "alias", - "path": "omniread.xlsx.parser.openpyxl", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.xlsx.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.xlsx.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.xlsx.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.xlsx.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.xlsx.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -2728,21 +2378,21 @@ "name": "XlsxParserBase", "kind": "class", "path": "omniread.xlsx.parser.XlsxParserBase", - "signature": "", + "signature": null, "docstring": "Base xlsx parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces xlsx content-type compatibility and provides\n the extension point for implementing concrete xlsx parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.xlsx.parser.XlsxParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (XLSX only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.parser.XlsxParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse xlsx content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -2751,7 +2401,7 @@ "name": "XlsxParser", "kind": "class", "path": "omniread.xlsx.parser.XlsxParser", - "signature": "", + "signature": "XlsxParser(content: Content, *, data_only: bool = True, read_only: bool = True)", "docstring": "Generic xlsx parser producing string rows from a worksheet.\n\nNotes:\n **Responsibilities:**\n\n - Lazily load the workbook owned by the parser's content.\n - Normalize cells (including dates and numeric values) into\n deterministic string representations.\n - Expose sheet discovery and row extraction helpers.\n\n **Constraints:**\n\n - Cells are rendered with ``str(value)`` after trimming; date and\n datetime values are rendered in ISO format. Consumers requiring\n locale-specific formatting must convert on their side.", "members": { "workbook": { @@ -2772,14 +2422,14 @@ "name": "parse", "kind": "function", "path": "omniread.xlsx.parser.XlsxParser.parse", - "signature": "", + "signature": "parse() -> list[list[str]]", "docstring": "Parse the first worksheet into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the default (first) worksheet." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.xlsx.parser.XlsxParser.rows", - "signature": "", + "signature": "rows(sheet: int | str | None = None, *, skip_empty: bool = True) -> list[list[str]]", "docstring": "Extract normalized string rows from a worksheet.\n\nArgs:\n sheet (int | str | None):\n Worksheet index or title; defaults to the first worksheet.\n skip_empty (bool):\n When True (default), rows whose cells are all blank are omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row.\n\nRaises:\n ValueError:\n If the requested sheet does not exist." } } @@ -2793,74 +2443,53 @@ "signature": null, "docstring": "# Summary\n\nXLSX parser base implementation for OmniRead.\n\nThis module defines the **XLSX-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for Office Open\nXML spreadsheet content.", "members": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.xlsx.parser_base.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.xlsx.parser_base.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.xlsx.parser_base.TypeVar", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.xlsx.parser_base.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -2869,35 +2498,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.xlsx.parser_base.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.xlsx.parser_base.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.xlsx.parser_base.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.parser_base.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.xlsx.parser_base.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -2913,7 +2542,7 @@ "name": "XlsxParserBase", "kind": "class", "path": "omniread.xlsx.parser_base.XlsxParserBase", - "signature": "", + "signature": null, "docstring": "Base xlsx parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces xlsx content-type compatibility and provides\n the extension point for implementing concrete xlsx parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { @@ -2927,7 +2556,7 @@ "name": "parse", "kind": "function", "path": "omniread.xlsx.parser_base.XlsxParserBase.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse xlsx content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -2941,53 +2570,39 @@ "signature": null, "docstring": "# Summary\n\nXLSX scraper for OmniRead.\n\nThis module defines the scraper responsible for acquiring raw Office Open\nXML spreadsheet content from a backing store via a configured client.\n\nThe scraper does not interpret or parse the acquired bytes; it wraps them in\nthe canonical `Content` model.", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.xlsx.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.xlsx.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.xlsx.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -2996,49 +2611,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.xlsx.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -3047,14 +2662,14 @@ "name": "BaseXlsxClient", "kind": "class", "path": "omniread.xlsx.scraper.BaseXlsxClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving spreadsheet bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full xlsx binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.scraper.BaseXlsxClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw xlsx bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -3063,14 +2678,14 @@ "name": "XlsxScraper", "kind": "class", "path": "omniread.xlsx.scraper.XlsxScraper", - "signature": "", + "signature": "XlsxScraper(*, client: BaseXlsxClient)", "docstring": "Scraper for xlsx spreadsheet documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw xlsx bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n XLSX content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.scraper.XlsxScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch an xlsx document from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw xlsx bytes, source\n identifier, XLSX content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } diff --git a/docs/mcp/modules/omniread.pdf.client.json b/docs/mcp/modules/omniread.pdf.client.json index ea9dcfe..b73e277 100644 --- a/docs/mcp/modules/omniread.pdf.client.json +++ b/docs/mcp/modules/omniread.pdf.client.json @@ -4,46 +4,18 @@ "path": "omniread.pdf.client", "docstring": "# Summary\n\nPDF client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw PDF\nbytes from a concrete backing store.\n\nClients provide low-level access to PDF binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems", "objects": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.pdf.client.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.pdf.client.abstractmethod", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "omniread.pdf.client.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.pdf.client.Any", - "signature": "", - "docstring": null - }, "BasePDFClient": { "name": "BasePDFClient", "kind": "class", "path": "omniread.pdf.client.BasePDFClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving PDF bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full PDF binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.client.BasePDFClient.fetch", - "signature": "", + "signature": "fetch(source: Any) -> bytes", "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -52,14 +24,14 @@ "name": "FileSystemPDFClient", "kind": "class", "path": "omniread.pdf.client.FileSystemPDFClient", - "signature": "", + "signature": null, "docstring": "PDF client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads PDF files directly from the disk and returns\n their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.client.FileSystemPDFClient.fetch", - "signature": "", + "signature": "fetch(path: Path) -> bytes", "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the PDF file.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } diff --git a/docs/mcp/modules/omniread.pdf.json b/docs/mcp/modules/omniread.pdf.json index 28d9555..1695b44 100644 --- a/docs/mcp/modules/omniread.pdf.json +++ b/docs/mcp/modules/omniread.pdf.json @@ -8,14 +8,14 @@ "name": "FileSystemPDFClient", "kind": "class", "path": "omniread.pdf.FileSystemPDFClient", - "signature": "", + "signature": null, "docstring": "PDF client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads PDF files directly from the disk and returns\n their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.FileSystemPDFClient.fetch", - "signature": "", + "signature": "fetch(path: Path)", "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the PDF file.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -24,14 +24,14 @@ "name": "PDFScraper", "kind": "class", "path": "omniread.pdf.PDFScraper", - "signature": "", + "signature": "PDFScraper(*, client: BasePDFClient)", "docstring": "Scraper for PDF sources.\n\nNotes:\n **Responsibilities:**\n\n - Delegates byte retrieval to a PDF client and normalizes output\n into `Content`.\n - Preserves caller-provided metadata.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.PDFScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF source as understood by the configured PDF client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the PDF client." } } @@ -40,21 +40,21 @@ "name": "PDFParser", "kind": "class", "path": "omniread.pdf.PDFParser", - "signature": "", + "signature": null, "docstring": "Base PDF parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces PDF content-type compatibility and provides\n the extension point for implementing concrete PDF parsing strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.pdf.PDFParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (PDF only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.pdf.PDFParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse PDF content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the PDF binary payload and\n return a deterministic, structured output." } } @@ -66,46 +66,18 @@ "signature": null, "docstring": "# Summary\n\nPDF client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw PDF\nbytes from a concrete backing store.\n\nClients provide low-level access to PDF binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.pdf.client.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.pdf.client.abstractmethod", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "omniread.pdf.client.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.pdf.client.Any", - "signature": "", - "docstring": null - }, "BasePDFClient": { "name": "BasePDFClient", "kind": "class", "path": "omniread.pdf.client.BasePDFClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving PDF bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full PDF binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.client.BasePDFClient.fetch", - "signature": "", + "signature": "fetch(source: Any) -> bytes", "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -114,14 +86,14 @@ "name": "FileSystemPDFClient", "kind": "class", "path": "omniread.pdf.client.FileSystemPDFClient", - "signature": "", + "signature": null, "docstring": "PDF client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads PDF files directly from the disk and returns\n their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.client.FileSystemPDFClient.fetch", - "signature": "", + "signature": "fetch(path: Path) -> bytes", "docstring": "Read a PDF file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the PDF file.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -135,74 +107,53 @@ "signature": null, "docstring": "# Summary\n\nPDF parser base implementations for OmniRead.\n\nThis module defines the **PDF-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for PDF content.\n\nPDF parsers are responsible for interpreting binary PDF data and producing\nstructured representations suitable for downstream consumption.", "members": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.pdf.parser.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.pdf.parser.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.pdf.parser.TypeVar", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.pdf.parser.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -211,35 +162,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.pdf.parser.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.pdf.parser.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.pdf.parser.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.pdf.parser.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.pdf.parser.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -255,7 +206,7 @@ "name": "PDFParser", "kind": "class", "path": "omniread.pdf.parser.PDFParser", - "signature": "", + "signature": null, "docstring": "Base PDF parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces PDF content-type compatibility and provides\n the extension point for implementing concrete PDF parsing strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { @@ -269,7 +220,7 @@ "name": "parse", "kind": "function", "path": "omniread.pdf.parser.PDFParser.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse PDF content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the PDF binary payload and\n return a deterministic, structured output." } } @@ -283,53 +234,39 @@ "signature": null, "docstring": "# Summary\n\nPDF scraping implementation for OmniRead.\n\nThis module provides a PDF-specific scraper that coordinates PDF byte\nretrieval via a client and normalizes the result into a `Content` object.\n\nThe scraper implements the core `BaseScraper` contract while delegating\nall storage and access concerns to a `BasePDFClient` implementation.", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.pdf.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.pdf.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.pdf.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.pdf.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.pdf.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.pdf.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.pdf.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -338,49 +275,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.pdf.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -389,14 +326,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.pdf.scraper.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.scraper.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } @@ -405,14 +342,14 @@ "name": "BasePDFClient", "kind": "class", "path": "omniread.pdf.scraper.BasePDFClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving PDF bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full PDF binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.scraper.BasePDFClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -421,14 +358,14 @@ "name": "PDFScraper", "kind": "class", "path": "omniread.pdf.scraper.PDFScraper", - "signature": "", + "signature": "PDFScraper(*, client: BasePDFClient)", "docstring": "Scraper for PDF sources.\n\nNotes:\n **Responsibilities:**\n\n - Delegates byte retrieval to a PDF client and normalizes output\n into `Content`.\n - Preserves caller-provided metadata.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.scraper.PDFScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF source as understood by the configured PDF client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the PDF client." } } diff --git a/docs/mcp/modules/omniread.pdf.parser.json b/docs/mcp/modules/omniread.pdf.parser.json index 8fe1584..e330994 100644 --- a/docs/mcp/modules/omniread.pdf.parser.json +++ b/docs/mcp/modules/omniread.pdf.parser.json @@ -4,74 +4,53 @@ "path": "omniread.pdf.parser", "docstring": "# Summary\n\nPDF parser base implementations for OmniRead.\n\nThis module defines the **PDF-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for PDF content.\n\nPDF parsers are responsible for interpreting binary PDF data and producing\nstructured representations suitable for downstream consumption.", "objects": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.pdf.parser.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.pdf.parser.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.pdf.parser.TypeVar", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.pdf.parser.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.pdf.parser.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -80,35 +59,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.pdf.parser.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.pdf.parser.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.pdf.parser.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.pdf.parser.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.pdf.parser.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -124,7 +103,7 @@ "name": "PDFParser", "kind": "class", "path": "omniread.pdf.parser.PDFParser", - "signature": "", + "signature": null, "docstring": "Base PDF parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces PDF content-type compatibility and provides\n the extension point for implementing concrete PDF parsing strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { @@ -138,7 +117,7 @@ "name": "parse", "kind": "function", "path": "omniread.pdf.parser.PDFParser.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse PDF content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully interpret the PDF binary payload and\n return a deterministic, structured output." } } diff --git a/docs/mcp/modules/omniread.pdf.scraper.json b/docs/mcp/modules/omniread.pdf.scraper.json index 7f07064..ff03d34 100644 --- a/docs/mcp/modules/omniread.pdf.scraper.json +++ b/docs/mcp/modules/omniread.pdf.scraper.json @@ -4,53 +4,39 @@ "path": "omniread.pdf.scraper", "docstring": "# Summary\n\nPDF scraping implementation for OmniRead.\n\nThis module provides a PDF-specific scraper that coordinates PDF byte\nretrieval via a client and normalizes the result into a `Content` object.\n\nThe scraper implements the core `BaseScraper` contract while delegating\nall storage and access concerns to a `BasePDFClient` implementation.", "objects": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.pdf.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.pdf.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.pdf.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.pdf.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.pdf.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.pdf.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.pdf.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -59,49 +45,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.pdf.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.pdf.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -110,14 +96,14 @@ "name": "BaseScraper", "kind": "class", "path": "omniread.pdf.scraper.BaseScraper", - "signature": "", + "signature": null, "docstring": "Base interface for all scrapers.\n\nNotes:\n **Responsibilities:**\n\n - A scraper is responsible ONLY for fetching raw content (bytes)\n from a source. It must not interpret or parse it.\n - A scraper is a stateless acquisition component that retrieves raw\n content from a source and returns it as a `Content` object.\n - Scrapers define how content is obtained, not what the content means.\n - Implementations may vary in transport mechanism, authentication\n strategy, retry and backoff behavior.\n\n **Constraints:**\n\n - Implementations must not parse content, modify content semantics,\n or couple scraping logic to a specific parser.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.scraper.BaseScraper.fetch", - "signature": "", + "signature": "fetch(source: str, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch raw content from the given source.\n\nArgs:\n source (str):\n Location identifier (URL, file path, S3 URI, etc.).\n\n metadata (Mapping[str, Any] | None, optional):\n Optional hints for the scraper (headers, auth, etc.).\n\nReturns:\n Content:\n Content object containing raw bytes and metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must retrieve the content referenced by `source`\n and return it as raw bytes wrapped in a `Content` object." } } @@ -126,14 +112,14 @@ "name": "BasePDFClient", "kind": "class", "path": "omniread.pdf.scraper.BasePDFClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving PDF bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full PDF binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.scraper.BasePDFClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw PDF bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF location, such as a file path, object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw PDF bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -142,14 +128,14 @@ "name": "PDFScraper", "kind": "class", "path": "omniread.pdf.scraper.PDFScraper", - "signature": "", + "signature": "PDFScraper(*, client: BasePDFClient)", "docstring": "Scraper for PDF sources.\n\nNotes:\n **Responsibilities:**\n\n - Delegates byte retrieval to a PDF client and normalizes output\n into `Content`.\n - Preserves caller-provided metadata.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.pdf.scraper.PDFScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch a PDF document from the given source.\n\nArgs:\n source (Any):\n Identifier of the PDF source as understood by the configured PDF client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw PDF bytes, source identifier, PDF content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the PDF client." } } diff --git a/docs/mcp/modules/omniread.xlsx.client.json b/docs/mcp/modules/omniread.xlsx.client.json index de78b9a..0234f37 100644 --- a/docs/mcp/modules/omniread.xlsx.client.json +++ b/docs/mcp/modules/omniread.xlsx.client.json @@ -4,46 +4,18 @@ "path": "omniread.xlsx.client", "docstring": "# Summary\n\nXLSX client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw\nOffice Open XML spreadsheet bytes from a concrete backing store.\n\nClients provide low-level access to xlsx binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems", "objects": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.xlsx.client.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.xlsx.client.abstractmethod", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "omniread.xlsx.client.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.xlsx.client.Any", - "signature": "", - "docstring": null - }, "BaseXlsxClient": { "name": "BaseXlsxClient", "kind": "class", "path": "omniread.xlsx.client.BaseXlsxClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving spreadsheet bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full xlsx binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.client.BaseXlsxClient.fetch", - "signature": "", + "signature": "fetch(source: Any) -> bytes", "docstring": "Fetch raw xlsx bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -52,14 +24,14 @@ "name": "FileSystemXlsxClient", "kind": "class", "path": "omniread.xlsx.client.FileSystemXlsxClient", - "signature": "", + "signature": null, "docstring": "XLSX client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads spreadsheet files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.client.FileSystemXlsxClient.fetch", - "signature": "", + "signature": "fetch(path: Path) -> bytes", "docstring": "Read an xlsx file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the spreadsheet file.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } diff --git a/docs/mcp/modules/omniread.xlsx.json b/docs/mcp/modules/omniread.xlsx.json index f939e62..ef391a2 100644 --- a/docs/mcp/modules/omniread.xlsx.json +++ b/docs/mcp/modules/omniread.xlsx.json @@ -8,14 +8,14 @@ "name": "BaseXlsxClient", "kind": "class", "path": "omniread.xlsx.BaseXlsxClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving spreadsheet bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full xlsx binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.BaseXlsxClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw xlsx bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -24,14 +24,14 @@ "name": "FileSystemXlsxClient", "kind": "class", "path": "omniread.xlsx.FileSystemXlsxClient", - "signature": "", + "signature": null, "docstring": "XLSX client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads spreadsheet files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.FileSystemXlsxClient.fetch", - "signature": "", + "signature": "fetch(path: Path)", "docstring": "Read an xlsx file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the spreadsheet file.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -40,35 +40,35 @@ "name": "XlsxParser", "kind": "class", "path": "omniread.xlsx.XlsxParser", - "signature": "", + "signature": "XlsxParser(content: Content, *, data_only: bool = True, read_only: bool = True)", "docstring": "Generic xlsx parser producing string rows from a worksheet.\n\nNotes:\n **Responsibilities:**\n\n - Lazily load the workbook owned by the parser's content.\n - Normalize cells (including dates and numeric values) into\n deterministic string representations.\n - Expose sheet discovery and row extraction helpers.\n\n **Constraints:**\n\n - Cells are rendered with ``str(value)`` after trimming; date and\n datetime values are rendered in ISO format. Consumers requiring\n locale-specific formatting must convert on their side.", "members": { "workbook": { "name": "workbook", "kind": "attribute", "path": "omniread.xlsx.XlsxParser.workbook", - "signature": "", + "signature": null, "docstring": "The lazily loaded workbook backing this parser's content." }, "sheet_names": { "name": "sheet_names", "kind": "attribute", "path": "omniread.xlsx.XlsxParser.sheet_names", - "signature": "", + "signature": null, "docstring": "Names of all worksheets contained in the workbook." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.XlsxParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the first worksheet into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the default (first) worksheet." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.xlsx.XlsxParser.rows", - "signature": "", + "signature": "rows(sheet: int | str | None = None, *, skip_empty: bool = True)", "docstring": "Extract normalized string rows from a worksheet.\n\nArgs:\n sheet (int | str | None):\n Worksheet index or title; defaults to the first worksheet.\n skip_empty (bool):\n When True (default), rows whose cells are all blank are omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row.\n\nRaises:\n ValueError:\n If the requested sheet does not exist." } } @@ -77,21 +77,21 @@ "name": "XlsxParserBase", "kind": "class", "path": "omniread.xlsx.XlsxParserBase", - "signature": "", + "signature": null, "docstring": "Base xlsx parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces xlsx content-type compatibility and provides\n the extension point for implementing concrete xlsx parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.xlsx.XlsxParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (XLSX only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.XlsxParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse xlsx content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -100,14 +100,14 @@ "name": "XlsxScraper", "kind": "class", "path": "omniread.xlsx.XlsxScraper", - "signature": "", + "signature": "XlsxScraper(*, client: BaseXlsxClient)", "docstring": "Scraper for xlsx spreadsheet documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw xlsx bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n XLSX content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.XlsxScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None)", "docstring": "Fetch an xlsx document from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw xlsx bytes, source\n identifier, XLSX content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } @@ -119,46 +119,18 @@ "signature": null, "docstring": "# Summary\n\nXLSX client abstractions for OmniRead.\n\nThis module defines the **client layer** responsible for retrieving raw\nOffice Open XML spreadsheet bytes from a concrete backing store.\n\nClients provide low-level access to xlsx binaries and are intentionally\ndecoupled from scraping and parsing logic. They do not perform validation,\ninterpretation, or content extraction.\n\nTypical backing stores include:\n\n- Local filesystems\n- Object storage (S3, GCS, etc.)\n- Network file systems", "members": { - "ABC": { - "name": "ABC", - "kind": "alias", - "path": "omniread.xlsx.client.ABC", - "signature": "", - "docstring": null - }, - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.xlsx.client.abstractmethod", - "signature": "", - "docstring": null - }, - "Path": { - "name": "Path", - "kind": "alias", - "path": "omniread.xlsx.client.Path", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.xlsx.client.Any", - "signature": "", - "docstring": null - }, "BaseXlsxClient": { "name": "BaseXlsxClient", "kind": "class", "path": "omniread.xlsx.client.BaseXlsxClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving spreadsheet bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full xlsx binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.client.BaseXlsxClient.fetch", - "signature": "", + "signature": "fetch(source: Any) -> bytes", "docstring": "Fetch raw xlsx bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -167,14 +139,14 @@ "name": "FileSystemXlsxClient", "kind": "class", "path": "omniread.xlsx.client.FileSystemXlsxClient", - "signature": "", + "signature": null, "docstring": "XLSX client that reads from the local filesystem.\n\nNotes:\n **Guarantees:**\n\n - This client reads spreadsheet files directly from the disk and\n returns their raw binary contents.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.client.FileSystemXlsxClient.fetch", - "signature": "", + "signature": "fetch(path: Path) -> bytes", "docstring": "Read an xlsx file from the local filesystem.\n\nArgs:\n path (Path):\n Filesystem path to the spreadsheet file.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n FileNotFoundError:\n If the path does not exist.\n ValueError:\n If the path exists but is not a file." } } @@ -188,67 +160,39 @@ "signature": null, "docstring": "# Summary\n\nXLSX parser implementations for OmniRead.\n\nThis module provides a concrete, generic parser for Office Open XML\nspreadsheets. It exposes workbook sheets as lists of string rows so\ndownstream consumers can interpret tabular content without depending on\nopenpyxl directly.\n\nThe parser is intentionally statement-agnostic: it performs no header\ndetection or column interpretation beyond basic cell normalization.", "members": { - "datetime": { - "name": "datetime", - "kind": "alias", - "path": "omniread.xlsx.parser.datetime", - "signature": "", - "docstring": null - }, - "BytesIO": { - "name": "BytesIO", - "kind": "alias", - "path": "omniread.xlsx.parser.BytesIO", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.xlsx.parser.Any", - "signature": "", - "docstring": null - }, - "openpyxl": { - "name": "openpyxl", - "kind": "alias", - "path": "omniread.xlsx.parser.openpyxl", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.xlsx.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.xlsx.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.xlsx.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.xlsx.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.xlsx.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -257,21 +201,21 @@ "name": "XlsxParserBase", "kind": "class", "path": "omniread.xlsx.parser.XlsxParserBase", - "signature": "", + "signature": null, "docstring": "Base xlsx parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces xlsx content-type compatibility and provides\n the extension point for implementing concrete xlsx parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.xlsx.parser.XlsxParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (XLSX only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.parser.XlsxParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse xlsx content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -280,7 +224,7 @@ "name": "XlsxParser", "kind": "class", "path": "omniread.xlsx.parser.XlsxParser", - "signature": "", + "signature": "XlsxParser(content: Content, *, data_only: bool = True, read_only: bool = True)", "docstring": "Generic xlsx parser producing string rows from a worksheet.\n\nNotes:\n **Responsibilities:**\n\n - Lazily load the workbook owned by the parser's content.\n - Normalize cells (including dates and numeric values) into\n deterministic string representations.\n - Expose sheet discovery and row extraction helpers.\n\n **Constraints:**\n\n - Cells are rendered with ``str(value)`` after trimming; date and\n datetime values are rendered in ISO format. Consumers requiring\n locale-specific formatting must convert on their side.", "members": { "workbook": { @@ -301,14 +245,14 @@ "name": "parse", "kind": "function", "path": "omniread.xlsx.parser.XlsxParser.parse", - "signature": "", + "signature": "parse() -> list[list[str]]", "docstring": "Parse the first worksheet into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the default (first) worksheet." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.xlsx.parser.XlsxParser.rows", - "signature": "", + "signature": "rows(sheet: int | str | None = None, *, skip_empty: bool = True) -> list[list[str]]", "docstring": "Extract normalized string rows from a worksheet.\n\nArgs:\n sheet (int | str | None):\n Worksheet index or title; defaults to the first worksheet.\n skip_empty (bool):\n When True (default), rows whose cells are all blank are omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row.\n\nRaises:\n ValueError:\n If the requested sheet does not exist." } } @@ -322,74 +266,53 @@ "signature": null, "docstring": "# Summary\n\nXLSX parser base implementation for OmniRead.\n\nThis module defines the **XLSX-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for Office Open\nXML spreadsheet content.", "members": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.xlsx.parser_base.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.xlsx.parser_base.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.xlsx.parser_base.TypeVar", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.xlsx.parser_base.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -398,35 +321,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.xlsx.parser_base.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.xlsx.parser_base.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.xlsx.parser_base.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.parser_base.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.xlsx.parser_base.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -442,7 +365,7 @@ "name": "XlsxParserBase", "kind": "class", "path": "omniread.xlsx.parser_base.XlsxParserBase", - "signature": "", + "signature": null, "docstring": "Base xlsx parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces xlsx content-type compatibility and provides\n the extension point for implementing concrete xlsx parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { @@ -456,7 +379,7 @@ "name": "parse", "kind": "function", "path": "omniread.xlsx.parser_base.XlsxParserBase.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse xlsx content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -470,53 +393,39 @@ "signature": null, "docstring": "# Summary\n\nXLSX scraper for OmniRead.\n\nThis module defines the scraper responsible for acquiring raw Office Open\nXML spreadsheet content from a backing store via a configured client.\n\nThe scraper does not interpret or parse the acquired bytes; it wraps them in\nthe canonical `Content` model.", "members": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.xlsx.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.xlsx.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.xlsx.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -525,49 +434,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.xlsx.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -576,14 +485,14 @@ "name": "BaseXlsxClient", "kind": "class", "path": "omniread.xlsx.scraper.BaseXlsxClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving spreadsheet bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full xlsx binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.scraper.BaseXlsxClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw xlsx bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -592,14 +501,14 @@ "name": "XlsxScraper", "kind": "class", "path": "omniread.xlsx.scraper.XlsxScraper", - "signature": "", + "signature": "XlsxScraper(*, client: BaseXlsxClient)", "docstring": "Scraper for xlsx spreadsheet documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw xlsx bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n XLSX content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.scraper.XlsxScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch an xlsx document from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw xlsx bytes, source\n identifier, XLSX content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } diff --git a/docs/mcp/modules/omniread.xlsx.parser.json b/docs/mcp/modules/omniread.xlsx.parser.json index 38c958a..3621e93 100644 --- a/docs/mcp/modules/omniread.xlsx.parser.json +++ b/docs/mcp/modules/omniread.xlsx.parser.json @@ -4,67 +4,39 @@ "path": "omniread.xlsx.parser", "docstring": "# Summary\n\nXLSX parser implementations for OmniRead.\n\nThis module provides a concrete, generic parser for Office Open XML\nspreadsheets. It exposes workbook sheets as lists of string rows so\ndownstream consumers can interpret tabular content without depending on\nopenpyxl directly.\n\nThe parser is intentionally statement-agnostic: it performs no header\ndetection or column interpretation beyond basic cell normalization.", "objects": { - "datetime": { - "name": "datetime", - "kind": "alias", - "path": "omniread.xlsx.parser.datetime", - "signature": "", - "docstring": null - }, - "BytesIO": { - "name": "BytesIO", - "kind": "alias", - "path": "omniread.xlsx.parser.BytesIO", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.xlsx.parser.Any", - "signature": "", - "docstring": null - }, - "openpyxl": { - "name": "openpyxl", - "kind": "alias", - "path": "omniread.xlsx.parser.openpyxl", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.xlsx.parser.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.xlsx.parser.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.xlsx.parser.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.xlsx.parser.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.xlsx.parser.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -73,21 +45,21 @@ "name": "XlsxParserBase", "kind": "class", "path": "omniread.xlsx.parser.XlsxParserBase", - "signature": "", + "signature": null, "docstring": "Base xlsx parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces xlsx content-type compatibility and provides\n the extension point for implementing concrete xlsx parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.xlsx.parser.XlsxParserBase.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser (XLSX only)." }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.parser.XlsxParserBase.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse xlsx content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } @@ -96,7 +68,7 @@ "name": "XlsxParser", "kind": "class", "path": "omniread.xlsx.parser.XlsxParser", - "signature": "", + "signature": "XlsxParser(content: Content, *, data_only: bool = True, read_only: bool = True)", "docstring": "Generic xlsx parser producing string rows from a worksheet.\n\nNotes:\n **Responsibilities:**\n\n - Lazily load the workbook owned by the parser's content.\n - Normalize cells (including dates and numeric values) into\n deterministic string representations.\n - Expose sheet discovery and row extraction helpers.\n\n **Constraints:**\n\n - Cells are rendered with ``str(value)`` after trimming; date and\n datetime values are rendered in ISO format. Consumers requiring\n locale-specific formatting must convert on their side.", "members": { "workbook": { @@ -117,14 +89,14 @@ "name": "parse", "kind": "function", "path": "omniread.xlsx.parser.XlsxParser.parse", - "signature": "", + "signature": "parse() -> list[list[str]]", "docstring": "Parse the first worksheet into normalized string rows.\n\nReturns:\n list[list[str]]:\n Rows of the default (first) worksheet." }, "rows": { "name": "rows", "kind": "function", "path": "omniread.xlsx.parser.XlsxParser.rows", - "signature": "", + "signature": "rows(sheet: int | str | None = None, *, skip_empty: bool = True) -> list[list[str]]", "docstring": "Extract normalized string rows from a worksheet.\n\nArgs:\n sheet (int | str | None):\n Worksheet index or title; defaults to the first worksheet.\n skip_empty (bool):\n When True (default), rows whose cells are all blank are omitted.\n\nReturns:\n list[list[str]]:\n Normalized rows; trailing blank cells are trimmed per row.\n\nRaises:\n ValueError:\n If the requested sheet does not exist." } } diff --git a/docs/mcp/modules/omniread.xlsx.parser_base.json b/docs/mcp/modules/omniread.xlsx.parser_base.json index 598340d..200e04a 100644 --- a/docs/mcp/modules/omniread.xlsx.parser_base.json +++ b/docs/mcp/modules/omniread.xlsx.parser_base.json @@ -4,74 +4,53 @@ "path": "omniread.xlsx.parser_base", "docstring": "# Summary\n\nXLSX parser base implementation for OmniRead.\n\nThis module defines the **XLSX-specific parser contract**, extending the\nformat-agnostic `BaseParser` with constraints appropriate for Office Open\nXML spreadsheet content.", "objects": { - "abstractmethod": { - "name": "abstractmethod", - "kind": "alias", - "path": "omniread.xlsx.parser_base.abstractmethod", - "signature": "", - "docstring": null - }, - "Generic": { - "name": "Generic", - "kind": "alias", - "path": "omniread.xlsx.parser_base.Generic", - "signature": "", - "docstring": null - }, - "TypeVar": { - "name": "TypeVar", - "kind": "alias", - "path": "omniread.xlsx.parser_base.TypeVar", - "signature": "", - "docstring": null - }, "ContentType": { "name": "ContentType", "kind": "class", "path": "omniread.xlsx.parser_base.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.xlsx.parser_base.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -80,35 +59,35 @@ "name": "BaseParser", "kind": "class", "path": "omniread.xlsx.parser_base.BaseParser", - "signature": "", + "signature": "BaseParser(content: Content)", "docstring": "Base interface for all parsers.\n\nNotes:\n **Guarantees:**\n\n - A parser is a self-contained object that owns the `Content` it is\n responsible for interpreting.\n - Consumers may rely on early validation of content compatibility\n and type-stable return values from `parse()`.\n\n **Responsibilities:**\n\n - Implementations must declare supported content types via `supported_types`.\n - Implementations must raise parsing-specific exceptions from `parse()`.\n - Implementations must remain deterministic for a given input.", "members": { "supported_types": { "name": "supported_types", "kind": "attribute", "path": "omniread.xlsx.parser_base.BaseParser.supported_types", - "signature": "", + "signature": null, "docstring": "Set of content types supported by this parser. An empty set indicates that the parser is content-type agnostic." }, "content": { "name": "content", "kind": "attribute", "path": "omniread.xlsx.parser_base.BaseParser.content", - "signature": "", + "signature": null, "docstring": null }, "parse": { "name": "parse", "kind": "function", "path": "omniread.xlsx.parser_base.BaseParser.parse", - "signature": "", + "signature": "parse()", "docstring": "Parse the owned content into structured output.\n\nReturns:\n T:\n Parsed, structured representation.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation.\n\nNotes:\n **Responsibilities:**\n\n - Implementations must fully consume the provided content and\n return a deterministic, structured output." }, "supports": { "name": "supports", "kind": "function", "path": "omniread.xlsx.parser_base.BaseParser.supports", - "signature": "", + "signature": "supports()", "docstring": "Check whether this parser supports the content's type.\n\nReturns:\n bool:\n True if the content type is supported; False otherwise." } } @@ -124,7 +103,7 @@ "name": "XlsxParserBase", "kind": "class", "path": "omniread.xlsx.parser_base.XlsxParserBase", - "signature": "", + "signature": null, "docstring": "Base xlsx parser.\n\nNotes:\n **Responsibilities:**\n\n - This class enforces xlsx content-type compatibility and provides\n the extension point for implementing concrete xlsx parsing\n strategies.\n\n **Constraints:**\n\n - Concrete implementations must define the output type `T` and\n implement the `parse()` method.", "members": { "supported_types": { @@ -138,7 +117,7 @@ "name": "parse", "kind": "function", "path": "omniread.xlsx.parser_base.XlsxParserBase.parse", - "signature": "", + "signature": "parse() -> T", "docstring": "Parse xlsx content into a structured output.\n\nReturns:\n T:\n Parsed representation of type `T`.\n\nRaises:\n Exception:\n Parsing-specific errors as defined by the implementation." } } diff --git a/docs/mcp/modules/omniread.xlsx.scraper.json b/docs/mcp/modules/omniread.xlsx.scraper.json index e87cd15..7e5cdac 100644 --- a/docs/mcp/modules/omniread.xlsx.scraper.json +++ b/docs/mcp/modules/omniread.xlsx.scraper.json @@ -4,53 +4,39 @@ "path": "omniread.xlsx.scraper", "docstring": "# Summary\n\nXLSX scraper for OmniRead.\n\nThis module defines the scraper responsible for acquiring raw Office Open\nXML spreadsheet content from a backing store via a configured client.\n\nThe scraper does not interpret or parse the acquired bytes; it wraps them in\nthe canonical `Content` model.", "objects": { - "Mapping": { - "name": "Mapping", - "kind": "alias", - "path": "omniread.xlsx.scraper.Mapping", - "signature": "", - "docstring": null - }, - "Any": { - "name": "Any", - "kind": "alias", - "path": "omniread.xlsx.scraper.Any", - "signature": "", - "docstring": null - }, "Content": { "name": "Content", "kind": "class", "path": "omniread.xlsx.scraper.Content", - "signature": "", + "signature": "Content(raw: bytes, source: str, content_type: ContentType | None = ..., metadata: Mapping[str, Any] | None = ...)", "docstring": "Normalized representation of extracted content.\n\nNotes:\n **Responsibilities:**\n\n - A `Content` instance represents a raw content payload along with\n minimal contextual metadata describing its origin and type.\n - This class is the primary exchange format between scrapers,\n parsers, and downstream consumers.", "members": { "raw": { "name": "raw", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.raw", - "signature": "", + "signature": null, "docstring": "Raw content bytes as retrieved from the source." }, "source": { "name": "source", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.source", - "signature": "", + "signature": null, "docstring": "Identifier of the content origin (URL, file path, or logical name)." }, "content_type": { "name": "content_type", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.content_type", - "signature": "", + "signature": null, "docstring": "Optional MIME type of the content, if known." }, "metadata": { "name": "metadata", "kind": "attribute", "path": "omniread.xlsx.scraper.Content.metadata", - "signature": "", + "signature": null, "docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)." } } @@ -59,49 +45,49 @@ "name": "ContentType", "kind": "class", "path": "omniread.xlsx.scraper.ContentType", - "signature": "", + "signature": null, "docstring": "Supported MIME types for extracted content.\n\nNotes:\n **Guarantees:**\n\n - This enum represents the declared or inferred media type of the\n content source.\n - It is primarily used for routing content to the appropriate\n parser or downstream consumer.", "members": { "HTML": { "name": "HTML", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.HTML", - "signature": "", + "signature": null, "docstring": "HTML document content." }, "PDF": { "name": "PDF", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.PDF", - "signature": "", + "signature": null, "docstring": "PDF document content." }, "XLSX": { "name": "XLSX", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.XLSX", - "signature": "", + "signature": null, "docstring": "Office Open XML spreadsheet (xlsx/xlsm) content." }, "CSV": { "name": "CSV", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.CSV", - "signature": "", + "signature": null, "docstring": "Comma-separated-value document content." }, "JSON": { "name": "JSON", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.JSON", - "signature": "", + "signature": null, "docstring": "JSON document content." }, "XML": { "name": "XML", "kind": "attribute", "path": "omniread.xlsx.scraper.ContentType.XML", - "signature": "", + "signature": null, "docstring": "XML document content." } } @@ -110,14 +96,14 @@ "name": "BaseXlsxClient", "kind": "class", "path": "omniread.xlsx.scraper.BaseXlsxClient", - "signature": "", + "signature": null, "docstring": "Abstract client responsible for retrieving spreadsheet bytes.\n\nRetrieves bytes from a specific backing store (filesystem, S3, FTP, etc.).\n\nNotes:\n **Responsibilities:**\n\n - Implementations must accept a source identifier appropriate to\n the backing store.\n - Return the full xlsx binary payload.\n - Raise retrieval-specific errors on failure.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.scraper.BaseXlsxClient.fetch", - "signature": "", + "signature": "fetch(source: Any)", "docstring": "Fetch raw xlsx bytes from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet location, such as a file path,\n object storage key, or remote reference.\n\nReturns:\n bytes:\n Raw xlsx bytes.\n\nRaises:\n Exception:\n Retrieval-specific errors defined by the implementation." } } @@ -126,14 +112,14 @@ "name": "XlsxScraper", "kind": "class", "path": "omniread.xlsx.scraper.XlsxScraper", - "signature": "", + "signature": "XlsxScraper(*, client: BaseXlsxClient)", "docstring": "Scraper for xlsx spreadsheet documents.\n\nNotes:\n **Responsibilities:**\n\n - Fetch raw xlsx bytes via the configured client.\n - Wrap the payload in a canonical `Content` instance with the\n XLSX content type and source identifier.\n\n **Constraints:**\n\n - The scraper does not perform parsing or interpretation.\n - Does not assume a specific storage backend.", "members": { "fetch": { "name": "fetch", "kind": "function", "path": "omniread.xlsx.scraper.XlsxScraper.fetch", - "signature": "", + "signature": "fetch(source: Any, *, metadata: Mapping[str, Any] | None = None) -> Content", "docstring": "Fetch an xlsx document from the given source.\n\nArgs:\n source (Any):\n Identifier of the spreadsheet source as understood by the\n configured client.\n metadata (Mapping[str, Any] | None, optional):\n Optional metadata to attach to the returned content.\n\nReturns:\n Content:\n A `Content` instance containing raw xlsx bytes, source\n identifier, XLSX content type, and optional metadata.\n\nRaises:\n Exception:\n Retrieval-specific errors raised by the client." } } diff --git a/docs/mkdocs.lib.yml b/docs/mkdocs.lib.yml index 42ea310..a89652d 100644 --- a/docs/mkdocs.lib.yml +++ b/docs/mkdocs.lib.yml @@ -85,3 +85,15 @@ nav: - pdf/client.md - pdf/parser.md - pdf/scraper.md +- CSV Handling: + - csv/index.md + - csv/client.md + - csv/parser_base.md + - csv/parser.md + - csv/scraper.md +- XLSX Handling: + - xlsx/index.md + - xlsx/client.md + - xlsx/parser_base.md + - xlsx/parser.md + - xlsx/scraper.md diff --git a/docs/mkdocs.wiki.yml b/docs/mkdocs.wiki.yml new file mode 100644 index 0000000..03e9e71 --- /dev/null +++ b/docs/mkdocs.wiki.yml @@ -0,0 +1,69 @@ +site_name: OmniRead Documentation +docs_dir: wiki +site_dir: ../site/wiki + +nav: +- Home: index.md +- Overview: 01_overview.md +- How to Use: 02_how_to_use.md +- Extending OmniRead: 03_extending.md +- Development: 04_development.md + +theme: + name: material + palette: + scheme: slate + primary: blue grey + accent: teal + font: + text: Roboto + code: JetBrains Mono + features: + - navigation.sections + - navigation.expand + - navigation.top + - navigation.instant + - navigation.tracking + - navigation.indexes + - content.code.copy + - content.code.annotate + - content.tabs.link + - content.action.edit + - search.highlight + - search.share + - search.suggest + - navigation.tabs + - toc.integrate + - header.autohide + - announce.dismiss + - footer.social + - content.code.select + - content.code.line_numbers + - content.tooltips + icon: + logo: material/book-open-page-variant + repo: fontawesome/brands/github +markdown_extensions: +- pymdownx.superfences +- pymdownx.inlinehilite +- pymdownx.snippets +- admonition +- pymdownx.details +- pymdownx.highlight: + linenums: true + anchor_linenums: true + line_spans: __span + pygments_lang_class: true +- pymdownx.tabbed: + alternate_style: true +- pymdownx.tasklist: + custom_checkbox: true +- tables +- footnotes +- pymdownx.caret +- pymdownx.tilde +- pymdownx.mark +extra_css: +- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css +plugins: +- search \ No newline at end of file diff --git a/docs/wiki/01_overview.md b/docs/wiki/01_overview.md new file mode 100644 index 0000000..b7d846f --- /dev/null +++ b/docs/wiki/01_overview.md @@ -0,0 +1,86 @@ +# 🧱 Overview + +OmniRead is designed as a **decoupled content engine** with three distinct +layers. Understanding them is the key to using and extending the library. + +--- + +## πŸ—οΈ Architecture + +```text + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Source (URL, file, storage) β”‚ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Scraper / Client β”‚ fetches raw bytes + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ returns + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Content β”‚ raw + source + type + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + β”‚ Parser β”‚ parse() β†’ structured T + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +1. **Scraper** (`BaseScraper`) β€” fetches raw bytes from a source (HTTP URL, + filesystem path, object storage). Returns a `Content` instance. + Scrapers never interpret content. +2. **Content** (`Content`) β€” the canonical exchange model: raw bytes, + source identifier, and optional `ContentType` enum. +3. **Parser** (`BaseParser[T]`) β€” receives a `Content` and returns a + structured result of type `T` via `parse()`. + +--- + +## πŸ“¦ The `Content` model + +Defined in `omniread.core.content`: + +```python +from dataclasses import dataclass +from omniread import Content, ContentType + +@dataclass(slots=True) +class Content: + raw: bytes + source: str + content_type: ContentType | None = None +``` + +- `raw` β€” the raw bytes exactly as retrieved. +- `source` β€” URL, file path, or logical name identifying the origin. +- `content_type` β€” optional `ContentType` enum value. + +--- + +## 🎭 The `ContentType` enum + +| Value | MIME | Used by | +|---|---|---| +| `HTML` | `text/html` | HTMLScraper | +| `PDF` | `application/pdf` | PDFScraper | +| `XLSX` | `application/vnd.openxmlformats-...` | XlsxScraper | +| `CSV` | `text/csv` | CsvScraper | +| `JSON` | `application/json` | β€” | +| `XML` | `application/xml` | β€” | + +--- + +## 🧩 Format modules at a glance + +| Module | Scraper | Parser | Client | Notes | +|---|---|---|---|---| +| `omniread.html` | `HTMLScraper` | `HTMLParser` | β€” | httpx + BeautifulSoup | +| `omniread.pdf` | `PDFScraper` | `PDFParser` | `FileSystemPDFClient` | explicit client layer | +| `omniread.csv` | `CsvScraper` | `CsvParser` | `FileSystemCsvClient` | stdlib csv module | +| `omniread.xlsx` | `XlsxScraper` | `XlsxParser` | `FileSystemXlsxClient` | openpyxl-backed | + +--- + +## πŸ“š Read Next + +- [How to Use](02_how_to_use.md) β€” working examples per format. +- [Extending OmniRead](03_extending.md) β€” subclassing scrapers and parsers. \ No newline at end of file diff --git a/docs/wiki/02_how_to_use.md b/docs/wiki/02_how_to_use.md new file mode 100644 index 0000000..1fd1974 --- /dev/null +++ b/docs/wiki/02_how_to_use.md @@ -0,0 +1,109 @@ +# πŸ–₯️ How to Use + +Every format follows the same pipeline: **scrape β†’ `Content` β†’ parse**. +This page shows each supported format with working patterns. + +--- + +## 🌐 HTML + +```python +from omniread import HTMLScraper, HTMLParser + +class TitleParser(HTMLParser[str]): + def parse(self) -> str: + return self._soup.title.string + +scraper = HTMLScraper() # httpx under the hood +content = scraper.fetch("https://example.com") + +title = TitleParser(content).parse() +``` + +`HTMLScraper` accepts an optional `client` (an `httpx.Client`) for transport +control β€” the test suite wires one to a mock transport. + +--- + +## πŸ“• PDF + +PDFs need a **client** to supply raw bytes before parsing: + +```python +from pathlib import Path +from omniread import FileSystemPDFClient, PDFScraper, PDFParser + +class TextPDFParser(PDFParser[str]): + def parse(self) -> str: + # implement your extraction logic + return self.content.raw # bytes, decode as needed + +client = FileSystemPDFClient() +scraper = PDFScraper(client=client) +content = scraper.fetch(Path("document.pdf")) + +result = TextPDFParser(content).parse() +``` + +`PDFParser` subclasses receive `self.content` and implement `parse()`. + +--- + +## πŸ“Š CSV + +```python +from omniread import FileSystemCsvClient, CsvScraper, CsvParser + +scraper = CsvScraper(client=FileSystemCsvClient()) +content = scraper.fetch("data.csv") + +parser = CsvParser(content) +for row in parser.rows(): + print(row) +``` + +`CsvParser.rows()` yields string rows trimmed of empties by default +(`skip_empty=True`). + +--- + +## πŸ“‘ XLSX + +```python +from omniread import FileSystemXlsxClient, XlsxScraper, XlsxParser + +scraper = XlsxScraper(client=FileSystemXlsxClient()) +content = scraper.fetch("statement.xlsx") + +parser = XlsxParser(content) +print(parser.sheet_names) # e.g. ["Statement"] +rows = parser.rows(sheet="Statement") # by name or index +all_rows = parser.parse() # alias for rows() +``` + +Key behaviors: + +- `rows(skip_empty=False)` keeps blank rows (off by default). +- Cells render as trimmed strings; date cells convert to ISO format + (`2026-06-01T00:00:00`). +- `rows(sheet="Missing")` raises for an unknown sheet. + +--- + +## πŸ”€ End-to-end flow + +```python +content = scraper.fetch(source) # 1. acquire β†’ Content +assert isinstance(content.raw, bytes) +assert content.content_type is not None + +parser = MyParser(content) # 2. interpret β†’ T +result = parser.parse() +``` + +--- + +## πŸ“š Read Next + +- [Overview](01_overview.md) β€” the full architecture. +- [Extending OmniRead](03_extending.md) β€” custom clients and parsers. \ No newline at end of file diff --git a/docs/wiki/03_extending.md b/docs/wiki/03_extending.md new file mode 100644 index 0000000..da2ff35 --- /dev/null +++ b/docs/wiki/03_extending.md @@ -0,0 +1,104 @@ +# 🧩 Extending OmniRead + +OmniRead is meant to be extended by subclassing. All public extension points +are generic over their result type, so your parser returns exactly the shape +you need. + +--- + +## 🧬 Custom parsers + +Subclass `BaseParser[T]` (or a format parser) and implement `parse()`: + +```python +from pydantic import BaseModel +from omniread import HTMLParser + +class Page(BaseModel): + title: str + content: str | None + +class PageParser(HTMLParser[Page]): + def parse(self) -> Page: + soup = self._soup + div = soup.find("div", id="content") + return Page( + title=soup.title.string, + content=div.get_text() if div else None, + ) +``` + +The parsed page is validated by Pydantic on construction β€” no manual +assertions required. + +--- + +## 🧬 Custom PDF parsers + +PDF binary layout is format-specific, so parsers return your own model: + +```python +from typing import Literal +from pydantic import BaseModel +from omniread import PDFParser + +class ParsedPDF(BaseModel): + size_bytes: int + magic: Literal[b"%PDF"] + +class SimplePDFParser(PDFParser[ParsedPDF]): + def parse(self) -> ParsedPDF: + if not self.content.raw.startswith(b"%PDF"): + raise ValueError("Not a valid PDF") + return ParsedPDF(size_bytes=len(self.content.raw), magic=b"%PDF") +``` + +--- + +## 🧬 Custom clients + +Clients supply raw bytes to a scraper. For PDFs, subclass +`BasePDFClient` (or `FileSystemPDFClient`) and implement +`fetch(source) -> bytes`: + +```python +from omniread.pdf.client import BasePDFClient + +class MockPDFClient(BasePDFClient): + def fetch(self, source): + return b"%PDF ..." # bytes for the logical identifier +``` + +The same pattern applies to `BaseCsvClient` and `BaseXlsxClient`. + +--- + +## πŸš€ Custom scrapers + +Festch something that a built-in scraper does not cover by extending +`BaseScraper`: + +```python +from omniread import BaseScraper, Content, ContentType + +class StorageScraper(BaseScraper): + def fetch(self, source, *, metadata=None): + raw = my_object_storage.download(source) # your I/O + return Content(raw=raw, source=source, content_type=ContentType.JSON) +``` + +--- + +## βœ… Extension checklist + +1. Keep **scraper** and **parser** separate β€” never mix I/O into `parse()`. +2. Return `Content` from any scraper/client so downstream stays uniform. +3. Return a *typed* result from your parser (Pydantic model, dataclass, str). +4. Test your custom layers with a mock client, not a live network. + +--- + +## πŸ“š Read Next + +- [How to Use](02_how_to_use.md) β€” built-in example flows. +- [Development](04_development.md) β€” running tests and docs. \ No newline at end of file diff --git a/docs/wiki/04_development.md b/docs/wiki/04_development.md new file mode 100644 index 0000000..69e4f8c --- /dev/null +++ b/docs/wiki/04_development.md @@ -0,0 +1,87 @@ +# πŸ› οΈ Development + +Working on `omniread` itself. + +--- + +## πŸ“‚ Repository layout + +| Path | Purpose | +|---|---| +| `omniread/` | The library package (core + html, pdf, csv, xlsx modules) | +| `omniread/*.pyi` | Type stubs kept in sync with implementations | +| `tests/` | End-to-end and unit tests against mock transports/clients | +| `covers` | β€” | +| `docs/lib/` | Generated library reference (docforge, flat layout) | +| `docs/mcp/` | Machine-readable bundle served by the MCP server | +| `docs/wiki/` | This hand-written wiki | + +--- + +## πŸ”§ Setup + +```bash +python -m venv .venv +.venv/Scripts/pip install -e ".[dev]" +``` + +--- + +## πŸ§ͺ Tests + +Run the suite (offline; a mock httpx transport and mock PDF client are used): + +```bash +.venv/Scripts/pytest +``` + +Coverage spans end-to-end scrape β†’ parse flows for HTML, PDF, and XLSX, +plus client validation and CSV/XLSX parsing edge cases. + +--- + +## βœ… Quality gates + +The CI quality gate runs, matching the Drone pipeline: + +```bash +.venv/Scripts/black --check . +.venv/Scripts/ruff check . +.venv/Scripts/mypy +.venv/Scripts/pytest +``` + +--- + +## πŸ“ Building documentation (docforge) + +The site is generated by [`docforge`](https://git.aetoskia.com/aetos/doc-forge) +and served per kind under `site/{kind}`: + +```bash +doc-forge build \ + --mkdocs --mcp \ + --module-is-source --module omniread \ + --site-name "OmniRead" +``` + +- `--module-is-source` renders the flat `docs/lib/` layout (no nesting under + `omniread/`), matching `docforge.nav.yml` and `docs/mkdocs.lib.yml`. +- `--mcp` regenerates the structured bundle in `docs/mcp/`. +- `--wiki` builds this wiki. +- `gen_api.py` (if present) regenerates the API docs. + +Preview locally: + +```bash +doc-forge serve --lib +doc-forge serve --wiki +doc-forge serve --mcp +``` + +--- + +## πŸ“š Read Next + +- [Extending OmniRead](03_extending.md) β€” custom parsers, scrapers, clients. +- [Overview](01_overview.md) β€” the core architecture. \ No newline at end of file diff --git a/docs/wiki/index.md b/docs/wiki/index.md new file mode 100644 index 0000000..7256d4b --- /dev/null +++ b/docs/wiki/index.md @@ -0,0 +1,64 @@ +# πŸ“„ OmniRead β€” Format-Agnostic Content Acquisition and Parsing + +`OmniRead` is a composable content ingestion framework with pluggable scrapers +and parsers for HTML, PDF, CSV, and XLSX. It cleanly separates fetching +(I/O) from interpretation (parsing) through a canonical `Content` exchange +model, giving each format its own scraper and parser while sharing one +uniform pipeline. + +> **Doc model:** this wiki is written for humans β€” how‑to guides, examples, +> and extension recipes. The authoritative API contracts live in the code +> (GSDFC docstrings) and the machine‑readable bundle under `docs/mcp/`. + +--- + +## πŸš€ Key Features + +* 🧱 **Content/Scraper/Parser architecture** β€” fetch and interpret in + independent, testable layers +* πŸ“„ **Canonical `Content` model** β€” raw bytes + metadata passed between all + layers via one dataclass +* 🌐 **HTML** β€” HTTP-based scraper with httpx; DOM parsing via BeautifulSoup +* πŸ“• **PDF** β€” client + scraper for raw PDF bytes; user-defined parsers +* πŸ“Š **CSV** β€” standard-library CSV parser over `rows()` iterator +* πŸ“‘ **XLSX** β€” openpyxl-backed spreadsheet parser with sheet selection, + empty-row control, and ISO date conversion + +--- + +## ⚑ Quick Start + +```python +from omniread import HTMLScraper, HTMLParser + +class TitleParser(HTMLParser[str]): + def parse(self) -> str: + return self._soup.title.string + +content = HTMLScraper().fetch("https://example.com") +title = TitleParser(content).parse() +assert title == "Example Domain" +``` + +--- + +## πŸ“ Documentation Structure + +| Section | What you'll find | +|---|---| +| [Overview](01_overview.md) | The three-layer architecture and the `Content` model | +| [How to Use](02_how_to_use.md) | Ready-to-run examples for HTML, PDF, CSV, and XLSX | +| [Extending OmniRead](03_extending.md) | Subclassing scrapers, parsers, and clients | +| [Development](04_development.md) | Setup, tests, and regenerating docs | + +--- + +## πŸ”— Related Resources + +* **Source Code:** [Gitea Repository](https://git.aetoskia.com/aetos/omniread) +* **Internal PyPI:** [pip.aetoskia.com/simple/omniread](https://pip.aetoskia.com/simple/omniread) +* **CI:** Builds and publishes tagged releases, gated on black / ruff / mypy / pytest. + +--- + +Β© Aetoskia Internal β€” `omniread` 0.0.1 \ No newline at end of file