Files
omniread/docs/mcp/modules/omniread.csv.json
Vishesh 'ironeagle' Bangotra b984dd5f42 docs: add wiki, complete lib nav, and rebuild mcp artifacts
- Add hand-written wiki (index, overview, how-to, extending, dev) with
  MkDocs config following the platform anatomy
- Complete the library nav by registering the csv and xlsx groups in
  docforge.nav.yml and docs/mkdocs.lib.yml
- Regenerate lib/MCP outputs with the rebuilt nav
2026-09-16 19:58:59 +05:30

492 lines
29 KiB
JSON

{
"module": "omniread.csv",
"content": {
"path": "omniread.csv",
"docstring": "# Summary\n\nCSV subpackage for OmniRead.\n\nProvides acquisition and parsing of comma-separated-value content:\n\n- `BaseCsvClient`: abstract backing-store client for csv bytes.\n- `FileSystemCsvClient`: local filesystem implementation.\n- `CsvScraper`: wraps fetched bytes into canonical `Content`.\n- `CsvParserBase`: content-type-enforcing parser contract.\n- `CsvParser`: generic string-row parser built on the standard csv module.",
"objects": {
"BaseCsvClient": {
"name": "BaseCsvClient",
"kind": "class",
"path": "omniread.csv.BaseCsvClient",
"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": "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."
}
}
},
"FileSystemCsvClient": {
"name": "FileSystemCsvClient",
"kind": "class",
"path": "omniread.csv.FileSystemCsvClient",
"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": "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."
}
}
},
"CsvParser": {
"name": "CsvParser",
"kind": "class",
"path": "omniread.csv.CsvParser",
"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": "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": "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."
}
}
},
"CsvParserBase": {
"name": "CsvParserBase",
"kind": "class",
"path": "omniread.csv.CsvParserBase",
"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": null,
"docstring": "Set of content types supported by this parser (CSV only)."
},
"parse": {
"name": "parse",
"kind": "function",
"path": "omniread.csv.CsvParserBase.parse",
"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."
}
}
},
"CsvScraper": {
"name": "CsvScraper",
"kind": "class",
"path": "omniread.csv.CsvScraper",
"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": "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."
}
}
},
"client": {
"name": "client",
"kind": "module",
"path": "omniread.csv.client",
"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": {
"BaseCsvClient": {
"name": "BaseCsvClient",
"kind": "class",
"path": "omniread.csv.client.BaseCsvClient",
"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": "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."
}
}
},
"FileSystemCsvClient": {
"name": "FileSystemCsvClient",
"kind": "class",
"path": "omniread.csv.client.FileSystemCsvClient",
"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": "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."
}
}
}
}
},
"parser": {
"name": "parser",
"kind": "module",
"path": "omniread.csv.parser",
"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": {
"Content": {
"name": "Content",
"kind": "class",
"path": "omniread.csv.parser.Content",
"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": null,
"docstring": "Raw content bytes as retrieved from the source."
},
"source": {
"name": "source",
"kind": "attribute",
"path": "omniread.csv.parser.Content.source",
"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": null,
"docstring": "Optional MIME type of the content, if known."
},
"metadata": {
"name": "metadata",
"kind": "attribute",
"path": "omniread.csv.parser.Content.metadata",
"signature": null,
"docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
}
}
},
"CsvParserBase": {
"name": "CsvParserBase",
"kind": "class",
"path": "omniread.csv.parser.CsvParserBase",
"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": null,
"docstring": "Set of content types supported by this parser (CSV only)."
},
"parse": {
"name": "parse",
"kind": "function",
"path": "omniread.csv.parser.CsvParserBase.parse",
"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."
}
}
},
"CsvParser": {
"name": "CsvParser",
"kind": "class",
"path": "omniread.csv.parser.CsvParser",
"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": "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": "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."
}
}
}
}
},
"parser_base": {
"name": "parser_base",
"kind": "module",
"path": "omniread.csv.parser_base",
"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": {
"ContentType": {
"name": "ContentType",
"kind": "class",
"path": "omniread.csv.parser_base.ContentType",
"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": null,
"docstring": "HTML document content."
},
"PDF": {
"name": "PDF",
"kind": "attribute",
"path": "omniread.csv.parser_base.ContentType.PDF",
"signature": null,
"docstring": "PDF document content."
},
"XLSX": {
"name": "XLSX",
"kind": "attribute",
"path": "omniread.csv.parser_base.ContentType.XLSX",
"signature": null,
"docstring": "Office Open XML spreadsheet (xlsx/xlsm) content."
},
"CSV": {
"name": "CSV",
"kind": "attribute",
"path": "omniread.csv.parser_base.ContentType.CSV",
"signature": null,
"docstring": "Comma-separated-value document content."
},
"JSON": {
"name": "JSON",
"kind": "attribute",
"path": "omniread.csv.parser_base.ContentType.JSON",
"signature": null,
"docstring": "JSON document content."
},
"XML": {
"name": "XML",
"kind": "attribute",
"path": "omniread.csv.parser_base.ContentType.XML",
"signature": null,
"docstring": "XML document content."
}
}
},
"BaseParser": {
"name": "BaseParser",
"kind": "class",
"path": "omniread.csv.parser_base.BaseParser",
"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": 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": null,
"docstring": null
},
"parse": {
"name": "parse",
"kind": "function",
"path": "omniread.csv.parser_base.BaseParser.parse",
"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": "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."
}
}
},
"T": {
"name": "T",
"kind": "attribute",
"path": "omniread.csv.parser_base.T",
"signature": null,
"docstring": null
},
"CsvParserBase": {
"name": "CsvParserBase",
"kind": "class",
"path": "omniread.csv.parser_base.CsvParserBase",
"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_base.CsvParserBase.supported_types",
"signature": null,
"docstring": "Set of content types supported by this parser (CSV only)."
},
"parse": {
"name": "parse",
"kind": "function",
"path": "omniread.csv.parser_base.CsvParserBase.parse",
"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."
}
}
}
}
},
"scraper": {
"name": "scraper",
"kind": "module",
"path": "omniread.csv.scraper",
"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": {
"Content": {
"name": "Content",
"kind": "class",
"path": "omniread.csv.scraper.Content",
"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": null,
"docstring": "Raw content bytes as retrieved from the source."
},
"source": {
"name": "source",
"kind": "attribute",
"path": "omniread.csv.scraper.Content.source",
"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": null,
"docstring": "Optional MIME type of the content, if known."
},
"metadata": {
"name": "metadata",
"kind": "attribute",
"path": "omniread.csv.scraper.Content.metadata",
"signature": null,
"docstring": "Optional, implementation-defined metadata associated with the content (e.g., headers, encoding hints, extraction notes)."
}
}
},
"ContentType": {
"name": "ContentType",
"kind": "class",
"path": "omniread.csv.scraper.ContentType",
"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": null,
"docstring": "HTML document content."
},
"PDF": {
"name": "PDF",
"kind": "attribute",
"path": "omniread.csv.scraper.ContentType.PDF",
"signature": null,
"docstring": "PDF document content."
},
"XLSX": {
"name": "XLSX",
"kind": "attribute",
"path": "omniread.csv.scraper.ContentType.XLSX",
"signature": null,
"docstring": "Office Open XML spreadsheet (xlsx/xlsm) content."
},
"CSV": {
"name": "CSV",
"kind": "attribute",
"path": "omniread.csv.scraper.ContentType.CSV",
"signature": null,
"docstring": "Comma-separated-value document content."
},
"JSON": {
"name": "JSON",
"kind": "attribute",
"path": "omniread.csv.scraper.ContentType.JSON",
"signature": null,
"docstring": "JSON document content."
},
"XML": {
"name": "XML",
"kind": "attribute",
"path": "omniread.csv.scraper.ContentType.XML",
"signature": null,
"docstring": "XML document content."
}
}
},
"BaseCsvClient": {
"name": "BaseCsvClient",
"kind": "class",
"path": "omniread.csv.scraper.BaseCsvClient",
"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": "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."
}
}
},
"CsvScraper": {
"name": "CsvScraper",
"kind": "class",
"path": "omniread.csv.scraper.CsvScraper",
"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": "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."
}
}
}
}
}
}
}
}