python-fragments 0.1__tar.gz

python_fragments-0.1/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: python-fragments
+Version: 0.1
+Summary: HTML template rendering in Python
+Author-email: The Running Algorithm <services@therunningalgorithm.info>
+License: Proprietary
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: lsp
+Requires-Dist: basedpyright>=1.39.0; extra == "lsp"
+Requires-Dist: pygls>=1.3.0; extra == "lsp"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.4.1; extra == "dev"
+
+# Python Fragments
+
+> **This package is in early development and not yet stable. The API may change without notice between releases.**
+
+Production-ready, modern HTML template rendering in Python — no build step, no template files, and native HTML awareness out of the box.
+
+```python
+from fragments import loader  # isort: skip
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from components import Layout, PostCard
+
+app = FastAPI()
+
+POSTS = [...]
+
+@app.get("/", response_class=HTMLResponse)
+async def index() -> str:
+    published = [p for p in POSTS if p.published]
+    return <>
+        <Layout title="My Blog">
+            <h1>Latest Posts</h1>
+            <PostCard for={{ post in published }} post={{ post }} />
+        </Layout>
+    </>
+```
+
+## Installation
+
+```bash
+pip install python-fragments
+```
+
+Register the loader at your application's entry point, before importing any modules that contain fragments:
+
+```python
+from fragments import loader  # isort: skip
+```
+
+Any `.py` file containing `<>` is transpiled automatically. Nothing else to configure.

python_fragments-0.1/README.md

@@ -0,0 +1,41 @@
+# Python Fragments
+
+> **This package is in early development and not yet stable. The API may change without notice between releases.**
+
+Production-ready, modern HTML template rendering in Python — no build step, no template files, and native HTML awareness out of the box.
+
+```python
+from fragments import loader  # isort: skip
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+from components import Layout, PostCard
+
+app = FastAPI()
+
+POSTS = [...]
+
+@app.get("/", response_class=HTMLResponse)
+async def index() -> str:
+    published = [p for p in POSTS if p.published]
+    return <>
+        <Layout title="My Blog">
+            <h1>Latest Posts</h1>
+            <PostCard for={{ post in published }} post={{ post }} />
+        </Layout>
+    </>
+```
+
+## Installation
+
+```bash
+pip install python-fragments
+```
+
+Register the loader at your application's entry point, before importing any modules that contain fragments:
+
+```python
+from fragments import loader  # isort: skip
+```
+
+Any `.py` file containing `<>` is transpiled automatically. Nothing else to configure.

python_fragments-0.1/fragments/ast_nodes.py

@@ -0,0 +1,237 @@
+from dataclasses import dataclass, field
+from typing import Sequence
+
+
+@dataclass(slots=True)
+class ASTModule:
+    source_start: int = field(compare=False)
+    source_end: int = field(compare=False)
+
+    children: list["ASTPython | ASTFragment"]
+
+    transpiled_content: str = field(init=False)
+    transpiled_start: int = field(init=False)
+    transpiled_end: int = field(init=False)
+
+    __template__: str = "from fragments.html.elements import el, sequence, comment\n{}"
+
+    def transpile(self, transpiled_start: int = 0) -> None:
+        self.transpiled_start = transpiled_start
+        transpiled_start += len(self.__template__) - 2
+        for child in self.children:
+            child.transpile(transpiled_start)
+            transpiled_start = child.transpiled_end
+
+        children: str = "".join(child.transpiled_content for child in self.children)
+        self.transpiled_content = self.__template__.format(children)
+        self.transpiled_end = self.transpiled_start + len(self.transpiled_content)
+
+
+@dataclass(slots=True)
+class ASTPython:
+    source_start: int = field(compare=False)
+    source_end: int = field(compare=False)
+    content: str
+
+    transpiled_content: str = field(init=False)
+    transpiled_start: int = field(init=False)
+    transpiled_end: int = field(init=False)
+
+    def transpile(self, transpiled_start: int) -> None:
+        self.transpiled_start = transpiled_start
+        self.transpiled_content = self.content
+        self.transpiled_end = self.transpiled_start + len(self.transpiled_content)
+
+
+@dataclass(slots=True)
+class ASTFragment:
+    source_start: int = field(compare=False)
+    source_end: int = field(compare=False)
+
+    children: list["ASTHTMLElement | ASTHTMLComment | ASTHTMLText | ASTInterpolation"]
+
+    transpiled_content: str = field(init=False)
+    transpiled_start: int = field(init=False)
+    transpiled_end: int = field(init=False)
+
+    __template__: str = """sequence([{}])"""
+
+    def transpile(self, transpiled_start: int) -> None:
+        self.transpiled_start = transpiled_start
+        transpiled_start += 10
+        for child in self.children:
+            child.transpile(transpiled_start)
+            transpiled_start = child.transpiled_end + 1
+        transpiled_start -= 1
+
+        self.transpiled_content = self.__template__.format(",".join(child.transpiled_content for child in self.children))
+        self.transpiled_end = self.transpiled_start + len(self.transpiled_content)
+
+
+@dataclass(slots=True)
+class ASTHTMLElement:
+    source_start: int = field(compare=False)
+    source_end: int = field(compare=False)
+
+    name: str
+    attributes: dict[str, "ASTHTMLAttribute"]
+    if_attribute: "ASTInterpolation | None"
+    for_attribute: "ASTInterpolation | None"
+    children: Sequence["ASTHTMLElement | ASTHTMLText | ASTInterpolation"]
+    one_line: bool
+
+    transpiled_content: str = field(init=False)
+    transpiled_start: int = field(init=False)
+    transpiled_end: int = field(init=False)
+
+    __for_template__: str = """sequence([{} for {}])"""
+    __if_template__: str = """{} if {} else ''"""
+    __element_template__: str = """el("{}",[{}],oneline={},{})"""
+    __component_template__: str = """{}([{}],{})"""
+
+    def transpile(self, transpiled_start: int) -> None:
+        self.transpiled_start = transpiled_start
+
+        if self.for_attribute is not None:
+            transpiled_start += 10
+
+        if self.name[0].capitalize() == self.name[0]:
+            self._transpile_component_call(transpiled_start)
+        else:
+            self._transpile_element_call(transpiled_start)
+
+        if self.if_attribute is not None:
+            self.if_attribute.transpile(self.transpiled_end + 4)
+            self.transpiled_content = self.__if_template__.format(self.transpiled_content, self.if_attribute.transpiled_content)
+            self.transpiled_end = self.if_attribute.transpiled_end + 8
+        elif self.for_attribute is not None:
+            self.for_attribute.transpile(self.transpiled_end + 5)
+            self.transpiled_content = self.__for_template__.format(self.transpiled_content, self.for_attribute.transpiled_content)
+            self.transpiled_end = self.for_attribute.transpiled_end + 2
+
+    def _transpile_element_call(self, start: int) -> None:
+        transpiled_start = start + len(self.name) + 7
+        for child in self.children:
+            child.transpile(transpiled_start)
+            transpiled_start = child.transpiled_end + 1
+        transpiled_start -= 1
+        children = ",".join(child.transpiled_content for child in self.children)
+
+        oneline_offset = len(str(self.one_line))
+
+        transpiled_start += 10 + oneline_offset + 1
+
+        for attribute in self.attributes.values():
+            attribute.transpile(transpiled_start)
+            transpiled_start = attribute.transpiled_end + 1
+        transpiled_start -= 1
+
+        attributes = ",".join(attribute.transpiled_content for attribute in self.attributes.values())
+        self.transpiled_content = self.__element_template__.format(self.name, children, self.one_line, attributes)
+        self.transpiled_end = start + len(self.transpiled_content)
+
+    def _transpile_component_call(self, start: int) -> None:
+        transpiled_start = start + len(self.name) + 2
+        for child in self.children:
+            child.transpile(transpiled_start)
+            transpiled_start = child.transpiled_end + 1
+        transpiled_start -= 1
+        children = ",".join(child.transpiled_content for child in self.children)
+
+        if len(self.attributes) == 0:
+            self.transpiled_content = self.__component_template__.format(self.name, children, "")
+            self.transpiled_end = start + len(self.transpiled_content)
+            return
+
+        transpiled_start += 2
+        for attribute in self.attributes.values():
+            attribute.transpile(transpiled_start)
+            transpiled_start = attribute.transpiled_end + 1
+
+        attributes = ",".join(attribute.transpiled_content for attribute in self.attributes.values())
+        self.transpiled_content = self.__component_template__.format(self.name, children, attributes)
+        self.transpiled_end = start + len(self.transpiled_content)
+
+
+@dataclass(slots=True)
+class ASTHTMLComment:
+    source_start: int = field(compare=False)
+    source_end: int = field(compare=False)
+
+    content: str
+
+    transpiled_content: str = field(init=False)
+    transpiled_start: int = field(init=False)
+    transpiled_end: int = field(init=False)
+
+    __template__: str = """comment("{}")"""
+
+    def transpile(self, transpiled_start: int) -> None:
+        self.transpiled_start = transpiled_start
+        self.transpiled_content = self.__template__.format(self.content)
+        self.transpiled_end = self.transpiled_start + len(self.transpiled_content)
+
+
+@dataclass(slots=True)
+class ASTHTMLAttribute:
+    source_start: int = field(compare=False)
+    source_end: int = field(compare=False)
+
+    name: str
+    value: str | None
+    interpolation: "ASTInterpolation | None"
+
+    transpiled_content: str = field(init=False)
+    transpiled_start: int = field(init=False)
+    transpiled_end: int = field(init=False)
+
+    __value_template__: str = '{}="{}"'
+    __interpolation_template__: str = "{}={}"
+
+    def transpile(self, transpiled_start: int) -> None:
+        self.transpiled_start = transpiled_start
+
+        if self.value is not None:
+            self.transpiled_content = self.__value_template__.format(self.name, self.value)
+            self.transpiled_end = self.transpiled_start + len(self.transpiled_content)
+            return
+
+        assert self.interpolation is not None
+        self.interpolation.transpile(self.transpiled_start + len(self.name) + 1)
+        self.transpiled_content = self.__interpolation_template__.format(self.name, self.interpolation.transpiled_content)
+        self.transpiled_end = self.transpiled_start + len(self.transpiled_content)
+
+
+@dataclass(slots=True)
+class ASTHTMLText:
+    source_start: int = field(compare=False)
+    source_end: int = field(compare=False)
+
+    text: str
+
+    transpiled_content: str = field(init=False)
+    transpiled_start: int = field(init=False)
+    transpiled_end: int = field(init=False)
+
+    __template__: str = '"{}"'
+
+    def transpile(self, transpiled_start: int) -> None:
+        self.transpiled_content = self.__template__.format(self.text)
+        self.transpiled_start = transpiled_start
+        self.transpiled_end = self.transpiled_start + len(self.transpiled_content)
+
+
+@dataclass(slots=True)
+class ASTInterpolation:
+    source_start: int = field(compare=False)
+    source_end: int = field(compare=False)
+    expression: str
+
+    transpiled_content: str = field(init=False)
+    transpiled_start: int = field(init=False)
+    transpiled_end: int = field(init=False)
+
+    def transpile(self, transpiled_start: int) -> None:
+        self.transpiled_content = self.expression
+        self.transpiled_start = transpiled_start
+        self.transpiled_end = self.transpiled_start + len(self.transpiled_content)

python_fragments-0.1/fragments/cli.py

@@ -0,0 +1,20 @@
+import argparse
+
+from fragments import transpiler
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser("fragments", description="Fragments transpilation CLI tool")
+    parser.add_argument("--input", type=str, required=True)
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+    with open(args.input, "r") as f:
+        source = f.read()
+    print(transpiler.transpile(source))
+
+
+if __name__ == "__main__":
+    main()

python_fragments-0.1/fragments/grammar.py

@@ -0,0 +1,206 @@
+from re import Match
+import re
+
+from fragments.ast_nodes import ASTFragment, ASTHTMLAttribute, ASTHTMLComment, ASTHTMLElement, ASTHTMLText, ASTInterpolation, ASTModule, ASTPython
+from fragments.source import Source
+
+PYTHON = r"([\s\S]*?)(?=<>)|[\s\S]*$"
+IDENTIFIER = r"[a-zA-Z_][a-zA-Z0-9_]*"
+STRING_CONTENTS = r"(.*?)(?=\")"
+INTERPOLATION_EXPRESSION = r"(.*?)(?= }})"
+HTML_IDENTIFIER = r"[a-zA-Z][a-zA-Z0-9_-]*"
+HTML_TEXT = r"(.*?)(?=<)"
+
+
+class ParsingError(Exception):
+    def __init__(self, message: str, source_start: int) -> None:
+        super().__init__(message)
+        self.source_start: int = source_start
+
+
+def optional_regex(source: Source, pattern: str) -> tuple[Source, str | None]:
+    """Expect the source to start with the given pattern, return the source after the pattern and the found match (if any)."""
+    result: Match[str] | None = re.match(pattern, source.remaining())
+    if result is None:
+        return source, None
+    return source.eat(result.end()), result.group(0)
+
+
+def expect_regex(source: Source, pattern: str, label: str) -> tuple[Source, str]:
+    """Expect the source to start with the given pattern, return the source after the pattern and the found match."""
+    source, result = optional_regex(source, pattern)
+    if result is None:
+        raise ParsingError(f"Expected {label}", source.offset)
+    return source, result
+
+
+def expect_string(source: Source, string: str) -> Source:
+    """Expect the source to start with the given string, return the source after the string."""
+    if not source.remaining().startswith(string):
+        raise ParsingError(f"Expected {string}", source.offset)
+    return source.eat(len(string))
+
+
+def expect_module(source: Source) -> tuple[Source, ASTModule]:
+    """The top level of the recursive descent grammar."""
+    children: list["ASTPython | ASTFragment"] = []
+    source_start: int = source.offset
+    while not source.at_end():
+        if source.remaining().startswith("<>"):
+            source, fragment = expect_fragment(source)
+            children.append(fragment)
+        else:
+            source, python = expect_python(source)
+            children.append(python)
+    return source, ASTModule(source_start, source.offset, children)
+
+
+def expect_python(source: Source) -> tuple[Source, ASTPython]:
+    """Vanilla Python code."""
+    source_start: int = source.offset
+    source, python = expect_regex(source, PYTHON, "python source")
+    return source, ASTPython(source_start, source.offset, python)
+
+
+def expect_fragment(source: Source) -> tuple[Source, ASTFragment]:
+    """A fragment - the top level of things created by this library."""
+    source_start: int = source.offset
+    source = expect_string(source, "<>")
+
+    children: list[ASTHTMLElement | ASTHTMLComment | ASTHTMLText | ASTInterpolation] = []
+    while not source.remaining().startswith("</>"):
+        source, _ = source.eat_whitespace()
+        if source.remaining().startswith("</>"):
+            break
+        source, child = expect_expression(source)
+        children.append(child)
+
+    source, _ = source.eat_whitespace()
+    source = expect_string(source, "</>")
+    source_end: int = source.offset
+
+    return source, ASTFragment(source_start, source_end, children)
+
+
+def expect_expression(source: Source) -> tuple[Source, ASTHTMLElement | ASTHTMLComment | ASTHTMLText | ASTInterpolation]:
+    """Any HTML / functional block that might appear as part of the fragment."""
+    if source.remaining().startswith("<!--"):
+        source, html_comment = expect_html_comment(source)
+        return source, html_comment
+
+    if source.remaining().startswith("<"):
+        source, html_element = expect_html_element(source)
+        return source, html_element
+
+    if source.remaining().startswith("{{"):
+        source, interpolation = expect_interpolation(source)
+        return source, interpolation
+
+    source, html_text = expect_html_text(source)
+    return source, html_text
+
+
+def expect_html_comment(source: Source) -> tuple[Source, ASTHTMLComment]:
+    source_start = source.offset
+    source = expect_string(source, "<!--")
+    source, content = expect_regex(source, r"[\s\S]*?(?=-->)", "comment content")
+    source = expect_string(source, "-->")
+    return source, ASTHTMLComment(source_start, source.offset, content)
+
+
+def expect_html_element(source: Source) -> tuple[Source, ASTHTMLElement]:
+    """An HTML element that may appear in the fragment tree."""
+    element_source_start = source.offset
+    source = expect_string(source, "<")
+    source, _ = source.eat_whitespace()
+    source, name = expect_regex(source, HTML_IDENTIFIER, "element name")
+    source, _ = source.eat_whitespace()
+
+    attributes: dict[str, ASTHTMLAttribute] = {}
+    while not (source.remaining().startswith(">") or source.remaining().startswith("/>")):
+        attribute_source_start = source.offset
+        source, attribute_name = expect_regex(source, HTML_IDENTIFIER, "attribute name")
+        if not source.remaining().startswith("="):
+            attribute = ASTHTMLAttribute(attribute_source_start, source.offset, attribute_name, None, None)
+            attributes[attribute_name] = attribute
+            continue
+        source = expect_string(source, "=")
+
+        if source.remaining().startswith('"'):
+            source = expect_string(source, '"')
+            source, attribute_value = expect_regex(source, STRING_CONTENTS, "attribute value")
+            source = expect_string(source, '"')
+            attribute = ASTHTMLAttribute(attribute_source_start, source.offset, attribute_name, attribute_value, None)
+            attributes[attribute_name] = attribute
+        elif source.remaining().startswith("{{"):
+            source, interpolation = expect_interpolation(source)
+            attribute = ASTHTMLAttribute(attribute_source_start, source.offset, attribute_name, None, interpolation)
+            attributes[attribute_name] = attribute
+
+        source, _ = source.eat_whitespace()
+
+    if_attribute = attributes.pop("if") if "if" in attributes else None
+    for_attribute = attributes.pop("for") if "for" in attributes else None
+
+    if source.remaining().startswith("/>"):
+        source = expect_string(source, "/>")
+        html_element = ASTHTMLElement(
+            element_source_start,
+            source.offset,
+            name,
+            attributes,
+            if_attribute.interpolation if if_attribute is not None else None,
+            for_attribute.interpolation if for_attribute is not None else None,
+            [],
+            True,
+        )
+        return source, html_element
+
+    source = expect_string(source, ">")
+    source, _ = source.eat_whitespace()
+
+    children: list[ASTHTMLElement | ASTHTMLComment | ASTHTMLText | ASTInterpolation] = []
+    while not source.remaining().startswith("</"):
+        source, child = expect_expression(source)
+        children.append(child)
+        source, _ = source.eat_whitespace()
+
+    source = expect_string(source, "</")
+    source, _ = source.eat_whitespace()
+    source, closing_name = expect_regex(source, IDENTIFIER, "element name")
+
+    if name != closing_name:
+        raise ParsingError(f"Element closed ({closing_name!r}) is not the same as currently opened element ({name!r})", source.offset)
+
+    source, _ = source.eat_whitespace()
+    source = expect_string(source, ">")
+
+    html_element = ASTHTMLElement(
+        element_source_start,
+        source.offset,
+        name,
+        attributes,
+        if_attribute.interpolation if if_attribute is not None else None,
+        for_attribute.interpolation if for_attribute is not None else None,
+        children,
+        False,
+    )
+    return source, html_element
+
+
+def expect_interpolation(source: Source) -> tuple[Source, ASTInterpolation]:
+    """An interpolation block."""
+    source_start = source.offset
+    source = expect_string(source, "{{")
+    source, _ = source.eat_whitespace()
+    source, expression = expect_regex(source, INTERPOLATION_EXPRESSION, "expression")
+    source, _ = source.eat_whitespace()
+    source = expect_string(source, "}}")
+    return source, ASTInterpolation(source_start, source.offset, expression)
+
+
+def expect_html_text(source: Source) -> tuple[Source, ASTHTMLText]:
+    """Text as the child of an HTML expression."""
+    source_start = source.offset
+    source, text = expect_regex(source, HTML_TEXT, "text")
+    return source, ASTHTMLText(source_start, source.offset, text)

python_fragments-0.1/fragments/html/elements.py

@@ -0,0 +1,54 @@
+from typing import Any
+
+
+def sequence(children: list[str]) -> str:
+    return "".join(children)
+
+
+def el(
+    name: str,
+    children: list[str],
+    oneline: bool,
+    **attributes: dict[str, Any],
+) -> str:
+    tag_contents = [
+        name,
+        classes_to_string(attributes.pop("classes")) if "classes" in attributes else None,
+        style_to_string(attributes.pop("style")) if "style" in attributes else None,
+        attributes_to_string(attributes) if attributes is not None else None,
+    ]
+    tag_contents = [item for item in tag_contents if item is not None]
+    tag_contents_string = " ".join(tag_contents)
+
+    if oneline:
+        return f"""<{tag_contents_string} />"""
+
+    children_string = "".join(str(child) for child in children)
+
+    return f"""<{tag_contents_string}>{children_string}</{name}>"""
+
+
+def comment(content: str) -> str:
+    return f"<!-- {content} -->"
+
+
+def attributes_to_string(attributes: dict[str, Any]) -> str:
+    return " ".join("=".join([key, f'"{value}"']) if value is not None else key for key, value in attributes.items())
+
+
+def classes_to_string(classes: list[str] | str) -> str:
+    if isinstance(classes, list):
+        inner = " ".join(classes)
+    else:
+        inner = classes
+
+    return f'class="{inner}"'
+
+
+def style_to_string(style: dict[str, str] | str) -> str:
+    if isinstance(style, dict):
+        inner = ";".join(": ".join(pair) for pair in style.items())
+    else:
+        inner = style
+
+    return f'style="{inner}"'

python_fragments-0.1/fragments/loader.py

@@ -0,0 +1,32 @@
+import importlib.abc
+import importlib.machinery
+import sys
+
+from fragments import transpiler
+
+
+class TranspilingLoader(importlib.machinery.SourceFileLoader):
+    def get_data(self, path: str) -> bytes:
+        if not path.endswith(".py"):
+            return super().get_data(path)
+
+        source = super().get_data(path).decode("utf-8")
+
+        if "<>" not in source:
+            return source.encode("utf-8")
+
+        transpiled = transpiler.transpile(source)
+        return transpiled.encode("utf-8")
+
+
+class TranspilingFinder(importlib.abc.MetaPathFinder):
+    def find_spec(self, fullname: str, path, target=None):
+        spec = importlib.machinery.PathFinder.find_spec(fullname, path)
+        if spec is None or not isinstance(spec.loader, importlib.machinery.SourceFileLoader):
+            return None
+        assert spec.origin is not None
+        spec.loader = TranspilingLoader(fullname, spec.origin)
+        return spec
+
+
+sys.meta_path.insert(0, TranspilingFinder())