typedcsv-lib 0.1.0__tar.gz

typedcsv_lib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tiago Tresoldi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typedcsv_lib-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: typedcsv-lib
+Version: 0.1.0
+Summary: Typed CSVs via header-embedded types and validators
+Author: Tiago Tresoldi
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tresoldi/typedcsv
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# typedcsv
+
+Typed CSVs via **header-embedded types** (sigils or `:type`) plus optional **header-embedded validation** — **stdlib-only**, Python **3.10+**.
+
+The core lives in a single module and is copy-pasteable into projects.
+
+```bash
+pip install typedcsv-lib
+```
+
+---
+
+## Header typing
+
+Declare types using either **suffix sigils** or **explicit `:type`** (not both on the same column).
+
+| Type       | Sigil (suffix) | Explicit     |
+|------------|-----------------|--------------|
+| `int`      | `#`             | `:int`       |
+| `float`    | `%`             | `:float`     |
+| `bool`     | `?`             | `:bool`      |
+| `datetime` | `@`             | `:datetime`  |
+| `str`      | `$`             | `:str`       |
+
+Untyped columns default to `str`.
+
+**Logical column names** are the header names with the type marker removed:
+
+- `age#` becomes key `"age"`
+- `created:datetime` becomes key `"created"`
+
+---
+
+## Validators
+
+Add an optional validator clause after the type marker:
+
+```text
+age# [min=0 max=120]
+ratio% [min=0 max=1]
+status$ [in=OPEN|CLOSED|PENDING]
+code$ [re=^[A-Z]{3}\d{2}$]
+created@ [min=2020-01-01T00:00:00 max=2030-12-31T23:59:59]
+```
+
+Notes:
+
+- Validators are space-separated `key=value` pairs inside `[ ... ]`.
+- `re=` uses Python `re.fullmatch`.
+- `in=` uses `|` as separator.
+- Unknown validator keys raise an error.
+
+---
+
+## Missing values (nullable by default)
+
+- An empty cell (`""`) is missing.
+- For `str` columns, missing stays `""`.
+- For non-`str` columns, missing becomes `None`.
+- Missing values skip validation.
+
+---
+
+## Reading
+
+```python
+import typedcsv
+
+with open("data.csv", newline="") as f:
+    for row in typedcsv.DictReader(f):
+        print(row)
+```
+
+Example CSV:
+
+```csv
+id#,name$,active?,created@
+1,Alice,true,2021-05-01T12:30:00
+2,Bob,false,
+```
+
+Produces:
+
+```python
+{'id': 1, 'name': 'Alice', 'active': True, 'created': datetime(2021, 5, 1, 12, 30)}
+{'id': 2, 'name': 'Bob', 'active': False, 'created': None}
+```
+
+---
+
+## Writing (canonical formatting)
+
+- `None` → empty cell
+- `bool` → `true` / `false`
+- `datetime` → `isoformat()`
+- `float` → `repr(f)`
+- Header preserved exactly as provided to `DictWriter(fieldnames=...)`
+
+```python
+import typedcsv
+from datetime import datetime
+
+rows = [
+    {"id": 1, "name": "Alice", "active": True, "created": datetime(2021, 5, 1, 12, 30)},
+    {"id": 2, "name": "Bob", "active": False, "created": None},
+]
+
+with open("out.csv", "w", newline="") as f:
+    w = typedcsv.DictWriter(f, fieldnames=["id#", "name$", "active?", "created@"])
+    w.writeheader()
+    w.writerows(rows)
+```
+
+---
+
+## More examples
+
+### Validators with quoted values
+
+```csv
+name$ [in="Alice Smith"|Bob]
+```
+
+### Regex validation (fullmatch)
+
+```csv
+code$ [re=^[A-Z]{3}\d{2}$]
+ABC12
+```
+
+### Type inference for untyped columns
+
+```python
+import typedcsv
+import io
+
+data = "a,b\n1,true\n2,false\n"
+rows = list(typedcsv.DictReader(io.StringIO(data), infer_types=True))
+```
+
+---
+
+## Errors
+
+Parsing/validation failures raise `TypedCSVError` with context:
+
+- `row` (1-based; header row is 1)
+- `col` (0-based)
+- `column` (logical name)
+- `header` (raw header cell)
+- `value` (raw cell)
+- `reason` (short message)
+
+---
+
+## API reference (csv-compatible)
+
+typedcsv mirrors Python's `csv` module API and is designed to be a drop-in replacement where you want typed rows.
+
+- `typedcsv.reader(f, ...)` → yields typed list rows (header consumed)
+- `typedcsv.DictReader(f, ...)` → yields typed dict rows keyed by logical names (header consumed)
+- `typedcsv.writer(f, ...)` → returns a standard `csv.writer`
+- `typedcsv.DictWriter(f, fieldnames, ...)` → writes typed dict rows with canonical formatting
+
+---

typedcsv_lib-0.1.0/README.md

@@ -0,0 +1,165 @@
+# typedcsv
+
+Typed CSVs via **header-embedded types** (sigils or `:type`) plus optional **header-embedded validation** — **stdlib-only**, Python **3.10+**.
+
+The core lives in a single module and is copy-pasteable into projects.
+
+```bash
+pip install typedcsv-lib
+```
+
+---
+
+## Header typing
+
+Declare types using either **suffix sigils** or **explicit `:type`** (not both on the same column).
+
+| Type       | Sigil (suffix) | Explicit     |
+|------------|-----------------|--------------|
+| `int`      | `#`             | `:int`       |
+| `float`    | `%`             | `:float`     |
+| `bool`     | `?`             | `:bool`      |
+| `datetime` | `@`             | `:datetime`  |
+| `str`      | `$`             | `:str`       |
+
+Untyped columns default to `str`.
+
+**Logical column names** are the header names with the type marker removed:
+
+- `age#` becomes key `"age"`
+- `created:datetime` becomes key `"created"`
+
+---
+
+## Validators
+
+Add an optional validator clause after the type marker:
+
+```text
+age# [min=0 max=120]
+ratio% [min=0 max=1]
+status$ [in=OPEN|CLOSED|PENDING]
+code$ [re=^[A-Z]{3}\d{2}$]
+created@ [min=2020-01-01T00:00:00 max=2030-12-31T23:59:59]
+```
+
+Notes:
+
+- Validators are space-separated `key=value` pairs inside `[ ... ]`.
+- `re=` uses Python `re.fullmatch`.
+- `in=` uses `|` as separator.
+- Unknown validator keys raise an error.
+
+---
+
+## Missing values (nullable by default)
+
+- An empty cell (`""`) is missing.
+- For `str` columns, missing stays `""`.
+- For non-`str` columns, missing becomes `None`.
+- Missing values skip validation.
+
+---
+
+## Reading
+
+```python
+import typedcsv
+
+with open("data.csv", newline="") as f:
+    for row in typedcsv.DictReader(f):
+        print(row)
+```
+
+Example CSV:
+
+```csv
+id#,name$,active?,created@
+1,Alice,true,2021-05-01T12:30:00
+2,Bob,false,
+```
+
+Produces:
+
+```python
+{'id': 1, 'name': 'Alice', 'active': True, 'created': datetime(2021, 5, 1, 12, 30)}
+{'id': 2, 'name': 'Bob', 'active': False, 'created': None}
+```
+
+---
+
+## Writing (canonical formatting)
+
+- `None` → empty cell
+- `bool` → `true` / `false`
+- `datetime` → `isoformat()`
+- `float` → `repr(f)`
+- Header preserved exactly as provided to `DictWriter(fieldnames=...)`
+
+```python
+import typedcsv
+from datetime import datetime
+
+rows = [
+    {"id": 1, "name": "Alice", "active": True, "created": datetime(2021, 5, 1, 12, 30)},
+    {"id": 2, "name": "Bob", "active": False, "created": None},
+]
+
+with open("out.csv", "w", newline="") as f:
+    w = typedcsv.DictWriter(f, fieldnames=["id#", "name$", "active?", "created@"])
+    w.writeheader()
+    w.writerows(rows)
+```
+
+---
+
+## More examples
+
+### Validators with quoted values
+
+```csv
+name$ [in="Alice Smith"|Bob]
+```
+
+### Regex validation (fullmatch)
+
+```csv
+code$ [re=^[A-Z]{3}\d{2}$]
+ABC12
+```
+
+### Type inference for untyped columns
+
+```python
+import typedcsv
+import io
+
+data = "a,b\n1,true\n2,false\n"
+rows = list(typedcsv.DictReader(io.StringIO(data), infer_types=True))
+```
+
+---
+
+## Errors
+
+Parsing/validation failures raise `TypedCSVError` with context:
+
+- `row` (1-based; header row is 1)
+- `col` (0-based)
+- `column` (logical name)
+- `header` (raw header cell)
+- `value` (raw cell)
+- `reason` (short message)
+
+---
+
+## API reference (csv-compatible)
+
+typedcsv mirrors Python's `csv` module API and is designed to be a drop-in replacement where you want typed rows.
+
+- `typedcsv.reader(f, ...)` → yields typed list rows (header consumed)
+- `typedcsv.DictReader(f, ...)` → yields typed dict rows keyed by logical names (header consumed)
+- `typedcsv.writer(f, ...)` → returns a standard `csv.writer`
+- `typedcsv.DictWriter(f, fieldnames, ...)` → writes typed dict rows with canonical formatting
+
+---

typedcsv_lib-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "typedcsv-lib"
+version = "0.1.0"
+description = "Typed CSVs via header-embedded types and validators"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  {name = "Tiago Tresoldi"}
+]
+urls = {"Homepage" = "https://github.com/tresoldi/typedcsv"}
+
+[project.optional-dependencies]
+dev = ["pytest", "ruff", "mypy", "twine"]
+
+[tool.setuptools]
+packages = ["typedcsv"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_return_any = true
+disallow_untyped_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+
+[[tool.mypy.overrides]]
+module = ["test_typedcsv", "tests.test_typedcsv"]
+disallow_untyped_defs = false

typedcsv_lib-0.1.0/setup.cfg

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

typedcsv_lib-0.1.0/tests/test_typedcsv.py

@@ -0,0 +1,157 @@
+import io
+import importlib.util
+import sys
+from datetime import datetime
+from pathlib import Path
+
+import pytest
+
+_PKG_INIT = Path(__file__).resolve().parents[1] / "typedcsv" / "__init__.py"
+_SPEC = importlib.util.spec_from_file_location("typedcsv_pkg", _PKG_INIT)
+assert _SPEC and _SPEC.loader
+typedcsv = importlib.util.module_from_spec(_SPEC)
+sys.modules[_SPEC.name] = typedcsv
+_SPEC.loader.exec_module(typedcsv)
+
+
+def read_rows(text, **kwargs):
+    f = io.StringIO(text)
+    return list(typedcsv.reader(f, **kwargs))
+
+
+def read_dicts(text, **kwargs):
+    f = io.StringIO(text)
+    return list(typedcsv.DictReader(f, **kwargs))
+
+
+def test_header_parsing_conflict_sigil_and_explicit():
+    text = "age#:int\n1\n"
+    with pytest.raises(typedcsv.TypedCSVError) as exc:
+        read_rows(text)
+    assert "both explicit type and sigil" in str(exc.value)
+
+
+def test_header_parsing_unknown_explicit_type_is_error():
+    text = "age:integer\n1\n"
+    with pytest.raises(typedcsv.TypedCSVError) as exc:
+        read_rows(text)
+    assert "Unknown explicit type" in str(exc.value)
+
+
+def test_header_parsing_duplicate_logical_names():
+    text = "age#,age:int\n1,2\n"
+    with pytest.raises(typedcsv.TypedCSVError) as exc:
+        read_rows(text)
+    assert "Duplicate logical column name" in str(exc.value)
+
+
+def test_header_parsing_malformed_validators_clause():
+    text = "age# [min=0\n1\n"
+    with pytest.raises(typedcsv.TypedCSVError) as exc:
+        read_rows(text)
+    assert "Malformed validators clause" in str(exc.value)
+
+
+def test_validators_enforcement_int_min_max_in():
+    text = "age# [min=0 max=10 in=1|2|3]\n2\n4\n"
+    f = io.StringIO(text)
+    r = typedcsv.reader(f)
+    assert next(r)[0] == 2
+    with pytest.raises(typedcsv.TypedCSVError):
+        next(r)
+
+
+def test_validators_unknown_key_error():
+    text = "age# [nope=1]\n1\n"
+    with pytest.raises(typedcsv.TypedCSVError) as exc:
+        read_rows(text)
+    assert "not allowed" in str(exc.value)
+
+
+def test_missing_values_behavior():
+    text = "name$,age#\n,\n"
+    rows = read_rows(text)
+    assert rows[0][0] == ""
+    assert rows[0][1] is None
+
+
+def test_missing_values_skip_validation():
+    text = "age# [min=10]\n\n"
+    rows = read_rows(text)
+    assert rows[0][0] is None
+
+
+def test_bool_parsing_variants():
+    text = "b?\ntrue\nFALSE\nT\nf\nYes\nno\n1\n0\n"
+    rows = read_rows(text)
+    assert [r[0] for r in rows] == [True, False, True, False, True, False, True, False]
+
+
+def test_datetime_parsing_and_min_max():
+    text = "ts@ [min=2020-01-01T00:00:00 max=2020-12-31T23:59:59]\n2020-06-01T12:00:00\n2019-01-01T00:00:00\n"
+    f = io.StringIO(text)
+    r = typedcsv.reader(f)
+    assert isinstance(next(r)[0], datetime)
+    with pytest.raises(typedcsv.TypedCSVError):
+        next(r)
+
+
+def test_re_fullmatch_for_str():
+    text = "code$ [re=^[A-Z]{3}\\d{2}$]\nABC12\nAB12\n"
+    f = io.StringIO(text)
+    r = typedcsv.reader(f)
+    assert next(r)[0] == "ABC12"
+    with pytest.raises(typedcsv.TypedCSVError):
+        next(r)
+
+
+def test_error_context_fields_for_parse_error():
+    text = "age#\nnope\n"
+    with pytest.raises(typedcsv.TypedCSVError) as exc:
+        read_rows(text)
+    err = exc.value
+    assert err.row == 2
+    assert err.col == 0
+    assert err.column == "age"
+    assert err.header == "age#"
+    assert err.value == "nope"
+    assert "Parse failed" in err.reason
+
+
+def test_writer_canonicalization_and_float_repr():
+    f = io.StringIO()
+    w = typedcsv.DictWriter(f, fieldnames=["i#", "b?", "f%", "t@", "s$"])
+    w.writeheader()
+    w.writerow({
+        "i": 1,
+        "b": True,
+        "f": 1.5,
+        "t": datetime(2021, 5, 1, 12, 30),
+        "s": "x",
+    })
+    out = f.getvalue().splitlines()
+    assert out[0] == "i#,b?,f%,t@,s$"
+    assert out[1].startswith("1,true,1.5,2021-05-01T12:30:00,x")
+
+
+def test_round_trip_dictwriter_to_dictreader():
+    f = io.StringIO()
+    w = typedcsv.DictWriter(f, fieldnames=["id#", "name$", "active?", "created@"])
+    w.writeheader()
+    w.writerow({"id": 1, "name": "Alice", "active": True, "created": datetime(2021, 5, 1, 12, 30)})
+    w.writerow({"id": 2, "name": "Bob", "active": False, "created": None})
+
+    f.seek(0)
+    rows = list(typedcsv.DictReader(f))
+    assert rows[0]["id"] == 1
+    assert rows[0]["name"] == "Alice"
+    assert rows[0]["active"] is True
+    assert rows[0]["created"] == datetime(2021, 5, 1, 12, 30)
+    assert rows[1]["created"] is None
+
+
+def test_infer_types_untyped_only_without_validators():
+    text = "a,b [minlen=1]\n1,x\n2,y\n"
+    rows = read_rows(text, infer_types=True)
+    assert rows[0][0] == 1
+    assert rows[0][1] == "x"