labschema 0.1.0__py3-none-any.whl

labschema/__init__.py

@@ -0,0 +1,25 @@
+"""LabSchema: Typed schemas with physical units and validation for lab-style tables."""
+
+from labschema.errors import ErrorCode, LabSchemaError, SchemaError, ValidationIssue
+from labschema.fields import Field
+from labschema.infer import infer_schema
+from labschema.schema import TableSchema
+from labschema.units import u
+from labschema.validate import ValidationReport, ValidationResult, validate_rows
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Field",
+    "TableSchema",
+    "u",
+    "ValidationResult",
+    "ValidationReport",
+    "ValidationIssue",
+    "ErrorCode",
+    "SchemaError",
+    "LabSchemaError",
+    "infer_schema",
+    "validate_rows",
+    "__version__",
+]

labschema/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m labschema."""
+
+from labschema.cli import main
+
+if __name__ == "__main__":
+    main()

labschema/cli.py

@@ -0,0 +1,309 @@
+"""Command-line interface for LabSchema."""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+from labschema import __version__
+from labschema.errors import LabSchemaError, ReadError, SchemaError
+from labschema.infer import infer_schema, schema_to_python
+from labschema.io import read_csv
+from labschema.schema import TableSchema
+
+
+def _load_schema(schema_path: str) -> TableSchema:
+    """Load a schema from a file path or Python import path.
+
+    Args:
+        schema_path: Either a file path (ending in .json) or a Python import
+                     path like 'mymodule:schema'.
+
+    Returns:
+        The loaded TableSchema.
+
+    Raises:
+        SchemaError: If the schema cannot be loaded.
+    """
+    if ":" in schema_path and not Path(schema_path).exists():
+        module_path, attr_name = schema_path.rsplit(":", 1)
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as e:
+            raise SchemaError(f"Cannot import module {module_path!r}: {e}") from e
+
+        try:
+            schema = getattr(module, attr_name)
+        except AttributeError as e:
+            raise SchemaError(f"Module {module_path!r} has no attribute {attr_name!r}") from e
+
+        if not isinstance(schema, TableSchema):
+            raise SchemaError(
+                f"{module_path}:{attr_name} is not a TableSchema (got {type(schema).__name__})"
+            )
+        return schema
+
+    return TableSchema.load(schema_path)
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    """Run the validate command."""
+    try:
+        schema = _load_schema(args.schema)
+    except (SchemaError, ReadError) as e:
+        print(f"Error loading schema: {e}", file=sys.stderr)
+        return 2
+
+    na_values = list(args.na) if args.na else []
+
+    try:
+        result = read_csv(
+            args.data,
+            schema,
+            delimiter=args.delimiter,
+            decimal=args.decimal,
+            thousands=args.thousands,
+            encoding=args.encoding,
+            extra_na_values=na_values,
+            skip_rows=args.skip_rows,
+            comment=args.comment,
+            max_errors=args.max_errors if args.max_errors > 0 else None,
+        )
+    except ReadError as e:
+        print(f"Error reading file: {e}", file=sys.stderr)
+        return 2
+
+    if args.strict:
+        has_problems = len(result.report.errors) > 0 or len(result.report.warnings) > 0
+    else:
+        has_problems = len(result.report.errors) > 0
+
+    if args.quiet:
+        return 1 if has_problems else 0
+
+    if args.format == "json":
+        output = {
+            "file": str(args.data),
+            "total_rows": result.total_rows,
+            "valid_rows": result.valid_rows,
+            **result.report.to_dict(),
+        }
+        print(json.dumps(output, indent=2))
+    else:
+        error_count = len(result.report.errors)
+        warning_count = len(result.report.warnings)
+        print(
+            f"{args.data}: {result.total_rows} rows, "
+            f"{result.valid_rows} valid, "
+            f"{error_count} errors, "
+            f"{warning_count} warnings"
+        )
+
+        if result.report.issues:
+            result.report.print_summary()
+
+    return 1 if has_problems else 0
+
+
+def cmd_infer(args: argparse.Namespace) -> int:
+    """Run the infer command."""
+    try:
+        schema = infer_schema(
+            args.data,
+            sample_rows=args.sample_rows,
+            name=args.name,
+        )
+    except ReadError as e:
+        print(f"Error reading file: {e}", file=sys.stderr)
+        return 2
+
+    output = schema_to_python(schema) if args.format == "python" else schema.to_json()
+
+    if args.output:
+        Path(args.output).write_text(output, encoding="utf-8")
+    else:
+        print(output)
+
+    return 0
+
+
+def cmd_export_schema(args: argparse.Namespace) -> int:
+    """Run the export-schema command."""
+    try:
+        schema = _load_schema(args.schema)
+    except (SchemaError, ReadError) as e:
+        print(f"Error loading schema: {e}", file=sys.stderr)
+        return 2
+
+    if args.format == "jsonschema":
+        output = json.dumps(schema.to_json_schema(), indent=2)
+    else:
+        output = schema.to_json()
+
+    if args.output:
+        Path(args.output).write_text(output, encoding="utf-8")
+    else:
+        print(output)
+
+    return 0
+
+
+def main(argv: list[str] | None = None) -> NoReturn:
+    """Main entry point for the labschema CLI."""
+    parser = argparse.ArgumentParser(
+        prog="labschema",
+        description="Validate lab-style CSV/TSV files against typed schemas with units.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"labschema {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate_parser = subparsers.add_parser(
+        "validate",
+        help="Validate a data file against a schema.",
+    )
+    validate_parser.add_argument(
+        "data",
+        help="Path to the CSV/TSV file to validate.",
+    )
+    validate_parser.add_argument(
+        "--schema",
+        required=True,
+        help="Path to a LabSchema JSON file, or a Python import path (module:attr).",
+    )
+    validate_parser.add_argument(
+        "--delimiter",
+        help="Column delimiter (default: auto-detect).",
+    )
+    validate_parser.add_argument(
+        "--decimal",
+        default=".",
+        choices=[".", ","],
+        help="Decimal separator (default: '.').",
+    )
+    validate_parser.add_argument(
+        "--thousands",
+        help="Thousands separator to strip.",
+    )
+    validate_parser.add_argument(
+        "--encoding",
+        default="utf-8-sig",
+        help="File encoding (default: utf-8-sig).",
+    )
+    validate_parser.add_argument(
+        "--skip-rows",
+        type=int,
+        default=0,
+        dest="skip_rows",
+        help="Lines to skip before the header.",
+    )
+    validate_parser.add_argument(
+        "--comment",
+        help="Lines starting with this prefix are ignored.",
+    )
+    validate_parser.add_argument(
+        "--na",
+        action="append",
+        help="Extra missing-value sentinel (repeatable).",
+    )
+    validate_parser.add_argument(
+        "--max-errors",
+        type=int,
+        default=1000,
+        dest="max_errors",
+        help="Maximum errors to collect (0 = unlimited, default: 1000).",
+    )
+    validate_parser.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format (default: text).",
+    )
+    validate_parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Treat warnings as errors.",
+    )
+    validate_parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Print nothing; rely on exit code.",
+    )
+    validate_parser.set_defaults(func=cmd_validate)
+
+    infer_parser = subparsers.add_parser(
+        "infer",
+        help="Infer a draft schema from a data file.",
+    )
+    infer_parser.add_argument(
+        "data",
+        help="Path to the CSV/TSV file to analyze.",
+    )
+    infer_parser.add_argument(
+        "--sample-rows",
+        type=int,
+        default=100,
+        dest="sample_rows",
+        help="Number of rows to sample (default: 100).",
+    )
+    infer_parser.add_argument(
+        "--name",
+        help="Schema name (default: derived from filename).",
+    )
+    infer_parser.add_argument(
+        "--format",
+        choices=["json", "python"],
+        default="json",
+        help="Output format (default: json).",
+    )
+    infer_parser.add_argument(
+        "-o",
+        "--output",
+        help="Output file path (default: stdout).",
+    )
+    infer_parser.set_defaults(func=cmd_infer)
+
+    export_parser = subparsers.add_parser(
+        "export-schema",
+        help="Export a schema to JSON or JSON Schema format.",
+    )
+    export_parser.add_argument(
+        "schema",
+        help="Path to a LabSchema JSON file, or a Python import path (module:attr).",
+    )
+    export_parser.add_argument(
+        "--format",
+        choices=["labschema", "jsonschema"],
+        default="labschema",
+        help="Output format (default: labschema).",
+    )
+    export_parser.add_argument(
+        "-o",
+        "--output",
+        help="Output file path (default: stdout).",
+    )
+    export_parser.set_defaults(func=cmd_export_schema)
+
+    args = parser.parse_args(argv)
+
+    try:
+        exit_code = args.func(args)
+    except LabSchemaError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+    sys.exit(exit_code)
+
+
+if __name__ == "__main__":
+    main()

labschema/errors.py

@@ -0,0 +1,101 @@
+"""Error codes, validation issues, and exceptions for LabSchema."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ErrorCode(str, Enum):
+    """Stable machine-readable error codes for validation issues.
+
+    These codes are part of the public API and will not change meaning
+    within a major version.
+    """
+
+    MISSING_COLUMN = "missing_column"
+    EXTRA_COLUMN = "extra_column"
+    DUPLICATE_COLUMN = "duplicate_column"
+    UNIT_UNKNOWN = "unit_unknown"
+    UNIT_INCOMPATIBLE = "unit_incompatible"
+    UNIT_UNEXPECTED = "unit_unexpected"
+    UNIT_AMBIGUOUS = "unit_ambiguous"
+    ROW_LENGTH_MISMATCH = "row_length_mismatch"
+    NULL_NOT_ALLOWED = "null_not_allowed"
+    TYPE_ERROR = "type_error"
+    LESS_THAN_MINIMUM = "less_than_minimum"
+    GREATER_THAN_MAXIMUM = "greater_than_maximum"
+    NOT_IN_ENUM = "not_in_enum"
+    PATTERN_MISMATCH = "pattern_mismatch"
+    CUSTOM_VALIDATOR = "custom_validator"
+    DUPLICATE_PRIMARY_KEY = "duplicate_primary_key"
+    PARSE_ERROR = "parse_error"
+
+
+@dataclass(frozen=True)
+class ValidationIssue:
+    """A single validation issue found during validation.
+
+    Attributes:
+        code: Stable machine-readable error code.
+        severity: 'error' or 'warning'. Only errors make a result invalid.
+        message: Human-readable description of the issue.
+        row: 1-based file line number (header is line 1). None for file-level issues.
+        column: Raw header text as it appears in the file. None for row-level issues.
+        field_name: Schema field name. None if the issue isn't field-specific.
+        value: Raw cell text (truncated to 80 chars). None if not applicable.
+        context: Code-specific details (e.g., {'ge': 0, 'unit': 'mg/L'}).
+    """
+
+    code: ErrorCode
+    severity: str
+    message: str
+    row: int | None = None
+    column: str | None = None
+    field_name: str | None = None
+    value: str | None = None
+    context: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the issue to a dictionary for JSON serialization."""
+        result: dict[str, Any] = {
+            "code": self.code.value,
+            "severity": self.severity,
+            "message": self.message,
+        }
+        if self.row is not None:
+            result["row"] = self.row
+        if self.column is not None:
+            result["column"] = self.column
+        if self.field_name is not None:
+            result["field"] = self.field_name
+        if self.value is not None:
+            result["value"] = self.value
+        if self.context:
+            result["context"] = self.context
+        return result
+
+
+class LabSchemaError(Exception):
+    """Base exception for all LabSchema errors."""
+
+    pass
+
+
+class SchemaError(LabSchemaError):
+    """Exception raised for invalid schema definitions.
+
+    This is raised at construction or load time, not during validation.
+    """
+
+    pass
+
+
+class ReadError(LabSchemaError):
+    """Exception raised when a file cannot be read.
+
+    This includes encoding failures, empty files, and other I/O errors.
+    """
+
+    pass