cellgraph 0.1.0__py3-none-any.whl

cellgraph/core.py

@@ -0,0 +1,87 @@
+"""The core vocabulary: ``@name``, ``@after``, ``@nocache``, ``@variant``, ``@per_variant``.
+
+The parsing rules and diagnostic codes are Strata's (``annotations.py`` and
+``annotation_validation.py``), which these were ported from.
+"""
+
+from __future__ import annotations
+
+from cellgraph.effects import After, FanOut, Member, NoCache
+from cellgraph.grammar import Directive
+from cellgraph.vocabulary import Annotation, AnnotationError, flag, mark_stacked, scalar
+
+
+def _parse_after(directives: list[Directive]) -> list[str]:
+    """One edge per whitespace-separated id; lines stack, and a repeated id counts once."""
+    ids: list[str] = []
+    for directive in directives:
+        if not directive.value:
+            raise AnnotationError("`@after` needs a cell id", line=directive.line)
+        for token in directive.value.split():
+            token = token.strip().rstrip(",")
+            if token and token not in ids:
+                ids.append(token)
+    return ids
+
+
+mark_stacked(_parse_after)
+
+
+def _parse_variant(directives: list[Directive]) -> tuple[str, str]:
+    """``# @variant <group> <name>``, both identifiers; the last line wins."""
+    for directive in directives:
+        parts = directive.value.split()
+        if len(parts) != 2 or not all(part.isidentifier() for part in parts):
+            raise AnnotationError(
+                f"`@variant {directive.value}`: expected `@variant <group> <name>`, "
+                "both Python identifiers",
+                code="variant_malformed",
+                line=directive.line,
+            )
+    group, name = directives[-1].value.split()
+    return group, name
+
+
+def _parse_per_variant(directives: list[Directive]) -> str | None:
+    """``# @per_variant`` (the single sweep group read) or ``# @per_variant <group>``."""
+    for directive in directives:
+        tokens = directive.value.split()
+        if len(tokens) > 1 or (tokens and not tokens[0].isidentifier()):
+            raise AnnotationError(
+                f"`@per_variant {directive.value}`: expected at most one group name, "
+                "a Python identifier",
+                line=directive.line,
+            )
+    tokens = directives[-1].value.split()
+    return tokens[0] if tokens else None
+
+
+def core_annotations() -> list[Annotation]:
+    return [
+        Annotation("name", parse=scalar(str), in_key=False),
+        Annotation(
+            "after",
+            parse=_parse_after,
+            in_key=False,
+            effects=lambda ids: [After(ids)],
+        ),
+        Annotation(
+            "nocache",
+            parse=flag(),
+            in_key=False,
+            effects=lambda on: [NoCache()] if on else [],
+        ),
+        Annotation(
+            "variant",
+            parse=_parse_variant,
+            in_key=False,
+            effects=lambda value: [Member(group=value[0], name=value[1])],
+        ),
+        # The group decides which upstream binds a scalar, so it is in the key; a
+        # bare ``@per_variant`` is present with the value None.
+        Annotation(
+            "per_variant",
+            parse=_parse_per_variant,
+            effects=lambda group: [FanOut(group)],
+        ),
+    ]

cellgraph/diagnostics.py

@@ -0,0 +1,26 @@
+"""What analysis says about a cell: a code, a severity and where."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class Severity(StrEnum):
+    """An ``ERROR`` keeps the cell, and every cell that depends on it, from planning."""
+
+    ERROR = "error"
+    WARN = "warn"
+    INFO = "info"
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """One finding. ``annotation`` is the directive key it is about, if any."""
+
+    code: str
+    severity: Severity
+    message: str
+    cell: str | None = None
+    annotation: str | None = None
+    line: int | None = None

cellgraph/effects.py

@@ -0,0 +1,127 @@
+"""The ten effects an annotation can have on the graph (design 4.1).
+
+The set is closed: ``analyze`` applies these and never interprets a host's
+annotation beyond them. Names are tuples, so an effect is hashable and compares
+by value.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+def _names(names: Any) -> tuple[str, ...]:
+    return (names,) if isinstance(names, str) else tuple(names)
+
+
+@dataclass(frozen=True, init=False)
+class Binds:
+    """Names put in the namespace before the body runs; never resolved to an upstream."""
+
+    names: tuple[str, ...]
+
+    def __init__(self, names: Any) -> None:
+        object.__setattr__(self, "names", _names(names))
+
+
+@dataclass(frozen=True, init=False)
+class Defines:
+    """Outputs the body does not assign."""
+
+    names: tuple[str, ...]
+
+    def __init__(self, names: Any) -> None:
+        object.__setattr__(self, "names", _names(names))
+
+
+@dataclass(frozen=True, init=False)
+class Reads:
+    """References the body's analysis cannot see.
+
+    With ``even_if_defined=False`` a name the cell defines is not added.
+    """
+
+    names: tuple[str, ...]
+    even_if_defined: bool
+
+    def __init__(self, names: Any, even_if_defined: bool = False) -> None:
+        object.__setattr__(self, "names", _names(names))
+        object.__setattr__(self, "even_if_defined", even_if_defined)
+
+
+@dataclass(frozen=True, init=False)
+class Keeps:
+    """Outputs kept with no downstream reader."""
+
+    names: tuple[str, ...]
+
+    def __init__(self, names: Any) -> None:
+        object.__setattr__(self, "names", _names(names))
+
+
+@dataclass(frozen=True, init=False)
+class After:
+    """Ordering edges from these cells, with no variable."""
+
+    cell_ids: tuple[str, ...]
+
+    def __init__(self, cell_ids: Any) -> None:
+        object.__setattr__(self, "cell_ids", _names(cell_ids))
+
+
+@dataclass(frozen=True)
+class Seeds:
+    """Resolve ``name`` from ``cell_id``, in place of its latest earlier producer."""
+
+    cell_id: str
+    name: str
+
+
+@dataclass(frozen=True)
+class Member:
+    """Member ``name`` of variant group ``group``."""
+
+    group: str
+    name: str
+
+
+@dataclass(frozen=True)
+class FanOut:
+    """Run once per member of ``group``, or of the single sweep group the cell reads."""
+
+    group: str | None = None
+
+
+@dataclass(frozen=True)
+class Input:
+    """An external input the host resolves.
+
+    ``name`` is the binding name (or another stable name); ``spec`` is whatever the
+    host's resolver for ``kind`` needs. One input per ``(kind, name)`` in a cell.
+    """
+
+    kind: str
+    name: str
+    spec: Any = field(default=None, compare=False)
+
+
+@dataclass(frozen=True)
+class NoCache:
+    """Never served from cache; a downstream key follows this cell's bytes."""
+
+
+Effect = Binds | Defines | Reads | Keeps | After | Seeds | Member | FanOut | Input | NoCache
+
+EFFECT_TYPES: tuple[type, ...] = (
+    Binds,
+    Defines,
+    Reads,
+    Keeps,
+    After,
+    Seeds,
+    Member,
+    FanOut,
+    Input,
+    NoCache,
+)

cellgraph/grammar.py

@@ -0,0 +1,144 @@
+"""The ``# @key value`` directive block at the top of a cell.
+
+One object holds the whole syntax: finding the leading block, reading a directive,
+stripping the block, and setting or removing a directive, so editing round-trips
+with parsing. A second syntax (Quarto's ``#| key: value``) would be another
+``Grammar``.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Container, Iterator
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Directive:
+    """One ``# @key value`` line: its lower-cased key, its value, and its 1-based line."""
+
+    key: str
+    value: str
+    line: int
+
+
+class Grammar:
+    """The ``# @key value`` syntax of a cell's leading comment block."""
+
+    directive_re = re.compile(r"^#\s*@(\w+)\s*(.*?)\s*$")
+
+    def block(self, source: str) -> Iterator[tuple[int, str]]:
+        """Yield ``(1-based lineno, raw_line)`` for the leading comment block.
+
+        The block is the first contiguous run of blank and ``#`` lines; blank lines
+        are not yielded.
+        """
+        for lineno, line in enumerate(source.splitlines(), start=1):
+            stripped = line.strip()
+            if not stripped:
+                continue
+            if not stripped.startswith("#"):
+                break
+            yield lineno, line
+
+    def parse_directive(self, line: str) -> tuple[str, str] | None:
+        """Match one ``# @key value`` line and return ``(key.lower(), value)``, or ``None``."""
+        match = self.directive_re.match(line.strip())
+        if not match:
+            return None
+        return match.group(1).lower(), match.group(2).strip()
+
+    def directives(self, source: str, keys: Container[str] | None = None) -> list[Directive]:
+        """Every directive of the leading block, in source order; only *keys* when given."""
+        found = []
+        for lineno, line in self.block(source):
+            parsed = self.parse_directive(line)
+            if parsed is not None and (keys is None or parsed[0] in keys):
+                found.append(Directive(key=parsed[0], value=parsed[1], line=lineno))
+        return found
+
+    def strip(self, source: str) -> str:
+        """Return *source* with the leading comment block removed."""
+        lines = source.splitlines()
+        for i, line in enumerate(lines):
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            return "\n".join(lines[i:])
+        return ""
+
+    def strip_directives(self, source: str, keys: Container[str] | None = None) -> str:
+        """Return *source* without the directive lines of its leading block.
+
+        With *keys*, only those keys' lines go. Other comments stay: they are the
+        body's, for its normalizer to judge.
+        """
+        lines = source.splitlines()
+        end = self._block_end(lines)
+
+        def is_directive(line: str) -> bool:
+            parsed = self.parse_directive(line)
+            return parsed is not None and (keys is None or parsed[0] in keys)
+
+        kept = [line for i, line in enumerate(lines) if i >= end or not is_directive(line)]
+        return "\n".join(kept)
+
+    def set_directive(self, source: str, key: str, value: str) -> str:
+        """Return *source* with a single ``# @key value`` directive set.
+
+        Replaces the first ``# @key`` in the leading block and drops duplicates; when
+        absent, inserts after the last directive (or at the top).
+        """
+        key = key.lower()
+        new_line = self._format(key, value)
+        sep = self._line_sep(source)
+        lines = source.splitlines()
+        end = self._block_end(lines)
+
+        matches = [i for i in range(end) if (d := self.parse_directive(lines[i])) and d[0] == key]
+        if matches:
+            lines[matches[0]] = new_line
+            for i in reversed(matches[1:]):
+                del lines[i]
+        else:
+            directives = [i for i in range(end) if self.parse_directive(lines[i])]
+            lines.insert(directives[-1] + 1 if directives else 0, new_line)
+
+        result = sep.join(lines)
+        return result + sep if source.endswith("\n") else result
+
+    def remove_directive(self, source: str, key: str) -> str:
+        """Return *source* with every ``# @key`` directive removed from the block."""
+        key = key.lower()
+        sep = self._line_sep(source)
+        lines = source.splitlines()
+        end = self._block_end(lines)
+        kept = [
+            line
+            for i, line in enumerate(lines)
+            if not (i < end and (d := self.parse_directive(line)) is not None and d[0] == key)
+        ]
+        result = sep.join(kept)
+        return result + sep if source.endswith("\n") else result
+
+    @staticmethod
+    def _block_end(lines: list[str]) -> int:
+        """Index of the first body line: the end of the leading comment block."""
+        for i, line in enumerate(lines):
+            stripped = line.strip()
+            if stripped and not stripped.startswith("#"):
+                return i
+        return len(lines)
+
+    @staticmethod
+    def _format(key: str, value: str) -> str:
+        value = value.strip()
+        return f"# @{key} {value}" if value else f"# @{key}"
+
+    @staticmethod
+    def _line_sep(source: str) -> str:
+        """The dominant line ending, so a splice preserves CRLF vs LF."""
+        return "\r\n" if "\r\n" in source else "\n"
+
+
+GRAMMAR = Grammar()