django-template-compiler 0.0.1__tar.gz

django_template_compiler-0.0.1/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /home/sam/django-template-compiler show --stat HEAD)",
+      "Bash(python3 -c \"import django; print\\(django.__version__\\)\")"
+    ]
+  }
+}

django_template_compiler-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        django-version: ["4.2", "5.1", "5.2"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          pip install "django~=${{ matrix.django-version }}.0" pytest
+          pip install -e .
+      - name: Test
+        run: pytest -q
+
+  # Compatibility oracle: Django's own template_tests suite, run with dtc's
+  # compiled render path patched in (scripts/run_django_suite.py).
+  django-suite:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        django-version: ["4.2", "5.1", "5.2"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          pip install "django~=${{ matrix.django-version }}.0"
+          pip install -e .
+      - name: Clone Django source at installed version
+        run: |
+          VERSION=$(python -c "import django; print(django.__version__)")
+          git clone --depth 1 --branch "$VERSION" https://github.com/django/django.git /tmp/django-src
+      - name: Run Django template_tests against dtc
+        run: python scripts/run_django_suite.py /tmp/django-src
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build and check distribution
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*

django_template_compiler-0.0.1/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

django_template_compiler-0.0.1/CLAUDE.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project goal
+
+A drop-in replacement for Django's template engine that compiles templates to Python for speed, with **100% compatibility** as a hard requirement — including third-party custom tags and filters. Output must be byte-identical to Django's stock engine in all cases. When compatibility and speed conflict, compatibility wins: anything the compiler can't handle correctly must fall back to Django's interpreted renderer rather than approximate it.
+
+Work proceeded in phases — see `ROADMAP.md` for the full record, including where the design diverged from the plan. All eight phases' engineering is complete (scope locals, context flattening, int fast path, the disk cache, and the literal-include fast path included); what remains before 0.1.0 is release work: a trial against a real application and the PyPI release.
+
+Correctness invariants to preserve when changing the compiler:
+- Oracle suites run **strict** (`DTC_STRICT`): compiler errors fail CI rather than falling back. Keep it that way.
+- Compiled shortcuts must honor a patched `Template._render` (test instrumentation, autopatch, third-party hooks) — see `runtime._render_is_patched`.
+- Templates whose compiled function embeds bridged or identity-keyed-state nodes are non-shareable across parses (`__dtc_shareable__`).
+- `tests/test_fuzz.py` fuzzes with a fresh seed every run; a CI fuzz failure is a real bug — reproduce with the printed `DTC_FUZZ_SEED`.
+
+## Naming
+
+The PyPI distribution name is `django-template-compiler`; the import name is `dtc` (the bare name `dtc` is taken on PyPI). Source lives in `src/dtc/`.
+
+## Commands
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'   # one-time setup
+.venv/bin/pytest                                             # run tests
+.venv/bin/pytest tests/test_backend.py -k differential       # run a subset
+.venv/bin/python -m build && .venv/bin/twine check dist/*    # build + validate dists
+.venv/bin/python benchmarks/bench.py                         # speed vs stock engine + cold-start report
+.venv/bin/python scripts/run_django_suite.py <django-src>    # Django's own template_tests vs dtc (strict)
+DTC_FUZZ_ITERS=10000 .venv/bin/pytest tests/test_fuzz.py     # extended differential fuzzing
+```
+
+For the last command, `<django-src>` is a Django source checkout whose tag matches the installed version (the script verifies): `git clone --depth 1 --branch $(python -c 'import django; print(django.__version__)') https://github.com/django/django.git`. It works by installing `dtc.autopatch`, which patches `Template._render` engine-wide (and `django.test.utils.instrumented_test_render`, preserving the `template_rendered` signal) — that's what routes Django's engine-level test templates through the compiler. It prints compiled/fallback stats at exit; a run where `renders_compiled` is 0 proved nothing.
+
+Version is single-sourced from `__version__` in `src/dtc/__init__.py` (hatchling dynamic version). CI (`.github/workflows/ci.yml`) tests Python 3.10–3.13 × Django 4.2/5.1/5.2 — code must work across that whole matrix.
+
+## Architecture
+
+The design is **hybrid: compile what we can, bridge what we can't.**
+
+- Templates are parsed by Django's own `Lexer`/`Parser` (never reimplement parsing — reusing it is a deliberate compatibility decision). Only the render path is replaced.
+- `src/dtc/backend.py` — `DTCTemplates`, a `BACKENDS` engine that subclasses Django's stock `DjangoTemplates` backend, inheriting all configuration/loader/OPTIONS handling unchanged (the one dtc-specific option, `dtc_disk_cache`, is popped before Django's `Engine` sees it). Its `Template` proxy renders through `runtime.template_render`, which takes the compiled path when available and otherwise Django's own `Template.render`; either way `Template.render`'s observable bookkeeping (`render_context.push_state`, `bind_template` — which runs context processors and exposes `context.template.engine`) is reproduced exactly.
+- `src/dtc/compiler.py` — the compiler. Contract: `compile_template(template) -> callable(Context) -> str | None`, where the callable replaces `Template._render`. `None` now means only "debug engine" (by policy) or "internal compiler error" (fail-open, logged to logger `dtc`, counted in `stats["templates_error"]`; raises instead under `dtc.compiler.STRICT` / `DTC_STRICT=1`). **Every parseable template compiles.** Dedicated codegen covers text, variables (filters call the registered functions directly, with `is_safe`/`needs_autoescape`/`expects_localtime` specialization decided at compile time — custom filters compile natively), `{% if %}`, `{% for %}`, `{% with %}`, `{% autoescape %}`, `{% comment %}`, `{% verbatim %}`, `{% load %}`, inheritance (`{% block %}`/`{% extends %}`/`{% include %}`), `@simple_tag`, `@inclusion_tag`, and the container tags (`{% spaceless %}`, `{% filter %}`, `{% ifchanged %}`, `{% localize %}`, `{% localtime %}`, `{% timezone %}`, `{% language %}` — containers matter because bridging one forces its subtree to render interpreted); any other node bridges as `render_annotated(context)`, exact because compiled code performs *real* `context.push()/pop()/__setitem__` operations. Leaf tags (`url`, `csrf_token`, `static`, ...) stay bridged deliberately: their render is the work itself. Literal `{% include "name" %}` sites get a fast path: `construct_relative_path` folds at compile time, the target and its compiled function resolve once per top-level render (cached on `render_context`, the same lifetime as `IncludeNode.render`'s own per-node cache, so loader reload semantics match stock), and each call reproduces `IncludeNode.render` inline — real `context.push()`/`new()`, inlined `push_state` — before calling the target's compiled function directly; a patched `Template._render` (anything not in `runtime._transparent_renders`) or an uncompiled target falls back to the runtime mirror per call. Speed layers, each gated by the analysis pass: exact-type output fast paths (`str`/`SafeString`/`int`); the `forloop` dict elided when provably unreferenced (bridged nodes, blocks, non-isolated includes, and `takes_context` tags inside a loop disable elision — isolated `{% include ... only %}` renders against `context.new()` and doesn't — unseen content may reference `forloop`, and `IfChangedNode` uses the dict as its state frame); scope locals for loop/`with`-bound names (disabled per scope when its body contains an opaque bridge or a `takes_context` tag call, either of which can rebind names behind the locals); and a flattened read snapshot for names the unit never writes (disabled template-wide by any opaque bridge or `takes_context` tag, threshold-gated by weighted read count; the snapshot excludes the root context layer — `runtime.flatten_tail` — so a `context.dicts[0]` write from any nested template is never served stale: root-resolved reads miss and replay through the live walk). A tag declared context-safe (`dtc_context_safe` attribute / `dtc.declare_safe`) or writes-declared (`dtc_context_writes` naming the instance attributes that hold its written key names / `dtc.declare_writes`; both verified at render time under `DTC_CHECK_DECLARATIONS=1`) waives the write-opacity — it keeps the snapshot (declared writes join the unit's written set), scope locals (a shadowed local resyncs from the live context right after the bridge), and shareability; it still bridges via `render_annotated` and still forces `forloop` in loops (declarations don't enumerate reads); its `child_nodelists` are analyzed normally, so nested writers still gate. Compiled functions embedding bridged or identity-keyed-state nodes are marked non-shareable (`__dtc_shareable__`) — stateful nodes key state by node identity, so per-parse functions must stay per-parse (declared-safe bridges are exempt: the declaration promises no identity-keyed state).
+- `src/dtc/diskcache.py` — opt-in cold-start cache (`OPTIONS["dtc_disk_cache"]` / `DTC_DISK_CACHE`): marshaled code objects keyed by SHA-256 of the generated source (self-validating — codegen still runs per process to rebuild the namespace from live parse objects; only `compile()` is skipped). Fail-open on every read; loaded code is exec'd, so the directory must be trusted.
+- `src/dtc/runtime.py` — render-time support: `compiled_for()` (per-instance + per-(engine, name, source) compile caching — the latter prevents recompiling per render under non-cached loaders; only `__dtc_shareable__` functions enter the source cache), the pristine-`_render` check (`_render_is_patched`) that routes around the compiled path when anything has patched `Template._render` (plus `_transparent_renders`, the list of render functions the literal-include fast path may route around — pristine `_render` and autopatch's stats-only replacement), `resolve_include` (per-render resolution for literal include sites), the `stats` counters, and mirrors of `BlockNode`/`ExtendsNode`/`IncludeNode.render` with the template-render call made compiled-aware. Block bodies compile to standalone functions attached to BlockNodes as `_dtc_body`, linked at render time through Django's own `BlockContext`, so mixed compiled/interpreted inheritance chains work in both directions. The mirrors are verified byte-identical across Django 4.2–5.2; the CI oracle suites police upstream drift.
+- `src/dtc/autopatch.py` — opt-in engine-wide hook (patches `Template._render`); used by the oracle suite runner. The supported integration is the backend.
+
+The central exactness strategy (originally the "context escape hatch" problem, dissolved in phase 3): **the live `Context` is always maintained and always authoritative** — compiled code performs real `push()/pop()/__setitem__` operations, which is what makes bridging arbitrary third-party nodes exact. Scope locals and the flattened snapshot are read-only accelerations layered on top, gated off by analysis wherever an opaque node could write behind them. The gating is per-template, which leaves one documented compatibility boundary (README "Limitation"): a third-party tag that mutates an *intermediate* context layer (`context.dicts[i]` indexing, `Context.set_upward`, deletions, unbalanced push) from inside an included/extended template can stale an enclosing template's snapshot or scope locals — cross-template effects are assumed scope-limited or root-layer (the snapshot excludes `dicts[0]` so root writes stay exact). Same-template use of such tags is exact; `test_known_limitation_intermediate_layer_writes` pins the boundary. The hoisted `_autoescape` local is resynced after every site that hands the live context to foreign code (bridged renders, slow-path node replays, `takes_context` calls, the block/include mirrors) — such code may set `context.autoescape`, which stock rendering reads live. Generated fast paths inline only the provably-identical happy paths of `Variable._resolve_lookup`/`render_value_in_context`/`FilterExpression.resolve`; any deviation (lookup failure, callable, unusual type) replays through the *original node*, so every slow path is Django's own code. Preserve both halves of this when changing codegen.
+
+## Testing policy
+
+Three oracle layers, all in CI:
+
+1. Differential tests: `tests/test_backend.py` and `tests/test_compiler.py` render each case through both dtc and Django's stock backend and assert identical output. Differential tests for compiled features must also assert `template._compiled is not None` — otherwise they silently compare Django with Django (and the test settings must keep `DEBUG=False`, since debug engines never compile). Any new compiler capability needs differential cases covering it, including edge semantics (autoescape/`mark_safe`, silent `VariableDoesNotExist`, context push/pop scoping, `forloop`/`parentloop`, `{{ block.super }}`).
+2. Django's own `template_tests` suite runs against dtc in CI on every supported Django version, in strict mode, via `scripts/run_django_suite.py` — it has caught real bugs every time coverage grew. The stats it prints must show a large `renders_compiled` and `templates_error: 0`.
+3. `tests/test_fuzz.py` — grammar-based differential fuzzer, fresh seed per run (`DTC_FUZZ_SEED=<printed seed>` to reproduce, `DTC_FUZZ_ITERS` to scale up; run ≥10k iterations locally after codegen changes).
+
+`benchmarks/bench.py` measures speedup per scenario plus a cold-start report (parse vs. compile vs. disk-cache-warm); run it when touching codegen — it has caught performance regressions the tests can't (recompile-per-render, fast-path misses).

django_template_compiler-0.0.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Sam Tregar
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

django_template_compiler-0.0.1/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: django-template-compiler
+Version: 0.0.1
+Summary: A drop-in replacement for Django's template engine, 100% compatible including custom tags and filters, but much faster
+Project-URL: Homepage, https://github.com/samtregar/django-template-compiler
+Project-URL: Repository, https://github.com/samtregar/django-template-compiler
+Project-URL: Issues, https://github.com/samtregar/django-template-compiler/issues
+Author-email: Sam Tregar <sam@tregar.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: compiler,django,performance,templates
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: Django
+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 :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# django-template-compiler
+
+A drop-in replacement for Django's template engine, 100% compatible including custom tags and filters, but much faster.
+
+**Status: pre-alpha, but substantially complete.** Every parseable template compiles: dedicated code generation for the core template language (variables, filters, control flow, inheritance, `simple_tag`/`inclusion_tag`, container tags), with anything else — arbitrary third-party tags included — running as-is against the live context. dtc passes Django's own template test suite (Django 4.2–5.2) in CI, plus a differential fuzzer. Typical speedups: 1.6–2.1x on template-bound rendering, with a ~1.0x floor when a template is dominated by bridged tags. Not yet exercised by production traffic — try it and report.
+
+Two behaviors worth knowing:
+
+- **`DEBUG=True` disables compilation** (per engine): Django's debug error page and exception annotation need the interpreted render path. Production configs get the compiled path; development keeps perfect debugging.
+- **Django test instrumentation is honored**: when `setup_test_environment()` (the test runner / `assertTemplateUsed`) patches template rendering, dtc detects the patch and routes through it, so the `template_rendered` signal fires exactly as with stock Django.
+
+## How it works
+
+Templates are parsed with Django's own lexer and parser, then compiled to Python code — a `{% for %}` loop becomes a real Python `for` loop, variable lookups become direct attribute/key access. Anything the compiler can't handle yet (including arbitrary custom tags) falls back to Django's interpreted render path, so output is always exactly what Django would produce.
+
+## Benchmarks
+
+`benchmarks/bench.py`, Python 3.11, Django 5.2 (µs per render; higher speedup is better):
+
+| scenario | django | dtc | speedup |
+|---|---:|---:|---:|
+| 40 plain variables | 52.2 | 28.6 | 1.8x |
+| 100-row loop | 165.7 | 73.2 | 2.3x |
+| 100-row loop with `forloop.counter` | 679.4 | 126.9 | **5.4x** |
+| 50×4 table (nested loop + if) | 516.3 | 271.9 | 1.9x |
+| with/if scopes | 206.8 | 91.2 | 2.3x |
+| spaceless-wrapped table | 248.2 | 114.6 | 2.2x |
+| inheritance + include in loop | 151.4 | 93.5 | 1.6x |
+| bridged unknown tag (worst case) | 26.3 | 21.0 | 1.3x |
+
+For reference, Jinja2 renders the table scenario in ~80µs — dtc closes about half the gap to Jinja2 while producing byte-identical Django output. The remaining distance is the price of Django's semantics themselves (silent variable failures, callable auto-invocation, the context stack), which dtc preserves exactly and Jinja2 deliberately dropped.
+
+## Installation
+
+```bash
+pip install django-template-compiler
+```
+
+The import name is `dtc`.
+
+## Usage
+
+Change one line in your `TEMPLATES` setting:
+
+```python
+TEMPLATES = [
+    {
+        "BACKEND": "dtc.backend.DTCTemplates",  # was django.template.backends.django.DjangoTemplates
+        "DIRS": [BASE_DIR / "templates"],
+        "APP_DIRS": True,
+        "OPTIONS": {
+            # all DjangoTemplates options work unchanged
+            "context_processors": [...],
+        },
+    },
+]
+```
+
+Everything else — template syntax, custom tag libraries, context processors, `{% load %}`, filters — works unchanged.
+
+### Cold starts and the disk cache
+
+Compiling costs roughly 9x Django's parse per template, paid once per process. If your deployment restarts processes often (serverless, aggressive autoscaling), enable the disk cache, which persists compiled code objects across processes and cuts that overhead by ~70%:
+
+```python
+"OPTIONS": {
+    "dtc_disk_cache": True,  # ~/.cache/dtc/..., or pass an explicit path
+},
+```
+
+Cache entries are keyed by a hash of the generated code, so stale entries are impossible by construction; corrupt or version-mismatched entries are silently recompiled. Point it only at a directory you trust — cached code is executed.
+
+### Declaring custom tags context-safe
+
+A custom tag without dedicated codegen renders through its own `render()` against the live context, which is always exact — but because the compiler can't see what that `render()` does, one such tag disables the read optimizations around it: the flattened read snapshot (template-wide), scope locals (in every enclosing `{% for %}`/`{% with %}`), and compiled-function sharing across template instances (which matters without a cached loader). `takes_context` simple/inclusion tags pay the first two as well.
+
+Most tags never write the context. If yours is one of them, declare it:
+
+```python
+class BreadcrumbNode(Node):
+    dtc_context_safe = True   # stock Django ignores this; dtc keeps its
+    ...                       # optimizations around the tag
+
+# takes_context tags declare the *function*:
+@register.simple_tag(takes_context=True)
+def current_section(context):
+    return context.get("section", "home")
+current_section.dtc_context_safe = True
+
+# third-party tags you can't edit, e.g. in settings or AppConfig.ready():
+import dtc
+dtc.declare_safe(SomeThirdPartyNode)
+```
+
+The declaration is a promise about every `render()` call: the context stack and its mappings are left exactly as found (balanced push/pop inside is fine); no state keyed on the node's identity (Django's `CycleNode`/`IfChangedNode` pattern); behavior depends only on the parsed source. *Reading* the context is always fine, as is setting `context.autoescape`. A container tag may render nested writers freely, provided every nodelist it renders is listed in the standard `child_nodelists` attribute — the compiler analyzes those children itself; a rendered-but-unlisted nodelist is the one thing that can silently break output. Subclasses inherit the declaration with the `render()` it describes (`dtc_context_safe = False` opts back out). See `help(dtc.declare_safe)` for the precise contract.
+
+Tags that *do* write the context can declare **what** they write instead, as long as the target names are fixed at parse time — the common capture/setter shape:
+
+```python
+class CaptureNode(Node):
+    # names the instance attributes holding the written context keys
+    dtc_context_writes = ("target",)
+
+    def __init__(self, nodelist, target):
+        self.nodelist = nodelist
+        self.target = target            # {% capture NAME %}...{% endcapture %}
+
+    def render(self, context):
+        context[self.target] = self.nodelist.render(context)
+        return ""
+
+# or for classes you can't edit:
+dtc.declare_writes(SomeVendorSetterNode, "dest")
+```
+
+The compiler routes reads of the declared names through the live context and keeps every optimization on for everything else — including scope locals: if a declared write shadows a `{% for %}`/`{% with %}` name, the generated code re-reads that local right after the tag runs. The rest of the contract matches `dtc_context_safe`; the declared keys may be *set* only (no deletions), and an attribute holding `None` means an optional target unused at that site. See `help(dtc.declare_writes)`.
+
+Declared writes may target the normal top-of-stack (`context[key] = value`) **or** the root layer (`context.dicts[0][key] = value` — the pattern used by tags that persist a value across template boundaries, past every scope pop). Root-written names are never served from the read snapshot (it excludes the root layer by design), so they stay exact across template boundaries, includes, and re-writes.
+
+A wrong declaration produces wrong output silently — so verify it: run your test suite with `DTC_CHECK_DECLARATIONS=1` and dtc checks every declared render, raising `dtc.ContextSafeViolation` on any write outside the declaration. (Containers wrapping legitimate writers are skipped by the checker; the source-determinism clause isn't mechanically checkable.)
+
+Tags that just compute a value from their arguments — a formatter, a calculator, a lookup — are better rewritten as `@register.simple_tag`: those compile natively, declaration-free, with argument resolution inlined.
+
+### Limitation: tags that rewrite enclosing context layers
+
+Within a single template, *any* custom tag is rendered exactly — the compiler disables its read optimizations around every tag it doesn't recognize. Across template boundaries there is one assumption: a tag's context effects that outlive an `{% include %}`/`{% block %}`/`{% extends %}` are either **scope-limited** (ordinary `context[key] = value` writes and balanced push/pop, which die with the layers that the include/block machinery pops) or **root-layer** (`context.dicts[0][key] = value`, which dtc handles as described above). Every Django built-in and every `simple_tag`/`inclusion_tag` satisfies this.
+
+A tag that mutates an *intermediate* layer of the caller's stack — indexing `context.dicts[1]`, calling `Context.set_upward()`, deleting keys from enclosing layers, or leaking an unbalanced `push()` — from inside an included or extended template **can produce output that differs from stock Django**: the enclosing template was compiled without knowledge of that tag, and its read snapshot or scope locals may serve the pre-mutation value. `DTC_CHECK_DECLARATIONS` cannot catch this (the tag carries no declaration, and the effect surfaces in a different template than the tag).
+
+If you have such a tag, the supported paths are: write the root layer instead (`dicts[0]` — fully supported and declarable), write the top of the stack, or confine the mutation to the template that renders the tag. Note that intermediate-layer writes are fragile under stock Django too — what `dicts[1]` *is* depends on the stack depth at the call site.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).