lombokcsv 1.1.0__tar.gz

lombokcsv-1.1.0/LICENSE

@@ -0,0 +1,154 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined in Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity exercising
+      permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or Object
+      form, made available under the License, as indicated by a copyright
+      notice that is included in or attached to the work (an example is
+      provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship, thus excluding
+      simple mechanical transformations or merely linking (or binding by
+      name) to the interfaces of, the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original Work and any Derivative Works thereof, that is
+      intentionally submitted to, or incorporated into, the Work by
+      Licensor for inclusion in the Work by the copyright owner or by an
+      individual or Legal Entity authorized to submit on behalf of the
+      copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, such as but not limited to
+      communication on electronic mailing lists, source code control
+      systems, and issue tracking systems that are managed by, or on behalf
+      of, the Licensor for the purpose of discussing and improving the Work,
+      but excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated into the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file, then any
+          Derivative Works that You distribute must include a readable
+          copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contribution.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

lombokcsv-1.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: lombokcsv
+Version: 1.1.0
+Summary: RFC 4180 CSV parser with type detection, safe HTML tables, JSON export and GROUP BY aggregation. Pure Python, zero dependencies. Part of the Lombok Ecosystem.
+Author: codinglombok
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/codinglombok/LombokCSV
+Project-URL: Issues, https://github.com/codinglombok/LombokCSV/issues
+Keywords: csv,rfc4180,parser,group-by,type-detection,zero-dependency,lombok-ecosystem
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# LombokCSV — Python port
+
+Python implementation of the [LombokCSV](../../README.md) contract: RFC 4180 CSV parsing, column type detection, safe HTML tables, JSON export and GROUP BY aggregation. Zero runtime dependencies.
+
+| Item | Value |
+|---|---|
+| Package | `lombokcsv` (PyPI) |
+| Version | 1.1.0 |
+| Contract | [SPEC](../../docs/SPEC_LombokCSV_v1.1.0.md) |
+| Vectors | runs all 152 cases in [`vectors/lombokcsv-vectors-v1.json`](../../vectors/lombokcsv-vectors-v1.json) |
+| Acceptance | every vector case passes with byte-identical results (GP-11) |
+| Python | >= 3.9 |
+
+## Installation
+
+```bash
+pip install lombokcsv
+```
+
+The package has not been published to PyPI yet; until then install from the repository root (`pip install ./python`).
+
+## Quick start
+
+```python
+from lombokcsv import CSV, AggregationOptions
+
+csv = CSV("Region,Product,Qty\nWest,Rice,120\nWest,Corn,80\nEast,Rice,95")
+
+csv.get_headers()  # ['Region', 'Product', 'Qty']
+csv.get_types()    # ['string', 'string', 'number']
+csv.to_json()      # [{'Region': 'West', 'Product': 'Rice', 'Qty': '120'}, ...]
+csv.to_html()
+
+csv.aggregate(AggregationOptions(group_by="Region", sum=["Qty"], avg=["Qty"], count=True))
+# [{'Region': 'West', 'Qty_sum': 200.0, 'Qty_avg': 100.0, 'count': 2},
+#  {'Region': 'East', 'Qty_sum': 95.0, 'Qty_avg': 95.0, 'count': 1}]
+```
+
+The Python API mirrors the TypeScript reference with PEP 8 names: `toJSON` → `to_json`, `getHeaders` → `get_headers`, `className` → `class_name`, `hasHeader` → `has_header`. Behaviour, error codes (`INVALID_OPTION`, `UNKNOWN_COLUMN`) and the `[CODE] message` texts are identical across ports (SPEC section 7).
+
+## Development
+
+```bash
+python -m pip install pytest coverage
+python -m coverage run --branch --source=lombokcsv -m pytest -q
+python -m coverage report -m --fail-under=90
+```
+
+Contributions are welcome; see [CONTRIBUTING.md](../../CONTRIBUTING.md).

lombokcsv-1.1.0/README.md

@@ -0,0 +1,49 @@
+# LombokCSV — Python port
+
+Python implementation of the [LombokCSV](../../README.md) contract: RFC 4180 CSV parsing, column type detection, safe HTML tables, JSON export and GROUP BY aggregation. Zero runtime dependencies.
+
+| Item | Value |
+|---|---|
+| Package | `lombokcsv` (PyPI) |
+| Version | 1.1.0 |
+| Contract | [SPEC](../../docs/SPEC_LombokCSV_v1.1.0.md) |
+| Vectors | runs all 152 cases in [`vectors/lombokcsv-vectors-v1.json`](../../vectors/lombokcsv-vectors-v1.json) |
+| Acceptance | every vector case passes with byte-identical results (GP-11) |
+| Python | >= 3.9 |
+
+## Installation
+
+```bash
+pip install lombokcsv
+```
+
+The package has not been published to PyPI yet; until then install from the repository root (`pip install ./python`).
+
+## Quick start
+
+```python
+from lombokcsv import CSV, AggregationOptions
+
+csv = CSV("Region,Product,Qty\nWest,Rice,120\nWest,Corn,80\nEast,Rice,95")
+
+csv.get_headers()  # ['Region', 'Product', 'Qty']
+csv.get_types()    # ['string', 'string', 'number']
+csv.to_json()      # [{'Region': 'West', 'Product': 'Rice', 'Qty': '120'}, ...]
+csv.to_html()
+
+csv.aggregate(AggregationOptions(group_by="Region", sum=["Qty"], avg=["Qty"], count=True))
+# [{'Region': 'West', 'Qty_sum': 200.0, 'Qty_avg': 100.0, 'count': 2},
+#  {'Region': 'East', 'Qty_sum': 95.0, 'Qty_avg': 95.0, 'count': 1}]
+```
+
+The Python API mirrors the TypeScript reference with PEP 8 names: `toJSON` → `to_json`, `getHeaders` → `get_headers`, `className` → `class_name`, `hasHeader` → `has_header`. Behaviour, error codes (`INVALID_OPTION`, `UNKNOWN_COLUMN`) and the `[CODE] message` texts are identical across ports (SPEC section 7).
+
+## Development
+
+```bash
+python -m pip install pytest coverage
+python -m coverage run --branch --source=lombokcsv -m pytest -q
+python -m coverage report -m --fail-under=90
+```
+
+Contributions are welcome; see [CONTRIBUTING.md](../../CONTRIBUTING.md).

lombokcsv-1.1.0/lombokcsv/__init__.py

@@ -0,0 +1,42 @@
+"""LombokCSV - public API of the Python port."""
+
+from lombokcsv.csv import (
+    TYPE_SAMPLE_ROWS,
+    CSV,
+    CSVAggregator,
+    CSVData,
+    CSVError,
+    CSVOptions,
+    CSVParser,
+    HTMLOptions,
+    HTMLGenerator,
+    AggregationOptions,
+    DataType,
+    detect_types,
+    escape_html,
+    is_boolean,
+    is_date,
+    is_number,
+)
+
+__version__ = "1.1.0"
+
+__all__ = [
+    "__version__",
+    "TYPE_SAMPLE_ROWS",
+    "AggregationOptions",
+    "CSV",
+    "CSVAggregator",
+    "CSVData",
+    "CSVError",
+    "CSVOptions",
+    "CSVParser",
+    "DataType",
+    "HTMLOptions",
+    "HTMLGenerator",
+    "detect_types",
+    "escape_html",
+    "is_boolean",
+    "is_date",
+    "is_number",
+]

lombokcsv-1.1.0/lombokcsv/csv.py

@@ -0,0 +1,389 @@
+"""LombokCSV - RFC 4180 CSV parser, type detector, HTML table generator, aggregator.
+
+Zero runtime dependencies. Normative behaviour: docs/SPEC_LombokCSV_v<version>.md.
+The Python port consumes the same shared vector file as every other port
+(vectors/lombokcsv-vectors-v1.json) and must produce byte-identical results.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Sequence, Union
+
+__all__ = [
+    "TYPE_SAMPLE_ROWS",
+    "CSV",
+    "CSVAggregator",
+    "CSVData",
+    "CSVError",
+    "CSVOptions",
+    "CSVParser",
+    "HTMLOptions",
+    "HTMLGenerator",
+    "AggregationOptions",
+    "detect_types",
+    "escape_html",
+    "is_boolean",
+    "is_date",
+    "is_number",
+]
+
+TYPE_SAMPLE_ROWS = 10
+
+NUMBER_RE = re.compile(r"^-?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$", re.ASCII)
+DATE_RES = [
+    re.compile(r"^\d{4}-\d{2}-\d{2}$", re.ASCII),
+    re.compile(r"^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?$", re.ASCII),
+    re.compile(r"^\d{1,2}/\d{1,2}/\d{4}$", re.ASCII),
+    re.compile(r"^\d{1,2}-\d{1,2}-\d{4}$", re.ASCII),
+]
+BOOLEAN_RE = re.compile(r"^(true|false|yes|no|1|0)$", re.ASCII | re.IGNORECASE)
+
+DataType = str
+
+TRAILING_BLANKS = re.compile(r"[ \t]+$")
+
+
+class CSVError(Exception):
+    """Error with a stable, language-neutral `code` (SPEC section 7)."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+        self.name = "CSVError"
+
+
+@dataclass
+class CSVOptions:
+    """Parser options (SPEC section 1)."""
+
+    delimiter: str = ","
+    quote: str = '"'
+    has_header: Optional[bool] = None  # default True
+    trim: bool = True
+    escape: Optional[str] = None  # deprecated, ignored
+
+
+@dataclass
+class CSVData:
+    headers: Optional[List[str]] = None
+    rows: List[List[str]] = field(default_factory=list)
+    types: List[DataType] = field(default_factory=list)
+
+
+@dataclass
+class AggregationOptions:
+    group_by: Union[str, int, float]
+    sum: Optional[List[Union[str, int, float]]] = None
+    avg: Optional[List[Union[str, int, float]]] = None
+    count: bool = False
+
+
+@dataclass
+class HTMLOptions:
+    class_name: str = ""
+    id: str = ""
+
+
+def is_number(val: str) -> bool:
+    return NUMBER_RE.match(val) is not None
+
+
+def is_date(val: str) -> bool:
+    return any(pattern.match(val) is not None for pattern in DATE_RES)
+
+
+def is_boolean(val: str) -> bool:
+    return BOOLEAN_RE.match(val) is not None
+
+
+def _strip(val: str) -> str:
+    """Strips SPACE, TAB, CR and LF from both ends (SPEC section 0.3)."""
+    return val.strip(" \t\r\n")
+
+
+def _single_char(name: str, value: str) -> str:
+    # SPEC section 0.4: exactly one UTF-16 code unit, i.e. one code point
+    # no greater than U+FFFF, and not CR/LF.
+    if len(value) != 1 or ord(value) > 0xFFFF or value in ("\n", "\r"):
+        raise CSVError("INVALID_OPTION", f"[INVALID_OPTION] {name} must be a single character other than CR/LF")
+    return value
+
+
+def detect_types(rows: Sequence[Sequence[str]]) -> List[DataType]:
+    """Detects one type per column from the first TYPE_SAMPLE_ROWS rows (SPEC section 3)."""
+    num_cols = 0
+    for r in rows:
+        if len(r) > num_cols:
+            num_cols = len(r)
+    types: List[DataType] = []
+    sample = list(rows)[:TYPE_SAMPLE_ROWS]
+    for col in range(num_cols):
+        any_value = False
+        num = date = boolean = True
+        for row in sample:
+            val = _strip(row[col] if col < len(row) else "")
+            if val == "":
+                continue
+            any_value = True
+            if num and not is_number(val):
+                num = False
+            if date and not is_date(val):
+                date = False
+            if boolean and not is_boolean(val):
+                boolean = False
+        if not any_value:
+            types.append("string")
+        elif num:
+            types.append("number")
+        elif date:
+            types.append("date")
+        elif boolean:
+            types.append("boolean")
+        else:
+            types.append("string")
+    return types
+
+
+def escape_html(text: str) -> str:
+    """Escapes text for HTML element content and double-quoted attribute values."""
+    return (
+        text.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&#39;")
+    )
+
+
+class CSVParser:
+    """CSV parser - RFC 4180 records with configurable delimiter and quote."""
+
+    def __init__(self, data: str, options: Optional[CSVOptions] = None) -> None:
+        options = options or CSVOptions()
+        self.data = data[1:] if data[:1] == "" else data
+        self.delimiter = _single_char("delimiter", options.delimiter)
+        self.quote = _single_char("quote", options.quote)
+        if self.delimiter == self.quote:
+            raise CSVError("INVALID_OPTION", "[INVALID_OPTION] delimiter and quote must differ")
+        self.trim = options.trim
+
+    def parse(self, has_header: bool = True) -> CSVData:
+        rows = self.parse_rows()
+        if not rows:
+            return CSVData()
+        headers = rows.pop(0) if has_header else None
+        return CSVData(headers=headers, rows=rows, types=detect_types(rows))
+
+    def parse_rows(self) -> List[List[str]]:
+        """Splits the input into records (SPEC section 2)."""
+        data, delimiter, quote, trim = self.data, self.delimiter, self.quote, self.trim
+        rows: List[List[str]] = []
+        row: List[str] = []
+        chars: List[str] = []
+        quoted = False
+        row_quoted = False
+        # 0 = field start, 1 = unquoted, 2 = inside quotes, 3 = after closing quote
+        state = 0
+
+        def end_field() -> None:
+            nonlocal chars, quoted, row_quoted, state
+            f = "".join(chars)
+            if trim and not quoted:
+                f = TRAILING_BLANKS.sub("", f)
+            row.append(f)
+            row_quoted = row_quoted or quoted
+            chars = []
+            quoted = False
+            state = 0
+
+        def end_record() -> None:
+            nonlocal row, row_quoted
+            end_field()
+            # A line holding a single empty unquoted field is blank and skipped.
+            if len(row) > 1 or row[0] != "" or row_quoted:
+                rows.append(row)
+            row = []
+            row_quoted = False
+
+        i = 0
+        n = len(data)
+        while i < n:
+            c = data[i]
+            if state == 2:
+                if c == quote:
+                    if i + 1 < n and data[i + 1] == quote:
+                        chars.append(quote)
+                        i += 2
+                        continue
+                    state = 3
+                else:
+                    chars.append(c)
+                i += 1
+                continue
+            if c == delimiter:
+                end_field()
+            elif c == "\n" or c == "\r":
+                end_record()
+                if c == "\r" and i + 1 < n and data[i + 1] == "\n":
+                    i += 1
+            elif state == 0:
+                if c == quote:
+                    quoted = True
+                    state = 2
+                elif not (trim and (c == " " or c == "\t")):
+                    chars.append(c)
+                    state = 1
+            elif state == 3:
+                # Lenient: text after a closing quote is appended literally.
+                if not (trim and (c == " " or c == "\t")):
+                    chars.append(c)
+            else:
+                chars.append(c)
+            i += 1
+        if state != 0 or len(row) > 0:
+            end_record()
+        return rows
+
+
+class HTMLGenerator:
+    """HTML generator - semantic table markup (SPEC section 4)."""
+
+    def __init__(self, data: CSVData) -> None:
+        self.data = data
+
+    def generate(self, options: Optional[HTMLOptions] = None) -> str:
+        class_attr = f' class="{escape_html(options.class_name)}"' if options and options.class_name else ""
+        id_attr = f' id="{escape_html(options.id)}"' if options and options.id else ""
+
+        parts: List[str] = [f"<table{class_attr}{id_attr}>\n"]
+        if self.data.headers:
+            parts.append("<thead>\n<tr>\n")
+            for header in self.data.headers:
+                parts.append(f"<th>{escape_html(header)}</th>\n")
+            parts.append("</tr>\n</thead>\n")
+        parts.append("<tbody>\n")
+        for row in self.data.rows:
+            parts.append("<tr>\n")
+            for i, cell in enumerate(row):
+                align = ' style="text-align: right"' if i < len(self.data.types) and self.data.types[i] == "number" else ""
+                parts.append(f"<td{align}>{escape_html(cell)}</td>\n")
+            parts.append("</tr>\n")
+        parts.append("</tbody>\n</table>")
+        return "".join(parts)
+
+
+class CSVAggregator:
+    """Aggregator - GROUP BY with SUM / COUNT / AVG (SPEC section 5)."""
+
+    def __init__(self, data: CSVData) -> None:
+        self.data = data
+
+    def _width(self) -> int:
+        w = len(self.data.headers) if self.data.headers is not None else 0
+        for r in self.data.rows:
+            if len(r) > w:
+                w = len(r)
+        return w
+
+    def _resolve(self, col: Union[str, int, float]) -> int:
+        if isinstance(col, bool):
+            raise CSVError("UNKNOWN_COLUMN", f"[UNKNOWN_COLUMN] column index out of range: {col}")
+        if isinstance(col, str):
+            idx = -1
+            if self.data.headers is not None:
+                try:
+                    idx = self.data.headers.index(col)
+                except ValueError:
+                    idx = -1
+            if idx < 0:
+                raise CSVError("UNKNOWN_COLUMN", f"[UNKNOWN_COLUMN] unknown column: {col}")
+            return idx
+        if isinstance(col, float):
+            if not col.is_integer():
+                raise CSVError("UNKNOWN_COLUMN", f"[UNKNOWN_COLUMN] column index out of range: {col}")
+            col = int(col)
+        if col < 0 or col >= self._width():
+            raise CSVError("UNKNOWN_COLUMN", f"[UNKNOWN_COLUMN] column index out of range: {col}")
+        return int(col)
+
+    def _name(self, idx: int) -> str:
+        if self.data.headers is not None and idx < len(self.data.headers):
+            return self.data.headers[idx]
+        return f"col_{idx}"
+
+    def aggregate(self, options: AggregationOptions) -> List[Dict[str, Any]]:
+        g = self._resolve(options.group_by)
+        sums = [self._resolve(c) for c in (options.sum or [])]
+        avgs = [self._resolve(c) for c in (options.avg or [])]
+        group_name = self._name(g)
+
+        groups: Dict[str, Dict[str, Any]] = {}
+        for row in self.data.rows:
+            key = row[g] if g < len(row) else ""
+            acc = groups.get(key)
+            if acc is None:
+                acc = {"key": key, "count": 0, "sum": [0.0] * len(sums), "avg_sum": [0.0] * len(avgs), "avg_n": [0] * len(avgs)}
+                groups[key] = acc
+            acc["count"] += 1
+            for k, c in enumerate(sums):
+                v = _strip(row[c] if c < len(row) else "")
+                if is_number(v):
+                    acc["sum"][k] += float(v)
+            for k, c in enumerate(avgs):
+                v = _strip(row[c] if c < len(row) else "")
+                if is_number(v):
+                    acc["avg_sum"][k] += float(v)
+                    acc["avg_n"][k] += 1
+
+        out: List[Dict[str, Any]] = []
+        for acc in groups.values():
+            r: Dict[str, Any] = {group_name: acc["key"]}
+            for k, c in enumerate(sums):
+                r[f"{self._name(c)}_sum"] = acc["sum"][k]
+            for k, c in enumerate(avgs):
+                r[f"{self._name(c)}_avg"] = None if acc["avg_n"][k] == 0 else acc["avg_sum"][k] / acc["avg_n"][k]
+            if options.count:
+                r["count"] = acc["count"]
+            out.append(r)
+        return out
+
+
+class CSV:
+    """Main API combining parser, generator and aggregator."""
+
+    def __init__(self, data: str, options: Optional[CSVOptions] = None) -> None:
+        parser = CSVParser(data, options)
+        has_header = options.has_header if options is not None and options.has_header is not None else True
+        self._data = parser.parse(has_header)
+
+    def to_html(self, options: Optional[HTMLOptions] = None) -> str:
+        return HTMLGenerator(self._data).generate(options)
+
+    def aggregate(self, options: AggregationOptions) -> List[Dict[str, Any]]:
+        return CSVAggregator(self._data).aggregate(options)
+
+    def get_headers(self) -> Optional[List[str]]:
+        return self._data.headers
+
+    def get_rows(self) -> List[List[str]]:
+        return self._data.rows
+
+    def get_types(self) -> List[DataType]:
+        return self._data.types
+
+    def to_json(self) -> Union[List[Dict[str, str]], List[List[str]]]:
+        """Rows as objects keyed by header (SPEC section 6). Missing cells become
+        "", extra cells are dropped, and for duplicate header names the last
+        column wins. Without a header row the raw rows are returned."""
+        headers = self._data.headers
+        if headers is None:
+            return self._data.rows
+        out: List[Dict[str, str]] = []
+        for row in self._data.rows:
+            obj: Dict[str, str] = {}
+            for i, h in enumerate(headers):
+                obj[h] = row[i] if i < len(row) else ""
+            out.append(obj)
+        return out

lombokcsv-1.1.0/lombokcsv.egg-info/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: lombokcsv
+Version: 1.1.0
+Summary: RFC 4180 CSV parser with type detection, safe HTML tables, JSON export and GROUP BY aggregation. Pure Python, zero dependencies. Part of the Lombok Ecosystem.
+Author: codinglombok
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/codinglombok/LombokCSV
+Project-URL: Issues, https://github.com/codinglombok/LombokCSV/issues
+Keywords: csv,rfc4180,parser,group-by,type-detection,zero-dependency,lombok-ecosystem
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# LombokCSV — Python port
+
+Python implementation of the [LombokCSV](../../README.md) contract: RFC 4180 CSV parsing, column type detection, safe HTML tables, JSON export and GROUP BY aggregation. Zero runtime dependencies.
+
+| Item | Value |
+|---|---|
+| Package | `lombokcsv` (PyPI) |
+| Version | 1.1.0 |
+| Contract | [SPEC](../../docs/SPEC_LombokCSV_v1.1.0.md) |
+| Vectors | runs all 152 cases in [`vectors/lombokcsv-vectors-v1.json`](../../vectors/lombokcsv-vectors-v1.json) |
+| Acceptance | every vector case passes with byte-identical results (GP-11) |
+| Python | >= 3.9 |
+
+## Installation
+
+```bash
+pip install lombokcsv
+```
+
+The package has not been published to PyPI yet; until then install from the repository root (`pip install ./python`).
+
+## Quick start
+
+```python
+from lombokcsv import CSV, AggregationOptions
+
+csv = CSV("Region,Product,Qty\nWest,Rice,120\nWest,Corn,80\nEast,Rice,95")
+
+csv.get_headers()  # ['Region', 'Product', 'Qty']
+csv.get_types()    # ['string', 'string', 'number']
+csv.to_json()      # [{'Region': 'West', 'Product': 'Rice', 'Qty': '120'}, ...]
+csv.to_html()
+
+csv.aggregate(AggregationOptions(group_by="Region", sum=["Qty"], avg=["Qty"], count=True))
+# [{'Region': 'West', 'Qty_sum': 200.0, 'Qty_avg': 100.0, 'count': 2},
+#  {'Region': 'East', 'Qty_sum': 95.0, 'Qty_avg': 95.0, 'count': 1}]
+```
+
+The Python API mirrors the TypeScript reference with PEP 8 names: `toJSON` → `to_json`, `getHeaders` → `get_headers`, `className` → `class_name`, `hasHeader` → `has_header`. Behaviour, error codes (`INVALID_OPTION`, `UNKNOWN_COLUMN`) and the `[CODE] message` texts are identical across ports (SPEC section 7).
+
+## Development
+
+```bash
+python -m pip install pytest coverage
+python -m coverage run --branch --source=lombokcsv -m pytest -q
+python -m coverage report -m --fail-under=90
+```
+
+Contributions are welcome; see [CONTRIBUTING.md](../../CONTRIBUTING.md).

lombokcsv-1.1.0/lombokcsv.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+lombokcsv/__init__.py
+lombokcsv/csv.py
+lombokcsv/py.typed
+lombokcsv.egg-info/PKG-INFO
+lombokcsv.egg-info/SOURCES.txt
+lombokcsv.egg-info/dependency_links.txt
+lombokcsv.egg-info/top_level.txt
+tests/test_api.py

lombokcsv-1.1.0/lombokcsv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lombokcsv-1.1.0/lombokcsv.egg-info/top_level.txt

@@ -0,0 +1 @@
+lombokcsv

lombokcsv-1.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "lombokcsv"
+version = "1.1.0"
+description = "RFC 4180 CSV parser with type detection, safe HTML tables, JSON export and GROUP BY aggregation. Pure Python, zero dependencies. Part of the Lombok Ecosystem."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "codinglombok" }]
+requires-python = ">=3.9"
+keywords = ["csv", "rfc4180", "parser", "group-by", "type-detection", "zero-dependency", "lombok-ecosystem"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Text Processing :: Markup",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/codinglombok/LombokCSV"
+Issues = "https://github.com/codinglombok/LombokCSV/issues"
+
+[tool.setuptools]
+packages = ["lombokcsv"]
+
+[tool.setuptools.package-data]
+lombokcsv = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

lombokcsv-1.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lombokcsv-1.1.0/tests/test_api.py

@@ -0,0 +1,212 @@
+"""Unit tests for the Python port (mirrors the TypeScript unit suite)."""
+
+from __future__ import annotations
+
+import pytest
+
+import lombokcsv
+from lombokcsv import CSV, CSVError, CSVOptions, CSVParser, AggregationOptions
+
+
+def test_version() -> None:
+    assert lombokcsv.__version__ == "1.1.0"
+
+
+def test_parses_simple_csv() -> None:
+    csv = CSV("a,b,c\n1,2,3")
+    assert csv.get_rows() == [["1", "2", "3"]]
+
+
+def test_parses_with_headers() -> None:
+    csv = CSV("Name,Age,City\nJohn,30,NYC")
+    assert csv.get_headers() == ["Name", "Age", "City"]
+    assert len(csv.get_rows()) == 1
+
+
+def test_handles_quoted_fields() -> None:
+    csv = CSV('"Name","Age"\n"John Smith",30')
+    assert csv.get_headers() == ["Name", "Age"]
+    assert csv.get_rows()[0][0] == "John Smith"
+
+
+def test_handles_commas_inside_quotes() -> None:
+    csv = CSV('Name,Address\n"Smith, John","123 Main, Apt 4"')
+    assert csv.get_rows()[0][0] == "Smith, John"
+    assert csv.get_rows()[0][1] == "123 Main, Apt 4"
+
+
+def test_handles_newlines_inside_quotes() -> None:
+    csv = CSV('Name,Description\n"John","Line 1\nLine 2"')
+    assert len(csv.get_rows()) == 1
+
+
+def test_parses_multiple_rows() -> None:
+    csv = CSV("A,B\n1,2\n3,4\n5,6")
+    assert len(csv.get_rows()) == 3
+
+
+def test_detects_types() -> None:
+    csv = CSV("Name,Value,Date,Active\nTest,123,2026-01-01,true")
+    types = csv.get_types()
+    assert types == ["string", "number", "date", "boolean"]
+
+
+def test_boolean_detection() -> None:
+    csv = CSV("b\ntrue\nFALSE\nYes\nno")
+    assert csv.get_types() == ["boolean"]
+
+
+def test_mixed_column_falls_back_to_string() -> None:
+    csv = CSV("m\n1\nabc")
+    assert csv.get_types() == ["string"]
+
+
+def test_generates_html() -> None:
+    csv = CSV("Name,Age\nJohn,30")
+    html = csv.to_html()
+    assert "<table>" in html
+    assert "<thead>" in html
+    assert "<th>Name</th>" in html
+    assert '<td style="text-align: right">30</td>' in html
+
+
+def test_escapes_html_in_content() -> None:
+    csv = CSV("Name\n<script>alert(\"xss\")</script>")
+    html = csv.to_html()
+    assert "<script>" not in html
+    assert "&lt;script&gt;" in html
+
+
+def test_escapes_class_and_id_attributes() -> None:
+    csv = CSV("A\n1")
+    html = csv.to_html(lombokcsv.HTMLOptions(class_name='data-table', id='t1'))
+    assert 'class="data-table"' in html
+    assert 'id="t1"' in html
+    evil = CSV("A\nx").to_html(lombokcsv.HTMLOptions(class_name='" onclick="alert(1)'))
+    assert 'onclick="alert(1)"' not in evil
+
+
+def test_aggregation_group_by() -> None:
+    data = "Department,Employee,Salary\nIT,John,50000\nIT,Jane,55000\nSales,Bob,40000\nSales,Alice,45000"
+    csv = CSV(data)
+    result = csv.aggregate(AggregationOptions(group_by="Department", sum=["Salary"], count=True))
+    by_dept = {r["Department"]: r for r in result}
+    assert by_dept["IT"]["Salary_sum"] == 105000
+    assert by_dept["Sales"]["Salary_sum"] == 85000
+    assert by_dept["IT"]["count"] == 2
+
+
+def test_aggregation_avg_ignores_non_numeric() -> None:
+    csv = CSV("g,v\nx,1\nx,abc\nx,\nx,2")
+    result = csv.aggregate(AggregationOptions(group_by="g", sum=["v"], avg=["v"], count=True))
+    assert result == [{"g": "x", "v_sum": 3.0, "v_avg": 1.5, "count": 4}]
+
+
+def test_avg_null_without_numbers() -> None:
+    csv = CSV("g,v\nx,abc")
+    result = csv.aggregate(AggregationOptions(group_by="g", sum=["v"], avg=["v"]))
+    assert result == [{"g": "x", "v_sum": 0, "v_avg": None}]
+
+
+def test_unknown_column_error() -> None:
+    csv = CSV("a,b\n1,2")
+    with pytest.raises(CSVError) as excinfo:
+        csv.aggregate(AggregationOptions(group_by="Missing", count=True))
+    assert excinfo.value.code == "UNKNOWN_COLUMN"
+    assert str(excinfo.value) == "[UNKNOWN_COLUMN] unknown column: Missing"
+
+
+def test_index_out_of_range_error() -> None:
+    csv = CSV("a,b\n1,2")
+    with pytest.raises(CSVError) as excinfo:
+        csv.aggregate(AggregationOptions(group_by=3))
+    assert excinfo.value.code == "UNKNOWN_COLUMN"
+    assert str(excinfo.value) == "[UNKNOWN_COLUMN] column index out of range: 3"
+
+
+def test_invalid_option_error() -> None:
+    with pytest.raises(CSVError) as excinfo:
+        CSV("a,b", CSVOptions(delimiter=""))
+    assert excinfo.value.code == "INVALID_OPTION"
+    assert str(excinfo.value) == "[INVALID_OPTION] delimiter must be a single character other than CR/LF"
+
+
+def test_delimiter_equals_quote_error() -> None:
+    with pytest.raises(CSVError) as excinfo:
+        CSV("a,b", CSVOptions(delimiter='"'))
+    assert excinfo.value.code == "INVALID_OPTION"
+    assert str(excinfo.value) == "[INVALID_OPTION] delimiter and quote must differ"
+
+
+def test_json_export() -> None:
+    csv = CSV("Name,Age\nJohn,30\nJane,25")
+    assert csv.to_json() == [{"Name": "John", "Age": "30"}, {"Name": "Jane", "Age": "25"}]
+
+
+def test_json_without_header() -> None:
+    csv = CSV("1,2\n3,4", lombokcsv.CSVOptions(has_header=False))
+    assert csv.to_json() == [["1", "2"], ["3", "4"]]
+
+
+def test_duplicate_headers_last_wins() -> None:
+    csv = CSV("a,a\n1,2")
+    assert csv.to_json() == [{"a": "2"}]
+
+
+def test_missing_cells_fill_empty_string() -> None:
+    csv = CSV("a,b\n1")
+    assert csv.to_json() == [{"a": "1", "b": ""}]
+
+
+def test_empty_csv() -> None:
+    csv = CSV("")
+    assert csv.get_rows() == []
+    assert csv.get_headers() is None
+
+
+def test_windows_line_endings() -> None:
+    csv = CSV("A,B\r\n1,2\r\n3,4")
+    assert len(csv.get_rows()) == 2
+
+
+def test_bom_is_removed() -> None:
+    csv = CSV("a,b\n1,2")
+    assert csv.get_headers() == ["a", "b"]
+
+
+def test_blank_lines_are_skipped() -> None:
+    csv = CSV("a,b\n\n1,2")
+    assert csv.get_rows() == [["1", "2"]]
+
+
+def test_unterminated_quote_is_lenient() -> None:
+    parser = CSVParser('"unterminated,x\ny')
+    assert parser.parse_rows() == [["unterminated,x\ny"]]
+
+
+def test_parser_parse_rows_includes_header_row() -> None:
+    parser = CSVParser("a,b\n1,2")
+    assert parser.parse_rows() == [["a", "b"], ["1", "2"]]
+
+
+def test_trim_false_keeps_blanks() -> None:
+    parser = CSVParser("  a  ,  b  ", CSVOptions(trim=False))
+    assert parser.parse_rows() == [["  a  ", "  b  "]]
+
+
+def test_quoted_content_is_never_trimmed() -> None:
+    parser = CSVParser('" a ",b')
+    assert parser.parse_rows() == [[" a ", "b"]]
+
+
+def test_custom_delimiter_and_quote() -> None:
+    parser = CSVParser("'a,b',c", CSVOptions(quote="'"))
+    assert parser.parse_rows() == [["a,b", "c"]]
+    parser2 = CSVParser("a;b;c\n1;2;3", CSVOptions(delimiter=";"))
+    assert parser2.parse_rows() == [["a", "b", "c"], ["1", "2", "3"]]
+
+
+def test_large_csv() -> None:
+    rows = "\n".join(f"{i},value_{i}" for i in range(1000))
+    csv = CSV(f"ID,Value\n{rows}")
+    assert len(csv.get_rows()) == 1000