hyperscribe 0.1.0__tar.gz

hyperscribe-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# mypyc generated files
+*.so
+
+# Sphinx
+docs/_build/
+
+# pytest-benchmark
+.benchmarks/

hyperscribe-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: hyperscribe
+Version: 0.1.0
+Summary: A small, dependency-free HTML templating engine that writes markup with context managers.
+Project-URL: Homepage, https://github.com/septatrix/hyperscribe
+Project-URL: Repository, https://github.com/septatrix/hyperscribe
+Project-URL: Issues, https://github.com/septatrix/hyperscribe/issues
+Author-email: Septatrix <24257556+septatrix@users.noreply.github.com>
+Keywords: context-manager,html,markup,template-engine,templating
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# hyperscribe
+
+A small, dependency-free HTML templating engine for Python.
+You write markup as ordinary Python code with context managers,
+and hyperscribe streams escaped, indented HTML to any file-like object.
+
+```python
+from io import StringIO
+
+from hyperscribe import DocWriter
+
+output = StringIO()
+doc = DocWriter(output)
+
+with doc.html(lang="en"):
+    with doc.body.main:
+        doc.h1("Hello & welcome")
+        with doc.ul:
+            for name in ("one", "two"):
+                doc.li(name)
+
+print(output.getvalue())
+```
+
+```html
+<html lang="en">
+  <body>
+    <main>
+      <h1>Hello &amp; welcome</h1>
+      <ul>
+        <li>one</li>
+        <li>two</li>
+      </ul>
+    </main>
+  </body>
+</html>
+```
+
+## Features
+
+- Templates are plain Python: use loops, functions, and `@contextmanager` layouts.
+- Text and attribute values are escaped by default.
+- Output is streamed to anything with a `write(str)` method.
+- No dependencies, fully typed, and supports Python 3.10 and newer.
+
+## Installation
+
+```sh
+pip install hyperscribe
+```
+
+## Documentation
+
+Full documentation is available at
+<https://septatrix.github.io/hyperscribe/>.
+
+## Development
+
+```sh
+make sync     # install dependencies
+make check    # lint, type-check, check formatting, and test
+make format   # format the code with ruff
+make docs     # build the documentation
+```
+
+Run `make help` to list all targets.
+Use `uv run sphinx-autobuild docs docs/_build/html` to preview the docs while editing.
+
+The [benchmarks](benchmarks/README.md) compare hyperscribe with other Python HTML templating libraries
+using pytest-benchmark.
+Their dependencies live in the optional `benchmarks` dependency group
+and need Python 3.14:
+
+```sh
+uv run --group benchmarks pytest benchmarks
+```
+
+## Releasing
+
+The version is derived from git tags by `hatch-vcs`.
+To release, publish a GitHub release whose tag is `v` plus the version, such as `v0.2.0`.
+The `Publish` workflow builds the package
+and uploads it to PyPI through
+[trusted publishing](https://docs.pypi.org/trusted-publishers/).
+Copy the files in `contrib/workflows/` to `.github/workflows/` once,
+using a credential that may edit workflows.
+
+## Status
+
+hyperscribe is in early development
+and its API may change between minor releases.

hyperscribe-0.1.0/README.md

@@ -0,0 +1,91 @@
+# hyperscribe
+
+A small, dependency-free HTML templating engine for Python.
+You write markup as ordinary Python code with context managers,
+and hyperscribe streams escaped, indented HTML to any file-like object.
+
+```python
+from io import StringIO
+
+from hyperscribe import DocWriter
+
+output = StringIO()
+doc = DocWriter(output)
+
+with doc.html(lang="en"):
+    with doc.body.main:
+        doc.h1("Hello & welcome")
+        with doc.ul:
+            for name in ("one", "two"):
+                doc.li(name)
+
+print(output.getvalue())
+```
+
+```html
+<html lang="en">
+  <body>
+    <main>
+      <h1>Hello &amp; welcome</h1>
+      <ul>
+        <li>one</li>
+        <li>two</li>
+      </ul>
+    </main>
+  </body>
+</html>
+```
+
+## Features
+
+- Templates are plain Python: use loops, functions, and `@contextmanager` layouts.
+- Text and attribute values are escaped by default.
+- Output is streamed to anything with a `write(str)` method.
+- No dependencies, fully typed, and supports Python 3.10 and newer.
+
+## Installation
+
+```sh
+pip install hyperscribe
+```
+
+## Documentation
+
+Full documentation is available at
+<https://septatrix.github.io/hyperscribe/>.
+
+## Development
+
+```sh
+make sync     # install dependencies
+make check    # lint, type-check, check formatting, and test
+make format   # format the code with ruff
+make docs     # build the documentation
+```
+
+Run `make help` to list all targets.
+Use `uv run sphinx-autobuild docs docs/_build/html` to preview the docs while editing.
+
+The [benchmarks](benchmarks/README.md) compare hyperscribe with other Python HTML templating libraries
+using pytest-benchmark.
+Their dependencies live in the optional `benchmarks` dependency group
+and need Python 3.14:
+
+```sh
+uv run --group benchmarks pytest benchmarks
+```
+
+## Releasing
+
+The version is derived from git tags by `hatch-vcs`.
+To release, publish a GitHub release whose tag is `v` plus the version, such as `v0.2.0`.
+The `Publish` workflow builds the package
+and uploads it to PyPI through
+[trusted publishing](https://docs.pypi.org/trusted-publishers/).
+Copy the files in `contrib/workflows/` to `.github/workflows/` once,
+using a credential that may edit workflows.
+
+## Status
+
+hyperscribe is in early development
+and its API may change between minor releases.

hyperscribe-0.1.0/benchmarks/README.md

@@ -0,0 +1,80 @@
+# Python HTML templating benchmark
+
+This directory compares rendering the same article list with Jinja, Mako,
+Cheetah3, Airium, Yattag, dominate, Ludic, Hyperscript, Tagflow, Hyperscribe,
+and `xml.etree.ElementTree`. The template includes
+conditional featured badges, optional authors, tag loops, and comment counts.
+It also renders a reusable topic-list component in the page navigation and for
+each article with tags. Jinja defines the component as a macro; each Python
+renderer exposes and calls a matching helper function.
+The default workload contains 500 articles and varies the data to exercise each
+branch. Jinja, Mako, and Cheetah3 each use a base template with overridable
+navigation and content sections. The Jinja template lives in
+`benchmarks/templates/articles.jinja2`; each renderer has its own module under
+`benchmarks/renderers/`. Hyperscribe wraps the shared page container in a
+`@contextmanager` function and uses the standalone package in `src/hyperscribe/`.
+It renders each topic list on a single line with `doc.inline()`,
+which suppresses line breaks and indentation inside its block,
+so its output stays close to Jinja's.
+Tagflow is the unrelated [`tagflow`](https://pypi.org/project/tagflow/) package from PyPI,
+which builds an ElementTree through context managers backed by context variables.
+
+The benchmarks are a [pytest-benchmark](https://pytest-benchmark.readthedocs.io/) suite.
+Their dependencies are in the optional `benchmarks` dependency group
+and require Python 3.14.
+Run everything with:
+
+```sh
+uv run --group benchmarks pytest benchmarks
+```
+
+Select renderers or escaping cases with `-k`,
+and change the workload with `--items`
+(the default is 500 articles):
+
+```sh
+uv run --group benchmarks pytest benchmarks -k "Jinja or Hyperscribe" --items 1000
+```
+
+Use pytest-benchmark's own options to control the measurement
+and to sort, compare, or save results:
+
+```sh
+uv run --group benchmarks pytest benchmarks \
+    --benchmark-sort=mean --benchmark-min-rounds=50 --benchmark-warmup=on \
+    --benchmark-save=baseline
+```
+
+`--benchmark-skip` runs only the output and memory checks
+and `--benchmark-only` runs only the timings.
+
+## Rendering
+
+`test_render.py` renders the same article list with each library.
+`test_output` first checks that every renderer produces the same document:
+it compares tags, attributes, and visible text
+while ignoring indentation-only whitespace,
+because formatters lay out whitespace differently.
+`test_render` then times the render,
+excluding input construction and Jinja template compilation.
+`test_memory` measures the peak traced Python memory of one render
+after a warm-up render
+and, like the output size, prints it in a table after the timing results.
+`tracemalloc` does not include native allocations.
+
+To regenerate Jinja's generated Python source for inspection, run:
+
+```sh
+uv run --group benchmarks python -m benchmarks.compile_jinja
+```
+
+The generated source is saved in `benchmarks/generated_jinja.py`.
+It shows the Python function Jinja compiles for `articles.jinja2`;
+the benchmark still uses Jinja's normal `Template.render()` path.
+
+## Escaping
+
+`test_escape.py` compares text and attribute escaping independently of document rendering.
+It benchmarks `html.escape`, chained `str.replace`,
+and a precomputed `str.maketrans` table with `str.translate`
+on short and long strings, and checks that they agree.

hyperscribe-0.1.0/docs/api.md

@@ -0,0 +1,24 @@
+# API reference
+
+```{eval-rst}
+.. module:: hyperscribe
+
+.. autoclass:: hyperscribe.DocWriter
+   :members: tag, inline, text, write_raw
+   :special-members: __call__, __getattr__
+```
+
+## Tag objects
+
+Accessing an attribute on a {class}`~hyperscribe.DocWriter` returns a tag builder.
+Calling {meth}`~hyperscribe.DocWriter.tag` returns a tag context.
+Both are documented here because they appear in the signatures above,
+but you normally do not create them yourself.
+
+```{eval-rst}
+.. autoclass:: hyperscribe._TagBuilder
+   :members:
+   :special-members: __call__, __getattr__
+
+.. autoclass:: hyperscribe._TagContext
+```

hyperscribe-0.1.0/docs/benchmarks.md

@@ -0,0 +1,23 @@
+# Benchmarks
+
+The repository includes a benchmark comparing hyperscribe with
+Jinja, Mako, Cheetah3, Airium, Yattag, dominate, Ludic, Hyperscript, Tagflow,
+and `xml.etree.ElementTree`.
+Each library renders the same article list
+with conditional badges, optional authors, tag loops and a reusable component.
+
+```sh
+uv sync --group benchmarks
+uv run --group benchmarks pytest benchmarks
+uv run --group benchmarks pytest benchmarks -k "Jinja or Hyperscribe" --items 1000
+```
+
+The benchmarks use [pytest-benchmark](https://pytest-benchmark.readthedocs.io/),
+so its options for sorting, comparing, and saving results all apply.
+The dependencies are in the optional `benchmarks` dependency group
+and require Python 3.14.
+
+Every renderer is first checked to produce the same document.
+The report then shows the timing statistics for each library,
+followed by a table of the peak traced Python memory and output size of one render.
+See `benchmarks/README.md` in the repository for the methodology.

hyperscribe-0.1.0/docs/conf.py

@@ -0,0 +1,35 @@
+"""Sphinx configuration for the hyperscribe documentation."""
+
+from importlib.metadata import version as _version
+
+project = "hyperscribe"
+author = "Septatrix"
+copyright = "Septatrix"
+release = _version("hyperscribe")
+version = release
+
+extensions = [
+    "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+]
+
+myst_enable_extensions = ["colon_fence"]
+myst_heading_anchors = 3
+
+autodoc_member_order = "bysource"
+autodoc_typehints = "signature"
+autodoc_typehints_format = "short"
+python_use_unqualified_type_names = True
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+html_theme = "furo"
+html_title = f"hyperscribe {release}"
+html_theme_options = {
+    "source_repository": "https://github.com/septatrix/hyperscribe/",
+    "source_branch": "main",
+    "source_directory": "docs/",
+}

hyperscribe-0.1.0/docs/guide.md

@@ -0,0 +1,202 @@
+# User guide
+
+## Writing a document
+
+Everything starts with a {class}`~hyperscribe.DocWriter`,
+which wraps any object with a `write(str)` method:
+a {class}`io.StringIO`, an open file, or a socket wrapper.
+
+```python
+from io import StringIO
+
+from hyperscribe import DocWriter
+
+output = StringIO()
+doc = DocWriter(output)
+```
+
+Accessing an attribute on the writer, such as `doc.div`, gives you a tag.
+Tags are used in one of two ways.
+
+### Leaf tags
+
+Calling a tag with a string writes the complete element on one line.
+The content is escaped.
+
+```python
+doc.p("Fish & chips")
+# <p>Fish &amp; chips</p>
+```
+
+### Container tags
+
+Using a tag as a context manager writes the opening tag,
+indents everything inside the block,
+and writes the closing tag when the block ends.
+
+```python
+with doc.ul:
+    doc.li("one")
+    doc.li("two")
+# <ul>
+#   <li>one</li>
+#   <li>two</li>
+# </ul>
+```
+
+Because the closing tag is written by the context manager,
+it is emitted even if you leave the block early with `break` or `return`.
+
+## Attributes
+
+Pass attributes as keyword arguments, both to leaf and to container tags.
+Values must be strings and are escaped for use inside double quotes.
+
+```python
+doc.a("Home", href="/")
+with doc.div(id="main"):
+    ...
+```
+
+Keyword names are written exactly as given.
+For names that are not valid Python identifiers or are reserved words,
+such as `class` or `data-id`, use {meth}`~hyperscribe.DocWriter.tag`
+with dictionary unpacking:
+
+```python
+with doc.tag("div", **{"class": "card", "data-id": "7"}):
+    doc.p("content")
+# <div class="card" data-id="7">
+#   <p>content</p>
+# </div>
+```
+
+## Nested tags
+
+Chaining attributes opens several tags at once,
+which avoids deeply nested `with` statements.
+
+```python
+with doc.body.main:
+    doc.h1("Title")
+# <body>
+#   <main>
+#     <h1>Title</h1>
+#   </main>
+# </body>
+```
+
+Chained tags work for leaves, too.
+`doc.small.span("hi", title="t")` produces `<small><span title="t">hi</span></small>`,
+with the attributes applied to the innermost tag.
+
+## Text
+
+Use {meth}`~hyperscribe.DocWriter.text`, or call the writer directly,
+to write escaped text on its own line.
+
+```python
+with doc.p:
+    doc("Some ")
+    doc.strong("important")
+    doc(" text")
+```
+
+### Inline formatting
+
+By default every tag gets its own line.
+That is what you want for structure, but it inserts whitespace into running text.
+Wrap content in {meth}`~hyperscribe.DocWriter.inline` to keep it on one line:
+
+```python
+with doc.inline(), doc.li:
+    doc("hi, ")
+    doc.b("there")
+# <li>hi, <b>there</b></li>
+```
+
+The block is indented and ends its line like any other tag.
+Inline blocks may be nested;
+normal formatting resumes once the outermost one exits.
+
+### Raw output
+
+{meth}`~hyperscribe.DocWriter.write_raw` writes a string exactly as given,
+without escaping or indentation.
+Use it for a doctype or for markup you have already made safe.
+
+```python
+doc.write_raw("<!DOCTYPE html>\n")
+```
+
+```{warning}
+`write_raw` bypasses escaping.
+Never pass it untrusted input.
+```
+
+## Escaping
+
+Text content escapes `&`, `<` and `>`.
+Attribute values additionally escape quotes.
+Nothing else is escaped,
+so do not use hyperscribe to write into `<script>` or `<style>` elements
+with untrusted data.
+
+## Void elements
+
+hyperscribe does not know which HTML elements are void.
+A tag is only written when it is called with content or used as a context manager,
+so `doc.br` on its own does nothing.
+Write void elements with {meth}`~hyperscribe.DocWriter.write_raw`:
+
+```python
+doc.write_raw("<br>\n")
+```
+
+## Layouts and components
+
+Since templates are Python, components are functions
+and layouts can be generators or `@contextmanager` functions.
+The layout below yields once per replaceable section:
+
+```python
+from collections.abc import Iterator
+from typing import Literal
+
+from hyperscribe import DocWriter
+
+
+def topic_list(doc: DocWriter, topics: list[str]) -> None:
+    with doc.inline(), doc.div:
+        for index, topic in enumerate(topics):
+            if index:
+                doc(", ")
+            doc.span(topic)
+
+
+def page(doc: DocWriter) -> Iterator[Literal["head", "content"]]:
+    with doc.html(lang="en"):
+        with doc.head:
+            yield "head"
+        with doc.body:
+            yield "content"
+
+
+doc.write_raw("<!DOCTYPE html>\n")
+for section in page(doc):
+    match section:
+        case "head":
+            doc.title("Topics")
+        case "content":
+            topic_list(doc, ["python", "html"])
+```
+
+The `benchmarks/renderers/hyperscribe.py` module in the repository
+shows a larger example.
+
+## Streaming
+
+Because output goes straight to the object you provide,
+nothing is buffered by hyperscribe itself.
+Pass a file or a socket wrapper to send the document as it is generated,
+or a `StringIO` to get the result as a string.

hyperscribe-0.1.0/docs/index.md

@@ -0,0 +1,41 @@
+# hyperscribe
+
+hyperscribe is a small, dependency-free HTML templating engine for Python.
+Instead of a separate template language,
+you write markup as Python code with context managers
+and hyperscribe streams escaped, indented HTML to any file-like object.
+
+```python
+from io import StringIO
+
+from hyperscribe import DocWriter
+
+output = StringIO()
+doc = DocWriter(output)
+
+with doc.html(lang="en"):
+    with doc.body.main:
+        doc.h1("Hello & welcome")
+
+print(output.getvalue())
+```
+
+```html
+<html lang="en">
+  <body>
+    <main>
+      <h1>Hello &amp; welcome</h1>
+    </main>
+  </body>
+</html>
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: Contents
+
+installation
+guide
+api
+benchmarks
+```

hyperscribe-0.1.0/docs/installation.md

@@ -0,0 +1,27 @@
+# Installation
+
+hyperscribe requires Python 3.10 or newer and has no dependencies.
+
+```sh
+pip install hyperscribe
+```
+
+or, with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv add hyperscribe
+```
+
+## Development setup
+
+```sh
+git clone https://github.com/septatrix/hyperscribe
+cd hyperscribe
+make sync     # install dependencies
+make check    # lint, type-check, check formatting, and test
+make format   # format the code with ruff
+make docs     # build the documentation
+```
+
+Run `make help` to list all targets.
+Use `uv run sphinx-autobuild docs docs/_build/html` to preview the docs while editing.

hyperscribe-0.1.0/pyproject.toml

@@ -0,0 +1,104 @@
+[project]
+name = "hyperscribe"
+dynamic = ["version"]
+description = "A small, dependency-free HTML templating engine that writes markup with context managers."
+readme = "README.md"
+authors = [
+    { name = "Septatrix", email = "24257556+septatrix@users.noreply.github.com" }
+]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["html", "templating", "template-engine", "markup", "context-manager"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Markup :: HTML",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/septatrix/hyperscribe"
+Repository = "https://github.com/septatrix/hyperscribe"
+Issues = "https://github.com/septatrix/hyperscribe/issues"
+
+[build-system]
+requires = ["hatchling>=1.27", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options = { tag_regex = "^v(?P<version>.+)$", git_describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "v*"] }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hyperscribe"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/hyperscribe", "tests", "README.md", "docs"]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.13",
+    "pytest>=8",
+    "ruff>=0.8",
+]
+docs = [
+    "furo>=2024.8.6",
+    "myst-parser>=4",
+    "sphinx>=8",
+    "sphinx-autobuild>=2024.10.3",
+    "sphinx-copybutton>=0.5.2",
+]
+benchmarks = [
+    "airium>=0.2.6; python_version >= '3.14'",
+    "ct3>=3.4.0.post5; python_version >= '3.14'",
+    "dominate>=2.9.1; python_version >= '3.14'",
+    "pytest-benchmark>=5; python_version >= '3.14'",
+    "hyperscript>=0.3.0; python_version >= '3.14'",
+    "jinja2>=3.1.6; python_version >= '3.14'",
+    "legacy-cgi>=2.6.4; python_version >= '3.14'",
+    "ludic>=1.0.0; python_version >= '3.14'",
+    "mako>=1.4.3; python_version >= '3.14'",
+    "setuptools>=84.0.0; python_version >= '3.14'",
+    "tagflow>=0.12.0; python_version >= '3.14'",
+    "yattag>=1.16.1; python_version >= '3.14'",
+]
+
+[tool.uv]
+default-groups = ["dev", "docs"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+src = ["src", "."]
+extend-exclude = ["benchmarks/generated_jinja.py"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src", "tests", "benchmarks"]
+exclude = ["benchmarks/generated_jinja\\.py"]
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = ["benchmarks.*"]
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+disallow_untyped_calls = false
+warn_return_any = false
+
+[[tool.mypy.overrides]]
+module = ["Cheetah.*", "dominate.*", "hyperscript.*", "mako.*"]
+ignore_missing_imports = true

hyperscribe-0.1.0/src/hyperscribe/__init__.py

@@ -0,0 +1,224 @@
+"""A minimal tag/text writer with Airium-style dynamic tag access."""
+
+from __future__ import annotations
+
+import html
+from contextlib import AbstractContextManager
+from dataclasses import dataclass, field
+from types import TracebackType
+from typing import TextIO, overload
+
+
+def _escape_text(value: str) -> str:
+    """Skip the replacement work for the common case with no HTML metacharacters."""
+    if "&" not in value and "<" not in value and ">" not in value:
+        return value
+    return html.escape(value, quote=False)
+
+
+@dataclass(slots=True)
+class _TagContext:
+    """Write a tag while the document tracks its nesting for indentation."""
+
+    doc: DocWriter
+    openings: tuple[str, ...]
+    closings: tuple[str, ...]
+
+    def __enter__(self) -> None:
+        for opening in self.openings:
+            self.doc._open_tag(opening)
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        for closing in reversed(self.closings):
+            self.doc._close_tag(closing)
+
+
+@dataclass(slots=True)
+class _InlineContext:
+    """Write everything in the block on one line, indented once and ended once."""
+
+    doc: DocWriter
+    previous_prefixes: list[str] = field(init=False)
+    previous_end: str = field(init=False)
+
+    def __enter__(self) -> None:
+        doc = self.doc
+        doc._write(doc._prefix(doc._depth))
+        self.previous_prefixes = doc._prefixes
+        self.previous_end = doc._end
+        doc._prefixes = doc._inline_prefixes
+        doc._end = ""
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        doc = self.doc
+        doc._prefixes = self.previous_prefixes
+        doc._end = self.previous_end
+        doc._write(doc._end)
+
+
+@dataclass(slots=True)
+class _TagBuilder:
+    """Represent a tag, usable directly or with attributes supplied by a call."""
+
+    _doc: DocWriter
+    _path: tuple[str, ...]
+    _context: _TagContext = field(init=False)
+
+    def __post_init__(self) -> None:
+        self._context = self._doc._context_for(self._path)
+
+    def __getattr__(self, name: str) -> _TagBuilder:
+        """Return a builder for a nested tag, such as ``body`` in ``doc.body.main``."""
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return _TagBuilder(self._doc, (*self._path, name))
+
+    @overload
+    def __call__(self, /, **attrs: str) -> AbstractContextManager[None]: ...
+
+    @overload
+    def __call__(self, content: str, /, **attrs: str) -> None: ...
+
+    def __call__(
+        self, content: str | None = None, /, **attrs: str
+    ) -> AbstractContextManager[None] | None:
+        """Write a leaf element when given content, else return a context manager."""
+        if content is not None:
+            context = (
+                self._doc._context_for(self._path, **attrs) if attrs else self._context
+            )
+            self._doc._render_leaf(context, content)
+            return None
+        return self._doc._context_for(self._path, **attrs)
+
+    def __enter__(self) -> None:
+        return self._context.__enter__()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self._context.__exit__(exc_type, exc_value, traceback)
+
+
+class DocWriter:
+    """Write escaped HTML fragments to any object with a ``write(str)`` method."""
+
+    def __init__(self, writer: TextIO) -> None:
+        self._write = writer.write
+        self._tags: dict[str, _TagContext] = {}
+        self._tag_builders: dict[str, _TagBuilder] = {}
+        self._indentation = "  "
+        self._depth: int = 0
+        # Indentation by depth and the line ending written after each tag, like
+        # print(); inline blocks swap in empty strings for both.
+        self._end = "\n"
+        self._line_prefixes: list[str] = []
+        self._inline_prefixes: list[str] = []
+        self._prefixes = self._line_prefixes
+
+    def __getattr__(self, name: str) -> _TagBuilder:
+        """Return a cached tag object usable directly or with attributes."""
+        if name.startswith("_"):
+            raise AttributeError(name)
+
+        tag_builders = self._tag_builders
+        if name not in tag_builders:
+            tag_builders[name] = _TagBuilder(self, (name,))
+        return tag_builders[name]
+
+    def __call__(self, value: str) -> None:
+        """Write escaped text to the document."""
+        self.text(value)
+
+    def inline(self) -> AbstractContextManager[None]:
+        """Suppress line breaks and indentation for the markup written in the block.
+
+        The block is indented and ends its line like any other tag,
+        so ``with doc.inline(), doc.div:`` renders the whole ``div`` on one line.
+        Blocks may be nested; formatting resumes once the outermost one exits.
+        """
+        return _InlineContext(self)
+
+    def tag(self, name: str, **attrs: str) -> _TagContext:
+        """Return a context manager for a tag with any name and attributes.
+
+        Use it for names or attributes that are not valid Python identifiers,
+        such as ``doc.tag("div", **{"class": "card"})``.
+        """
+        if attrs:
+            attributes = "".join(
+                f' {key}="{html.escape(value, quote=True)}"'
+                for key, value in attrs.items()
+            )
+            return _TagContext(self, (f"<{name}{attributes}>",), (f"</{name}>",))
+
+        if context := self._tags.get(name):
+            return context
+
+        context = _TagContext(self, (f"<{name}>",), (f"</{name}>",))
+        self._tags[name] = context
+        return context
+
+    def _context_for(self, path: tuple[str, ...], **attrs: str) -> _TagContext:
+        """Make a context manager for a tag chain, adding attributes to its leaf."""
+        if len(path) == 1:
+            return self.tag(path[0], **attrs)
+
+        contexts = [self.tag(name) for name in path[:-1]]
+        contexts.append(self.tag(path[-1], **attrs))
+        return _TagContext(
+            self,
+            tuple(context.openings[0] for context in contexts),
+            tuple(context.closings[0] for context in contexts),
+        )
+
+    def _generate_prefix(self, depth: int) -> str:
+        """Return the prefix for a depth, extending the per-depth caches as needed."""
+        for missing in range(len(self._line_prefixes), depth + 1):
+            self._line_prefixes.append(self._indentation * missing)
+            self._inline_prefixes.append("")
+        return self._line_prefixes[depth]
+
+    def _prefix(self, depth: int) -> str:
+        """Return what to write before a tag at this depth, honoring inline blocks."""
+        try:
+            return self._prefixes[depth]
+        except IndexError:
+            self._generate_prefix(depth)
+            return self._prefixes[depth]
+
+    def _render_leaf(self, context: _TagContext, text: str) -> None:
+        """Write shorthand leaf markup inline, without context manager allocation."""
+        prefix = self._prefix(self._depth)
+        openings = "".join(context.openings)
+        closings = "".join(reversed(context.closings))
+        self._write(f"{prefix}{openings}{_escape_text(text)}{closings}{self._end}")
+
+    def _open_tag(self, opening: str) -> None:
+        self._write(f"{self._prefix(self._depth)}{opening}{self._end}")
+        self._depth += 1
+
+    def _close_tag(self, closing: str) -> None:
+        self._depth -= 1
+        self._write(f"{self._prefix(self._depth)}{closing}{self._end}")
+
+    def write_raw(self, value: str) -> None:
+        """Write unescaped text to the document, bypassing the escaping logic."""
+        self._write(value)
+
+    def text(self, value: str) -> None:
+        """Write escaped text to the document on its own line."""
+        self._write(f"{self._prefix(self._depth)}{_escape_text(value)}{self._end}")

hyperscribe-0.1.0/tests/test_docwriter.py

@@ -0,0 +1,96 @@
+from collections.abc import Callable
+from io import StringIO
+
+from hyperscribe import DocWriter
+
+
+def render(build: Callable[[DocWriter], object]) -> str:
+    output = StringIO()
+    build(DocWriter(output))
+    return output.getvalue()
+
+
+def test_leaf_tag_is_written_on_one_line() -> None:
+    assert render(lambda doc: doc.p("hello")) == "<p>hello</p>\n"
+
+
+def test_text_is_escaped() -> None:
+    assert render(lambda doc: doc.p("a & <b>")) == "<p>a &amp; &lt;b&gt;</p>\n"
+
+
+def test_attributes_are_escaped() -> None:
+    result = render(lambda doc: doc.a("x", href='a"b&c'))
+    assert result == '<a href="a&quot;b&amp;c">x</a>\n'
+
+
+def test_nested_tags_are_indented() -> None:
+    def build(doc: DocWriter) -> None:
+        with doc.ul:
+            doc.li("one")
+
+    assert render(build) == "<ul>\n  <li>one</li>\n</ul>\n"
+
+
+def test_chained_tags_open_together() -> None:
+    def build(doc: DocWriter) -> None:
+        with doc.body.main:
+            doc.p("x")
+
+    assert render(build) == "<body>\n  <main>\n    <p>x</p>\n  </main>\n</body>\n"
+
+
+def test_chained_leaf_with_attributes() -> None:
+    result = render(lambda doc: doc.small.span("hi", title="t"))
+    assert result == '<small><span title="t">hi</span></small>\n'
+
+
+def test_tag_method_supports_arbitrary_names() -> None:
+    def build(doc: DocWriter) -> None:
+        with doc.tag("my-element", id="1"):
+            doc.text("t")
+
+    assert render(build) == '<my-element id="1">\n  t\n</my-element>\n'
+
+
+def test_call_writes_escaped_text() -> None:
+    assert render(lambda doc: doc("1 < 2")) == "1 &lt; 2\n"
+
+
+def test_write_raw_is_not_escaped_or_indented() -> None:
+    def build(doc: DocWriter) -> None:
+        with doc.div:
+            doc.write_raw("<hr>\n")
+
+    assert render(build) == "<div>\n<hr>\n</div>\n"
+
+
+def test_inline_suppresses_whitespace() -> None:
+    def build(doc: DocWriter) -> None:
+        with doc.ul:
+            with doc.inline(), doc.li:
+                doc("hi, ")
+                doc.b("there")
+
+    assert render(build) == "<ul>\n  <li>hi, <b>there</b></li>\n</ul>\n"
+
+
+def test_nested_inline_resumes_formatting_after_outermost_exit() -> None:
+    def build(doc: DocWriter) -> None:
+        with doc.inline():
+            with doc.inline(), doc.span:
+                doc("a")
+        doc.p("b")
+
+    assert render(build) == "<span>a</span>\n<p>b</p>\n"
+
+
+def test_writes_to_any_object_with_write() -> None:
+    chunks: list[str] = []
+
+    class Sink:
+        def write(self, value: str) -> int:
+            chunks.append(value)
+            return len(value)
+
+    DocWriter(Sink()).p("x")  # type: ignore[arg-type]
+    assert "".join(chunks) == "<p>x</p>\n"