pygments-citry 0.1.0__tar.gz

pygments_citry-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 citry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

pygments_citry-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: pygments-citry
+Version: 0.1.0
+Summary: Pygments lexer for Citry components: highlights the HTML, JS, and CSS embedded in a component's template/js/css strings
+Author-email: Juro Oravec <juraj.oravec.josefson@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://citry.dev
+Project-URL: Repository, https://github.com/citry-dev/citry
+Project-URL: Changelog, https://github.com/citry-dev/citry/blob/main/packages/py/pygments_citry/CHANGELOG.md
+Project-URL: Issues, https://github.com/citry-dev/citry/issues
+Keywords: citry,pygments,lexer,syntax highlighting,components,html
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygments>=2.15
+Dynamic: license-file
+
+# pygments-citry
+
+A [Pygments](https://pygments.org/) lexer for [Citry](https://citry.dev)
+components. It highlights a component the way an editor would: the Python class,
+plus the HTML, JavaScript, and CSS embedded in its `template`, `js`, and `css`
+string attributes, each in its own language.
+
+Without it, a Citry component in a ` ```python ` block renders the template,
+JS script, and CSS stylesheet as flat string literals. With it, a ` ```citry `
+block colours the `<c-*>` tags, the `{{ ... }}` interpolation, the embedded
+stylesheet, and the embedded script.
+
+## Install
+
+```bash
+pip install pygments-citry
+```
+
+The package registers a `citry` lexer as a Pygments plugin, so any tool that
+resolves lexers by name picks it up once it is installed.
+
+## Use it
+
+On the command line:
+
+```bash
+pygmentize -l citry my_component.py
+```
+
+In Python:
+
+```python
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import get_lexer_by_name
+
+lexer = get_lexer_by_name("citry")
+html = highlight(source, lexer, HtmlFormatter())
+```
+
+In a Markdown site (mkdocs with `pymdownx.highlight` / `pymdownx.superfences`,
+or any python-markdown setup that resolves Pygments lexers by name), tag the
+fence with `citry`:
+
+````markdown
+```citry
+from citry import Component
+
+class Welcome(Component):
+    template = """
+      <div class="card">
+        <h1>{{ title }}</h1>
+        <p c-if="count">You have {{ count }} new messages.</p>
+      </div>
+    """
+```
+````
+
+No superfences `custom_fences` entry is needed: once the package is installed,
+`citry` resolves like any other Pygments lexer.
+
+## What it highlights
+
+A `citry` block is highlighted as Python, and the following Citry constructs
+inside the `template` / `js` / `css` attributes are highlighted in their own
+language:
+
+- The HTML in `template`, including the `<c-*>` component and control-flow tags
+  (the built-ins `c-if`, `c-for`, `c-slot`, `<c-raw>`, and so on) and `c-*`
+  dynamic attributes.
+- `{{ ... }}` interpolation, whose body is a Python expression.
+- `{# ... #}` template comments.
+- The JavaScript in `js` and the CSS in `css`.
+
+The `<c-raw>...</c-raw>` element is treated as verbatim text, matching the
+engine: `{{ }}` and tags inside it are not interpreted.
+
+## Template-only blocks: `citry-html`
+
+For a fenced block that shows only a template, with no surrounding Python (just
+`<c-*>` tags, `{{ ... }}`, and `{# ... #}`), tag it `citry-html`:
+
+````markdown
+```citry-html
+<c-for each="item in items">
+  <li c-if="item.visible">{{ item.label }}</li>
+</c-for>
+```
+````
+
+`citry` expects full component code (Python with embedded strings), so a bare
+template belongs in a `citry-html` block instead.
+
+## License
+
+MIT. Part of the [Citry](https://github.com/citry-dev/citry) project.

pygments_citry-0.1.0/README.md

@@ -0,0 +1,96 @@
+# pygments-citry
+
+A [Pygments](https://pygments.org/) lexer for [Citry](https://citry.dev)
+components. It highlights a component the way an editor would: the Python class,
+plus the HTML, JavaScript, and CSS embedded in its `template`, `js`, and `css`
+string attributes, each in its own language.
+
+Without it, a Citry component in a ` ```python ` block renders the template,
+JS script, and CSS stylesheet as flat string literals. With it, a ` ```citry `
+block colours the `<c-*>` tags, the `{{ ... }}` interpolation, the embedded
+stylesheet, and the embedded script.
+
+## Install
+
+```bash
+pip install pygments-citry
+```
+
+The package registers a `citry` lexer as a Pygments plugin, so any tool that
+resolves lexers by name picks it up once it is installed.
+
+## Use it
+
+On the command line:
+
+```bash
+pygmentize -l citry my_component.py
+```
+
+In Python:
+
+```python
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import get_lexer_by_name
+
+lexer = get_lexer_by_name("citry")
+html = highlight(source, lexer, HtmlFormatter())
+```
+
+In a Markdown site (mkdocs with `pymdownx.highlight` / `pymdownx.superfences`,
+or any python-markdown setup that resolves Pygments lexers by name), tag the
+fence with `citry`:
+
+````markdown
+```citry
+from citry import Component
+
+class Welcome(Component):
+    template = """
+      <div class="card">
+        <h1>{{ title }}</h1>
+        <p c-if="count">You have {{ count }} new messages.</p>
+      </div>
+    """
+```
+````
+
+No superfences `custom_fences` entry is needed: once the package is installed,
+`citry` resolves like any other Pygments lexer.
+
+## What it highlights
+
+A `citry` block is highlighted as Python, and the following Citry constructs
+inside the `template` / `js` / `css` attributes are highlighted in their own
+language:
+
+- The HTML in `template`, including the `<c-*>` component and control-flow tags
+  (the built-ins `c-if`, `c-for`, `c-slot`, `<c-raw>`, and so on) and `c-*`
+  dynamic attributes.
+- `{{ ... }}` interpolation, whose body is a Python expression.
+- `{# ... #}` template comments.
+- The JavaScript in `js` and the CSS in `css`.
+
+The `<c-raw>...</c-raw>` element is treated as verbatim text, matching the
+engine: `{{ }}` and tags inside it are not interpreted.
+
+## Template-only blocks: `citry-html`
+
+For a fenced block that shows only a template, with no surrounding Python (just
+`<c-*>` tags, `{{ ... }}`, and `{# ... #}`), tag it `citry-html`:
+
+````markdown
+```citry-html
+<c-for each="item in items">
+  <li c-if="item.visible">{{ item.label }}</li>
+</c-for>
+```
+````
+
+`citry` expects full component code (Python with embedded strings), so a bare
+template belongs in a `citry-html` block instead.
+
+## License
+
+MIT. Part of the [Citry](https://github.com/citry-dev/citry) project.

pygments_citry-0.1.0/pygments_citry/__init__.py

@@ -0,0 +1,42 @@
+"""
+pygments-citry: a Pygments lexer for Citry components.
+
+Importing this package registers the ``citry`` lexer with Pygments, so
+``get_lexer_by_name("citry")`` resolves even in an environment where the plugin
+entry point was not picked up (for example an editable checkout whose plugin
+metadata is not written). For an installed package, the ``pygments.lexers``
+entry point in ``pyproject.toml`` is the primary registration and needs no
+import.
+"""
+
+from __future__ import annotations
+
+from pygments.lexers import LEXERS
+
+from pygments_citry.citry_html import CitryHtmlLexer
+from pygments_citry.lexers import CitryPythonLexer
+
+__all__ = ["CitryHtmlLexer", "CitryPythonLexer"]
+
+# Register in Pygments' builtin lexer table. get_lexer_by_name scans this table
+# before the entry-point plugins, so an explicit `import pygments_citry` becomes
+# a deterministic loader. Each tuple is (module, name, aliases, filenames,
+# mimetypes); _load_lexers imports the module and finds the class via __all__.
+#
+# `citry` is the full component lexer (Python + embedded template/js/css);
+# `citry-html` is the template lexer alone, for a fence that shows only a
+# template (`<c-*>` tags, `{{ }}`, `{# #}`) with no surrounding Python.
+LEXERS["CitryPythonLexer"] = (
+    "pygments_citry",
+    "Citry Python",
+    ("citry",),
+    (),
+    (),
+)
+LEXERS["CitryHtmlLexer"] = (
+    "pygments_citry",
+    "Citry HTML",
+    ("citry-html",),
+    (),
+    (),
+)

pygments_citry-0.1.0/pygments_citry/citry_html.py

@@ -0,0 +1,195 @@
+"""
+The lexer for the HTML that lives inside a Citry component's ``template``.
+
+Citry templates are HTML with a few additions: ``<c-*>`` component and
+control-flow tags, ``c-*`` dynamic attributes whose values are Python
+expressions, ``{{ python }}`` interpolation, ``{# comment #}``, and a verbatim
+``<c-raw>`` element. This lexer extends Pygments' plain ``HtmlLexer`` with those,
+so a Citry template highlights as HTML with the Citry bits called out, and the
+Python inside ``{{ }}`` and ``c-*`` values is handed to the Python lexer.
+
+It is registered as ``citry-html``, both on its own (for a fenced block that
+shows only a template) and embedded by ``CitryPythonLexer`` to highlight the
+``template`` string of a component.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+from pygments.lexer import ExtendedRegexLexer, bygroups, using
+from pygments.lexers.html import HtmlLexer
+from pygments.lexers.javascript import JavascriptLexer
+from pygments.lexers.python import PythonLexer
+from pygments.token import Comment, Name, Operator, Punctuation, Text
+
+if TYPE_CHECKING:
+    import re
+    from collections.abc import Iterator
+
+# An exact Citry tag name ends where the template grammar's tag name ends. The
+# explicit lookahead stops a built-in prefix such as ``c-slot`` from stealing
+# the start of a user component name such as ``c-slot-panel``.
+_TAG_END = r"(?=\s|/?>|\{#)"
+
+# One Python lexer, reused for the bodies of {{ ... }} interpolations.
+_PYTHON = PythonLexer()
+
+
+def _interpolation(_lexer: Any, match: re.Match[str], ctx: Any) -> Iterator[tuple[int, Any, str]]:
+    """
+    Tokenise a ``{{ ... }}`` interpolation, handing the expression to Python.
+
+    The closing ``}}`` is found by scanning for one at brace depth zero and
+    skipping Python string literals along the way, so a ``}}`` inside a string
+    (``{{ "}}" }}``) or a nested dict literal (``{{ {"a": {1: 2}} }}``) does not
+    end the block early. This mirrors how the engine's grammar finds the
+    boundary; a plain regex cannot, because it cannot count nesting.
+
+    Surrounding whitespace stays plain text and only the expression in the
+    middle is highlighted, matching how the rest of the lexer treats a value.
+    """
+    text = match.string
+    yield match.start(), Punctuation, "{{"
+    start = match.end()
+    length = len(text)
+    i = start
+    depth = 0
+    close = None
+    while i < length:
+        char = text[i]
+        if char in "\"'":  # skip a Python string literal, honouring backslash escapes
+            quote = char
+            i += 1
+            while i < length:
+                if text[i] == "\\":
+                    i += 2
+                    continue
+                if text[i] == quote:
+                    i += 1
+                    break
+                i += 1
+            continue
+        if char == "{":
+            depth += 1
+        elif char == "}":
+            if depth:
+                depth -= 1
+            elif i + 1 < length and text[i + 1] == "}":
+                close = i
+                break
+        i += 1
+
+    body = text[start : close if close is not None else length]
+    lead = body[: len(body) - len(body.lstrip())]
+    expr = body.strip()
+    if lead:
+        yield start, Text, lead
+    for offset, token, value in _PYTHON.get_tokens_unprocessed(expr):
+        yield start + len(lead) + offset, token, value
+    trail = body[len(lead) + len(expr) :]
+    if trail:
+        yield start + len(lead) + len(expr), Text, trail
+
+    if close is not None:
+        yield close, Punctuation, "}}"
+        ctx.pos = close + 2
+    else:
+        ctx.pos = length
+
+
+# The value of a c-* (or built-in) attribute is a Python expression, quoted or bare.
+_PY_ATTR_STATE = "python-attr"
+_JS_ATTR_STATE = "javascript-attr"
+# Attribute rules shared by ordinary and built-in tags: framework passthrough
+# names plain HtmlLexer cannot tokenise (@click, [style], (click)), ordinary
+# attributes (covers :class and v-model, which HtmlLexer handles), and the close.
+_COMMON_ATTR_RULES = [
+    (r"([@\[(][\w:@.()\[\]-]*)(\s*)(=)(\s*)", bygroups(Name.Attribute, Text, Operator, Text), "attr"),
+    (r"[@\[(][\w:@.()\[\]-]*", Name.Attribute),
+    (r"([\w:-]+)(\s*)(=)(\s*)", bygroups(Name.Attribute, Text, Operator, Text), "attr"),
+    (r"[\w:-]+", Name.Attribute),
+    (r"(/?)(\s*)(>)", bygroups(Punctuation, Text, Punctuation), "#pop"),
+]
+_WS_RULE = (r"\s+", Text)
+# `$c-props` is evaluated by the client runtime, so its value is JavaScript.
+_CLIENT_PROPS_ATTR_RULE = (
+    r"(\$c-props)(\s*)(=)(\s*)",
+    bygroups(Name.Attribute, Text, Operator, Text),
+    _JS_ATTR_STATE,
+)
+# A c-* dynamic attribute: the value is a Python expression.
+_C_ATTR_RULE = (r"(c-[\w$:@.-]*)(\s*)(=)(\s*)", bygroups(Name.Attribute, Text, Operator, Text), _PY_ATTR_STATE)
+# Structural control-flow tags carry Python-valued attributes that are not
+# c-*-prefixed. These rules live in tag-specific states because the same names
+# on other elements are ordinary static HTML attributes.
+_COND_ATTR_RULE = (r"(cond)(\s*)(=)(\s*)", bygroups(Name.Attribute, Text, Operator, Text), _PY_ATTR_STATE)
+_EACH_ATTR_RULE = (r"(each)(\s*)(=)(\s*)", bygroups(Name.Attribute, Text, Operator, Text), _PY_ATTR_STATE)
+
+
+class CitryHtmlLexer(ExtendedRegexLexer, HtmlLexer):
+    """Highlights the HTML (plus Citry tags and interpolation) of a Citry template."""
+
+    name = "Citry HTML"
+    aliases: ClassVar[list[str]] = ["citry-html"]
+
+    tokens: ClassVar[dict[str, Any]] = {
+        **HtmlLexer.tokens,
+        "root": [
+            # {# template comment #}
+            (r"\{#.*?#\}", Comment),
+            # {{ python-expression }}: a callback scans to the balanced }}
+            (r"\{\{", _interpolation),
+            # a lone { that is not part of {{ or {#
+            (r"\{", Text),
+            # <c-raw> ... </c-raw>: the body is verbatim (not interpreted)
+            (
+                r"(<)(\s*)(c-raw)" + _TAG_END,
+                bygroups(Punctuation, Text, Name.Tag),
+                ("raw-content", "tag"),
+            ),
+            # Only the structural tags with unprefixed Python attributes need
+            # special states. Every other c-* name falls through to HtmlLexer.
+            (
+                r"(</?)(\s*)(c-(?:if|elif))" + _TAG_END,
+                bygroups(Punctuation, Text, Name.Tag),
+                "condition-tag",
+            ),
+            (
+                r"(</?)(\s*)(c-for)" + _TAG_END,
+                bygroups(Punctuation, Text, Name.Tag),
+                "for-tag",
+            ),
+            # ordinary text, stopped at { so the interpolation/comment rules fire;
+            # everything after this is HtmlLexer's own root (its [^<&]+ text rule,
+            # which does not stop at {, is dropped by the [1:] slice)
+            (r"[^<&{]+", Text),
+            *HtmlLexer.tokens["root"][1:],
+        ],
+        # An ordinary element's attributes.
+        "tag": [_WS_RULE, _CLIENT_PROPS_ATTR_RULE, _C_ATTR_RULE, *_COMMON_ATTR_RULES],
+        "condition-tag": [_WS_RULE, _CLIENT_PROPS_ATTR_RULE, _C_ATTR_RULE, _COND_ATTR_RULE, *_COMMON_ATTR_RULES],
+        "for-tag": [_WS_RULE, _CLIENT_PROPS_ATTR_RULE, _C_ATTR_RULE, _EACH_ATTR_RULE, *_COMMON_ATTR_RULES],
+        # The value of a c-* (or built-in) attribute: a Python expression.
+        "python-attr": [
+            (r'(")((?:[^"\\]|\\.)*)(")', bygroups(Punctuation, using(PythonLexer), Punctuation), "#pop"),
+            (r"(')((?:[^'\\]|\\.)*)(')", bygroups(Punctuation, using(PythonLexer), Punctuation), "#pop"),
+            (r"[^\s>]+", using(PythonLexer), "#pop"),
+        ],
+        # The direct client props value is an Alpine/JavaScript expression.
+        "javascript-attr": [
+            (r'(")((?:[^"\\]|\\.)*)(")', bygroups(Punctuation, using(JavascriptLexer), Punctuation), "#pop"),
+            (r"(')((?:[^'\\]|\\.)*)(')", bygroups(Punctuation, using(JavascriptLexer), Punctuation), "#pop"),
+            (r"[^\s>]+", using(JavascriptLexer), "#pop"),
+        ],
+        # The verbatim body of <c-raw>...</c-raw>: plain text until the close tag.
+        "raw-content": [
+            (
+                r"(<)(\s*)(/)(\s*)(c-raw)(\s*)(>)",
+                bygroups(Punctuation, Text, Punctuation, Text, Name.Tag, Text, Punctuation),
+                "#pop",
+            ),
+            (r"[^<]+", Text),
+            (r"<", Text),
+        ],
+    }

pygments_citry-0.1.0/pygments_citry/lexers.py

@@ -0,0 +1,79 @@
+"""
+The ``citry`` lexer: Python, with the embedded ``template``/``js``/``css`` highlighted.
+
+``CitryPythonLexer`` behaves like Pygments' ``PythonLexer`` but recognises the
+three multiline string attributes a Citry component uses and hands each body to
+the right language:
+
+- ``template = \"\"\"...\"\"\"`` to the Citry HTML lexer (``<c-*>`` tags, ``{{ }}``, ...),
+- ``js = \"\"\"...\"\"\"`` to the JavaScript lexer,
+- ``css = \"\"\"...\"\"\"`` to the CSS lexer.
+
+The detection is deliberately simple, matching the upstream ``pygments-djc``: it
+fires on any ``template``/``js``/``css`` triple-quoted assignment, even one not
+on a component class. That is fine for documentation, where these names almost
+always mean a component.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from pygments.lexer import bygroups, using
+from pygments.lexers.css import CssLexer
+from pygments.lexers.javascript import JavascriptLexer
+from pygments.lexers.python import PythonLexer
+from pygments.token import Name, Operator, Punctuation, String, Text
+
+from pygments_citry.citry_html import CitryHtmlLexer
+
+# Matches `template = """` or the typed `template: some.Type = """` (and the ''' form).
+# The nine capture groups are highlighted individually by the bygroups action below.
+_CAPTURE = r'({name})(\s*)(?:(:)(\s*)([^\s=]+))?(\s*)(=)(\s*)((?:"""|\'\'\'))'
+
+# Highlights the nine groups of _CAPTURE. Reused for all three openers, which
+# differ only in the attribute name and the state they push.
+_OPENER = bygroups(
+    Name.Variable,  # the attribute name (template / js / css)
+    Text,
+    Punctuation,  # the ':' of an optional type annotation
+    Text,
+    Name.Class,  # the annotation type, if present
+    Text,
+    Operator,  # the '='
+    Text,
+    String.Doc,  # the opening triple quote
+)
+
+
+class CitryPythonLexer(PythonLexer):
+    """Lexer for Citry component code: Python plus the embedded template/js/css."""
+
+    name = "Citry Python"
+    aliases: ClassVar[list[str]] = ["citry"]
+
+    tokens: ClassVar[dict[str, Any]] = {
+        **PythonLexer.tokens,
+        # The three openers are prepended to Python's root so they win over its
+        # own string handling; each pushes a state that re-lexes the body.
+        "root": [
+            (_CAPTURE.format(name="template"), _OPENER, "template_string"),
+            (_CAPTURE.format(name="js"), _OPENER, "js_string"),
+            (_CAPTURE.format(name="css"), _OPENER, "css_string"),
+            *PythonLexer.tokens["root"],
+        ],
+        # Inside a body: the closing triple quote pops (first, so it wins);
+        # otherwise the run up to the close is handed to the embedded lexer.
+        "template_string": [
+            (r'(?:"""|\'\'\')', String.Doc, "#pop"),
+            (r'((?!"""|\'\'\')(?:.|\n))+', using(CitryHtmlLexer)),
+        ],
+        "js_string": [
+            (r'(?:"""|\'\'\')', String.Doc, "#pop"),
+            (r'((?!"""|\'\'\')(?:.|\n))+', using(JavascriptLexer)),
+        ],
+        "css_string": [
+            (r'(?:"""|\'\'\')', String.Doc, "#pop"),
+            (r'((?!"""|\'\'\')(?:.|\n))+', using(CssLexer)),
+        ],
+    }

pygments_citry-0.1.0/pygments_citry.egg-info/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: pygments-citry
+Version: 0.1.0
+Summary: Pygments lexer for Citry components: highlights the HTML, JS, and CSS embedded in a component's template/js/css strings
+Author-email: Juro Oravec <juraj.oravec.josefson@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://citry.dev
+Project-URL: Repository, https://github.com/citry-dev/citry
+Project-URL: Changelog, https://github.com/citry-dev/citry/blob/main/packages/py/pygments_citry/CHANGELOG.md
+Project-URL: Issues, https://github.com/citry-dev/citry/issues
+Keywords: citry,pygments,lexer,syntax highlighting,components,html
+Classifier: Environment :: Plugins
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygments>=2.15
+Dynamic: license-file
+
+# pygments-citry
+
+A [Pygments](https://pygments.org/) lexer for [Citry](https://citry.dev)
+components. It highlights a component the way an editor would: the Python class,
+plus the HTML, JavaScript, and CSS embedded in its `template`, `js`, and `css`
+string attributes, each in its own language.
+
+Without it, a Citry component in a ` ```python ` block renders the template,
+JS script, and CSS stylesheet as flat string literals. With it, a ` ```citry `
+block colours the `<c-*>` tags, the `{{ ... }}` interpolation, the embedded
+stylesheet, and the embedded script.
+
+## Install
+
+```bash
+pip install pygments-citry
+```
+
+The package registers a `citry` lexer as a Pygments plugin, so any tool that
+resolves lexers by name picks it up once it is installed.
+
+## Use it
+
+On the command line:
+
+```bash
+pygmentize -l citry my_component.py
+```
+
+In Python:
+
+```python
+from pygments import highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexers import get_lexer_by_name
+
+lexer = get_lexer_by_name("citry")
+html = highlight(source, lexer, HtmlFormatter())
+```
+
+In a Markdown site (mkdocs with `pymdownx.highlight` / `pymdownx.superfences`,
+or any python-markdown setup that resolves Pygments lexers by name), tag the
+fence with `citry`:
+
+````markdown
+```citry
+from citry import Component
+
+class Welcome(Component):
+    template = """
+      <div class="card">
+        <h1>{{ title }}</h1>
+        <p c-if="count">You have {{ count }} new messages.</p>
+      </div>
+    """
+```
+````
+
+No superfences `custom_fences` entry is needed: once the package is installed,
+`citry` resolves like any other Pygments lexer.
+
+## What it highlights
+
+A `citry` block is highlighted as Python, and the following Citry constructs
+inside the `template` / `js` / `css` attributes are highlighted in their own
+language:
+
+- The HTML in `template`, including the `<c-*>` component and control-flow tags
+  (the built-ins `c-if`, `c-for`, `c-slot`, `<c-raw>`, and so on) and `c-*`
+  dynamic attributes.
+- `{{ ... }}` interpolation, whose body is a Python expression.
+- `{# ... #}` template comments.
+- The JavaScript in `js` and the CSS in `css`.
+
+The `<c-raw>...</c-raw>` element is treated as verbatim text, matching the
+engine: `{{ }}` and tags inside it are not interpreted.
+
+## Template-only blocks: `citry-html`
+
+For a fenced block that shows only a template, with no surrounding Python (just
+`<c-*>` tags, `{{ ... }}`, and `{# ... #}`), tag it `citry-html`:
+
+````markdown
+```citry-html
+<c-for each="item in items">
+  <li c-if="item.visible">{{ item.label }}</li>
+</c-for>
+```
+````
+
+`citry` expects full component code (Python with embedded strings), so a bare
+template belongs in a `citry-html` block instead.
+
+## License
+
+MIT. Part of the [Citry](https://github.com/citry-dev/citry) project.

pygments_citry-0.1.0/pygments_citry.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+pygments_citry/__init__.py
+pygments_citry/citry_html.py
+pygments_citry/lexers.py
+pygments_citry/py.typed
+pygments_citry.egg-info/PKG-INFO
+pygments_citry.egg-info/SOURCES.txt
+pygments_citry.egg-info/dependency_links.txt
+pygments_citry.egg-info/entry_points.txt
+pygments_citry.egg-info/requires.txt
+pygments_citry.egg-info/top_level.txt
+tests/test_citry_html.py
+tests/test_lexers.py
+tests/test_registration.py

pygments_citry-0.1.0/pygments_citry.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pygments_citry-0.1.0/pygments_citry.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pygments.lexers]
+citry = pygments_citry.lexers:CitryPythonLexer
+citry-html = pygments_citry.citry_html:CitryHtmlLexer

pygments_citry-0.1.0/pygments_citry.egg-info/requires.txt

@@ -0,0 +1 @@
+pygments>=2.15

pygments_citry-0.1.0/pygments_citry.egg-info/top_level.txt

@@ -0,0 +1 @@
+pygments_citry

pygments_citry-0.1.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+# The `license-files` field below needs setuptools 77 or newer.
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pygments-citry"
+version = "0.1.0"
+requires-python = ">=3.10, <4.0"
+description = "Pygments lexer for Citry components: highlights the HTML, JS, and CSS embedded in a component's template/js/css strings"
+readme = "README.md"
+keywords = [
+    "citry",
+    "pygments",
+    "lexer",
+    "syntax highlighting",
+    "components",
+    "html",
+]
+authors = [{ name = "Juro Oravec", email = "juraj.oravec.josefson@gmail.com" }]
+classifiers = [
+    "Environment :: Plugins",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "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 :: Text Processing :: Markup :: HTML",
+    "Topic :: Software Development :: Documentation",
+    "Typing :: Typed",
+]
+license = "MIT"
+license-files = ["LICENSE"]
+# Only Pygments. The floor is where the plugin lexer API we rely on is stable;
+# the docs environment keeps its own upper pin (see the root pyproject `docs`
+# extra), which resolves against this floor.
+dependencies = ["pygments>=2.15"]
+
+# Registers the lexers as Pygments plugins: any environment with this package
+# installed resolves ```citry (full component) and ```citry-html (template only)
+# through get_lexer_by_name with no explicit import.
+[project.entry-points."pygments.lexers"]
+citry = "pygments_citry.lexers:CitryPythonLexer"
+citry-html = "pygments_citry.citry_html:CitryHtmlLexer"
+
+# The single declaration of this package's test deps. The uv workspace installs
+# them on `uv sync --all-packages`, so the shared venv and CI get them with no
+# separate root-level copy to keep in step.
+[dependency-groups]
+dev = ["pytest>=8.3.5"]
+
+[project.urls]
+Homepage = "https://citry.dev"
+Repository = "https://github.com/citry-dev/citry"
+Changelog = "https://github.com/citry-dev/citry/blob/main/packages/py/pygments_citry/CHANGELOG.md"
+Issues = "https://github.com/citry-dev/citry/issues"
+
+# Ship only the lexer package; the flat-layout auto-discovery would otherwise
+# also try to package the tests directory.
+[tool.setuptools.packages.find]
+include = ["pygments_citry*"]
+
+[tool.setuptools.package-data]
+pygments_citry = ["py.typed"]

pygments_citry-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pygments_citry-0.1.0/tests/test_citry_html.py

@@ -0,0 +1,231 @@
+"""Token-stream tests for the Citry template constructs inside a ``template`` string."""
+
+from pygments.lexers import get_lexer_by_name
+from pygments.token import Comment, Error, Keyword, Name, Operator, Punctuation, String, Text
+
+
+def lex_template(body):
+    """Lex a component whose ``template`` is `body`, returning its non-blank tokens."""
+    lexer = get_lexer_by_name("citry")
+    src = 'class C(Component):\n    template = """' + body + '"""\n'
+    return [(tok, val) for tok, val in lexer.get_tokens(src) if val.strip()]
+
+
+def lex_html(body):
+    """Lex `body` directly with the standalone ``citry-html`` lexer (a bare template)."""
+    lexer = get_lexer_by_name("citry-html")
+    return [(tok, val) for tok, val in lexer.get_tokens(body) if val.strip()]
+
+
+def test_interpolation_body_is_python():
+    toks = lex_template("<p>{{ count }}</p>")
+    assert (Punctuation, "{{") in toks
+    assert (Punctuation, "}}") in toks
+    assert (Name, "count") in toks
+
+
+def test_interpolation_boundary_skips_string_literals():
+    # the "}}" inside the Python string must not end the block early
+    toks = lex_template('{{ "}}" }}')
+    # exactly one closing }} punctuation, the real end (not the one in the string)
+    assert [v for tok, v in toks if (tok, v) == (Punctuation, "}}")] == ["}}"]
+    assert (String.Double, "}}") in toks  # the "}}" is part of a Python string
+
+
+def test_template_comment():
+    toks = lex_template("<i>{# note #}</i>")
+    assert (Comment, "{# note #}") in toks
+
+
+def test_lone_brace_is_text_not_interpolation():
+    toks = lex_template("a { b")
+    assert (Text, "{") in toks
+    assert (Punctuation, "{{") not in toks
+
+
+def test_builtin_and_user_component_names_are_html_tag_tokens():
+    toks = lex_template("<c-slot></c-slot><c-Card></c-Card>")
+    assert (Name.Tag, "c-slot") in toks
+    assert (Name.Tag, "c-Card") in toks
+    assert (Name.Builtin, "c-slot") not in toks
+
+
+def test_dynamic_attribute_value_is_python():
+    toks = lex_template('<li c-for="item in items"></li>')
+    assert (Name.Attribute, "c-for") in toks
+    assert (Operator.Word, "in") in toks  # `in` from the Python expression
+
+
+def test_dynamic_attribute_single_quoted_and_bare():
+    toks = lex_template("<b c-if='a and b' c-x=y></b>")
+    assert (Operator.Word, "and") in toks
+    assert (Name.Attribute, "c-x") in toks
+    assert (Name, "y") in toks
+
+
+def test_direct_client_props_value_is_javascript():
+    toks = lex_template('<c-child $c-props="{ enabled: true, count: localCount }" />')
+    assert (Name.Attribute, "$c-props") in toks
+    assert (Keyword.Constant, "true") in toks
+    assert (Name.Other, "localCount") in toks
+    assert not any(token is Error for token, _ in toks)
+
+
+def test_server_dynamic_client_props_value_is_python():
+    toks = lex_template('<c-child c-$c-props="primary if enabled else fallback" />')
+    assert (Name.Attribute, "c-$c-props") in toks
+    assert (Keyword, "if") in toks
+    assert (Keyword, "else") in toks
+    assert (Name, "fallback") in toks
+    assert not any(token is Error for token, _ in toks)
+
+
+def test_only_exact_client_props_name_gets_special_highlighting():
+    toks = lex_html('<div $other="true" $c-props-extra="true"></div>')
+    assert (Error, "$") in toks
+    assert (Name.Attribute, "$c-props") not in toks
+
+
+def test_c_raw_body_is_verbatim():
+    toks = lex_template("<c-raw>a < b {{ z }}</c-raw>")
+    assert (Name.Tag, "c-raw") in toks
+    # nothing inside c-raw is interpreted
+    assert (Punctuation, "{{") not in toks
+    assert (Name, "z") not in toks
+
+
+def test_framework_attributes_are_accepted():
+    toks = lex_template('<div @click="f" :class="c" [style]="s" (tap)="t"></div>')
+    assert (Name.Attribute, "@click") in toks
+    assert (Name.Attribute, "[style]") in toks
+    assert (Name.Attribute, "(tap)") in toks
+
+
+def test_boolean_attributes():
+    toks = lex_template("<input disabled [hidden]>")
+    assert (Name.Attribute, "disabled") in toks
+    assert (Name.Attribute, "[hidden]") in toks
+
+
+def test_interpolation_boundary_counts_nested_braces():
+    # the dict's closing }} must not end the block; the real end is the last }}
+    toks = lex_template('{{ {"a": {1: 2}} }}')
+    assert [v for tok, v in toks if (tok, v) == (Punctuation, "}}")] == ["}}"]
+    assert (Punctuation, "{") in toks  # the dict braces are highlighted as Python
+
+
+def test_control_flow_tag_attributes_are_python():
+    toks = lex_template('<c-if cond="a and b"></c-if><c-elif cond="c or d"></c-elif><c-for each="x in xs" />')
+    assert (Name.Attribute, "cond") in toks
+    assert (Name.Attribute, "each") in toks
+    assert (Operator.Word, "and") in toks  # cond value lexed as Python
+    assert (Operator.Word, "or") in toks  # c-elif uses the same condition state
+    assert (Operator.Word, "in") in toks  # each value lexed as Python
+
+
+def test_dynamic_component_static_and_python_targets_are_distinct():
+    toks = lex_template('<c-component is="widget" /><c-element c-is="widget" />')
+
+    assert (Name.Attribute, "is") in toks
+    assert (String, '"widget"') in toks
+    assert (Name.Attribute, "c-is") in toks
+    assert (Name, "widget") in toks
+
+
+def test_control_flow_attribute_names_on_other_tags_stay_strings():
+    toks = lex_template('<c-slot cond="a and b" each="x in xs" is="widget" />')
+
+    assert toks.count((String, '"a and b"')) == 1
+    assert toks.count((String, '"x in xs"')) == 1
+    assert toks.count((String, '"widget"')) == 1
+
+
+def test_is_on_an_ordinary_tag_stays_a_string():
+    # `is` is a real HTML attribute; on a plain element its value is a string
+    toks = lex_template('<button is="my-btn">x</button>')
+    assert (Name.Attribute, "is") in toks
+    assert (String, '"my-btn"') in toks
+
+
+def test_interpolation_skips_escaped_quote_in_string():
+    # a backslash-escaped quote must not end the string mid-scan
+    toks = lex_template(r'{{ "a\"}}b" + c }}')
+    assert [v for tok, v in toks if (tok, v) == (Punctuation, "}}")] == ["}}"]
+    assert (Name, "c") in toks
+
+
+def test_interpolation_without_surrounding_whitespace():
+    toks = lex_template("{{x}}")
+    assert (Punctuation, "{{") in toks
+    assert (Punctuation, "}}") in toks
+    assert (Name, "x") in toks
+
+
+def test_unclosed_interpolation_degrades_to_body():
+    # no closing }}: the rest is lexed as the expression, and nothing crashes
+    toks = lex_html("{{ oops")
+    assert (Punctuation, "{{") in toks
+    assert (Name, "oops") in toks
+    assert (Punctuation, "}}") not in toks
+
+
+def test_malformed_interpolations_do_not_crash():
+    # an unterminated string and a lone trailing } are degenerate but must not
+    # raise; the scanner just runs to the end of the text
+    for body in ('{{ "unterminated', "{{ a}"):
+        toks = lex_html(body)
+        assert (Punctuation, "{{") in toks
+
+
+def test_standalone_citry_html_lexer_on_a_bare_template():
+    toks = lex_html('<c-if cond="ok">{# note #}<c-slot />{{ user.name }}</c-if>')
+    assert (Name.Tag, "c-if") in toks
+    assert (Name.Tag, "c-slot") in toks
+    assert (Comment, "{# note #}") in toks
+    assert (Name.Attribute, "cond") in toks
+    assert (Name, "ok") in toks  # cond value is Python
+    assert (Name, "user") in toks  # {{ }} body is Python
+
+
+def test_every_citry_tag_name_uses_the_html_tag_token():
+    tags = (
+        "c-if",
+        "c-elif",
+        "c-else",
+        "c-for",
+        "c-empty",
+        "c-slot",
+        "c-fill",
+        "c-component",
+        "c-element",
+        "c-provide",
+        "c-css",
+        "c-js",
+        "c-raw",
+        "c-cache",
+        "c-error-fallback",
+        "c-template",
+        "c-Card",
+    )
+    toks = lex_html("".join(f"<{tag}></{tag}>" for tag in tags))
+
+    for tag in tags:
+        assert toks.count((Name.Tag, tag)) == 2
+        assert (Name.Builtin, tag) not in toks
+
+
+def test_builtin_prefixes_do_not_steal_user_component_names():
+    tags = (
+        "c-if-panel",
+        "c-elif-panel",
+        "c-for-panel",
+        "c-slot-panel",
+        "c-component-card",
+        "c-raw-data",
+    )
+    toks = lex_html("".join(f"<{tag}>{{{{ value }}}}</{tag}>" for tag in tags))
+
+    for tag in tags:
+        assert toks.count((Name.Tag, tag)) == 2
+    assert toks.count((Punctuation, "{{")) == len(tags)
+    assert toks.count((Punctuation, "}}")) == len(tags)

pygments_citry-0.1.0/tests/test_lexers.py

@@ -0,0 +1,68 @@
+"""Token-stream tests for the top-level ``citry`` lexer (Python plus the embeds)."""
+
+from pygments.lexers import get_lexer_by_name
+from pygments.token import Keyword, Name, String
+
+
+def lex(src):
+    """Lex `src` with the citry lexer, dropping whitespace-only tokens."""
+    lexer = get_lexer_by_name("citry")
+    return [(tok, val) for tok, val in lexer.get_tokens(src) if val.strip()]
+
+
+def test_alias_and_name():
+    lexer = get_lexer_by_name("citry")
+    assert lexer.name == "Citry Python"
+    assert "citry" in lexer.aliases
+
+
+def test_template_opener_and_html_embed():
+    toks = lex('class C(Component):\n    template = """<div>{{ x }}</div>"""\n')
+    assert (Name.Variable, "template") in toks
+    assert (String.Doc, '"""') in toks
+    assert (Name.Tag, "div") in toks
+    # the {{ }} body is handed to the Python lexer
+    assert (Name, "x") in toks
+
+
+def test_js_opener_embeds_javascript():
+    toks = lex('class C(Component):\n    js = """const x = `a`;"""\n')
+    assert (Name.Variable, "js") in toks
+    # `const` and a backtick template literal are JavaScript, not Python
+    assert (Keyword.Declaration, "const") in toks
+    assert (String.Backtick, "`") in toks
+
+
+def test_css_opener_embeds_css():
+    toks = lex('class C(Component):\n    css = """a { color: red; }"""\n')
+    assert (Name.Variable, "css") in toks
+    assert (Keyword, "color") in toks
+    assert (Keyword.Constant, "red") in toks
+
+
+def test_typed_opener_keeps_annotation_and_embeds_html():
+    toks = lex("class C(Component):\n    template: types.html = '''<br/>'''\n")
+    assert (Name.Variable, "template") in toks
+    assert (Name.Class, "types.html") in toks
+    assert (Name.Tag, "br") in toks
+
+
+def test_triple_single_quote_body():
+    toks = lex("class C(Component):\n    css = '''a{}'''\n")
+    assert (String.Doc, "'''") in toks
+    assert (Name.Tag, "a") in toks
+
+
+def test_full_component_highlights_all_three_and_stays_python():
+    src = (
+        "class Card(Component):\n"
+        '    template = """<c-slot></c-slot>{{ title }}"""\n'
+        '    js = """const n = 1;"""\n'
+        '    css = """.card { color: red; }"""\n'
+    )
+    toks = lex(src)
+    assert (Name.Variable, "template") in toks
+    assert (Name.Variable, "js") in toks
+    assert (Name.Variable, "css") in toks
+    # the class itself is still ordinary Python
+    assert (Name.Class, "Card") in toks

pygments_citry-0.1.0/tests/test_registration.py

@@ -0,0 +1,34 @@
+"""The ``citry`` lexer registers with Pygments as a plugin and on import."""
+
+from importlib.metadata import entry_points
+
+from pygments.lexers import LEXERS, get_lexer_by_name
+
+import pygments_citry
+
+
+def test_resolves_by_alias():
+    lexer = get_lexer_by_name("citry")
+    assert type(lexer).__name__ == "CitryPythonLexer"
+
+
+def test_plugin_entry_point_declared():
+    values = {ep.value for ep in entry_points(group="pygments.lexers") if ep.name == "citry"}
+    assert "pygments_citry.lexers:CitryPythonLexer" in values
+
+
+def test_import_registers_in_builtin_table():
+    assert "CitryPythonLexer" in LEXERS
+    assert "CitryHtmlLexer" in LEXERS
+    assert pygments_citry.CitryPythonLexer.name == "Citry Python"
+    assert pygments_citry.CitryHtmlLexer.name == "Citry HTML"
+
+
+def test_citry_html_resolves_by_alias():
+    lexer = get_lexer_by_name("citry-html")
+    assert type(lexer).__name__ == "CitryHtmlLexer"
+
+
+def test_citry_html_entry_point_declared():
+    values = {ep.value for ep in entry_points(group="pygments.lexers") if ep.name == "citry-html"}
+    assert "pygments_citry.citry_html:CitryHtmlLexer" in values