pygments-citry 0.1.0__py3-none-any.whl

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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+pygments_citry/__init__.py,sha256=jqjp95MlE7Rwt2TGvSS3ouWKlzbS3W0mBoEcqRuYh9U,1432
+pygments_citry/citry_html.py,sha256=qSxLRwqAfN5NKxBbtanxzqzZFdqXd0wiqK4Tky7XqjQ,8357
+pygments_citry/lexers.py,sha256=IU2oGLbDY9WWYTI1GK6p5HCV3cySGzrfooUbjq4wAdU,3130
+pygments_citry/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pygments_citry-0.1.0.dist-info/licenses/LICENSE,sha256=DWFXareDLD3iWrd8m9GgkBR6iIZC8AzSoaI35Rkr8y8,1063
+pygments_citry-0.1.0.dist-info/METADATA,sha256=ssqsww7vE06fBgC4B27cHdpNRNmU_hOa_LfKhEFCeGc,4153
+pygments_citry-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+pygments_citry-0.1.0.dist-info/entry_points.txt,sha256=_-eEsJ8zqulB42wm3CzbVZWySO-Zr-gVbtMeMChwjIQ,119
+pygments_citry-0.1.0.dist-info/top_level.txt,sha256=AFAUv1A1S3yVGiOWkqgLJabSJRZt_CjOax56ueluKI4,15
+pygments_citry-0.1.0.dist-info/RECORD,,

pygments_citry-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pygments_citry-0.1.0.dist-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.dist-info/licenses/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.dist-info/top_level.txt

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