labschema 0.1.0__py3-none-any.whl

labschema/fields.py

@@ -0,0 +1,270 @@
+"""Field definition for LabSchema table columns."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Collection, Sequence
+from dataclasses import dataclass
+from dataclasses import field as dataclass_field
+from typing import TYPE_CHECKING, Any
+
+from labschema.errors import SchemaError
+from labschema.units import get_unit_string, parse_unit
+
+if TYPE_CHECKING:
+    from pint import Unit
+
+_VALID_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+_ALLOWED_DTYPES = (int, float, str, bool)
+
+
+class _UnsetType:
+    """Sentinel for unset default values."""
+
+    _instance: _UnsetType | None = None
+
+    def __new__(cls) -> _UnsetType:
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "<UNSET>"
+
+    def __bool__(self) -> bool:
+        return False
+
+
+_UNSET: _UnsetType = _UnsetType()
+
+
+def _validate_name(name: str) -> None:
+    """Validate that a field name is a valid Python identifier-like string."""
+    if not _VALID_NAME_PATTERN.match(name):
+        raise SchemaError(f"Invalid field name: {name!r}. Names must match [A-Za-z_][A-Za-z0-9_]*")
+
+
+@dataclass(frozen=True, eq=True)
+class Field:
+    """Describes a single column in a table schema.
+
+    Attributes:
+        name: Canonical field name. Must be a valid Python identifier-like string.
+        dtype: One of int, float, str, bool.
+        unit: Declared unit. Only allowed when dtype is int or float.
+        nullable: Whether missing values are allowed.
+        description: Human-readable description; exported to JSON Schema.
+        aliases: Extra header names that map to this field.
+        ge: Greater than or equal constraint (numeric fields only).
+        gt: Greater than constraint (numeric fields only).
+        le: Less than or equal constraint (numeric fields only).
+        lt: Less than constraint (numeric fields only).
+        enum: Allowed values.
+        pattern: Regex pattern for str fields. Matched with re.fullmatch.
+        validators: Custom callables (value) -> value; raise ValueError to reject.
+        default: Value substituted for missing cells.
+    """
+
+    name: str
+    dtype: type
+    unit: Unit | str | None = None
+    nullable: bool = False
+    description: str | None = None
+    aliases: tuple[str, ...] = ()
+    ge: float | None = None
+    gt: float | None = None
+    le: float | None = None
+    lt: float | None = None
+    enum: Collection[Any] | None = None
+    pattern: str | None = None
+    validators: Sequence[Callable[[Any], Any]] = ()
+    default: Any = dataclass_field(default_factory=lambda: _UNSET)
+
+    def __post_init__(self) -> None:
+        """Validate field configuration at construction time."""
+        _validate_name(self.name)
+
+        if self.dtype not in _ALLOWED_DTYPES:
+            raise SchemaError(
+                f"Invalid dtype for field {self.name!r}: {self.dtype}. "
+                f"Allowed types: int, float, str, bool"
+            )
+
+        if self.unit is not None and self.dtype not in (int, float):
+            raise SchemaError(
+                f"Field {self.name!r}: unit is only allowed for numeric types (int, float)"
+            )
+
+        if self.unit is not None:
+            try:
+                parse_unit(self.unit if isinstance(self.unit, str) else str(self.unit))
+            except SchemaError as e:
+                raise SchemaError(f"Field {self.name!r}: {e}") from e
+
+        if self.pattern is not None and self.dtype is not str:
+            raise SchemaError(f"Field {self.name!r}: pattern is only allowed for str type")
+
+        if self.pattern is not None:
+            try:
+                re.compile(self.pattern)
+            except re.error as e:
+                raise SchemaError(f"Field {self.name!r}: invalid regex pattern: {e}") from e
+
+        if self.dtype not in (int, float) and any(
+            b is not None for b in (self.ge, self.gt, self.le, self.lt)
+        ):
+            raise SchemaError(
+                f"Field {self.name!r}: bounds (ge/gt/le/lt) are only allowed "
+                f"for numeric types (int, float)"
+            )
+
+        if self.ge is not None and self.gt is not None:
+            raise SchemaError(f"Field {self.name!r}: cannot set both 'ge' and 'gt'")
+
+        if self.le is not None and self.lt is not None:
+            raise SchemaError(f"Field {self.name!r}: cannot set both 'le' and 'lt'")
+
+    def __hash__(self) -> int:
+        """Make Field hashable by using only hashable attributes."""
+        enum_hash = tuple(self.enum) if self.enum is not None else None
+        validators_hash = tuple(id(v) for v in self.validators)
+        default_hash = id(self.default) if self.default is _UNSET else hash(str(self.default))
+        return hash(
+            (
+                self.name,
+                self.dtype,
+                get_unit_string(self.unit),
+                self.nullable,
+                self.description,
+                self.aliases,
+                self.ge,
+                self.gt,
+                self.le,
+                self.lt,
+                enum_hash,
+                self.pattern,
+                validators_hash,
+                default_hash,
+            )
+        )
+
+    @property
+    def has_default(self) -> bool:
+        """Check if this field has a default value set."""
+        return self.default is not _UNSET
+
+    @property
+    def unit_string(self) -> str | None:
+        """Get the canonical string representation of the unit."""
+        return get_unit_string(self.unit)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the field to a dictionary for JSON serialization."""
+        result: dict[str, Any] = {
+            "name": self.name,
+            "dtype": self.dtype.__name__,
+        }
+
+        if self.unit is not None:
+            result["unit"] = self.unit_string
+
+        if self.nullable:
+            result["nullable"] = True
+
+        if self.description is not None:
+            result["description"] = self.description
+
+        if self.aliases:
+            result["aliases"] = list(self.aliases)
+
+        if self.ge is not None:
+            result["ge"] = self.ge
+        if self.gt is not None:
+            result["gt"] = self.gt
+        if self.le is not None:
+            result["le"] = self.le
+        if self.lt is not None:
+            result["lt"] = self.lt
+
+        if self.enum is not None:
+            result["enum"] = list(self.enum)
+
+        if self.pattern is not None:
+            result["pattern"] = self.pattern
+
+        if self.validators:
+            result["validators"] = [getattr(v, "__name__", repr(v)) for v in self.validators]
+
+        if self.has_default:
+            result["default"] = self.default
+
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Field:
+        """Create a Field from a dictionary.
+
+        Args:
+            data: Dictionary with field attributes.
+
+        Returns:
+            A new Field instance.
+
+        Raises:
+            SchemaError: If the dictionary contains invalid data.
+        """
+        dtype_map = {"int": int, "float": float, "str": str, "bool": bool}
+
+        name = data.get("name")
+        if not isinstance(name, str):
+            raise SchemaError("Field 'name' is required and must be a string")
+
+        dtype_str = data.get("dtype")
+        if dtype_str not in dtype_map:
+            raise SchemaError(
+                f"Field {name!r}: invalid dtype {dtype_str!r}. Allowed: int, float, str, bool"
+            )
+        dtype = dtype_map[dtype_str]
+
+        kwargs: dict[str, Any] = {
+            "name": name,
+            "dtype": dtype,
+        }
+
+        if "unit" in data:
+            kwargs["unit"] = data["unit"]
+
+        if data.get("nullable"):
+            kwargs["nullable"] = True
+
+        if "description" in data:
+            kwargs["description"] = data["description"]
+
+        if "aliases" in data:
+            kwargs["aliases"] = tuple(data["aliases"])
+
+        for bound in ("ge", "gt", "le", "lt"):
+            if bound in data:
+                kwargs[bound] = data[bound]
+
+        if "enum" in data:
+            kwargs["enum"] = data["enum"]
+
+        if "pattern" in data:
+            kwargs["pattern"] = data["pattern"]
+
+        if "default" in data:
+            kwargs["default"] = data["default"]
+
+        if "validators" in data and data["validators"]:
+            import warnings
+
+            warnings.warn(
+                f"Field {name!r}: validators cannot be deserialized from JSON. "
+                f"Original validators: {data['validators']}",
+                UserWarning,
+                stacklevel=2,
+            )
+
+        return cls(**kwargs)

labschema/infer.py

@@ -0,0 +1,383 @@
+"""Schema inference from CSV/TSV files."""
+
+from __future__ import annotations
+
+import csv
+import io
+import os
+from collections.abc import Collection
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, TextIO
+
+from labschema.errors import ReadError
+from labschema.fields import Field
+from labschema.schema import TableSchema, normalize_name
+from labschema.units import parse_header_unit
+from labschema.validate import DEFAULT_NA_VALUES
+
+if TYPE_CHECKING:
+    pass
+
+
+def _get_version() -> str:
+    """Get version without circular import."""
+    from labschema import __version__
+
+    return __version__
+
+
+def _detect_delimiter(sample: str) -> str:
+    """Detect the delimiter from a sample of the file."""
+    try:
+        dialect = csv.Sniffer().sniff(sample, delimiters=",;\t|")
+        return dialect.delimiter
+    except csv.Error:
+        return ","
+
+
+def _try_parse_bool(value: str) -> bool | None:
+    """Try to parse a value as boolean."""
+    lower = value.lower()
+    if lower in ("true", "yes", "y", "1", "t"):
+        return True
+    if lower in ("false", "no", "n", "0", "f"):
+        return False
+    return None
+
+
+def _try_parse_int(value: str, decimal: str = ".") -> int | None:
+    """Try to parse a value as integer."""
+    try:
+        if decimal != ".":
+            value = value.replace(decimal, ".")
+
+        if "." in value:
+            float_val = float(value)
+            if float_val == int(float_val):
+                return int(float_val)
+            return None
+        return int(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _try_parse_float(value: str, decimal: str = ".") -> float | None:
+    """Try to parse a value as float."""
+    try:
+        if decimal != ".":
+            value = value.replace(decimal, ".")
+        return float(value)
+    except (ValueError, TypeError):
+        return None
+
+
+def _infer_dtype(values: list[str], decimal: str = ".") -> tuple[type, bool]:
+    """Infer the dtype from a list of non-missing values.
+
+    Returns:
+        (dtype, nullable) where nullable is True if there were any missing values.
+    """
+    if not values:
+        return str, True
+
+    all_bool = True
+    all_int = True
+    all_float = True
+
+    for v in values:
+        if all_bool and _try_parse_bool(v) is None:
+            all_bool = False
+
+        if all_int and _try_parse_int(v, decimal) is None:
+            all_int = False
+
+        if all_float and _try_parse_float(v, decimal) is None:
+            all_float = False
+
+        if not (all_bool or all_int or all_float):
+            break
+
+    if all_bool:
+        return bool, False
+    if all_int:
+        return int, False
+    if all_float:
+        return float, False
+    return str, False
+
+
+def _format_observed_range(values: list[Any], dtype: type) -> str | None:
+    """Format the observed range for a description."""
+    if not values:
+        return None
+
+    if dtype in (int, float):
+        numeric_values = []
+        for v in values:
+            parsed = _try_parse_int(str(v)) if dtype is int else _try_parse_float(str(v))
+            if parsed is not None:
+                numeric_values.append(parsed)
+
+        if numeric_values:
+            min_val = min(numeric_values)
+            max_val = max(numeric_values)
+            return f"observed range {min_val}–{max_val} in {len(values)} sampled rows"
+
+    return None
+
+
+def infer_schema(
+    source: str | os.PathLike[str] | TextIO,
+    *,
+    sample_rows: int = 100,
+    name: str | None = None,
+    delimiter: str | None = None,
+    decimal: Literal[".", ","] = ".",
+    thousands: str | None = None,
+    encoding: str = "utf-8-sig",
+    na_values: Collection[str] | None = None,
+    extra_na_values: Collection[str] = (),
+    skip_rows: int = 0,
+    comment: str | None = None,
+    strip: bool = True,
+) -> TableSchema:
+    """Infer a draft schema from a CSV/TSV file.
+
+    The inferred schema is a draft meant for human review before use.
+    Units are only inferred from headers, never from values.
+
+    Args:
+        source: File path, Path object, or text stream.
+        sample_rows: Number of rows to sample for type inference.
+        name: Schema name (default: derived from filename or 'inferred_schema').
+        delimiter: Column delimiter. None = auto-detect.
+        decimal: Decimal separator for numeric fields.
+        thousands: Thousands separator to strip.
+        encoding: File encoding (default: utf-8-sig to handle BOM).
+        na_values: Replace the default missing-value sentinel set.
+        extra_na_values: Add to the default missing-value sentinel set.
+        skip_rows: Lines to skip before the header.
+        comment: Lines starting with this prefix are ignored.
+        strip: Trim whitespace around cells.
+
+    Returns:
+        A TableSchema with inferred field types and units.
+
+    Raises:
+        ReadError: If the file cannot be read.
+    """
+    if na_values is not None:
+        all_na_values = frozenset(na_values)
+    else:
+        all_na_values = DEFAULT_NA_VALUES | frozenset(extra_na_values)
+
+    source_name: str | None = None
+
+    if isinstance(source, (str, os.PathLike)):
+        path = Path(source)
+        source_name = str(source)
+        try:
+            text_content = path.read_text(encoding=encoding)
+        except OSError as e:
+            raise ReadError(f"Cannot read file: {e}") from e
+        if name is None:
+            name = normalize_name(path.stem) or "inferred_schema"
+    else:
+        text_content = source.read()
+        if name is None:
+            name = "inferred_schema"
+
+    lines = text_content.splitlines(keepends=False)
+
+    for _ in range(skip_rows):
+        if lines:
+            lines.pop(0)
+
+    if comment:
+        lines = [line for line in lines if not line.startswith(comment)]
+
+    if not lines:
+        raise ReadError("File is empty or contains no data rows")
+
+    if delimiter is None:
+        sample = "\n".join(lines[: min(10, len(lines))])
+        delimiter = _detect_delimiter(sample)
+
+    content = "\n".join(lines)
+
+    try:
+        reader = csv.reader(io.StringIO(content), delimiter=delimiter)
+        rows = list(reader)
+    except csv.Error as e:
+        raise ReadError(f"Malformed CSV: {e}") from e
+
+    if not rows:
+        raise ReadError("File is empty or contains no data rows")
+
+    headers = rows[0]
+    if strip:
+        headers = [h.strip() for h in headers]
+
+    data_rows = rows[1 : 1 + sample_rows]
+
+    column_values: dict[int, list[str]] = {i: [] for i in range(len(headers))}
+    column_missing: dict[int, int] = dict.fromkeys(range(len(headers)), 0)
+
+    for row in data_rows:
+        if strip:
+            row = [cell.strip() for cell in row]
+
+        for i, cell in enumerate(row):
+            if i >= len(headers):
+                continue
+
+            if thousands and i < len(headers):
+                cell = cell.replace(thousands, "")
+
+            if cell in all_na_values:
+                column_missing[i] += 1
+            else:
+                column_values[i].append(cell)
+
+    fields: list[Field] = []
+
+    for i, header in enumerate(headers):
+        col_name, unit_str, _ = parse_header_unit(header)
+        field_name = normalize_name(col_name)
+
+        if not field_name:
+            field_name = f"column_{i + 1}"
+
+        values = column_values.get(i, [])
+        has_missing = column_missing.get(i, 0) > 0
+
+        dtype: type
+        if not values:
+            dtype = str
+            nullable = True
+        else:
+            dtype, _ = _infer_dtype(values, decimal)
+            nullable = has_missing
+
+        alias = header if header != col_name and header != field_name else None
+
+        description_parts: list[str] = []
+        observed_range = _format_observed_range(values, dtype)
+        if observed_range:
+            description_parts.append(observed_range)
+
+        if dtype is str and values:
+            unique_values = set(values)
+            if len(unique_values) <= 10 and len(values) >= 20:
+                sorted_values = sorted(unique_values)
+                description_parts.append(f"distinct values: {sorted_values}")
+
+        description = "; ".join(description_parts) if description_parts else None
+
+        field_kwargs: dict[str, Any] = {
+            "name": field_name,
+            "dtype": dtype,
+            "nullable": nullable,
+        }
+
+        if unit_str and dtype in (int, float):
+            field_kwargs["unit"] = unit_str
+
+        if description:
+            field_kwargs["description"] = description
+
+        if alias:
+            field_kwargs["aliases"] = (alias,)
+
+        fields.append(Field(**field_kwargs))
+
+    metadata: dict[str, Any] = {
+        "inferred": {
+            "sample_rows": len(data_rows),
+            "labschema_version": _get_version(),
+        }
+    }
+    if source_name:
+        metadata["inferred"]["source"] = source_name
+
+    return TableSchema(
+        name=name,
+        fields=fields,
+        metadata=metadata,
+    )
+
+
+def schema_to_python(schema: TableSchema) -> str:
+    """Generate Python source code for a TableSchema.
+
+    This creates editable source code that can be used in a Python script.
+
+    Args:
+        schema: The TableSchema to convert.
+
+    Returns:
+        Python source code as a string.
+    """
+    lines = [
+        "from labschema import Field, TableSchema, u",
+        "",
+        "schema = TableSchema(",
+        f"    name={schema.name!r},",
+    ]
+
+    if schema.primary_key:
+        lines.append(f"    primary_key={schema.primary_key!r},")
+
+    if schema.extra_columns != "warn":
+        lines.append(f"    extra_columns={schema.extra_columns!r},")
+
+    if schema.version:
+        lines.append(f"    version={schema.version!r},")
+
+    if schema.description:
+        lines.append(f"    description={schema.description!r},")
+
+    lines.append("    fields=[")
+
+    for f in schema.fields:
+        parts = [f"        Field({f.name!r}, {f.dtype.__name__}"]
+
+        if f.unit:
+            unit_str = f.unit_string or str(f.unit)
+            parts.append(f", unit={unit_str!r}")
+
+        if f.nullable:
+            parts.append(", nullable=True")
+
+        if f.ge is not None:
+            parts.append(f", ge={f.ge!r}")
+        if f.gt is not None:
+            parts.append(f", gt={f.gt!r}")
+        if f.le is not None:
+            parts.append(f", le={f.le!r}")
+        if f.lt is not None:
+            parts.append(f", lt={f.lt!r}")
+
+        if f.enum:
+            parts.append(f", enum={list(f.enum)!r}")
+
+        if f.pattern:
+            parts.append(f", pattern={f.pattern!r}")
+
+        if f.description:
+            desc = f.description
+            if len(desc) > 50:
+                desc = desc[:47] + "..."
+            parts.append(f", description={desc!r}")
+
+        if f.aliases:
+            parts.append(f", aliases={f.aliases!r}")
+
+        parts.append("),")
+        lines.append("".join(parts))
+
+    lines.append("    ],")
+    lines.append(")")
+    lines.append("")
+
+    return "\n".join(lines)

labschema/io/__init__.py

@@ -0,0 +1,5 @@
+"""I/O modules for LabSchema."""
+
+from labschema.io.csv import read_csv, read_text, read_tsv
+
+__all__ = ["read_csv", "read_tsv", "read_text"]