stec 0.1.0__py3-none-any.whl

stec/__init__.py

@@ -0,0 +1,27 @@
+"""stec: typed, expressive configuration in a tiny dependency-free language."""
+
+from .config import Stec as _StecClass
+from .errors import (
+    StecAlreadyLoadedError,
+    StecError,
+    StecLoadError,
+    StecNameError,
+    StecSyntaxError,
+    StecTypeError,
+)
+
+#: Global singleton instance: ``Stec.load(...)`` then read values anywhere.
+Stec = _StecClass()
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Stec",
+    "StecAlreadyLoadedError",
+    "StecError",
+    "StecLoadError",
+    "StecNameError",
+    "StecSyntaxError",
+    "StecTypeError",
+    "__version__",
+]

stec/config.py

@@ -0,0 +1,112 @@
+"""The Stec singleton: load once, read everywhere."""
+
+from __future__ import annotations
+
+import threading
+from pathlib import Path
+from typing import Any, Optional
+
+from .errors import StecAlreadyLoadedError, StecLoadError
+from .evaluator import evaluate
+from .parser import parse
+
+
+class Stec:
+    """Singleton registry of exposed configuration values.
+
+    Calling ``Stec()`` always returns the same shared object. The package
+    exports one ready-made instance, so the usual usage is simply::
+
+        from stec import Stec
+
+        Stec.load("app.stec")
+
+        Stec.port          # attribute access
+        Stec["port"]       # item access
+        Stec.get("port")   # with optional default
+        Stec.as_dict()     # full snapshot
+    """
+
+    _instance: Optional["Stec"] = None
+    _lock = threading.Lock()
+
+    def __new__(cls) -> "Stec":
+        with cls._lock:
+            if cls._instance is None:
+                instance = super().__new__(cls)
+                instance._values: dict[str, object] = {}
+                instance._loaded_from: Optional[str] = None
+                cls._instance = instance
+        return cls._instance
+
+    def load(self, path: str | Path, force: bool = False) -> "Stec":
+        """Parse and evaluate the file at *path* into the singleton.
+
+        Raises ``StecAlreadyLoadedError`` if the configuration was already
+        loaded unless *force* is set, which reloads it in place.
+        """
+        with Stec._lock:
+            if self._loaded_from is not None and not force:
+                raise StecAlreadyLoadedError(
+                    f"configuration already loaded from '{self._loaded_from}'; "
+                    "pass force=True to reload"
+                )
+            source = self._read(path)
+            document = parse(source)
+            values = evaluate(document)
+            self._values = values
+            self._loaded_from = str(path)
+        return self
+
+    @staticmethod
+    def _read(path: str | Path) -> str:
+        try:
+            return Path(path).read_text(encoding="utf-8")
+        except UnicodeDecodeError as error:
+            raise StecLoadError(f"cannot decode '{path}': not valid UTF-8") from error
+        except OSError as error:
+            reason = error.strerror or error.__class__.__name__
+            raise StecLoadError(f"cannot read '{path}': {reason}") from error
+
+    def reset(self) -> None:
+        """Forget the loaded configuration (mainly useful in tests)."""
+        with Stec._lock:
+            self._values = {}
+            self._loaded_from = None
+
+    @property
+    def is_loaded(self) -> bool:
+        """Whether a configuration file has been loaded."""
+        return self._loaded_from is not None
+
+    @property
+    def loaded_from(self) -> Optional[str]:
+        """Path the configuration was loaded from, if any."""
+        return self._loaded_from
+
+    def get(self, name: str, default: Any = None) -> Any:
+        """Return the exposed value *name*, or *default* if absent."""
+        return self._values.get(name, default)
+
+    def as_dict(self) -> dict[str, object]:
+        """Return a copy of all exposed values."""
+        return dict(self._values)
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._values
+
+    def __getitem__(self, name: str) -> Any:
+        try:
+            return self._values[name]
+        except KeyError:
+            raise KeyError(f"stec has no exposed value named {name!r}") from None
+
+    def __getattr__(self, name: str) -> Any:
+        values = self.__dict__.get("_values", {})
+        if name in values:
+            return values[name]
+        raise AttributeError(f"stec has no exposed value named {name!r}")
+
+    def __repr__(self) -> str:
+        keys = sorted(self._values)
+        return f"Stec(loaded_from={self._loaded_from!r}, keys={keys!r})"

stec/errors.py

@@ -0,0 +1,42 @@
+"""Custom exceptions raised by stec."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from .nodes import Position
+
+
+def _format_location(position: Optional[Position]) -> str:
+    if position is None:
+        return ""
+    return f" at line {position.line}, column {position.column}"
+
+
+class StecError(Exception):
+    """Base class for every error raised by stec."""
+
+    def __init__(self, message: str, position: Optional[Position] = None) -> None:
+        super().__init__(f"{message}{_format_location(position)}")
+        self.message = message
+        self.position = position
+
+
+class StecSyntaxError(StecError):
+    """Raised when the source text cannot be tokenized or parsed."""
+
+
+class StecTypeError(StecError):
+    """Raised when a value does not match the type declared on ``expose``."""
+
+
+class StecNameError(StecError):
+    """Raised for undefined variable references or duplicate declarations."""
+
+
+class StecLoadError(StecError):
+    """Raised when the configuration file cannot be read."""
+
+
+class StecAlreadyLoadedError(StecError):
+    """Raised when ``Stec.load`` is called twice without ``force=True``."""

stec/evaluator.py

@@ -0,0 +1,116 @@
+"""Evaluation of parsed stec documents into concrete values."""
+
+from __future__ import annotations
+
+from .nodes import (
+    Document,
+    ExposeDecl,
+    Expr,
+    Interp,
+    Literal,
+    Position,
+    Ternary,
+    Var,
+    VarDecl,
+)
+from .errors import StecError, StecNameError, StecTypeError
+
+
+def _infer_type(value: object) -> str:
+    if isinstance(value, bool):
+        return "bool"
+    if isinstance(value, int):
+        return "int"
+    if isinstance(value, float):
+        return "float"
+    if isinstance(value, str):
+        return "string"
+    raise StecError(f"internal error: unsupported value type {type(value).__name__}")
+
+
+def _format_value(value: object) -> str:
+    """Render a value for string interpolation."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _lookup(name: str, position: Position, environment: dict[str, object]) -> object:
+    if name not in environment:
+        raise StecNameError(
+            f"undefined name {name!r}; it must be declared before it is used",
+            position,
+        )
+    return environment[name]
+
+
+def _eval_expr(expr: Expr, environment: dict[str, object]) -> object:
+    if isinstance(expr, Literal):
+        return expr.value
+    if isinstance(expr, Var):
+        return _lookup(expr.name, expr.position, environment)
+    if isinstance(expr, Interp):
+        return "".join(
+            piece
+            if isinstance(piece, str)
+            else _format_value(_eval_expr(piece, environment))
+            for piece in expr.parts
+        )
+    if isinstance(expr, Ternary):
+        condition = _eval_expr(expr.condition, environment)
+        if _infer_type(condition) != "bool":
+            raise StecTypeError(
+                f"ternary condition must be a bool, got "
+                f"{_infer_type(condition)} {condition!r}",
+                expr.position,
+            )
+        if condition:
+            return _eval_expr(expr.then, environment)
+        return _eval_expr(expr.otherwise, environment)
+    raise StecError(
+        f"internal error: unsupported expression node {type(expr).__name__}"
+    )
+
+
+def _check_duplicate(
+    name: str,
+    position: Position,
+    environment: dict[str, object],
+) -> None:
+    if name in environment:
+        raise StecNameError(f"duplicate declaration of {name!r}", position)
+
+
+def evaluate(document: Document) -> dict[str, object]:
+    """Evaluate a document in order and return the exposed values.
+
+    ``var`` and ``expose`` declarations share one namespace: every declared
+    name becomes available to ``$name`` and ``${name}`` references made
+    afterwards. Only the exposed values are returned.
+    """
+    environment: dict[str, object] = {}
+    exposed: dict[str, object] = {}
+    for declaration in document:
+        if isinstance(declaration, VarDecl):
+            _check_duplicate(declaration.name, declaration.position, environment)
+            environment[declaration.name] = _eval_expr(
+                declaration.value, environment
+            )
+        elif isinstance(declaration, ExposeDecl):
+            _check_duplicate(declaration.name, declaration.position, environment)
+            value = _eval_expr(declaration.value, environment)
+            actual_type = _infer_type(value)
+            if actual_type != declaration.type:
+                raise StecTypeError(
+                    f"cannot expose {actual_type} value {value!r} "
+                    f"as '{declaration.type}' for '{declaration.name}'",
+                    declaration.position,
+                )
+            environment[declaration.name] = value
+            exposed[declaration.name] = value
+        else:
+            raise StecError(
+                f"internal error: unsupported declaration node "
+                f"{type(declaration).__name__}"
+            )
+    return exposed

stec/main.py

@@ -0,0 +1,36 @@
+"""Small playground to try the parser, evaluator, and singleton by hand."""
+
+from pathlib import Path
+import tempfile
+
+from stec import Stec
+from stec.evaluator import evaluate
+from stec.parser import parse
+
+SOURCE = """
+# runtime switches
+var dev = true  # flip for prod
+
+expose int port = 8080
+expose string secret = "secreteetoiertoiertoeritoeritoeriotio"
+expose string url = $dev ? "127.0.0.1" : "0.0.0.0"
+expose string api = "${url}:${port}/api"
+"""
+
+
+def main() -> None:
+    for declaration in parse(SOURCE):
+        print(declaration)
+
+    print(evaluate(parse(SOURCE)))
+
+    with tempfile.TemporaryDirectory() as directory:
+        path = Path(directory) / "app.stec"
+        path.write_text(SOURCE, encoding="utf-8")
+        Stec.load(path)
+        print(Stec.as_dict())
+        print(Stec.api, Stec["port"], Stec.get("secret"))
+
+
+if __name__ == "__main__":
+    main()

stec/nodes.py

@@ -0,0 +1,80 @@
+"""Abstract syntax tree nodes for stec documents."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Union
+
+
+@dataclass(frozen=True)
+class Position:
+    """A one-based (line, column) location in the source text."""
+
+    line: int
+    column: int
+
+    def __str__(self) -> str:
+        return f"{self.line}:{self.column}"
+
+
+@dataclass(frozen=True)
+class Literal:
+    """A literal value: int, float, string, or bool."""
+
+    value: object
+    kind: str
+    position: Position
+
+
+@dataclass(frozen=True)
+class Var:
+    """A reference to a previously declared ``var``."""
+
+    name: str
+    position: Position
+
+
+@dataclass(frozen=True)
+class Ternary:
+    """A conditional expression: ``condition ? then : otherwise``."""
+
+    condition: Expr
+    then: Expr
+    otherwise: Expr
+    position: Position
+
+
+@dataclass(frozen=True)
+class Interp:
+    """A string containing ``${name}`` interpolations.
+
+    ``parts`` alternates literal string chunks and variable references.
+    """
+
+    parts: tuple[Union[str, Var], ...]
+    position: Position
+
+
+Expr = Union[Literal, Var, Ternary, Interp]
+
+
+@dataclass(frozen=True)
+class VarDecl:
+    """An internal variable declaration: ``var NAME = value``."""
+
+    name: str
+    value: Expr
+    position: Position
+
+
+@dataclass(frozen=True)
+class ExposeDecl:
+    """A public, typed configuration value: ``expose TYPE NAME = value``."""
+
+    name: str
+    type: str
+    value: Expr
+    position: Position
+
+
+Document = list[Union[VarDecl, ExposeDecl]]