pytest-given 0.1.0__py3-none-any.whl

pytest_given/capture/glossary.py

@@ -0,0 +1,258 @@
+"""User-facing Glossary API: id derivation, value classes, registration."""
+
+from __future__ import annotations
+
+import difflib
+from dataclasses import dataclass
+from typing import Literal
+
+from ..model import (
+    Glossary,
+    GlossaryTerm,
+    PytestGivenError,
+    SourceLocation,
+    TermId,
+    id_derive,
+)
+from .source import capture_caller_source
+
+
+def _normalize_definition(definition: str | None) -> str | None:
+    """Collapse an empty or whitespace-only definition to None so 'undefined'
+    has exactly one representation."""
+    if definition is None:
+        return None
+    stripped = definition.strip()
+    return stripped or None
+
+
+@dataclass(frozen=True)
+class TermHandle:
+    """Common base: a GlossaryTerm + back-ref to its owning Glossary."""
+
+    _term: GlossaryTerm
+    _glossary: Glossary
+
+    @property
+    def term(self) -> GlossaryTerm:
+        return self._term
+
+    @property
+    def glossary(self) -> Glossary:
+        return self._glossary
+
+    @property
+    def id(self) -> TermId:
+        return self._term.id
+
+    @property
+    def canonical(self) -> str:
+        return self._term.canonical
+
+
+@dataclass(frozen=True)
+class Actor(TermHandle):
+    def __call__(self, display: str) -> ActorInstance:
+        return ActorInstance(actor=self, display=display)
+
+    @property
+    def low(self) -> ActorInstance:
+        """Instance whose surface is the canonical term lowercased -- the common
+        mid-sentence form (``guest.low`` instead of ``guest('guest')``)."""
+        return self(self.canonical.lower())
+
+
+@dataclass(frozen=True)
+class WorkObject(TermHandle):
+    def __call__(self, display: str) -> WorkObjectInstance:
+        return WorkObjectInstance(work_object=self, display=display)
+
+    @property
+    def low(self) -> WorkObjectInstance:
+        """Instance whose surface is the canonical term lowercased -- the common
+        mid-sentence form (``room.low`` instead of ``room('room')``)."""
+        return self(self.canonical.lower())
+
+
+@dataclass(frozen=True)
+class Verb(TermHandle):
+    def __call__(self, display: str) -> InflectedVerb:
+        return InflectedVerb(verb=self, display=display)
+
+    @property
+    def low(self) -> InflectedVerb:
+        """Inflection whose surface is the canonical term lowercased -- the common
+        mid-sentence form (``book.low`` instead of ``book('book')``)."""
+        return self(self.canonical.lower())
+
+
+@dataclass(frozen=True)
+class DeferredTermInstance:
+    handle: DeferredTermHandle
+    display: str
+
+
+@dataclass(frozen=True)
+class DeferredTermHandle(TermHandle):
+    """Deferred-kind handle for a term whose kind is resolved post-collection
+    (file-glossary terms and code-glossary g(...) / g[...] terms). One type for
+    all kinds, unlike the eager Actor/WorkObject/Verb handles. Callable to
+    override display."""
+
+    def __call__(self, display: str) -> DeferredTermInstance:
+        return DeferredTermInstance(handle=self, display=display)
+
+    @property
+    def low(self) -> DeferredTermInstance:
+        """Instance whose surface is the canonical term lowercased -- the common
+        mid-sentence form (``pg['Attachment'].low`` instead of
+        ``pg['Attachment']('attachment')``)."""
+        return self(self.canonical.lower())
+
+
+def terms_match(existing: GlossaryTerm, candidate: GlossaryTerm) -> bool:
+    """Whether two terms are the same registration: kind, canonical, and
+    definition agree (`source` is intentionally excluded). Shared by the
+    code-defined (`_register_kind`) and file-backed (`FileGlossary._add_row`)
+    idempotency-and-conflict checks so the identity rule lives in one place."""
+    return (
+        existing.kind == candidate.kind
+        and existing.canonical == candidate.canonical
+        and existing.definition == candidate.definition
+    )
+
+
+@dataclass(frozen=True)
+class ActorInstance:
+    actor: Actor
+    display: str
+
+
+@dataclass(frozen=True)
+class WorkObjectInstance:
+    work_object: WorkObject
+    display: str
+
+
+@dataclass(frozen=True)
+class InflectedVerb:
+    verb: Verb
+    display: str
+
+
+def _register_kind(
+    self: Glossary,
+    kind: Literal['actor', 'object', 'verb'] | None,
+    name: str,
+    definition: str | None,
+    source: SourceLocation | None = None,
+) -> GlossaryTerm:
+    """Idempotent registration. Returns the canonical term (existing or new).
+
+    `source` is the call site of the user-facing wrapper (g.actor / g.work_object /
+    g.verb) — captured by those wrappers and threaded through. First-registration
+    wins: re-registration with matching (kind, canonical, definition) returns the
+    existing term unchanged, preserving its original `source`.
+    """
+    new = GlossaryTerm(
+        id=id_derive(name),
+        kind=kind,
+        canonical=name,
+        definition=_normalize_definition(definition),
+        source=source,
+    )
+    existing = self.get(new.id)
+    if existing is not None:
+        if terms_match(existing, new):
+            return existing
+        raise PytestGivenError(
+            f'term {name!r} (id {new.id!r}) conflicts with prior registration '
+            f'(existing: kind={existing.kind!r}, canonical={existing.canonical!r}, '
+            f'definition={existing.definition!r}; new: kind={new.kind!r}, '
+            f'canonical={new.canonical!r}, definition={new.definition!r}).'
+        )
+    self._register(new)
+    return new
+
+
+_HANDLE_BY_KIND: dict[Literal['actor', 'object', 'verb'], type[TermHandle]] = {
+    'actor': Actor,
+    'object': WorkObject,
+    'verb': Verb,
+}
+
+
+def _mint_handle(
+    glossary: Glossary,
+    kind: Literal['actor', 'object', 'verb'],
+    name: str,
+    definition: str | None,
+) -> TermHandle:
+    # skip=3: this function → kind wrapper (actor/work_object/verb) → user call site
+    source = capture_caller_source(skip=3)
+    term = _register_kind(glossary, kind, name, definition, source)
+    return _HANDLE_BY_KIND[kind](_term=term, _glossary=glossary)
+
+
+def _glossary_actor(self: Glossary, name: str, definition: str | None = None) -> Actor:
+    handle = _mint_handle(self, 'actor', name, definition)
+    assert isinstance(handle, Actor)
+    return handle
+
+
+def _glossary_work_object(
+    self: Glossary, name: str, definition: str | None = None
+) -> WorkObject:
+    handle = _mint_handle(self, 'object', name, definition)
+    assert isinstance(handle, WorkObject)
+    return handle
+
+
+def _glossary_verb(self: Glossary, name: str, definition: str | None = None) -> Verb:
+    handle = _mint_handle(self, 'verb', name, definition)
+    assert isinstance(handle, Verb)
+    return handle
+
+
+def deferred_handle_or_raise(
+    glossary: Glossary,
+    name: str,
+    handle_cache: dict[TermId, DeferredTermHandle] | None = None,
+) -> DeferredTermHandle:
+    """Name-based, case-insensitive get-only lookup returning a deferred handle.
+    Raises PytestGivenError with a did-you-mean hint on an unknown name. Shared
+    by the code glossary's g[...] / g(...) lookups and FileGlossary."""
+    term_id = id_derive(name)
+    if handle_cache is not None and term_id in handle_cache:
+        return handle_cache[term_id]
+    term = glossary.get(term_id)
+    if term is None:
+        close = difflib.get_close_matches(
+            name, [candidate.canonical for candidate in glossary.terms], n=3
+        )
+        hint = f' Did you mean: {", ".join(close)}?' if close else ''
+        raise PytestGivenError(f'no glossary term named {name!r}.{hint}')
+    handle = DeferredTermHandle(_term=term, _glossary=glossary)
+    if handle_cache is not None:
+        handle_cache[term_id] = handle
+    return handle
+
+
+def _glossary_call(
+    self: Glossary, name: str, definition: str | None = None
+) -> DeferredTermHandle:
+    # skip=2: this function → user call site
+    source = capture_caller_source(skip=2)
+    term = _register_kind(self, None, name, definition, source)
+    return DeferredTermHandle(_term=term, _glossary=self)
+
+
+def _glossary_getitem(self: Glossary, name: str) -> DeferredTermHandle:
+    return deferred_handle_or_raise(self, name)
+
+
+Glossary.actor = _glossary_actor  # type: ignore[method-assign]
+Glossary.work_object = _glossary_work_object  # type: ignore[method-assign]
+Glossary.verb = _glossary_verb  # type: ignore[method-assign]
+Glossary.__call__ = _glossary_call  # type: ignore[method-assign]
+Glossary.__getitem__ = _glossary_getitem  # type: ignore[method-assign]

pytest_given/capture/kind_inference.py

@@ -0,0 +1,102 @@
+"""Post-collection inference of file-glossary term kinds from story usage.
+
+A term referenced by an activity path gets a kind from the slot positions it
+appears in across all stories: 0 → actor, odd → verb, even ≥ 2 → noun
+(actor or work object). Undeclared kinds are inferred; declared kinds are
+verified against observed positions. Conflicts raise."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import replace
+from typing import Literal
+
+from ..model import (
+    ActivityTermRef,
+    Glossary,
+    GlossaryTerm,
+    PytestGivenError,
+    Story,
+    TermId,
+)
+
+type _Kind = Literal['actor', 'object', 'verb']
+type _Slot = Literal['actor', 'verb', 'noun']
+
+
+def infer_glossary_kinds(glossary: Glossary, stories: list[Story]) -> Glossary:
+    """Return a new Glossary with each term's kind inferred/verified."""
+    stories_by_slot: dict[TermId, dict[_Slot, set[str]]] = defaultdict(
+        lambda: defaultdict(set)
+    )
+    for story in stories:
+        for activity in story.activities:
+            for activity_path in activity.paths:
+                for position, part in enumerate(activity_path.parts):
+                    if isinstance(part, ActivityTermRef):
+                        slot = _slot_for(position)
+                        stories_by_slot[part.term_id][slot].add(story.title)
+    inferred_terms = [
+        replace(term, kind=_infer_one(term, stories_by_slot.get(term.id, {})))
+        for term in glossary.terms
+    ]
+    return Glossary(terms=inferred_terms)
+
+
+def _slot_for(position: int) -> _Slot:
+    if position == 0:
+        return 'actor'
+    if position % 2 == 1:
+        return 'verb'
+    return 'noun'
+
+
+def _infer_one(
+    term: GlossaryTerm,
+    stories_by_slot: dict[_Slot, set[str]],
+) -> _Kind | None:
+    slots = set(stories_by_slot)
+    if term.kind is not None:
+        _verify_declared(term, stories_by_slot)
+        return term.kind
+    if 'verb' in slots and ('actor' in slots or 'noun' in slots):
+        other: _Slot = 'actor' if 'actor' in slots else 'noun'
+        where = _where(stories_by_slot, 'verb', other)
+        raise PytestGivenError(
+            f'term {term.canonical!r} is used in incompatible positions{where}: '
+            f'a verb slot and an actor/noun slot. Add a kind column to disambiguate.'
+        )
+    if 'verb' in slots:
+        return 'verb'
+    if 'actor' in slots:
+        return 'actor'
+    if 'noun' in slots:
+        return 'object'
+    return None
+
+
+def _verify_declared(
+    term: GlossaryTerm, stories_by_slot: dict[_Slot, set[str]]
+) -> None:
+    declared = term.kind
+    slots = set(stories_by_slot)
+    if 'verb' in slots and declared != 'verb':
+        _raise_declared(term, 'verb slot', _where(stories_by_slot, 'verb'))
+    if 'actor' in slots and declared != 'actor':
+        _raise_declared(term, 'actor slot', _where(stories_by_slot, 'actor'))
+    if 'noun' in slots and declared == 'verb':
+        _raise_declared(term, 'noun slot', _where(stories_by_slot, 'noun'))
+
+
+def _raise_declared(term: GlossaryTerm, slot: str, where: str) -> None:
+    raise PytestGivenError(
+        f'term {term.canonical!r} is declared kind {term.kind!r} but appears in '
+        f'a {slot}{where}, which is incompatible.'
+    )
+
+
+def _where(stories_by_slot: dict[_Slot, set[str]], *slots: _Slot) -> str:
+    """Story titles for just the named slots, so a conflict names only the
+    stories that actually contributed the offending positions."""
+    titles = sorted({title for slot in slots for title in stories_by_slot[slot]})
+    return f' (in {", ".join(titles)})' if titles else ''

pytest_given/capture/markdown_glossary.py

@@ -0,0 +1,147 @@
+"""Minimal GFM pipe-table parser for file-backed glossaries.
+
+Parses every pipe table in a Markdown document into GlossaryRow records.
+Not a full CommonMark parser — it recognises pipe tables, honours `\\|`
+escapes, and skips fenced code blocks. Column selection accepts a header
+name (case-insensitive) or a 0-based index.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..model import PytestGivenError
+
+type ColumnSpec = int | str
+
+_SEPARATOR_CELL = re.compile(r'^:?-+:?$')
+_FENCE = re.compile(r'^\s*(```|~~~)')
+_SPLIT_ON_UNESCAPED_PIPE = re.compile(r'(?<!\\)\|')
+
+# Unwrap inline emphasis so a term cell written as `**Scenario**` yields the
+# plain canonical `Scenario`. Only paired markers are unwrapped; a lone
+# underscore inside an identifier (e.g. work_object) is left untouched.
+_EMPHASIS = re.compile(r'\*\*(.+?)\*\*|__(.+?)__|\*(.+?)\*|`(.+?)`')
+
+
+@dataclass(frozen=True)
+class GlossaryRow:
+    term: str
+    definition: str
+    kind: str | None
+    line: int
+
+
+def parse_glossary_tables(
+    text: str,
+    *,
+    term_column: ColumnSpec,
+    description_column: ColumnSpec,
+    kind_column: ColumnSpec | None,
+) -> list[GlossaryRow]:
+    rows: list[GlossaryRow] = []
+    lines = text.splitlines()
+    in_code = False
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        if _FENCE.match(line):
+            in_code = not in_code
+            index += 1
+            continue
+        if in_code or not _is_table_row(line):
+            index += 1
+            continue
+        if index + 1 >= len(lines) or not _is_separator_row(lines[index + 1]):
+            index += 1
+            continue
+        header = _split_row(line)
+        term_idx = _resolve_column(term_column, header)
+        desc_idx = _resolve_column(description_column, header)
+        kind_idx = (
+            _resolve_column(kind_column, header) if kind_column is not None else None
+        )
+        index += 2  # consume header + separator
+        required_width = (
+            max(term_idx, desc_idx, kind_idx if kind_idx is not None else -1) + 1
+        )
+        while (
+            index < len(lines)
+            and _is_table_row(lines[index])
+            and not _FENCE.match(lines[index])
+        ):
+            cells = _split_row(lines[index])
+            if len(cells) < required_width:
+                raise PytestGivenError(
+                    f'data row at line {index + 1} has {len(cells)} column(s), '
+                    f'but {required_width} column(s) required.'
+                )
+            kind_value = (
+                _strip_emphasis(cells[kind_idx].strip()) if kind_idx is not None else ''
+            )
+            rows.append(
+                GlossaryRow(
+                    term=_strip_emphasis(cells[term_idx]),
+                    definition=cells[desc_idx],
+                    kind=kind_value or None,
+                    line=index + 1,
+                )
+            )
+            index += 1
+    if not rows:
+        raise PytestGivenError(
+            'found no Markdown pipe table in the glossary file (a table needs a '
+            'header row followed by a |---|---| separator row).'
+        )
+    return rows
+
+
+def _strip_emphasis(cell: str) -> str:
+    """Unwrap inline Markdown emphasis (**bold**, *italic*, `code`, __bold__)
+    from a cell, leaving its text content. Applied to term and kind cells so a
+    glossary written with emphasised term names renders clean pills."""
+    prev = None
+    text = cell
+    while prev != text:
+        prev = text
+        text = _EMPHASIS.sub(
+            lambda m: next(g for g in m.groups() if g is not None), text
+        )
+    return text.strip()
+
+
+def _is_table_row(line: str) -> bool:
+    return '|' in line
+
+
+def _is_separator_row(line: str) -> bool:
+    cells = _split_row(line)
+    return len(cells) > 0 and all(_SEPARATOR_CELL.match(cell) for cell in cells)
+
+
+def _split_row(line: str) -> list[str]:
+    stripped = line.strip()
+    if stripped.startswith('|'):
+        stripped = stripped[1:]
+    if stripped.endswith('|') and not stripped.endswith('\\|'):
+        stripped = stripped[:-1]
+    cells = _SPLIT_ON_UNESCAPED_PIPE.split(stripped)
+    return [cell.replace('\\|', '|').strip() for cell in cells]
+
+
+def _resolve_column(spec: ColumnSpec, header: list[str]) -> int:
+    if isinstance(spec, int):
+        if 0 <= spec < len(header):
+            return spec
+        raise PytestGivenError(
+            f'column index {spec} is out of range for a table with '
+            f'{len(header)} column(s): {header!r}.'
+        )
+    lowered = [cell.lower() for cell in header]
+    try:
+        return lowered.index(spec.lower())
+    except ValueError:
+        raise PytestGivenError(
+            f'column {spec!r} not found in table header {header!r}.'
+        ) from None