shipit-csv-validator 0.1.0__py3-none-any.whl

shipit_csv_validator/__init__.py

@@ -0,0 +1,5 @@
+"""Local CSV validation; values remain strings and input is never modified."""
+from .validate import validate_csv
+
+__all__ = ["validate_csv"]
+__version__ = "0.1.0"

shipit_csv_validator/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

shipit_csv_validator/cli.py

@@ -0,0 +1,106 @@
+"""Bounded UTF-8 CSV command-line input; never writes the source file."""
+import json
+import re
+import sys
+
+from . import __version__
+from .validate import _units, validate_csv
+
+LIMIT = 32 * 1024 * 1024
+HELP = """Usage: shipit-csv-validate [options] [FILE|-]
+Validate a UTF-8 CSV file or standard input without changing its contents.
+
+Options:
+  --json              Print a stable JSON report
+  --delimiter CHAR    Use one delimiter character (use "tab" for a tab)
+  --no-header         Treat the first record as data
+  --max-errors N      Maximum reported diagnostics (1-10000; default 100)
+  --help              Show this help
+  --version           Show the version
+  --                  End options; allows filenames starting with a dash
+
+Exit codes: 0 valid, 1 invalid CSV, 2 usage or input error.
+Limit: buffered UTF-8 input, up to 32 MiB. No type/schema inference.
+"""
+
+
+def _fail(json_mode, code, message):
+    if json_mode:
+        print(json.dumps({"valid": False, "error": {"code": code, "message": message}},
+                         ensure_ascii=True, separators=(",", ":")))
+    else:
+        print(message, file=sys.stderr)
+    return 2
+
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    boundary = args.index("--") if "--" in args else len(args)
+    json_mode = "--json" in args[:boundary]
+    delimiter, header, max_errors, filename = ",", True, 100, None
+    end_options = False
+    index = 0
+    try:
+        while index < len(args):
+            argument = args[index]
+            index += 1
+            if not end_options and argument == "--":
+                end_options = True
+                continue
+            if not end_options and argument == "--json":
+                continue
+            if not end_options and argument == "--help":
+                print(HELP, end="")
+                return 0
+            if not end_options and argument == "--version":
+                print(__version__)
+                return 0
+            if not end_options and argument == "--no-header":
+                header = False
+                continue
+            if not end_options and argument in ("--delimiter", "--max-errors"):
+                raw = args[index] if index < len(args) else None
+                index += 1
+                if argument == "--delimiter":
+                    delimiter = "\t" if raw == "tab" else raw
+                    if (not isinstance(delimiter, str) or len(_units(delimiter)) != 1
+                            or delimiter in ('"', "\r", "\n", "\0")):
+                        raise TypeError("Delimiter must be one character other than quote, newline or NUL")
+                else:
+                    if raw is None or len(raw) > 5 or not re.fullmatch(r"[1-9][0-9]*", raw) or int(raw) > 10000:
+                        raise TypeError("Maximum errors must be 1-10000")
+                    max_errors = int(raw)
+                continue
+            if not end_options and argument.startswith("-") and argument != "-":
+                raise TypeError("Unknown option; use --help")
+            if filename is not None:
+                raise TypeError("Provide one file, or standard input")
+            filename = argument
+    except TypeError as error:
+        return _fail(json_mode, "USAGE", str(error))
+    try:
+        if filename is None or filename == "-":
+            data = sys.stdin.buffer.read(LIMIT + 1)
+        else:
+            with open(filename, "rb") as source:
+                data = source.read(LIMIT + 1)
+    except (OSError, ValueError):
+        return _fail(json_mode, "INPUT_READ", "Could not read input")
+    if len(data) > LIMIT:
+        return _fail(json_mode, "INPUT_LIMIT", "Input exceeds the 32 MiB limit")
+    try:
+        text = data.decode("utf-8", "strict")
+    except UnicodeDecodeError:
+        return _fail(json_mode, "INPUT_ENCODING", "Input must be valid UTF-8")
+    report = validate_csv(text, delimiter=delimiter, header=header, max_errors=max_errors)
+    if json_mode:
+        print(json.dumps(report, ensure_ascii=True, separators=(",", ":")))
+    elif report["valid"]:
+        print(f'Valid CSV: {report["dataRecords"]} data records, {report["columns"]} columns')
+    else:
+        for issue in report["diagnostics"]:
+            print(f'{issue["code"]}: record {issue["record"]}, field {issue["field"]}, '
+                  f'line {issue["line"]}, column {issue["column"]}: {issue["message"]}')
+        if report["diagnosticsTruncated"]:
+            print("Additional diagnostics omitted")
+    return 0 if report["valid"] else 1

shipit_csv_validator/validate.py

@@ -0,0 +1,157 @@
+"""CSV conformance v1 without type inference or external dependencies."""
+
+
+def _units(text: str) -> str:
+    """Use UTF-16 units for the cross-language delimiter/column contract."""
+    data = text.encode("utf-16-le", "surrogatepass")
+    return "".join(chr(data[i] | data[i + 1] << 8) for i in range(0, len(data), 2))
+
+
+def validate_csv(
+    text: str, *, delimiter: str = ",", header: bool = True, max_errors: int = 100
+) -> dict[str, object]:
+    """Validate complete CSV text and return the shared JSON-compatible report.
+
+    Positions are one-based UTF-16 columns. The API has no byte limit; the CLI
+    bounds input at 32 MiB. No filesystem, network, environment or cell execution
+    occurs. Invalid arguments raise TypeError.
+    """
+    if not isinstance(text, str):
+        raise TypeError("Input must be a string")
+    if (
+        not isinstance(delimiter, str)
+        or len(_units(delimiter)) != 1
+        or delimiter in ('"', "\r", "\n", "\0")
+    ):
+        raise TypeError("Delimiter must be one character other than quote, newline or NUL")
+    if type(header) is not bool or type(max_errors) is not int or not 1 <= max_errors <= 10000:
+        raise TypeError("Invalid validation options")
+    source = _units(text[1:] if text.startswith("\ufeff") else text)
+    delimiter = _units(delimiter)
+    rows = []
+    diagnostics = []
+    truncated = False
+    record = line = column = 1
+    row_start = (line, column)
+    field_start = (line, column)
+    fields = []
+    value = []
+    state = "start"
+    row_touched = fatal = False
+
+    def error(code, message, at=None, field=None, row_number=None):
+        nonlocal truncated
+        if len(diagnostics) < max_errors:
+            at_line, at_column = (line, column) if at is None else at
+            diagnostics.append({
+                "code": code, "message": message,
+                "record": record if row_number is None else row_number,
+                "field": len(fields) + 1 if field is None else field,
+                "line": at_line, "column": at_column,
+            })
+        else:
+            truncated = True
+
+    def finish_field():
+        nonlocal value, state
+        fields.append(("".join(value), field_start))
+        value = []
+        state = "start"
+
+    def finish_record():
+        nonlocal fields, record, row_touched
+        finish_field()
+        rows.append((fields, row_start))
+        fields = []
+        record += 1
+        row_touched = False
+
+    index = 0
+    while index < len(source):
+        character = source[index]
+        newline = character in ("\r", "\n")
+        crlf = character == "\r" and source[index + 1:index + 2] == "\n"
+        if character == "\0":
+            error("NUL_CHARACTER", "NUL characters are not supported")
+            fatal = True
+            break
+        if state == "quoted":
+            row_touched = True
+            if character == '"':
+                if source[index + 1:index + 2] == '"':
+                    value.append('"')
+                    index += 2
+                    column += 2
+                    continue
+                state = "closed"
+            else:
+                value.append(character)
+                if crlf:
+                    value.append("\n")
+                    index += 1
+            if newline:
+                line += 1
+                column = 1
+            else:
+                column += 1
+            index += 1
+            continue
+        if character == delimiter:
+            row_touched = True
+            finish_field()
+            column += 1
+            field_start = (line, column)
+            index += 1
+            continue
+        if newline:
+            finish_record()
+            if crlf:
+                index += 1
+            line += 1
+            column = 1
+            row_start = field_start = (line, column)
+            index += 1
+            continue
+        if state == "closed":
+            error("TEXT_AFTER_QUOTE", "Only a delimiter or line ending may follow a closing quote")
+            fatal = True
+            break
+        if character == '"':
+            if state != "start":
+                error("QUOTE_IN_UNQUOTED_FIELD", "A quote must start at the beginning of a field")
+                fatal = True
+                break
+            state = "quoted"
+        else:
+            value.append(character)
+            state = "plain"
+        row_touched = True
+        column += 1
+        index += 1
+    if not fatal and state == "quoted":
+        error("UNCLOSED_QUOTE", "Quoted field is missing a closing quote", field_start)
+        fatal = True
+    if not fatal and (row_touched or fields or value):
+        finish_record()
+    width = len(rows[0][0]) if rows else 0
+    if not source:
+        error("EMPTY_INPUT", "Input contains no records", (1, 1), 1, 1)
+    if header and rows:
+        seen = {}
+        for index, (field_value, at) in enumerate(rows[0][0], 1):
+            if not field_value:
+                error("EMPTY_HEADER", "Header name is empty", at, index, 1)
+            if field_value in seen:
+                error("DUPLICATE_HEADER", f"Header repeats field {seen[field_value]}", at, index, 1)
+            else:
+                seen[field_value] = index
+    for index, (row_fields, at) in enumerate(rows, 1):
+        if len(row_fields) != width:
+            error("ROW_WIDTH", f"Expected {width} fields; found {len(row_fields)}",
+                  at, min(width, len(row_fields)) + 1, index)
+    return {
+        "valid": not diagnostics, "records": len(rows),
+        "dataRecords": max(0, len(rows) - (1 if header and rows else 0)),
+        "columns": width, "header": header, "diagnostics": diagnostics,
+        "diagnosticsTruncated": truncated, "parseComplete": not fatal,
+    }

shipit_csv_validator-0.1.0.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: shipit-csv-validator
+Version: 0.1.0
+Summary: Dependency-free local CSV validation with record, field and source diagnostics
+License-Expression: MIT
+Project-URL: Homepage, https://csvfile.tools/validate
+Project-URL: Repository, https://github.com/shipit-software/csv-validator
+Project-URL: Issues, https://github.com/shipit-software/csv-validator/issues
+Keywords: csv,validation,cli
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# CSV Validator for Python
+
+Validate UTF-8 CSV locally with record, field, line and column diagnostics.
+This is the Python implementation from the same
+[CSV Validator repository](https://github.com/shipit-software/csv-validator)
+as the JavaScript and Rust implementations. It has no runtime dependencies,
+network calls, type guessing, cell evaluation or automatic edits.
+
+For an interactive workflow, use the [CSV validator](https://csvfile.tools/validate).
+
+Requires Python 3.11 or newer. Install an available released version with:
+
+    python -m pip install shipit-csv-validator
+
+For a local source checkout, install the python directory instead.
+
+    python -m pip install ./python
+    shipit-csv-validate --json data.csv
+    python -m shipit_csv_validator --delimiter tab --no-header data.tsv
+    shipit-csv-validate --json -- -starts-with-dash.csv
+
+Omit the filename or use - to read standard input. Exit codes are 0 for valid
+CSV, 1 for invalid CSV and 2 for usage, read, encoding or input-limit errors.
+The CLI buffers at most 32 MiB plus one byte for detecting overflow. Files are
+opened read-only; it never changes input files. --help lists all options.
+
+    from shipit_csv_validator import validate_csv
+
+    report = validate_csv("id,name\n001,Ada")
+    assert report["valid"]
+    assert report["dataRecords"] == 1
+
+The API accepts complete text and keyword-only delimiter, header and max_errors
+options. Invalid options raise TypeError. API input is not limited by byte size.
+The returned dictionary uses the shared JSON report keys: valid, records,
+dataRecords, columns, header, diagnostics, diagnosticsTruncated and parseComplete.
+
+Checks include row widths, empty/duplicate exact header names, quote placement,
+unclosed quoted fields and NUL characters. Quoted delimiters/line endings,
+escaped quotes, an initial UTF-8 BOM and CRLF/LF/CR are supported. Spaces are
+significant. Header names are case-sensitive. Empty lines are records.
+Syntax errors stop parsing; counts then include completed records only.
+Positions are one-based, and columns count UTF-16 units for parity with the
+other implementations. A delimiter must be exactly one UTF-16 unit other than
+quote, CR, LF or NUL. Formula safety, application schemas, types, required values
+and domain-specific rules are outside this validator.
+
+From the repository root, run the shared 22-case corpus and additional CLI/API
+checks with:
+
+    PYTHONPATH=python/src python -m unittest discover -s python/tests -v
+
+All fixtures are synthetic. Code is MIT licensed; see LICENSE.

shipit_csv_validator-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+shipit_csv_validator/__init__.py,sha256=JSOjlb0bbCtgfZMSO9UDV_vsFqh47FKlyvbTrlNpA3s,164
+shipit_csv_validator/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+shipit_csv_validator/cli.py,sha256=YaVUa2L0ouzzUWEjczXh6enoYSXEQD5J43wECbqdRRI,4546
+shipit_csv_validator/validate.py,sha256=eQWe5YJTkoEH417r5CWIrGoTNTpfEgV29CsktUC0qok,5725
+shipit_csv_validator-0.1.0.dist-info/licenses/LICENSE,sha256=E_rh7CMJg1XonO5IlKk75XytR9tMhfYl_CmV9kdSB2w,1072
+shipit_csv_validator-0.1.0.dist-info/METADATA,sha256=ZmldLdTB5lWAH7o83-OKNvwT3MaMq9fWWJfUrr0hZi0,3063
+shipit_csv_validator-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+shipit_csv_validator-0.1.0.dist-info/entry_points.txt,sha256=HDbcvQo_JBnMuZgTKMsKv9HUdjgVfsngK4bDTXaNq6A,70
+shipit_csv_validator-0.1.0.dist-info/top_level.txt,sha256=GWrPJaB8U4AIvrjds_SxTqp8PgTKt_HkCHAS51qtXqA,21
+shipit_csv_validator-0.1.0.dist-info/RECORD,,

shipit_csv_validator-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

shipit_csv_validator-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shipit-csv-validate = shipit_csv_validator.cli:main

shipit_csv_validator-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipit Software
+
+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.

shipit_csv_validator-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+shipit_csv_validator