fstache 0.1.0__tar.gz

fstache-0.1.0/LICENSE

@@ -0,0 +1,12 @@
+Zero-Clause BSD
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

fstache-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: fstache
+Version: 0.1.0
+Summary: A fast and realistic Mustache-based HTML generator
+Author: vkorobkov
+License-Expression: 0BSD
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: ruff>=0.6.0 ; extra == 'dev'
+Requires-Dist: chevron==0.14.0 ; extra == 'dev'
+Requires-Dist: mstache==0.3.0 ; extra == 'dev'
+Requires-Dist: pystache==0.6.8 ; extra == 'dev'
+Requires-Dist: pytest ; extra == 'dev'
+Requires-Dist: ty ; extra == 'dev'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/servletcloud/fstache
+Project-URL: Repository, https://github.com/servletcloud/fstache
+Project-URL: Issues, https://github.com/servletcloud/fstache/issues
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# Fstache
+
+## Overview
+
+- Dependency-free [Mustache](https://mustache.github.io/) renderer for
+  [Python 3.12+](https://docs.python.org/3.12/).
+- Supports [upstream Mustache spec fixtures](https://github.com/mustache/spec),
+  including lambdas and dynamic partial names; **inheritance is unsupported**.
+- Built for speed; [benchmarked](#benchmarks) at 3.3x
+  [Chevron](https://github.com/noahmorrison/chevron), 3.1x
+  [mstache](https://pypi.org/project/mstache/), and 3.5x
+  [Pystache](https://github.com/defunkt/pystache).
+- [PEP 561](https://peps.python.org/pep-0561/) typed package.
+- Supports Python mappings, objects, sequences, and callables as render data.
+- Static partials are preloaded and inlined, eliminating render-time boundary overhead.
+
+
+## Benchmarks
+
+### Renderer Throughput
+
+| Library | Renders per second | Indentation details |
+| --- | ---: | --- |
+| Fstache | 4066.5 | **Deviates**: `ignore_indents=True` skips standard standalone partial reindentation. |
+| Fstache | 3102.2 | Follows standard standalone partial indentation. |
+| mstache | 1339.0 | **Deviates**: `keep_lines=True` keeps tag-only lines instead of collapsing them, so partial indentation is not reapplied to every partial line. |
+| mstache | 985.3 | Follows standard standalone partial indentation. |
+| Chevron | 951.1 | Follows standard standalone partial indentation. |
+| Pystache | 898.8 | Follows standard standalone partial indentation. |
+
+
+### Benchmark environment
+
+| Field | Value |
+| --- | --- |
+| Python | CPython 3.14.6 |
+| OS | Fedora Linux 44 (Workstation Edition), Linux 7.0.12-201.fc44.x86_64 |
+| CPU | AMD Ryzen 7 8845HS w/ Radeon 780M Graphics, 8 cores / 16 threads |
+| Compared versions | Fstache 0.1.0, Chevron 0.14.0, mstache 0.3.0, Pystache 0.6.8 |
+| Command | `RENDERER=<renderer> uv run --python 3.14 --extra dev python tests/perf_test.py`<br>`<renderer>` values: `fstache.no_indentation`, `fstache`, `mstache.no_indentation`, `mstache`, `chevron`, `pystache` |
+
+
+### Methodology
+
+- The benchmark renders a realistic, heavy marketing/docs HTML page from the
+  [source Mustache templates](demo/templates), [JSON data](demo/data.json), and
+  [perf script](tests/perf_test.py):
+  - About 100 KiB of [rendered HTML](https://servletcloud.github.io/fstache/)
+    ([source](demo/dist/index.html)) from 15 Mustache templates, including 14
+    partial files.
+  - Tailwind CSS v4 utility-heavy markup with Alpine.js attributes, inline SVG
+    icons, responsive navigation, cards, tables, accordions, and form controls.
+  - About 15 KiB of JSON context data with nested arrays for navigation,
+    feature cards, testimonials, a recursive docs tree, comparison rows, blog
+    posts, changelog entries, FAQs, and pricing plans.
+  - 42 section, inverted-section, and partial references, including 24 section
+    tags for loops and conditionals plus recursive `node` partial rendering.
+- The benchmark isolates render throughput from setup work:
+  - Each engine preloads the template files and partials during setup.
+  - Each engine uses the closest available precompiled, preparsed, or
+    pretokenized representation for the layout and partials.
+  - The timed render loop excludes disk I/O and one-time template preparation.
+
+---
+
+## Utility Commands
+
+### Generate Reference HTML
+Builds and renders the templates from `./demo` into `./demo/dist/index.html` (performing file I/O):
+```bash
+make build-html
+```
+
+### Format and Lint
+Runs ruff checks and auto-formats the project:
+```bash
+make post-ai-change
+```

fstache-0.1.0/README.md

@@ -0,0 +1,78 @@
+# Fstache
+
+## Overview
+
+- Dependency-free [Mustache](https://mustache.github.io/) renderer for
+  [Python 3.12+](https://docs.python.org/3.12/).
+- Supports [upstream Mustache spec fixtures](https://github.com/mustache/spec),
+  including lambdas and dynamic partial names; **inheritance is unsupported**.
+- Built for speed; [benchmarked](#benchmarks) at 3.3x
+  [Chevron](https://github.com/noahmorrison/chevron), 3.1x
+  [mstache](https://pypi.org/project/mstache/), and 3.5x
+  [Pystache](https://github.com/defunkt/pystache).
+- [PEP 561](https://peps.python.org/pep-0561/) typed package.
+- Supports Python mappings, objects, sequences, and callables as render data.
+- Static partials are preloaded and inlined, eliminating render-time boundary overhead.
+
+
+## Benchmarks
+
+### Renderer Throughput
+
+| Library | Renders per second | Indentation details |
+| --- | ---: | --- |
+| Fstache | 4066.5 | **Deviates**: `ignore_indents=True` skips standard standalone partial reindentation. |
+| Fstache | 3102.2 | Follows standard standalone partial indentation. |
+| mstache | 1339.0 | **Deviates**: `keep_lines=True` keeps tag-only lines instead of collapsing them, so partial indentation is not reapplied to every partial line. |
+| mstache | 985.3 | Follows standard standalone partial indentation. |
+| Chevron | 951.1 | Follows standard standalone partial indentation. |
+| Pystache | 898.8 | Follows standard standalone partial indentation. |
+
+
+### Benchmark environment
+
+| Field | Value |
+| --- | --- |
+| Python | CPython 3.14.6 |
+| OS | Fedora Linux 44 (Workstation Edition), Linux 7.0.12-201.fc44.x86_64 |
+| CPU | AMD Ryzen 7 8845HS w/ Radeon 780M Graphics, 8 cores / 16 threads |
+| Compared versions | Fstache 0.1.0, Chevron 0.14.0, mstache 0.3.0, Pystache 0.6.8 |
+| Command | `RENDERER=<renderer> uv run --python 3.14 --extra dev python tests/perf_test.py`<br>`<renderer>` values: `fstache.no_indentation`, `fstache`, `mstache.no_indentation`, `mstache`, `chevron`, `pystache` |
+
+
+### Methodology
+
+- The benchmark renders a realistic, heavy marketing/docs HTML page from the
+  [source Mustache templates](demo/templates), [JSON data](demo/data.json), and
+  [perf script](tests/perf_test.py):
+  - About 100 KiB of [rendered HTML](https://servletcloud.github.io/fstache/)
+    ([source](demo/dist/index.html)) from 15 Mustache templates, including 14
+    partial files.
+  - Tailwind CSS v4 utility-heavy markup with Alpine.js attributes, inline SVG
+    icons, responsive navigation, cards, tables, accordions, and form controls.
+  - About 15 KiB of JSON context data with nested arrays for navigation,
+    feature cards, testimonials, a recursive docs tree, comparison rows, blog
+    posts, changelog entries, FAQs, and pricing plans.
+  - 42 section, inverted-section, and partial references, including 24 section
+    tags for loops and conditionals plus recursive `node` partial rendering.
+- The benchmark isolates render throughput from setup work:
+  - Each engine preloads the template files and partials during setup.
+  - Each engine uses the closest available precompiled, preparsed, or
+    pretokenized representation for the layout and partials.
+  - The timed render loop excludes disk I/O and one-time template preparation.
+
+---
+
+## Utility Commands
+
+### Generate Reference HTML
+Builds and renders the templates from `./demo` into `./demo/dist/index.html` (performing file I/O):
+```bash
+make build-html
+```
+
+### Format and Lint
+Runs ruff checks and auto-formats the project:
+```bash
+make post-ai-change
+```

fstache-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "fstache"
+version = "0.1.0"
+description = "A fast and realistic Mustache-based HTML generator"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "0BSD"
+license-files = ["LICENSE"]
+authors = [{ name = "vkorobkov" }]
+classifiers = [
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.6.0",
+    "chevron==0.14.0",
+    "mstache==0.3.0",
+    "pystache==0.6.8",
+    "pytest",
+    "ty"
+]
+
+[tool.uv]
+exclude-newer = "24 hours"
+
+[project.urls]
+Homepage = "https://github.com/servletcloud/fstache"
+Repository = "https://github.com/servletcloud/fstache"
+Issues = "https://github.com/servletcloud/fstache/issues"

fstache-0.1.0/src/fstache/__init__.py

@@ -0,0 +1,86 @@
+"""Public API for compiling and rendering Fstache templates.
+
+The common entry points are :func:`compile`, :func:`render`, and the
+filesystem-backed renderer factories such as :func:`create_renderer`.
+`CompiledTemplate` values are intentionally treated as opaque by the public API:
+loaders, resolvers, and renderers pass them around, but callers should not rely
+on the private node dataclasses unless a future release explicitly promotes
+compiled-template introspection.
+"""
+
+from ._compiler import (
+    DEFAULT_DELIMITERS as DEFAULT_DELIMITERS,
+    EMPTY_TEMPLATE as EMPTY_TEMPLATE,
+    CompiledTemplate as CompiledTemplate,
+    Delimiters as Delimiters,
+    InvalidDelimiterError as InvalidDelimiterError,
+    InvalidNameError as InvalidNameError,
+    SectionSyntaxError as SectionSyntaxError,
+    TemplateSyntaxError as TemplateSyntaxError,
+    UnclosedTagError as UnclosedTagError,
+    UnsupportedTagError as UnsupportedTagError,
+    compile as compile,
+)
+from ._factories import (
+    TemplateRenderer as TemplateRenderer,
+    create_dev_renderer as create_dev_renderer,
+    create_prod_renderer as create_prod_renderer,
+    create_renderer as create_renderer,
+    create_test_renderer as create_test_renderer,
+)
+from ._inliner import inline_partials as inline_partials
+from ._missing import (
+    MissingTemplateError as MissingTemplateError,
+    MissingTemplateResolver as MissingTemplateResolver,
+    MissingVariableError as MissingVariableError,
+    MissingVariableResolver as MissingVariableResolver,
+    resolve_missing_template_as_empty as resolve_missing_template_as_empty,
+    resolve_missing_template_as_error as resolve_missing_template_as_error,
+    resolve_missing_variable_as_error as resolve_missing_variable_as_error,
+    resolve_missing_variable_as_none as resolve_missing_variable_as_none,
+)
+from ._renderer import (
+    EscapeFunction as EscapeFunction,
+    TemplateLoader as TemplateLoader,
+    RenderChunk as RenderChunk,
+    RenderedTemplate as RenderedTemplate,
+    TemplateCompiler as TemplateCompiler,
+    html_escape as html_escape,
+    render as render,
+)
+
+
+__all__ = (
+    "CompiledTemplate",
+    "DEFAULT_DELIMITERS",
+    "EMPTY_TEMPLATE",
+    "Delimiters",
+    "EscapeFunction",
+    "InvalidDelimiterError",
+    "InvalidNameError",
+    "MissingTemplateError",
+    "MissingTemplateResolver",
+    "MissingVariableError",
+    "MissingVariableResolver",
+    "RenderChunk",
+    "RenderedTemplate",
+    "SectionSyntaxError",
+    "TemplateCompiler",
+    "TemplateLoader",
+    "TemplateRenderer",
+    "TemplateSyntaxError",
+    "UnclosedTagError",
+    "UnsupportedTagError",
+    "compile",
+    "create_dev_renderer",
+    "create_prod_renderer",
+    "create_renderer",
+    "create_test_renderer",
+    "html_escape",
+    "inline_partials",
+    "render",
+    "resolve_missing_template_as_empty",
+    "resolve_missing_template_as_error",
+    "resolve_missing_variable_as_error",
+    "resolve_missing_variable_as_none",
+)