dataface 0.1.2__py3-none-any.whl

dataface/integrations/highlighting.py

@@ -0,0 +1,351 @@
+"""Dataface YAML Pygments lexer with embedded SQL block highlighting.
+
+The lexer handles Dataface face YAML and delegates the body of SQL block
+scalars (``sql: |``, ``sql: >``, ``query: |``, ``query: >``) to
+``pygments.lexers.SqlLexer`` so SQL keywords are visually distinct from
+the surrounding YAML structure.
+
+Public API
+----------
+- ``DatafaceYamlLexer`` — Pygments lexer class.  Reference it from
+  MkDocs / pymdownx config via
+  ``!!python/name:dataface.integrations.highlighting.DatafaceYamlLexer``.
+- ``highlight_face_yaml(source)`` — Highlight Dataface YAML and return an
+  HTML string.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Generator
+
+from pygments import highlight as pygments_highlight
+from pygments.formatters import HtmlFormatter
+from pygments.lexer import RegexLexer, bygroups
+from pygments.lexers import SqlLexer
+from pygments.token import (
+    Comment,
+    Keyword,
+    Name,
+    Number,
+    Punctuation,
+    String,
+    Text,
+)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Keys that open a SQL block: "sql: |", "query: |", "sql: >", "query: >"
+# Indent captured in group 1; key in group 2.
+_SQL_BLOCK_OPEN_RE = re.compile(
+    r"^( *)(?:sql|query)\s*:\s*[|>]",
+    re.MULTILINE,
+)
+
+# Detect a plain YAML key: <indent><word chars>:
+_YAML_KEY_RE = re.compile(r"^( *)([a-zA-Z_][a-zA-Z0-9_\-]*)\s*:")
+
+# Detect a list-item YAML key: <indent>- <word chars>:
+# Effective indent is the column of the dash (group 1 length), not the key itself.
+_YAML_LIST_KEY_RE = re.compile(r"^( *)-\s+([a-zA-Z_][a-zA-Z0-9_\-]*)\s*:")
+
+
+def _sql_block_ranges(source: str) -> list[tuple[int, int]]:
+    """Return (start, end) byte offsets of SQL block scalar bodies in *source*.
+
+    The body starts on the line after the ``sql: |`` / ``query: |`` line and
+    ends just before the next YAML key at the same or lower indent level (or
+    at EOF).  Offsets are character positions in *source*.
+    """
+    ranges: list[tuple[int, int]] = []
+    lines = source.splitlines(keepends=True)
+    line_starts: list[int] = []
+    pos = 0
+    for line in lines:
+        line_starts.append(pos)
+        pos += len(line)
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        m = _SQL_BLOCK_OPEN_RE.match(line)
+        if m:
+            opener_indent = len(m.group(1))
+            body_start_line = i + 1
+            # Find end: first line at indent <= opener_indent that is a YAML key.
+            # Also treat "  - key:" list-item lines as terminators; their effective
+            # indent is the dash column (group 1 length), not the key column.
+            j = body_start_line
+            while j < len(lines):
+                candidate = lines[j]
+                km = _YAML_KEY_RE.match(candidate)
+                if km and len(km.group(1)) <= opener_indent:
+                    break
+                lm = _YAML_LIST_KEY_RE.match(candidate)
+                if lm and len(lm.group(1)) <= opener_indent:
+                    break
+                j += 1
+            if body_start_line < j:
+                start = line_starts[body_start_line]
+                end = line_starts[j] if j < len(line_starts) else pos
+                ranges.append((start, end))
+            i = j
+        else:
+            i += 1
+    return ranges
+
+
+class DatafaceYamlLexer(RegexLexer):
+    """Pygments lexer for Dataface face YAML with embedded SQL in block scalars.
+
+    Top-level and nested keys, chart types, input types, and other Dataface
+    vocabulary are coloured distinctly.  Lines inside ``sql: |``, ``sql: >``,
+    ``query: |``, and ``query: >`` block scalars are delegated to
+    ``SqlLexer`` so SQL keywords (SELECT, FROM, WHERE, …) receive keyword
+    styling.
+    """
+
+    name = "Dataface YAML"
+    aliases = ["dataface", "dataface-yaml", "dfyaml"]
+    filenames = ["*.yml", "*.yaml"]
+    mimetypes = ["text/x-dataface-yaml"]
+
+    TOP_LEVEL_KEYWORDS = [
+        "title",
+        "description",
+        "tags",
+        "content",
+        "variables",
+        "queries",
+        "charts",
+        "rows",
+        "cols",
+        "grid",
+        "tabs",
+        "theme",
+        "id",
+        "style",
+        "width",
+        "height",
+    ]
+    CHART_PROPERTIES = [
+        "type",
+        "query",
+        "x",
+        "y",
+        "color",
+        "size",
+        "shape",
+        "value",
+        "glyph",
+        "tone",
+        "support",
+        "limit",
+        "interactions",
+        "filters",
+    ]
+    CHART_TYPES = [
+        "line",
+        "bar",
+        "area",
+        "scatter",
+        "table",
+        "kpi",
+        "heatmap",
+        "pie",
+        "donut",
+    ]
+    VARIABLE_PROPERTIES = [
+        "input",
+        "label",
+        "description",
+        "default",
+        "placeholder",
+        "required",
+        "allow_null",
+        "column",
+        "dimension",
+        "measure",
+        "model",
+        "options",
+        "min",
+        "max",
+        "step",
+        "operator",
+    ]
+    VARIABLE_INPUT_TYPES = [
+        "select",
+        "multiselect",
+        "input",
+        "textarea",
+        "slider",
+        "datepicker",
+        "daterange",
+        "checkbox",
+        "radio",
+    ]
+    QUERY_PROPERTIES = [
+        "sql",
+        "model",
+        "columns",
+        "metrics",
+        "dimensions",
+        "filters",
+        "time_grain",
+        "limit",
+        "url",
+        "method",
+        "headers",
+        "params",
+        "body",
+    ]
+    LAYOUT_PROPERTIES = [
+        "columns",
+        "row_height",
+        "gap",
+        "default_width",
+        "default_height",
+        "items",
+        "position",
+        "default",
+    ]
+    INTERACTION_PROPERTIES = [
+        "by",
+        "order",
+        "action",
+        "target",
+        "value_map",
+        "click",
+        "hover",
+    ]
+    STYLE_PROPERTIES = [
+        "palette",
+        "legend",
+        "disable",
+        "labels",
+        "x_axis",
+        "y_axis",
+    ]
+    SORT_ORDERS = ["asc", "desc"]
+    ACTIONS = ["filter", "open_link", "set_variable", "drill"]
+    TIME_GRAINS = ["day", "week", "month", "quarter", "year"]
+    HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH"]
+    LEGEND_VALUES = ["show", "hide"]
+    LABEL_VALUES = ["auto", "show", "hide"]
+    GAP_VALUES = ["sm", "md", "lg", "xl"]
+    POSITION_VALUES = ["top", "left"]
+
+    ALL_KEYWORDS = (
+        TOP_LEVEL_KEYWORDS
+        + CHART_PROPERTIES
+        + CHART_TYPES
+        + VARIABLE_PROPERTIES
+        + VARIABLE_INPUT_TYPES
+        + QUERY_PROPERTIES
+        + LAYOUT_PROPERTIES
+        + INTERACTION_PROPERTIES
+        + STYLE_PROPERTIES
+        + SORT_ORDERS
+        + ACTIONS
+        + TIME_GRAINS
+        + HTTP_METHODS
+        + LEGEND_VALUES
+        + LABEL_VALUES
+        + GAP_VALUES
+        + POSITION_VALUES
+    )
+    KEYWORD_PATTERN = r"\b(" + "|".join(ALL_KEYWORDS) + r")\b"
+
+    tokens = {
+        "root": [
+            (r"#.*$", Comment),
+            (r"\{#[^#]*#\}", Comment),
+            (r"^---\s*$", Punctuation),
+            (r"^\.\.\.\s*$", Punctuation),
+            (r'"[^"]*"', String.Double),
+            (r"'[^']*'", String.Single),
+            (r"\{\{[^}]*\}\}", String.Interpol),
+            (r"!![^\s]+", Keyword.Type),
+            (r"&[^\s]+", Name.Variable),
+            (r"\*[^\s]+", Name.Variable),
+            (r"([a-zA-Z_][a-zA-Z0-9_\-]*)(\s*:)", bygroups(Name.Tag, Punctuation)),
+            (r"^\s*-\s+", Punctuation),
+            (r"[\[\]{}]", Punctuation),
+            (r":", Punctuation),
+            (r"\|", Punctuation),
+            (r">", Punctuation),
+            (r"[-+]", Punctuation),
+            (r"\d+\.\d+", Number.Float),
+            (r"\d+", Number.Integer),
+            (r"\b(true|false|null|yes|no|on|off)\b", Keyword.Constant),
+            (KEYWORD_PATTERN, Keyword),
+            (r"[^\s:]+", Text),
+            (r"\s+", Text),
+        ]
+    }
+
+    def get_tokens_unprocessed(
+        self, text: str, stack: tuple[str, ...] = ("root",)
+    ) -> Generator[tuple[int, object, str], None, None]:
+        """Yield tokens, delegating SQL block bodies to SqlLexer.
+
+        For each character range identified as a SQL block body, the
+        corresponding text is re-tokenised with SqlLexer; the rest goes
+        through the normal YAML rules.
+
+        All yielded offsets are positions in *text* (the original string),
+        not positions within a chunk — required by the Pygments contract.
+        """
+        sql_ranges = _sql_block_ranges(text)
+        if not sql_ranges:
+            yield from super().get_tokens_unprocessed(text, stack)
+            return
+
+        sql_lexer = SqlLexer()
+        cursor = 0
+
+        for sql_start, sql_end in sql_ranges:
+            # Yield YAML tokens for the segment before this SQL block,
+            # adjusting chunk-relative offsets back to text-absolute positions.
+            if cursor < sql_start:
+                yaml_chunk = text[cursor:sql_start]
+                for chunk_offset, ttype, value in super().get_tokens_unprocessed(
+                    yaml_chunk, stack
+                ):
+                    yield cursor + chunk_offset, ttype, value
+
+            # Yield SQL tokens for the block body, offset-adjusted
+            sql_chunk = text[sql_start:sql_end]
+            for offset, ttype, value in sql_lexer.get_tokens_unprocessed(sql_chunk):
+                yield sql_start + offset, ttype, value
+
+            cursor = sql_end
+
+        # Remaining YAML after the last SQL block
+        if cursor < len(text):
+            yaml_tail = text[cursor:]
+            for chunk_offset, ttype, value in super().get_tokens_unprocessed(
+                yaml_tail, stack
+            ):
+                yield cursor + chunk_offset, ttype, value
+
+
+def highlight_face_yaml(source: str) -> str:
+    """Highlight Dataface face YAML and return an HTML string.
+
+    SQL inside ``sql: |``, ``sql: >``, ``query: |``, and ``query: >``
+    block scalars is coloured with SQL keyword rules.  The wrapping HTML
+    uses ``cssclass="highlight"`` for compatibility with the existing
+    ``extra.css`` rules.
+
+    Args:
+        source: Raw YAML source text.
+
+    Returns:
+        HTML string with Pygments token spans.
+    """
+    lexer = DatafaceYamlLexer()
+    formatter = HtmlFormatter(cssclass="highlight", nowrap=True)
+    return pygments_highlight(source, lexer, formatter)