shtemplate 0.2.1__tar.gz

shtemplate-0.2.1/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Third-party test files, fetched locally by scripts/fetch_upstream.py; only the manifest is tracked.
+tests/upstream/*
+!tests/upstream/MANIFEST.json

shtemplate-0.2.1/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-13
+
+### Changed
+
+- The excerpt of the POSIX standard is no longer committed or shipped in the sdist: the
+  cited example pairs stay in the tests, and `scripts/fetch_upstream.py` fetches the page,
+  checked against `tests/upstream/MANIFEST.json`, for the tests that prove each pair is on it.
+
+## [0.2.0]
+
+### Added
+
+- `${#NAME}` length and the pattern removals `${NAME%word}`, `${NAME%%word}`,
+  `${NAME#word}` and `${NAME##word}` with shell pattern matching notation: `*`, `?`,
+  bracket expressions with ranges, negation and character classes, and quoting.
+- `${NAME:=word}` and `${NAME=word}`: the assigned value is visible to later references in
+  the same template; the mapping is never mutated. The new `assigned=` argument collects
+  the assignments.
+- Nested words: the word of an operator is expanded when needed (`${A:-${B:-x}}`), and the
+  closing brace is found by recursive scanning, honouring quotes and `\}`.
+- Backslash escapes with here-document rules: `\$`, `` \` ``, `\\` and line continuation.
+- Typed errors with a `position`: `TemplateSyntaxError`, `UnsetVariableError`,
+  `ParameterError` and `UnsafeTemplateError`, all subclasses of `ExpansionError`.
+- `safe=True` for untrusted templates: rejects `$(...)`, `$((...))` and backquotes and caps
+  the output size; `max_output=` sets the cap explicitly.
+- `list_vars()` lists the referenced names without expanding; `escape()` turns any text into
+  a template that expands to it.
+- The `shtemplate` command (also `python -m shtemplate`): expands a file or stdin against the
+  environment, `--env-file` files and `--set` values, with `--strict`, `--safe`,
+  `--list-vars`, `-i` and `-o`.
+- GUIDE.md with the exact rules, the design decisions and the differences from the shell and
+  from `string.Template`.
+- A corpus of more than 1,600 templates checked against dash and bash --posix.
+
+### Changed (breaking)
+
+These change the output of some 0.1.0 templates, most visibly ones with a backslash before
+`$` (such as Windows paths) or a `$` inside an operator word.
+
+- The word of `:-`, `-`, `:+`, `+`, `:?` and `?` is now expanded as in the shell
+  (`${X:-$HOME/bin}` uses the value of `HOME`). In 0.1.0 it was taken literally; write
+  `\$` for a literal dollar inside a word.
+- A backslash before `$`, backquote or backslash is now an escape, as in the shell.
+- `strict=True` now also applies to `${#NAME}` and the pattern removals, like `set -u`.
+- The `:?` message is now `NAME: message`, as the shell prints it.
+
+## [0.1.0]
+
+- Add `expand`: POSIX shell-style expansion of `$VAR` and `${VAR}` over a mapping.
+- Support the `:-`, `-`, `:+`, `+`, `:?` and `?` operators and the `$$` literal.
+- Add an opt-in strict mode that raises on an unset plain reference.
+- Add `ExpansionError` for malformed templates and required variables.

shtemplate-0.2.1/GUIDE.md

@@ -0,0 +1,163 @@
+# shtemplate guide
+
+This guide states exactly what `shtemplate` does, which choices it makes where the shell
+standard leaves room, and how it differs from a real shell and from `string.Template`.
+
+The reference is POSIX.1-2024, Shell Command Language, section 2.6.2 Parameter Expansion,
+section 2.14 Pattern Matching Notation and section 2.2 Quoting:
+https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html
+
+## The model: a here-document body
+
+A template is read the way a POSIX shell reads the body of an unquoted here-document
+(`cat <<EOF`). That is the context where a shell expands parameters in free text without
+splitting words or globbing, so it is the natural meaning of "shell-style template".
+
+At the top level of a template:
+
+- `$NAME` and `${...}` are expanded. Without braces the longest valid name is used, so `$Ab`
+  reads `Ab`. A name is an ASCII letter or underscore followed by letters, digits or
+  underscores.
+- A backslash escapes `$`, backquote, backslash and newline: `\$` is `$`, `\\` is `\`,
+  and a backslash before a newline joins the two lines. Before any other character the
+  backslash is kept (`\n` stays two characters).
+- Single and double quotes are ordinary characters.
+- `$$` is a literal `$` (see "Differences from a shell").
+- A `$` that does not start a name or a brace stays literal: `$5`, `$ `, `$-`, `$1`.
+
+## Operators
+
+| Operator | Set and not empty | Set but empty | Unset |
+| --- | --- | --- | --- |
+| `${p:-w}` | value | `w` | `w` |
+| `${p-w}` | value | empty | `w` |
+| `${p:=w}` | value | assign `w` | assign `w` |
+| `${p=w}` | value | empty | assign `w` |
+| `${p:?w}` | value | error | error |
+| `${p?w}` | value | empty | error |
+| `${p:+w}` | `w` | empty | empty |
+| `${p+w}` | `w` | `w` | empty |
+
+`${#p}` is the length of the value in characters (0 when unset). `${p%w}`, `${p%%w}`,
+`${p#w}` and `${p##w}` remove the shortest or longest suffix or prefix that matches the
+pattern `w`; when nothing matches the value is unchanged.
+
+The word `w` is expanded only when its value is needed. An unused word may contain a
+`${X:?...}` that never fires or an assignment that never happens. Syntax errors are still
+reported for the whole template, used or not, because the template is parsed first.
+
+### Words of the defaulting operators
+
+Inside the word of `-`, `=`, `?` and `+` (written in the here-document context):
+
+- `$NAME` and `${...}` expand, and nest to any depth up to 64 levels.
+- A backslash escapes `$`, backquote, `"`, `\` and `}`. `${X:-a\}b}` gives `a}b`.
+- Double quotes are removed and protect a `}`: `${X:-"x}"y}` gives `x}y`. The standard
+  leaves unescaped double quotes here unspecified; dash and bash both behave this way.
+- Single quotes are ordinary characters: `${X:-'a'}` gives `'a'`, exactly as the shells do.
+
+### Words of the pattern operators
+
+The standard says the enclosing double quotes have no effect on the four pattern
+operators, so their word is read as unquoted shell text:
+
+- `*`, `?` and `[...]` are pattern characters.
+- A backslash quotes the next character, single quotes quote their content and double
+  quotes quote theirs (with `$` still expanding inside them). Quoted characters match
+  themselves: `${V#'*'}` removes a literal star.
+- The result of an unquoted `$NAME` inside the pattern is itself a pattern, so
+  `${V#$PREFIX}` treats a `*` in `PREFIX` as a wildcard. Write `${V#"$PREFIX"}` to match it
+  literally.
+- Words nested inside a pattern word follow the same unquoted rules.
+
+If the variable is unset its pattern word is not expanded at all; dash and bash agree.
+
+### Pattern matching notation
+
+- `?` matches one character, `*` any run of characters including none.
+- `[abc]`, ranges `[a-z]`, negation with `[!...]` (also `[^...]`, like bash), a leading `]`
+  as a member (`[]a]`), character classes `[[:alpha:]]` (`alnum alpha blank cntrl digit
+  graph lower print punct space upper xdigit`) and the one-character forms `[=a=]` and
+  `[.a.]`. An unknown class matches nothing. A `[` that does not start a valid bracket
+  expression matches itself.
+- Ranges compare code points. Classes use Python's Unicode string methods, except `digit`,
+  `xdigit` and `punct`, which are ASCII, and `blank`, which is space and tab.
+- Matching runs as an automaton over all prefixes at once, in
+  `O(len(value) * len(pattern))` time. No pattern can make it backtrack exponentially.
+  That product can still be large when both sides are long, so whenever `max_output` is set
+  (always in safe mode) a removal that would need more than ten times `max_output` steps
+  raises `UnsafeTemplateError` before matching starts.
+
+## Decisions where a mapping is not a shell
+
+- **Assignment.** `${p:=w}` and `${p=w}` cannot assign into a read-only mapping, and
+  `shtemplate` never mutates the mapping you pass. The assigned value lives in an overlay
+  for the rest of the expansion, so `${PORT:=80} $PORT` gives `80 80`, as in a shell. Pass
+  `assigned=` to receive the assignments after a successful expansion; it is not touched when
+  the expansion fails. Passing the same dict as `env` and `assigned` updates it in place.
+- **`:?` and `?`.** A shell prints the message and exits. `shtemplate` raises
+  `ParameterError` with `name`, `detail` and `position`; `str(error)` is `NAME: message`, or
+  `NAME: parameter null or not set` (`NAME: parameter not set` for `?`) when the word is empty,
+  matching dash.
+- **Strict mode** is `set -u`: a plain reference, `${#p}` or a pattern removal on an unset
+  variable raises `UnsetVariableError`. The defaulting operators still work, and an empty
+  value counts as set.
+- **Command substitution and arithmetic** (`$(...)`, backquotes, `$((...))`) are never
+  executed. By default they are left in the output as literal text. In safe mode they raise
+  `UnsafeTemplateError`. Escaped forms (`\$(`, `` \` ``) are plain text in both modes.
+- **Safe mode** also caps the output at one million characters (`max_output=` changes it,
+  and works without safe mode too). Assignments can double a value at every step, so a short
+  template could otherwise produce gigabytes. The same limit bounds pattern matching work, as
+  described above, so a few hundred bytes of template cannot keep the matcher busy for hours.
+- **Errors carry positions.** Every error has a zero-based `position` into the template:
+  the `$` of the failing expansion, or the start of the malformed construct.
+
+## Differences from a shell
+
+These are deliberate. The two that occur in the oracle corpus (`$-` and `${R#"$R"}`) are
+listed in `tests/test_oracle.py` with their reasons.
+
+- `$$` is a literal `$`, not a process id. A mapping has no process.
+- Positional and special parameters (`$1`, `${10}`, `$@`, `$*`, `$#`, `$?`, `$-`, `$!`,
+  `$0`) do not exist in a mapping. Without braces they stay literal text; with braces
+  (`${1}`, `${#}`) they are a `TemplateSyntaxError`.
+- `${V#"$P"}` matches the value of `P` literally, as POSIX requires and bash does. dash
+  still treats a bracket expression or a backslash coming from the quoted value as active.
+- `[^...]` negates, as in bash; dash treats `^` as an ordinary member.
+- `[[=a=]]` and `[[.a.]]` match `a`, as in bash; dash does not support these forms.
+- A backslash just before the closing brace in a word (`${X:-\\}`) is an escaped backslash
+  followed by the closing brace. dash and bash both report a syntax error.
+- When a variable is set but empty, its pattern word is expanded (POSIX and dash); bash skips
+  it.
+- Lengths and `?` count characters (Unicode code points), as bash does; dash counts bytes.
+- Tilde expansion does not apply: in a here-document a shell leaves `~` alone too.
+
+## Evidence
+
+- `tests/data/oracle_corpus.json`: more than 1,600 templates from `scripts/build_corpus.py`
+  (hand-written generation rules with a fixed seed plus hand-written edge cases), with the
+  outputs of `dash` and `bash --posix` under WSL. Every case matches dash except `$-` and
+  `${R#"$R"}`, the two deviations above that the corpus exercises. A live test sends a fresh seeded batch to dash when WSL is
+  available.
+- `tests/test_spec_examples.py` runs the informative examples of section 2.6.2, cited from
+  the standard; with the page fetched by `scripts/fetch_upstream.py`, it also proves each
+  example is on the page.
+- `tests/test_fuzz.py` throws random templates at every entry point and checks that only
+  `ExpansionError` is raised, that nothing hangs and that no process is ever started.
+
+## Compared with `string.Template`
+
+| Input | `string.Template.substitute` | `safe_substitute` | `shtemplate.expand` |
+| --- | --- | --- | --- |
+| `$x`, `${x}` (x set) | value | value | value |
+| `$xy` (xy unset) | `KeyError` | `$xy` | empty, or `UnsetVariableError` in strict mode |
+| `$$` | `$` | `$` | `$` |
+| `price $5` | `ValueError` | `price $5` | `price $5` |
+| `${x:-d}` | `ValueError` | `${x:-d}` | value of x, or `d` |
+| `\$x` | `\` + value | `\` + value | `$x` |
+| `${1}` | `ValueError` | `${1}` | `TemplateSyntaxError` |
+
+Both use ASCII names and `$$` for a literal dollar. `string.Template` has no defaults,
+required values, conditional text, pattern removal or length, and gives backslash no meaning.
+Its identifier and delimiter can be customised by subclassing; `shtemplate` follows the shell
+grammar and is not configurable that way.

shtemplate-0.2.1/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.

shtemplate-0.2.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,138 @@
+# 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/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shtemplate"
+version = "0.2.1"
+description = "POSIX shell parameter expansion ($VAR, ${VAR:-default}, ${VAR%pattern}, ...) over any mapping, with a CLI; typed, safe, zero-dependency"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Javier Lianes", email = "javier@lianes8studio.com" }]
+keywords = ["template", "shell", "posix", "envsubst", "expandvars", "parameter-expansion", "environment", "dotenv"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+    "Operating System :: OS Independent",
+    "Environment :: Console",
+    "Topic :: Text Processing",
+    "Topic :: Software Development :: Libraries",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.scripts]
+shtemplate = "shtemplate._cli:main"
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest", "build", "twine"]
+
+[project.urls]
+Homepage = "https://lianes8studio.com"
+Repository = "https://github.com/JaviLianes8/shtemplate"
+Issues = "https://github.com/JaviLianes8/shtemplate/issues"
+Changelog = "https://github.com/JaviLianes8/shtemplate/blob/main/CHANGELOG.md"
+LinkedIn = "https://www.linkedin.com/in/jlianes/"
+Funding = "https://buymeacoffee.com/jlianesglrs"
+
+[tool.hatch.build.targets.sdist]
+# Third-party test files are fetched locally and never shipped; only their manifest is.
+include = [
+    "src/shtemplate",
+    "tests/*.py",
+    "tests/data/oracle_corpus.json",
+    "tests/upstream/MANIFEST.json",
+    "scripts/*.py",
+    "CHANGELOG.md",
+    "GUIDE.md",
+    "README.md",
+    "LICENSE",
+    "pyproject.toml",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shtemplate"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+mypy_path = "scripts"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-q"