fs-schema 0.4.5__py3-none-any.whl

fs_schema/__init__.py

@@ -0,0 +1,31 @@
+from importlib.metadata import version as _version
+
+from beartype import (
+    BeartypeConf as _BeartypeConf,
+    BeartypeStrategy as _BeartypeStrategy,
+)
+from beartype.claw import beartype_this_package as _beartype_this_package
+
+__version__ = _version("fs-schema")
+
+_beartype_this_package(conf=_BeartypeConf(strategy=_BeartypeStrategy.On))
+
+from ._fmt import dt as dt
+from ._ops import (
+    MismatchErr as MismatchErr,
+    exists_opt as exists_opt,
+    is_mismatch as is_mismatch,
+    put as put,
+    raise_exn as raise_exn,
+    raise_mismatch as raise_mismatch,
+)
+from ._schema import (
+    FILES as FILES,
+    Dir as Dir,
+    File as File,
+    Layout as Layout,
+    Match as Match,
+    Schema as Schema,
+    SchemaRoot as SchemaRoot,
+)
+from ._types import Located as Located

fs_schema/_fmt.py

@@ -0,0 +1,162 @@
+"""Private compilation and parsing of fs-schema basename templates."""
+
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass, replace
+from datetime import date, datetime, time
+from enum import Enum
+from string import Formatter
+from typing import Final, TypeAlias
+
+from beartype.typing import Protocol
+from parse import Parser
+from typing_extensions import override
+
+FmtLike: TypeAlias = str
+# A parsed template field: {n:d} -> int, {stem} -> str, dt() -> datetime.
+FmtField: TypeAlias = str | int | datetime
+# Regex optional groups can be absent; format fields cannot.
+CaptureField: TypeAlias = FmtField | None
+_FORMATTER = Formatter()
+_DIRECTIVES = frozenset("aAwdbBmyYHIpMSfzZjUWcxX%")
+_INTEGER_TYPES = frozenset("bcdoxXn")
+
+
+class CaptureMap(Mapping[str, CaptureField]):
+    __slots__: Final = ("_values",)
+    _values: dict[str, CaptureField]
+
+    def __init__(self, values: Mapping[str, CaptureField]) -> None:
+        self._values = dict(values)
+
+    @override
+    def __getitem__(self, key: str) -> CaptureField:
+        return self._values[key]
+
+    @override
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._values)
+
+    @override
+    def __len__(self) -> int:
+        return len(self._values)
+
+    def __getattr__(self, name: str) -> CaptureField:
+        try:
+            return self._values[name]
+        except KeyError as error:
+            raise AttributeError(name) from error
+
+
+@dataclass(frozen=True, slots=True)
+class FormatField:
+    name: str
+    index: int
+    pattern: str = ""
+
+    @property
+    def positional(self) -> bool:
+        return not self.name or (self.name.isascii() and self.name.isdecimal())
+
+
+class _FormatFieldTemplate(Enum):
+    STRING = FormatField("", 0)
+    INTEGER = FormatField("", 0, "d")
+    DATETIME = FormatField("", 0, "%Y")
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedCaptures:
+    args: tuple[CaptureField, ...]
+    kwargs: CaptureMap
+
+
+class CompiledFormat:
+    __slots__: Final = ("_fields", "_parser", "_pattern")
+    _fields: tuple[FormatField, ...]
+    _parser: Parser
+    _pattern: str
+
+    def __init__(self, pattern: str) -> None:
+        self._fields = tuple(
+            _compile_field(name, spec or "", index)
+            for index, (_, name, spec, _) in enumerate(_FORMATTER.parse(pattern))
+            if name is not None
+        )
+        self._parser = Parser(pattern, case_sensitive=True)
+        self._pattern = pattern
+
+    @property
+    def pattern(self) -> str:
+        return self._pattern
+
+    @property
+    def fields(self) -> tuple[FormatField, ...]:
+        return self._fields
+
+    def format(self, *args: FmtField, **kwargs: FmtField) -> str:
+        return _FORMATTER.vformat(self.pattern, args, kwargs)
+
+    def parse(self, basename: str) -> ParsedCaptures | None:
+        if (parsed := _parse(self._parser, basename)) is None:
+            return None
+        return ParsedCaptures(
+            tuple(_capture_value(value) for value in parsed.fixed),
+            CaptureMap({name: _capture_value(value) for name, value in parsed.named.items()}),
+        )
+
+
+# These types only exist for enforced typechecking
+_ParserField: TypeAlias = str | int | date | time | datetime
+
+
+class _ParseResult(Protocol):
+    fixed: tuple[_ParserField, ...]
+    named: dict[str, _ParserField]
+
+
+def _parse(parser: Parser, basename: str) -> _ParseResult | None:
+    return parser.parse(basename)
+
+
+def _capture_value(value: _ParserField) -> FmtField:
+    match value:
+        case datetime():
+            return value
+        case date():
+            return datetime.combine(value, time.min)
+        case str() | int():
+            return value
+        case time():
+            raise TypeError("time captures are unsupported")
+        case _:  # pyright: ignore[reportUnnecessaryComparison]
+            raise TypeError("unexpected capture type")  # pyright: ignore[reportUnreachable]
+
+
+def _is_strftime_spec(spec: str) -> bool:
+    found = False
+    index = 0
+    while index < len(spec):
+        if spec[index] != "%":
+            index += 1
+            continue
+        if index + 1 >= len(spec) or spec[index + 1] not in _DIRECTIVES:
+            return False
+        found |= spec[index + 1] != "%"
+        index += 2
+    return found
+
+
+def _field_template(spec: str) -> _FormatFieldTemplate:
+    if _is_strftime_spec(spec):
+        return _FormatFieldTemplate.DATETIME
+    if spec[-1:] in _INTEGER_TYPES:
+        return _FormatFieldTemplate.INTEGER
+    return _FormatFieldTemplate.STRING
+
+
+def _compile_field(name: str, spec: str, index: int) -> FormatField:
+    return replace(_field_template(spec).value, name=name, index=index, pattern=spec)
+
+
+def dt(pattern: str) -> FmtLike:
+    return f"{{:{pattern}}}"

fs_schema/_mashumaro_json.py

@@ -0,0 +1,70 @@
+"""Mashumaro JSON conversion used by filesystem operations."""
+
+from dataclasses import is_dataclass
+from pathlib import Path
+from typing import TypeVar, cast
+
+from typing_extensions import Protocol, runtime_checkable
+
+from ._types import DataclassInstance
+
+_T = TypeVar("_T")
+_T_co = TypeVar("_T_co", covariant=True)
+_T_contra = TypeVar("_T_contra", contravariant=True)
+
+
+@runtime_checkable
+class _Encoder(Protocol[_T_contra]):
+    def encode(self, obj: _T_contra) -> str | bytes: ...
+
+
+@runtime_checkable
+class _Decoder(Protocol[_T_co]):
+    def decode(self, data: str | bytes | bytearray) -> _T_co: ...
+
+
+def _json_codecs(model: type[_T]) -> tuple[_Encoder[_T], _Decoder[_T]]:
+    try:
+        from mashumaro.codecs.json import JSONDecoder, JSONEncoder
+    except ModuleNotFoundError as error:
+        if error.name == "mashumaro":
+            raise TypeError("JSON dataclass conversion requires fs-schema[mashumaro]") from error
+        raise
+
+    try:
+        import orjson
+    except ModuleNotFoundError as error:
+        if error.name != "orjson":
+            raise
+        encoder, decoder = JSONEncoder(model), JSONDecoder(model)
+    else:
+        from mashumaro.codecs.orjson import ORJSONDecoder, ORJSONEncoder
+
+        _ = orjson
+        encoder, decoder = ORJSONEncoder(model), ORJSONDecoder(model)
+    return cast(_Encoder[_T], encoder), cast(_Decoder[_T], decoder)
+
+
+def _check_json(path: Path) -> None:
+    if path.suffix.casefold() != ".json":
+        raise TypeError(f"dataclass conversion requires a .json file, got {path.suffix or '<no suffix>'!r}")
+
+
+def _check_model(model: type[object]) -> None:
+    if not is_dataclass(model):
+        raise TypeError(f"declared model {model.__name__} is not a dataclass")
+
+
+def decode_json(path: Path, model: type[_T]) -> _T:
+    _check_json(path)
+    _check_model(model)
+    _, decoder = _json_codecs(model)
+    return decoder.decode(path.read_bytes())
+
+
+def encode_json(path: Path, value: DataclassInstance) -> str | bytes:
+    _check_json(path)
+    model = type(value)
+    _check_model(model)
+    encoder, _ = _json_codecs(model)
+    return encoder.encode(value)

fs_schema/_ops.py

@@ -0,0 +1,66 @@
+from pathlib import Path
+from shutil import copyfile
+from typing import TypeVar, cast
+
+from typing_extensions import TypeIs, assert_never
+
+from ._mashumaro_json import decode_json, encode_json
+from ._types import DataclassInstance, HasSave, LoadSpec, LoadT, PathIsh, Puttable
+
+# The passthrough value is returned unchanged when it is not a mismatch.
+_T = TypeVar("_T")
+
+
+class MismatchErr(Exception):
+    pass
+
+
+def is_mismatch(x: object) -> TypeIs[MismatchErr]:
+    return isinstance(x, MismatchErr)
+
+
+def raise_exn(x: _T | Exception) -> _T:
+    if isinstance(x, Exception):
+        raise x
+    return x
+
+
+def raise_mismatch(x: _T | MismatchErr) -> _T:
+    return raise_exn(x)
+
+
+def exists_opt(path: PathIsh) -> Path | None:
+    candidate = Path(path)
+    return candidate if candidate.exists() else None
+
+
+def put(path: PathIsh, data: Puttable) -> None:
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    match data:
+        case bytes():
+            _ = target.write_bytes(data)
+        case str():
+            _ = target.write_text(data)
+        case Path():
+            _ = copyfile(data, target)
+        case HasSave():
+            data.save(target)
+        case DataclassInstance():
+            encoded = encode_json(target, data)
+            if isinstance(encoded, bytes):
+                _ = target.write_bytes(encoded)
+            else:
+                _ = target.write_text(encoded)
+        case _:  # pragma: no cover - closed-union defense
+            assert_never(data)
+
+
+def load(path: PathIsh, decoder: LoadSpec[LoadT]) -> LoadT | Exception:
+    target = Path(path)
+    try:
+        if isinstance(decoder, type):
+            return cast(LoadT, decode_json(target, decoder))
+        return decoder(target)
+    except Exception as error:
+        return error