shtemplate 0.2.1__py3-none-any.whl

shtemplate/__init__.py

@@ -0,0 +1,31 @@
+"""POSIX shell-style string expansion over any mapping, typed and zero-dependency.
+
+>>> from shtemplate import expand
+>>> expand("$HOME/${APP:-demo}", {"HOME": "/home/ada"})
+'/home/ada/demo'
+"""
+
+from __future__ import annotations
+
+from ._core import expand
+from ._errors import (
+    ExpansionError,
+    ParameterError,
+    TemplateSyntaxError,
+    UnsafeTemplateError,
+    UnsetVariableError,
+)
+from ._tools import escape, list_vars
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "ExpansionError",
+    "ParameterError",
+    "TemplateSyntaxError",
+    "UnsafeTemplateError",
+    "UnsetVariableError",
+    "escape",
+    "expand",
+    "list_vars",
+]

shtemplate/__main__.py

@@ -0,0 +1,5 @@
+"""Run the command line tool with ``python -m shtemplate``."""
+
+from ._cli import main
+
+raise SystemExit(main())

shtemplate/_cli.py

@@ -0,0 +1,108 @@
+"""Command line tool: expand a template from a file or stdin."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from typing import NoReturn
+
+from . import __version__
+from ._core import expand
+from ._dotenv import EnvFileError, parse_env, valid_name
+from ._errors import ExpansionError
+from ._tools import list_vars
+
+_EPILOG = """\
+examples:
+  echo 'Hello ${USER:-world}' | shtemplate
+  shtemplate config.tpl -o config.ini
+  shtemplate -i --env-file prod.env --set PORT=8080 config.tpl
+  shtemplate --strict --safe untrusted.tpl
+  shtemplate --list-vars config.tpl
+
+variables come from the process environment, then each --env-file in order,
+then each --set; later sources win. -i starts from an empty environment.
+errors go to stderr and the exit status is 1.
+"""
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(1, f"{self.prog}: error: {message}\n")
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _Parser(
+        prog="shtemplate",
+        description="Expand POSIX shell parameter expansions ($VAR, ${VAR:-default},\n"
+        "${VAR%pattern}, ...) in a template. Nothing is ever executed.",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    add = parser.add_argument
+    add("template", nargs="?", default="-", help="template file, or - for stdin (default)")
+    add("-o", "--output", metavar="FILE", help="write the result to FILE instead of stdout")
+    add("-e", "--env-file", metavar="FILE", action="append", default=[], help="read NAME=VALUE")
+    add("-s", "--set", metavar="NAME=VALUE", action="append", default=[], help="set one variable")
+    add("-i", "--ignore-environment", action="store_true", help="do not read os.environ")
+    add("--strict", action="store_true", help="fail on unset variables, like set -u")
+    add("--safe", action="store_true", help="reject $(...), $((...)), backquotes; cap output")
+    add("--list-vars", action="store_true", help="print referenced names, one per line, and exit")
+    add("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def _read(path: str) -> str:
+    if path == "-":
+        data, label = sys.stdin.buffer.read(), "stdin"
+    else:
+        with open(path, "rb") as handle:
+            data, label = handle.read(), path
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise EnvFileError(f"{label}: not valid UTF-8 (byte {exc.start})") from None
+
+
+def _environment(args: argparse.Namespace) -> dict[str, str]:
+    env: dict[str, str] = {} if args.ignore_environment else dict(os.environ)
+    for path in args.env_file:
+        env.update(parse_env(_read(path), path))
+    for item in args.set:
+        name, sep, value = item.partition("=")
+        if not sep or not valid_name(name):
+            raise EnvFileError(f"--set expects NAME=VALUE with a valid name, got {item!r}")
+        env[name] = value
+    return env
+
+
+def _write(text: str, output: str | None) -> None:
+    # surrogateescape writes back undecodable bytes taken from os.environ or argv.
+    data = text.encode("utf-8", errors="surrogateescape")
+    if output is None:
+        sys.stdout.buffer.write(data)
+        sys.stdout.buffer.flush()
+    else:
+        with open(output, "wb") as handle:
+            handle.write(data)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line tool; return the exit status."""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        template = _read(args.template)
+        if args.list_vars:
+            names = list_vars(template)
+            _write("".join(name + "\n" for name in names), args.output)
+            return 0
+        result = expand(template, _environment(args), strict=args.strict, safe=args.safe)
+        _write(result, args.output)
+    except (ExpansionError, EnvFileError, OSError, UnicodeError) as exc:
+        print(f"shtemplate: error: {exc}", file=sys.stderr)
+        return 1
+    return 0

shtemplate/_core.py

@@ -0,0 +1,159 @@
+"""Expand a parsed template against a mapping."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping
+
+from ._errors import ParameterError, UnsafeTemplateError, UnsetVariableError
+from ._nodes import PATTERN_OPS, Node, Param, Text
+from ._parser import parse
+from ._pattern import remove
+
+SAFE_MAX_OUTPUT = 1_000_000
+WORK_FACTOR = 10
+Segment = tuple[str, bool]
+
+
+def expand(
+    template: str,
+    env: Mapping[str, str] | None = None,
+    *,
+    strict: bool = False,
+    safe: bool = False,
+    assigned: MutableMapping[str, str] | None = None,
+    max_output: int | None = None,
+) -> str:
+    """Expand POSIX shell parameter expansions in ``template`` from ``env``.
+
+    Supported forms: ``$NAME``, ``${NAME}``, ``${#NAME}``, the defaulting
+    operators ``:-``, ``-``, ``:=``, ``=``, ``:?``, ``?``, ``:+``, ``+`` and the
+    pattern removals ``#``, ``##``, ``%``, ``%%``. Operator words are expanded
+    only when needed, so they may nest (``${A:-${B:-x}}``). Backslash escapes
+    ``$``, backquote and backslash (``\\$HOME`` stays literal) and ``$$`` is a
+    literal dollar. Nothing is ever executed: ``$(...)`` and backquotes are left
+    as literal text, or rejected in safe mode.
+
+    Args:
+        template: The text to expand.
+        env: The variables. Defaults to an empty mapping; pass ``os.environ``
+            explicitly to read the process environment. Never mutated.
+        strict: Behave like ``set -u``: a plain reference, ``${#NAME}`` or a
+            pattern removal on an unset variable raises ``UnsetVariableError``.
+        safe: For untrusted templates: reject ``$(...)``, ``$((...))`` and
+            backquotes with ``UnsafeTemplateError`` and cap the output at
+            ``max_output`` (one million characters unless given).
+        assigned: If given, receives the values assigned by ``:=`` and ``=``
+            after a successful expansion. Pass ``env`` itself to update it.
+        max_output: Raise ``UnsafeTemplateError`` if any expansion grows past
+            this many characters, or if a pattern removal would need more than
+            ten times this many matching steps (value length times pattern
+            length), which bounds the time an untrusted template can take.
+
+    Returns:
+        The expanded string.
+
+    Raises:
+        TemplateSyntaxError: The template is malformed.
+        UnsetVariableError: Strict mode met an unset variable.
+        ParameterError: A ``:?`` or ``?`` expansion found its variable missing.
+        UnsafeTemplateError: Safe mode rejected the template or the output limit
+            was reached.
+
+    Examples:
+        >>> expand("${USER:-guest}@${HOST:-localhost}", {"USER": "ada"})
+        'ada@localhost'
+        >>> expand("${FILE%.*}.o ${#FILE}", {"FILE": "main.c"})
+        'main.o 6'
+        >>> expand("${URL#*://}", {"URL": "https://example.org"})
+        'example.org'
+    """
+    parsed = parse(template)
+    if safe:
+        if parsed.unsafe:
+            position, kind = parsed.unsafe[0]
+            raise UnsafeTemplateError(
+                f"{kind} is not allowed in safe mode (at position {position})", position
+            )
+        if max_output is None:
+            max_output = SAFE_MAX_OUTPUT
+    evaluator = _Evaluator(env if env is not None else {}, strict, max_output)
+    result = evaluator.text(parsed.nodes)
+    if assigned is not None:
+        assigned.update(evaluator.overlay)
+    return result
+
+
+class _Evaluator:
+    def __init__(self, env: Mapping[str, str], strict: bool, max_output: int | None) -> None:
+        self.env = env
+        self.strict = strict
+        self.max_output = max_output
+        self.overlay: dict[str, str] = {}
+
+    def lookup(self, name: str) -> str | None:
+        if name in self.overlay:
+            return self.overlay[name]
+        return self.env.get(name)
+
+    def _check(self, size: int) -> None:
+        if self.max_output is not None and size > self.max_output:
+            raise UnsafeTemplateError(
+                f"expansion exceeds the limit of {self.max_output} characters"
+            )
+
+    def segments(self, nodes: tuple[Node, ...]) -> list[Segment]:
+        """Expand ``nodes`` into ``(text, literal)`` pieces; literal pieces match as-is."""
+        parts: list[Segment] = []
+        for node in nodes:
+            if isinstance(node, Text):
+                parts.append((node.value, node.quoted))
+            else:
+                found = self.param(node)
+                if node.quoted:
+                    found = [(value, True) for value, _ in found]
+                parts.extend(found)
+        self._check(sum(len(value) for value, _ in parts))
+        return parts
+
+    def text(self, nodes: tuple[Node, ...]) -> str:
+        return "".join(value for value, _ in self.segments(nodes))
+
+    def pattern(self, nodes: tuple[Node, ...]) -> str:
+        return "".join(
+            "".join("\\" + c for c in value) if literal else value
+            for value, literal in self.segments(nodes)
+        )
+
+    def _unset(self, node: Param) -> str:
+        if self.strict:
+            raise UnsetVariableError(node.name, node.position)
+        return ""
+
+    def param(self, node: Param) -> list[Segment]:
+        value = self.lookup(node.name)
+        op = node.op
+        if op == "":
+            return [(self._unset(node) if value is None else value, False)]
+        if op == "len":
+            return [(str(len(self._unset(node) if value is None else value)), False)]
+        if op in PATTERN_OPS:
+            # dash and bash both skip the pattern word of an unset variable.
+            if value is None:
+                return [(self._unset(node), False)]
+            limit = None if self.max_output is None else self.max_output * WORK_FACTOR
+            return [(remove(value, self.pattern(node.word), op, limit), False)]
+        missing = value is None or (node.colon and value == "")
+        if op == "+":
+            return [] if missing else self.segments(node.word)
+        if not missing:
+            return [(value or "", False)]
+        if op == "-":
+            return self.segments(node.word)
+        if op == "=":
+            word = self.segments(node.word)
+            self.overlay[node.name] = "".join(text for text, _ in word)
+            return word
+        detail = self.text(node.word)
+        if not detail:
+            detail = "parameter null or not set" if node.colon else "parameter not set"
+        raise ParameterError(node.name, detail, node.position)

shtemplate/_dotenv.py

@@ -0,0 +1,78 @@
+"""Read ``.env``-style files for the command line tool.
+
+One ``NAME=VALUE`` per line. Blank lines and lines starting with ``#`` are
+skipped and an optional ``export`` prefix is ignored. Values may be bare (a
+blank followed by ``#`` starts a comment; surrounding blanks are trimmed),
+single-quoted (taken literally) or double-quoted (``\\n``, ``\\t``, ``\\r``,
+``\\"``, ``\\\\`` and ``\\$`` are unescaped). Values are never expanded.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ._nodes import NAME_REST, NAME_START
+
+_COMMENT = re.compile(r"\s#")
+_DQ_ESCAPES = {"n": "\n", "t": "\t", "r": "\r", '"': '"', "\\": "\\", "$": "$"}
+
+
+class EnvFileError(ValueError):
+    """A line of an env file cannot be parsed."""
+
+
+def parse_env(text: str, source: str = "<env>") -> dict[str, str]:
+    """Parse ``.env``-style ``text`` into a dict; ``source`` names it in errors."""
+    values: dict[str, str] = {}
+    for number, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export ") or line.startswith("export\t"):
+            line = line[7:].lstrip()
+        name, sep, rest = line.partition("=")
+        name = name.rstrip()
+        if not sep or not valid_name(name):
+            raise EnvFileError(f"{source}:{number}: expected NAME=VALUE")
+        try:
+            values[name] = _value(rest.strip())
+        except ValueError as exc:
+            raise EnvFileError(f"{source}:{number}: {exc}") from None
+    return values
+
+
+def valid_name(name: str) -> bool:
+    """Return True when ``name`` is a POSIX shell variable name."""
+    return bool(name) and name[0] in NAME_START and all(c in NAME_REST for c in name)
+
+
+def _value(rest: str) -> str:
+    if rest.startswith("'"):
+        end = rest.find("'", 1)
+        if end == -1:
+            raise ValueError("unterminated single quote")
+        _trailing(rest[end + 1 :])
+        return rest[1:end]
+    if rest.startswith('"'):
+        out: list[str] = []
+        i = 1
+        while i < len(rest):
+            char = rest[i]
+            if char == "\\" and i + 1 < len(rest):
+                out.append(_DQ_ESCAPES.get(rest[i + 1], "\\" + rest[i + 1]))
+                i += 2
+                continue
+            if char == '"':
+                _trailing(rest[i + 1 :])
+                return "".join(out)
+            out.append(char)
+            i += 1
+        raise ValueError("unterminated double quote")
+    comment = _COMMENT.search(rest)
+    return (rest[: comment.start()] if comment else rest).strip()
+
+
+def _trailing(tail: str) -> None:
+    tail = tail.strip()
+    if tail and not tail.startswith("#"):
+        raise ValueError("unexpected text after the closing quote")

shtemplate/_errors.py

@@ -0,0 +1,69 @@
+"""Errors raised while parsing or expanding a template.
+
+Every error is an :class:`ExpansionError`, which is a :class:`ValueError`, so a
+single ``except ExpansionError`` (or ``except ValueError``) catches them all.
+Each error records the zero-based ``position`` in the template where the
+offending construct starts.
+"""
+
+from __future__ import annotations
+
+
+class ExpansionError(ValueError):
+    """A template is malformed or a required variable is unset.
+
+    Attributes:
+        position: Zero-based index into the template of the construct that
+            failed, or ``None`` when no single position applies.
+    """
+
+    def __init__(self, message: str, position: int | None = None) -> None:
+        super().__init__(message)
+        self.position = position
+
+
+class TemplateSyntaxError(ExpansionError):
+    """The template cannot be parsed.
+
+    Raised for an unterminated ``${``, an invalid or unsupported parameter name
+    such as ``${}`` or ``${1}``, an unknown operator such as ``${X@y}``, an
+    unterminated quote inside a pattern, or nesting deeper than the parser allows.
+    """
+
+
+class UnsetVariableError(ExpansionError):
+    """Strict mode met a reference to a variable that is not set.
+
+    Attributes:
+        name: The variable name.
+    """
+
+    def __init__(self, name: str, position: int) -> None:
+        super().__init__(f"undefined variable: {name} (at position {position})", position)
+        self.name = name
+
+
+class ParameterError(ExpansionError):
+    """A ``${NAME:?word}`` or ``${NAME?word}`` expansion found its variable missing.
+
+    The message is ``"NAME: word"``, or the shell's default text when ``word``
+    is empty.
+
+    Attributes:
+        name: The variable name.
+        detail: The expanded ``word`` (or the default text), without the name.
+    """
+
+    def __init__(self, name: str, detail: str, position: int) -> None:
+        super().__init__(f"{name}: {detail}", position)
+        self.name = name
+        self.detail = detail
+
+
+class UnsafeTemplateError(ExpansionError):
+    """Safe mode rejected the template or stopped an oversized expansion.
+
+    Raised for command substitution (``$(...)``), backquotes and arithmetic
+    expansion (``$((...))``), none of which is ever executed, and when the output
+    would exceed the configured ``max_output``.
+    """

shtemplate/_nodes.py

@@ -0,0 +1,66 @@
+"""Node types produced by the parser and consumed by the evaluator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+NAME_START = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ_")
+NAME_REST = NAME_START | frozenset("0123456789")
+PATTERN_OPS = frozenset({"#", "##", "%", "%%"})
+
+
+@dataclass(frozen=True)
+class Text:
+    """Literal characters. ``quoted`` marks pattern characters that match literally."""
+
+    value: str
+    quoted: bool = False
+
+
+@dataclass(frozen=True)
+class Param:
+    """One ``$NAME`` or ``${...}`` expansion.
+
+    ``op`` is ``""`` (plain), ``"len"``, one of ``- = ? +`` or a pattern operator.
+    ``quoted`` marks an expansion whose result must match literally in a pattern.
+    """
+
+    name: str
+    position: int
+    op: str = ""
+    colon: bool = False
+    word: tuple[Node, ...] = ()
+    quoted: bool = False
+
+
+Node = Text | Param
+
+
+@dataclass(frozen=True)
+class Parsed:
+    """A parsed template plus the positions of constructs that are never executed."""
+
+    nodes: tuple[Node, ...]
+    unsafe: tuple[tuple[int, str], ...] = field(default=())
+
+
+def merge(nodes: list[Node]) -> tuple[Node, ...]:
+    """Join runs of adjacent ``Text`` nodes that share the same ``quoted`` flag."""
+    merged: list[Node] = []
+    run: list[str] = []
+    quoted = False
+    for node in nodes:
+        if isinstance(node, Text) and (not run or node.quoted == quoted):
+            run.append(node.value)
+            quoted = node.quoted
+            continue
+        if run:
+            merged.append(Text("".join(run), quoted))
+            run = []
+        if isinstance(node, Text):
+            run, quoted = [node.value], node.quoted
+        else:
+            merged.append(node)
+    if run:
+        merged.append(Text("".join(run), quoted))
+    return tuple(merged)

shtemplate/_parser.py

@@ -0,0 +1,196 @@
+"""Parse a template into literal text and parameter-expansion nodes.
+
+The template is read like the body of an unquoted shell here-document: only
+``$``, backquote and backslash are special at the top level. Operator words are
+read with the rules of POSIX.1-2024 2.6.2 and 2.2.3, so the closing brace is
+found by recursive scanning and quotes inside a word are honoured.
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+
+from ._errors import TemplateSyntaxError
+from ._nodes import NAME_START, PATTERN_OPS, Node, Param, Parsed, Text, merge
+
+MAX_DEPTH = 64
+CACHE_LIMIT = 4096
+_WORD_ESCAPES = frozenset('$`"\\}')
+_TOP_ESCAPES = frozenset("$`\\")
+_TOP_SPECIAL = re.compile(r"[$`\\]")
+_WORD_SPECIAL = re.compile(r"[}\\\"'$`]")
+_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+
+def parse(template: str) -> Parsed:
+    """Parse ``template`` (cached up to ``CACHE_LIMIT`` characters); raise on bad syntax."""
+    return _parse_cached(template) if len(template) <= CACHE_LIMIT else _parse(template)
+
+
+def _parse(template: str) -> Parsed:
+    parser = _Parser(template)
+    return Parsed(parser.top(), tuple(parser.unsafe))
+
+
+_parse_cached = lru_cache(maxsize=512)(_parse)
+
+
+class _Parser:
+    def __init__(self, text: str) -> None:
+        self.text = text
+        self.pos = 0
+        self.depth = 0
+        self.unsafe: list[tuple[int, str]] = []
+
+    def _peek(self, offset: int = 0) -> str:
+        index = self.pos + offset
+        return self.text[index] if index < len(self.text) else ""
+
+    def top(self) -> tuple[Node, ...]:
+        nodes: list[Node] = []
+        while self.pos < len(self.text):
+            char = self.text[self.pos]
+            if char == "\\" and self._peek(1) in _TOP_ESCAPES and self._peek(1):
+                nodes.append(Text(self._peek(1)))
+                self.pos += 2
+            elif char == "\\" and self._peek(1) == "\n":
+                self.pos += 2
+            elif char == "$":
+                nodes.append(self._dollar(quoted=False, unquoted=False))
+            else:
+                nodes.append(Text(self._run(_TOP_SPECIAL)))
+        return merge(nodes)
+
+    def _run(self, special: re.Pattern[str]) -> str:
+        """Consume one special character, or literal text up to the next special one."""
+        if self.text[self.pos] == "`":
+            self.unsafe.append((self.pos, "backquote command substitution"))
+        found = special.search(self.text, self.pos + 1)
+        end = found.start() if found else len(self.text)
+        if self.text[self.pos] in "`'":
+            end = self.pos + 1
+        chunk = self.text[self.pos : end]
+        self.pos = end
+        return chunk
+
+    def _read_name(self) -> str:
+        found = _NAME.match(self.text, self.pos)
+        if found is None:
+            return ""
+        self.pos = found.end()
+        return found.group()
+
+    def _dollar(self, quoted: bool, unquoted: bool) -> Node:
+        start = self.pos
+        nxt = self._peek(1)
+        if nxt == "{":
+            return self._braced(start, quoted, unquoted)
+        if nxt and nxt in NAME_START:
+            self.pos += 1
+            return Param(self._read_name(), start, quoted=quoted)
+        if nxt == "$":
+            self.pos += 2
+            return Text("$", quoted)
+        if nxt == "(":
+            kind = "arithmetic expansion" if self._peek(2) == "(" else "command substitution"
+            self.unsafe.append((start, kind))
+        self.pos += 1
+        return Text("$", quoted)
+
+    def _error(self, message: str, position: int) -> TemplateSyntaxError:
+        return TemplateSyntaxError(f"{message} at position {position}", position)
+
+    def _braced(self, start: int, quoted: bool, unquoted: bool) -> Param:
+        self.depth += 1
+        if self.depth > MAX_DEPTH:
+            raise self._error(f"expansions nested deeper than {MAX_DEPTH}", start)
+        self.pos += 2
+        if self._peek() == "#" and self._peek(1) in NAME_START and self._peek(1):
+            self.pos += 1
+            name = self._read_name()
+            if self._peek() != "}":
+                raise self._error("invalid length expansion", start)
+            self.pos += 1
+            self.depth -= 1
+            return Param(name, start, "len", quoted=quoted)
+        name = self._read_name()
+        if not name:
+            if not self._peek():
+                raise self._error("unterminated expansion: missing '}'", start)
+            raise self._error("invalid variable name in expansion", start)
+        op, colon = self._operator(start)
+        word: tuple[Node, ...] = ()
+        if op:
+            word = self._word(unquoted or op in PATTERN_OPS, start)
+        self.depth -= 1
+        return Param(name, start, op, colon, word, quoted)
+
+    def _operator(self, start: int) -> tuple[str, bool]:
+        char = self._peek()
+        if char == "}":
+            self.pos += 1
+            return "", False
+        if not char:
+            raise self._error("unterminated expansion: missing '}'", start)
+        colon = char == ":"
+        if colon:
+            self.pos += 1
+            char = self._peek()
+        if char and char in "-=?+":
+            self.pos += 1
+            return char, colon
+        if not colon and char in "#%":
+            double = self._peek(1) == char
+            self.pos += 2 if double else 1
+            return char * 2 if double else char, False
+        if not char:
+            raise self._error("unterminated expansion: missing '}'", start)
+        raise self._error(f"unknown operator {char!r} in expansion", start)
+
+    def _word(self, unquoted: bool, start: int) -> tuple[Node, ...]:
+        nodes: list[Node] = []
+        in_dq = False
+        while True:
+            char = self._peek()
+            if not char:
+                raise self._error("unterminated expansion: missing '}'", start)
+            if char == "}" and not in_dq:
+                self.pos += 1
+                return merge(nodes)
+            literal = unquoted and in_dq
+            if char == "\\":
+                nodes.extend(self._escape(unquoted, in_dq, start))
+            elif char == '"':
+                in_dq = not in_dq
+                self.pos += 1
+            elif char == "'" and unquoted and not in_dq:
+                nodes.append(Text(self._single_quoted(start), True))
+            elif char == "$":
+                nodes.append(self._dollar(literal, unquoted and not in_dq))
+            else:
+                nodes.append(Text(self._run(_WORD_SPECIAL), literal))
+
+    def _escape(self, unquoted: bool, in_dq: bool, start: int) -> list[Node]:
+        nxt = self._peek(1)
+        if not nxt:
+            raise self._error("unterminated expansion: missing '}'", start)
+        if nxt == "\n":
+            self.pos += 2
+            return []
+        if unquoted and not in_dq:
+            self.pos += 2
+            return [Text(nxt, True)]
+        if nxt in _WORD_ESCAPES:
+            self.pos += 2
+            return [Text(nxt, unquoted)]
+        self.pos += 1
+        return [Text("\\", unquoted)]
+
+    def _single_quoted(self, start: int) -> str:
+        end = self.text.find("'", self.pos + 1)
+        if end == -1:
+            raise self._error("unterminated single quote", start)
+        content = self.text[self.pos + 1 : end]
+        self.pos = end + 1
+        return content

shtemplate/_pattern.py

@@ -0,0 +1,193 @@
+"""Shell pattern matching notation (POSIX.1-2024 2.14) for prefix and suffix removal.
+
+A pattern is held as a string where a backslash makes the next character
+literal. ``?`` matches one character, ``*`` any run of characters and ``[...]``
+a bracket expression. Matching simulates the pattern as a small automaton, so
+every prefix of a value is tested in one pass: ``O(len(value) * len(pattern))``
+time with no backtracking blowups, whatever the pattern.
+"""
+
+from __future__ import annotations
+
+import string
+from collections.abc import Callable
+from functools import lru_cache
+
+from ._errors import UnsafeTemplateError
+
+Matcher = Callable[[str], bool]
+_STAR: Matcher = bool  # sentinel identity; never called
+
+_CLASSES: dict[str, Matcher] = {
+    "alnum": str.isalnum,
+    "alpha": str.isalpha,
+    "blank": lambda c: c in " \t",
+    "cntrl": lambda c: ord(c) < 32 or ord(c) == 127,
+    "digit": lambda c: c in string.digits,
+    "graph": lambda c: c.isprintable() and not c.isspace(),
+    "lower": str.islower,
+    "print": str.isprintable,
+    "punct": lambda c: c in string.punctuation,
+    "space": str.isspace,
+    "upper": str.isupper,
+    "xdigit": lambda c: c in string.hexdigits,
+}
+
+
+def _never(_: str) -> bool:
+    return False
+
+
+def _bracket(pattern: str, start: int) -> tuple[Matcher, int] | None:
+    """Parse a bracket expression at ``pattern[start] == "["``; None if invalid."""
+    j = start + 1
+    negate = j < len(pattern) and pattern[j] in "!^"
+    j += 1 if negate else 0
+    chars: set[str] = set()
+    ranges: list[tuple[str, str]] = []
+    tests: list[Matcher] = []
+    first = True
+    while j < len(pattern):
+        char = pattern[j]
+        if char == "]" and not first:
+            return _member(negate, frozenset(chars), tuple(ranges), tuple(tests)), j + 1
+        first = False
+        if char == "[" and pattern[j + 1 : j + 2] in (":", "=", "."):
+            kind = pattern[j + 1]
+            end = pattern.find(kind + "]", j + 2)
+            if end != -1:
+                name = pattern[j + 2 : end]
+                if kind == ":":
+                    tests.append(_CLASSES.get(name, _never))
+                elif len(name) == 1:
+                    chars.add(name)
+                j = end + 2
+                continue
+        low, j = _bracket_char(pattern, j)
+        if pattern[j : j + 1] == "-" and j + 1 < len(pattern) and pattern[j + 1] != "]":
+            high, j = _bracket_char(pattern, j + 1)
+            ranges.append((low, high))
+        else:
+            chars.add(low)
+    return None
+
+
+def _bracket_char(pattern: str, j: int) -> tuple[str, int]:
+    if pattern[j] == "\\" and j + 1 < len(pattern):
+        return pattern[j + 1], j + 2
+    return pattern[j], j + 1
+
+
+def _member(
+    negate: bool,
+    chars: frozenset[str],
+    ranges: tuple[tuple[str, str], ...],
+    tests: tuple[Matcher, ...],
+) -> Matcher:
+    def matches(char: str) -> bool:
+        found = (
+            char in chars
+            or any(low <= char <= high for low, high in ranges)
+            or any(test(char) for test in tests)
+        )
+        return found != negate
+
+    return matches
+
+
+def _literal(expected: str) -> Matcher:
+    return expected.__eq__
+
+
+def _any(_: str) -> bool:
+    return True
+
+
+def compile_pattern(pattern: str) -> tuple[Matcher, ...]:
+    """Turn ``pattern`` into a tuple of single-character matchers and ``_STAR`` marks."""
+    if len(pattern) <= 1024:
+        return _compile_cached(pattern)
+    return _compile(pattern)
+
+
+def _compile(pattern: str) -> tuple[Matcher, ...]:
+    items: list[Matcher] = []
+    i = 0
+    while i < len(pattern):
+        char = pattern[i]
+        if char == "\\" and i + 1 < len(pattern):
+            items.append(_literal(pattern[i + 1]))
+            i += 2
+            continue
+        if char == "*":
+            if not items or items[-1] is not _STAR:
+                items.append(_STAR)
+        elif char == "?":
+            items.append(_any)
+        elif char == "[" and (parsed := _bracket(pattern, i)) is not None:
+            items.append(parsed[0])
+            i = parsed[1]
+            continue
+        else:
+            items.append(_literal(char))
+        i += 1
+    return tuple(items)
+
+
+_compile_cached = lru_cache(maxsize=512)(_compile)
+
+
+def _closure(states: set[int], items: tuple[Matcher, ...]) -> set[int]:
+    for state in sorted(states):
+        index = state
+        while index < len(items) and items[index] is _STAR:
+            index += 1
+            states.add(index)
+    return states
+
+
+def match_lengths(items: tuple[Matcher, ...], text: str) -> list[int]:
+    """Return every ``n`` (ascending) such that ``text[:n]`` matches the whole pattern."""
+    end = len(items)
+    states = _closure({0}, items)
+    found = [0] if end in states else []
+    for count, char in enumerate(text, start=1):
+        step: set[int] = set()
+        for state in states:
+            if state == end:
+                continue
+            item = items[state]
+            if item is _STAR:
+                step.add(state)
+            elif item(char):
+                step.add(state + 1)
+        if not step:
+            break
+        states = _closure(step, items)
+        if end in states:
+            found.append(count)
+    return found
+
+
+def remove(value: str, pattern: str, op: str, work_limit: int | None = None) -> str:
+    """Apply ``#``, ``##``, ``%`` or ``%%`` with ``pattern`` to ``value``.
+
+    With ``work_limit``, raise :class:`UnsafeTemplateError` instead of matching
+    when ``len(value) * len(pattern)`` (the worst-case step count) exceeds it.
+    """
+    items = compile_pattern(pattern)
+    if work_limit is not None and len(value) * max(len(items), 1) > work_limit:
+        raise UnsafeTemplateError(
+            f"pattern matching would take more than {work_limit} steps "
+            f"({len(value)} characters against {len(items)} pattern items)"
+        )
+    if op.startswith("#"):
+        lengths = match_lengths(items, value)
+        if not lengths:
+            return value
+        return value[(lengths[0] if op == "#" else lengths[-1]) :]
+    lengths = match_lengths(items[::-1], value[::-1])
+    if not lengths:
+        return value
+    cut = lengths[0] if op == "%" else lengths[-1]
+    return value[: len(value) - cut]

shtemplate/_tools.py

@@ -0,0 +1,48 @@
+"""Helpers that work on a template without expanding it."""
+
+from __future__ import annotations
+
+from ._nodes import Node, Param
+from ._parser import parse
+
+_ESCAPES = {"\\": "\\\\", "$": "\\$", "`": "\\`"}
+
+
+def list_vars(template: str) -> list[str]:
+    """Return every variable name ``template`` references, in order of first use.
+
+    Names inside operator words are included even when that word would not be
+    needed, so the result is the full set of names the template may read.
+    Nothing is expanded and no mapping is needed.
+
+    Raises:
+        TemplateSyntaxError: The template is malformed.
+
+    Examples:
+        >>> list_vars("$HOME/${APP:-demo}/${APP_DIR:-$HOME/.app}")
+        ['HOME', 'APP', 'APP_DIR']
+    """
+    seen: dict[str, None] = {}
+    _collect(parse(template).nodes, seen)
+    return list(seen)
+
+
+def _collect(nodes: tuple[Node, ...], seen: dict[str, None]) -> None:
+    for node in nodes:
+        if isinstance(node, Param):
+            seen.setdefault(node.name, None)
+            _collect(node.word, seen)
+
+
+def escape(text: str) -> str:
+    r"""Return a template that expands to exactly ``text``.
+
+    Backslash, dollar and backquote are escaped with a backslash, so
+    ``expand(escape(text)) == text`` for every string, and a POSIX shell reading
+    the result as a here-document body prints ``text`` too.
+
+    Examples:
+        >>> print(escape(r"cost: $5 \o/"))
+        cost: \$5 \\o/
+    """
+    return "".join(_ESCAPES.get(char, char) for char in text)

shtemplate-0.2.1.dist-info/METADATA

@@ -0,0 +1,173 @@
+Metadata-Version: 2.5
+Name: shtemplate
+Version: 0.2.1
+Summary: POSIX shell parameter expansion ($VAR, ${VAR:-default}, ${VAR%pattern}, ...) over any mapping, with a CLI; typed, safe, zero-dependency
+Project-URL: Homepage, https://lianes8studio.com
+Project-URL: Repository, https://github.com/JaviLianes8/shtemplate
+Project-URL: Issues, https://github.com/JaviLianes8/shtemplate/issues
+Project-URL: Changelog, https://github.com/JaviLianes8/shtemplate/blob/main/CHANGELOG.md
+Project-URL: LinkedIn, https://www.linkedin.com/in/jlianes/
+Project-URL: Funding, https://buymeacoffee.com/jlianesglrs
+Author-email: Javier Lianes <javier@lianes8studio.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dotenv,environment,envsubst,expandvars,parameter-expansion,posix,shell,template
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# shtemplate
+
+POSIX shell parameter expansion (`$VAR`, `${VAR:-default}`, `${VAR%pattern}`, ...) over
+any mapping, with a command line tool. Typed, safe for untrusted templates, zero dependencies.
+
+Outputs are cross-checked against `dash` and `bash --posix` on a corpus of more than 1,600
+templates. Nothing in a template is ever executed.
+
+## Install
+
+```
+pip install shtemplate
+```
+
+## Usage
+
+```python
+from shtemplate import expand
+
+values = {"USER": "ada", "HOME": "/home/ada", "FILE": "report.tar.gz", "EMPTY": ""}
+
+expand("$HOME/${APP:-demo}", values)  # "/home/ada/demo"
+expand("${EMPTY:-guest} [${EMPTY-guest}]", values)  # "guest []"
+expand("${USER:+signed in as $USER}", values)  # "signed in as ada"
+expand("${CONF:-${XDG:-$HOME/.config}}/app", values)  # "/home/ada/.config/app"
+
+# Pattern removal and length
+expand("${FILE%.gz} ${FILE%%.*} ${FILE#*.} ${FILE##*.}", values)  # "report.tar report tar.gz gz"
+expand("${#USER}", values)  # "3"
+
+# Required values raise a typed error that names the variable
+expand("${TOKEN:?token is required}", values)  # ParameterError: TOKEN: token is required
+
+# Escapes: \$ and $$ are a literal dollar
+expand("price \\$5 or $$5", values)  # "price $5 or $5"
+```
+
+`env` is any `Mapping[str, str]` and is never mutated. It defaults to an empty mapping, so
+nothing is read from the process environment unless you pass `os.environ` yourself.
+
+### Strict and safe modes
+
+```python
+from shtemplate import expand
+
+expand("$MISSING", {}, strict=True)  # UnsetVariableError: undefined variable: MISSING ...
+expand("${MISSING:-ok}", {}, strict=True)  # "ok": the default handles the unset case
+
+expand("$(rm -rf ~)", {})  # "$(rm -rf ~)": left as literal text, never run
+expand("$(rm -rf ~)", {}, safe=True)  # UnsafeTemplateError: command substitution ...
+```
+
+`strict=True` behaves like `set -u`. `safe=True` is meant for templates you do not trust: it
+rejects `$(...)`, `$((...))` and backquotes, caps the output at one million characters
+(`max_output=` to change it) and bounds pattern matching work to match.
+
+### Inspecting and escaping
+
+```python
+from shtemplate import escape, expand, list_vars
+
+list_vars("$HOME/${APP:-demo}/${LOG:-$HOME/log}")  # ["HOME", "APP", "LOG"]
+expand(escape("cost: $5"), {})  # "cost: $5"
+```
+
+### Assignment
+
+`${NAME:=word}` and `${NAME=word}` substitute `word` and make it visible to later references
+in the same template. The mapping you pass is read-only to `shtemplate`; collect the
+assignments with `assigned=` (pass the same dict as `env` to update it in place).
+
+```python
+from shtemplate import expand
+
+sink: dict[str, str] = {}
+expand("${PORT:=8080} on $PORT", {}, assigned=sink)  # "8080 on 8080"; sink == {"PORT": "8080"}
+```
+
+### Supported forms
+
+| Form | Result |
+| --- | --- |
+| `${NAME}` | the value; empty if unset (an error in strict mode) |
+| `$NAME` | same, using the longest valid name |
+| `${NAME:-word}` | `word` if unset or empty |
+| `${NAME-word}` | `word` if unset |
+| `${NAME:=word}` | `word` if unset or empty, and assign it |
+| `${NAME=word}` | `word` if unset, and assign it |
+| `${NAME:+word}` | `word` if set and not empty, else empty |
+| `${NAME+word}` | `word` if set, else empty |
+| `${NAME:?word}` | raise `ParameterError` if unset or empty |
+| `${NAME?word}` | raise `ParameterError` if unset |
+| `${#NAME}` | the length in characters |
+| `${NAME%word}` | remove the shortest suffix matching the pattern `word` |
+| `${NAME%%word}` | remove the longest matching suffix |
+| `${NAME#word}` | remove the shortest matching prefix |
+| `${NAME##word}` | remove the longest matching prefix |
+| `$$` | a literal `$` |
+| `\$NAME` | a literal `$NAME` (backslash also escapes backquote and backslash) |
+
+`word` is expanded only when it is needed, so it may contain other expansions. Patterns use
+shell notation: `*`, `?`, `[a-z]`, `[!...]`, `[[:alpha:]]` and backslash or quotes for literal
+characters. Malformed templates raise `TemplateSyntaxError` with the position. Every error is an
+`ExpansionError`, which is a `ValueError`. The [GUIDE](GUIDE.md) covers the exact rules, the
+design decisions and the differences from the shell and from `string.Template`.
+
+## Command line
+
+```
+echo 'Hello ${USER:-world}' | shtemplate
+shtemplate config.tpl -o config.ini
+shtemplate -i --env-file prod.env --set PORT=8080 config.tpl
+shtemplate --strict --safe untrusted.tpl
+shtemplate --list-vars config.tpl
+```
+
+Variables come from the process environment, then each `--env-file` (`NAME=VALUE` lines, never
+expanded), then each `--set`. `-i` starts from an empty environment. Errors go to stderr with
+exit status 1. `python -m shtemplate` works too.
+
+## Why
+
+Python's `string.Template` understands `$NAME` and `${NAME}` only: no defaults, no required
+values, no pattern removal. `os.path.expandvars` silently leaves unknown names in place and
+reads only `os.environ`. `shtemplate` gives you the shell's full parameter expansion as a pure
+function over a mapping you choose, with typed errors, a strict mode, a safe mode for
+untrusted input and a CLI that does what `envsubst` does, plus defaults, required values and
+pattern removal.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- Website: https://lianes8studio.com
+- GitHub: https://github.com/JaviLianes8
+- LinkedIn: https://www.linkedin.com/in/jlianes/

shtemplate-0.2.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+shtemplate/__init__.py,sha256=MAqpeNWuMsxf1aJ8o9b7-iI6DAJubvC-AHVXHWmkOTA,642
+shtemplate/__main__.py,sha256=rJerH6mauVj6yv2u18MuZJmbqerga-STXhWvEw50Uf4,113
+shtemplate/_cli.py,sha256=Fu9mNH98TncIwrO350CO_AUL7R3knOR2aXFL462frHM,4130
+shtemplate/_core.py,sha256=B7xSENPShNfbEhMucQTHnDvFJYb6hw_jYvRsxYoFc-U,6483
+shtemplate/_dotenv.py,sha256=su9GRV0yBPsD1zlQDrG9iZHKfxhJp3rsQkz4pm1Nff0,2753
+shtemplate/_errors.py,sha256=da580QX0EPNF9CNdangEWVUk6OMOJubc03Elfq1Y1fQ,2310
+shtemplate/_nodes.py,sha256=6TixWsvR_K4M12PXghKVbaL0Eb3uS7aHQcG0IhXFgt0,1825
+shtemplate/_parser.py,sha256=IspFEeKJCwSF0iwHz_zVJSkUAEIUYBLdtS31wT0TU5s,7289
+shtemplate/_pattern.py,sha256=aeY5z-qCBeKHfCicE_VF2xzMOFxkm45vrYzZ68ldHQ8,6247
+shtemplate/_tools.py,sha256=Lr2W5EhZIUJu0waPrOOTi6tLFkecFINgo-GMqxMGBr8,1494
+shtemplate/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+shtemplate-0.2.1.dist-info/METADATA,sha256=6sI4e8suUKdCVHLiLD479efefPPlnPl8aFJtA-xK1qk,6895
+shtemplate-0.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+shtemplate-0.2.1.dist-info/entry_points.txt,sha256=pJ8Nuq7I_ckFLCxktkDXWllefHcpkscg4MnJSNV4Xtk,52
+shtemplate-0.2.1.dist-info/licenses/LICENSE,sha256=wirD5nCA2aQa5UusK_1YHLBogI3CGcw23xAnulp3L_U,1091
+shtemplate-0.2.1.dist-info/RECORD,,

shtemplate-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

shtemplate-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+shtemplate = shtemplate._cli:main

shtemplate-0.2.1.dist-info/licenses/LICENSE

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