dstrack 0.1.0__py3-none-any.whl

dstrack/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from . import _logging as _logging
+
+try:
+    __version__ = version("dstrack")
+except PackageNotFoundError:
+    __version__ = "unknown"

dstrack/_benchmark/__init__.py

@@ -0,0 +1,54 @@
+"""Benchmark for dstrack's snapshot creation pipeline.
+
+Generates a synthetic CSV in a temporary directory, then times how long it
+takes to build snapshot metadata and statistics for it, alongside a summary of
+the environment the benchmark ran in and a call tree of dstrack's own methods.
+
+Layers
+------
+[dstrack._benchmark._synthetic][]
+    Describes and writes the synthetic dataset.
+
+[dstrack._benchmark._runner][]
+    Runs the snapshot pipeline against it and times each phase.
+
+[dstrack._benchmark._profiling][]
+    Reduces the ``cProfile`` run to a call tree of dstrack's own methods.
+
+[dstrack._benchmark._environment][]
+    Describes the machine the benchmark ran on.
+
+[dstrack._benchmark._report][], [dstrack._benchmark._cli][]
+    Render runs to a console, and wire the whole thing to ``dstrack-benchmark``.
+"""
+
+from ._cli import app
+from ._environment import EnvironmentInfo, collect_environment_info
+from ._profiling import CallGraph, CallNode, CallScope
+from ._report import ConsoleReporter
+from ._runner import (
+    BenchmarkObserver,
+    BenchmarkResult,
+    BenchmarkRun,
+    BenchmarkRunner,
+    SilentObserver,
+)
+from ._synthetic import SyntheticColumn, SyntheticCsvSpec, write_synthetic_csv
+
+__all__ = [
+    "BenchmarkObserver",
+    "BenchmarkResult",
+    "BenchmarkRun",
+    "BenchmarkRunner",
+    "CallGraph",
+    "CallNode",
+    "CallScope",
+    "ConsoleReporter",
+    "EnvironmentInfo",
+    "SilentObserver",
+    "SyntheticColumn",
+    "SyntheticCsvSpec",
+    "app",
+    "collect_environment_info",
+    "write_synthetic_csv",
+]

dstrack/_benchmark/_cli.py

@@ -0,0 +1,114 @@
+"""Command-line entry point for the snapshot benchmark."""
+
+import shutil
+import tempfile
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from dstrack._benchmark._report import ConsoleReporter
+from dstrack._benchmark._runner import BenchmarkRunner
+from dstrack._benchmark._synthetic import SyntheticCsvSpec
+
+app = typer.Typer(
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+    help="Benchmark dstrack's snapshot creation pipeline against a synthetic CSV.",
+)
+
+_DEFAULTS = SyntheticCsvSpec()
+
+
+@app.callback()
+def _main() -> None:
+    """Keep ``run`` a named subcommand so a bare invocation shows help.
+
+    Typer promotes a lone command to the top level, which quietly discards
+    ``no_args_is_help``; an explicit callback keeps the command group intact so
+    running ``dstrack-benchmark`` with no arguments prints help instead of
+    silently kicking off a full-size benchmark.
+    """
+
+
+@contextmanager
+def _workspace(reporter: ConsoleReporter, *, keep_csv: bool) -> Iterator[Path]:
+    """Yield a path for the synthetic CSV, discarding it unless ``keep_csv``."""
+    tmp_dir = Path(tempfile.mkdtemp(prefix="dstrack-benchmark-"))
+    csv_path = tmp_dir / "synthetic_dataset.csv"
+    try:
+        yield csv_path
+    finally:
+        if keep_csv:
+            reporter.csv_kept(csv_path)
+        else:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+@app.command(help="Generate a synthetic CSV and benchmark snapshot creation on it.")
+def run(
+    rows: Annotated[
+        int, typer.Option(min=0, help="Number of data rows to generate.")
+    ] = _DEFAULTS.num_rows,
+    numeric_cols: Annotated[
+        int, typer.Option(min=0, help="Number of numeric (float) columns.")
+    ] = _DEFAULTS.num_numeric_cols,
+    string_cols: Annotated[
+        int, typer.Option(min=0, help="Number of string columns.")
+    ] = _DEFAULTS.num_string_cols,
+    datetime_cols: Annotated[
+        int, typer.Option(min=0, help="Number of datetime columns.")
+    ] = _DEFAULTS.num_datetime_cols,
+    bool_cols: Annotated[
+        int, typer.Option(min=0, help="Number of boolean columns.")
+    ] = _DEFAULTS.num_bool_cols,
+    null_rate: Annotated[
+        float,
+        typer.Option(min=0.0, max=1.0, help="Fraction of non-id cells left null."),
+    ] = _DEFAULTS.null_rate,
+    seed: Annotated[
+        int, typer.Option(help="Random seed for reproducible synthetic data.")
+    ] = _DEFAULTS.seed,
+    keep_csv: Annotated[
+        bool,
+        typer.Option(
+            help="Keep the generated CSV instead of deleting it after the run."
+        ),
+    ] = False,
+    profile: Annotated[
+        bool,
+        typer.Option(
+            help="Profile dstrack's own methods while building the snapshot. "
+            "Adds cProfile overhead to the reported metadata/stats timings."
+        ),
+    ] = True,
+    profile_limit: Annotated[
+        int,
+        typer.Option(
+            min=0,
+            help="Max number of child methods shown under each node of the "
+            "profile call tree, ranked by cumulative time.",
+        ),
+    ] = 20,
+) -> None:
+    spec = SyntheticCsvSpec(
+        num_rows=rows,
+        num_numeric_cols=numeric_cols,
+        num_string_cols=string_cols,
+        num_datetime_cols=datetime_cols,
+        num_bool_cols=bool_cols,
+        null_rate=null_rate,
+        seed=seed,
+    )
+    reporter = ConsoleReporter()
+    runner = BenchmarkRunner(spec, observer=reporter, profile=profile)
+
+    with _workspace(reporter, keep_csv=keep_csv) as csv_path:
+        benchmark_run = runner.run(csv_path)
+        reporter.report(benchmark_run, profile_limit=profile_limit)
+
+
+if __name__ == "__main__":
+    app()

dstrack/_benchmark/_environment.py

@@ -0,0 +1,144 @@
+"""Describes the machine and runtime a benchmark executed under.
+
+Hardware facts have no portable API, so each is read by a per-OS probe.  Every
+probe is best-effort: it returns ``None`` (or raises, which
+[_attempt()][dstrack._benchmark._environment._attempt] swallows) when the
+platform will not give up the answer, and the caller falls back to something
+always available.
+"""
+
+import os
+import platform
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypeVar
+
+from dstrack import __version__
+
+T = TypeVar("T")
+
+_PROBE_TIMEOUT_SECONDS = 5
+
+
+@dataclass(frozen=True)
+class EnvironmentInfo:
+    """Snapshot of the machine and runtime a benchmark executed under."""
+
+    os_name: str
+    os_release: str
+    os_version: str
+    machine: str
+    cpu_model: str
+    cpu_count: int | None
+    total_memory_gb: float | None
+    python_implementation: str
+    python_version: str
+    dstrack_version: str
+
+
+def _attempt(probe: Callable[[], T | None]) -> T | None:
+    """Run a probe, returning ``None`` if the platform refuses to answer."""
+    try:
+        return probe()
+    except (OSError, subprocess.SubprocessError, ValueError):
+        return None
+
+
+def _command_output(*args: str) -> str:
+    """Gets the stdout of a command, raising if it fails or times out."""
+    result = subprocess.run(
+        args,
+        capture_output=True,
+        text=True,
+        timeout=_PROBE_TIMEOUT_SECONDS,
+        check=True,
+    )
+    return result.stdout.strip()
+
+
+def _first_matching_line(path: Path, prefix: str) -> str | None:
+    """First line of ``path`` starting with ``prefix`` (case-insensitive)."""
+    if not path.is_file():
+        return None
+    for line in path.read_text().splitlines():
+        if line.lower().startswith(prefix.lower()):
+            return line
+    return None
+
+
+def _linux_cpu_model() -> str | None:
+    line = _first_matching_line(Path("/proc/cpuinfo"), "model name")
+    return line.split(":", 1)[1].strip() if line else None
+
+
+def _darwin_cpu_model() -> str | None:
+    return _command_output("sysctl", "-n", "machdep.cpu.brand_string")
+
+
+def _windows_cpu_model() -> str | None:
+    lines = [
+        line.strip()
+        for line in _command_output("wmic", "cpu", "get", "name").splitlines()
+        if line.strip()
+    ]
+    return lines[1] if len(lines) >= 2 else None
+
+
+def _linux_total_memory() -> int | None:
+    line = _first_matching_line(Path("/proc/meminfo"), "MemTotal:")
+    return int(line.split()[1]) * 1024 if line else None
+
+
+def _darwin_total_memory() -> int | None:
+    return int(_command_output("sysctl", "-n", "hw.memsize"))
+
+
+def _sysconf_total_memory() -> int | None:
+    """Page size times page count, on any POSIX platform exposing sysconf."""
+    if not hasattr(os, "sysconf") or "SC_PAGE_SIZE" not in os.sysconf_names:
+        return None
+    return os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
+
+
+_CPU_MODEL_PROBES: dict[str, Callable[[], str | None]] = {
+    "Linux": _linux_cpu_model,
+    "Darwin": _darwin_cpu_model,
+    "Windows": _windows_cpu_model,
+}
+
+_TOTAL_MEMORY_PROBES: dict[str, Callable[[], int | None]] = {
+    "Linux": _linux_total_memory,
+    "Darwin": _darwin_total_memory,
+}
+
+
+def _cpu_model() -> str:
+    """Best-effort human-readable CPU model string for the current machine."""
+    probe = _CPU_MODEL_PROBES.get(platform.system())
+    model = _attempt(probe) if probe is not None else None
+    return model or platform.processor() or platform.machine() or "unknown"
+
+
+def _total_memory_bytes() -> int | None:
+    """Best-effort total physical memory in bytes, or None if it can't be read."""
+    probe = _TOTAL_MEMORY_PROBES.get(platform.system(), _sysconf_total_memory)
+    return _attempt(probe)
+
+
+def collect_environment_info() -> EnvironmentInfo:
+    """Collect OS, hardware, and runtime details describing the current machine."""
+    total_memory = _total_memory_bytes()
+    return EnvironmentInfo(
+        os_name=platform.system(),
+        os_release=platform.release(),
+        os_version=platform.version(),
+        machine=platform.machine(),
+        cpu_model=_cpu_model(),
+        cpu_count=os.cpu_count(),
+        total_memory_gb=total_memory / (1024**3) if total_memory is not None else None,
+        python_implementation=platform.python_implementation(),
+        python_version=platform.python_version(),
+        dstrack_version=__version__,
+    )

dstrack/_benchmark/_profiling.py

@@ -0,0 +1,207 @@
+"""Reduces a ``cProfile`` run to a call tree of dstrack's own methods.
+
+This module is pure model: it turns raw ``pstats`` frames into
+[CallNode][dstrack._benchmark._profiling.CallNode] trees and knows nothing about
+how they are displayed. Rendering lives in [dstrack._benchmark._report][].
+"""
+
+import cProfile
+import pstats
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TypeAlias
+
+# (filename, lineno, funcname) - the key pstats uses to identify a profiled frame.
+FrameKey: TypeAlias = tuple[str, int, str]
+# (primitive_calls, total_calls, total_time, cumulative_time)
+_FrameTotals: TypeAlias = tuple[int, int, float, float]
+# What pstats.Stats.stats maps each frame to: its totals plus its callers.
+_RawStats: TypeAlias = dict[
+    FrameKey, tuple[int, int, float, float, dict[FrameKey, _FrameTotals]]
+]
+
+
+@dataclass(frozen=True)
+class CallScope:
+    """The source files whose profiled frames are worth reporting.
+
+    A frame is in scope when it lives under ``root`` and under none of the
+    ``exclude`` paths, which keeps the tree focused on the code being measured
+    instead of the interpreter and the benchmark harness itself.
+
+    Attributes:
+        root: Directory every reported frame must live under.
+        exclude: Sub-directories of ``root`` to leave out.
+    """
+
+    root: Path
+    exclude: tuple[Path, ...] = ()
+
+    def contains(self, filename: str) -> bool:
+        """True if frames from ``filename`` belong in the call tree."""
+        try:
+            resolved = Path(filename).resolve()
+        except OSError:
+            return False
+        if not resolved.is_relative_to(self.root):
+            return False
+        return not any(resolved.is_relative_to(path) for path in self.exclude)
+
+    def location(self, filename: str, lineno: int) -> str:
+        """Render a frame's source location relative to ``root``."""
+        return f"{Path(filename).resolve().relative_to(self.root)}:{lineno}"
+
+
+def dstrack_scope() -> CallScope:
+    """Scope covering dstrack's own code, minus this benchmark package."""
+    benchmark_package = Path(__file__).resolve().parent
+    return CallScope(root=benchmark_package.parent, exclude=(benchmark_package,))
+
+
+@dataclass(frozen=True)
+class CallNode:
+    """One method in the call tree, with the callees it was measured calling.
+
+    Attributes:
+        funcname: Name of the profiled function.
+        location: Source location, relative to the scope root.
+        num_calls: Total number of calls, including recursive ones.
+        total_seconds: Time spent in the function itself.
+        cumulative_seconds: Time spent in the function and everything it called.
+        children: Callees, ordered by cumulative time, descending.
+        hidden_children: Callees omitted to respect the tree's child limit.
+        recursive: True if this node already appears higher up the same path,
+            in which case its callees are not expanded again.
+    """
+
+    funcname: str
+    location: str
+    num_calls: int
+    total_seconds: float
+    cumulative_seconds: float
+    children: tuple["CallNode", ...] = ()
+    hidden_children: int = 0
+    recursive: bool = False
+
+
+@dataclass
+class CallGraph:
+    """Caller/callee edges among the profiled frames that fall within a scope.
+
+    ``pstats`` records, for every frame, the frames that called it.  This
+    inverts those edges so a method that calls other in-scope methods (e.g.
+    [StatsComputer.compute()][dstrack.snapshot._stats.StatsComputer.compute]
+    calling ``_build_dataset_stats``) becomes their parent, then projects the
+    result into trees rooted at the methods nothing in scope called.
+    """
+
+    _scope: CallScope
+    _totals: dict[FrameKey, _FrameTotals] = field(default_factory=dict)
+    _children: dict[FrameKey, list[FrameKey]] = field(default_factory=dict)
+    _roots: list[FrameKey] = field(default_factory=list)
+
+    @classmethod
+    def from_profile(cls, profiler: cProfile.Profile, scope: CallScope) -> "CallGraph":
+        """Build the in-scope call graph of a profiler that has finished running."""
+        raw: _RawStats = pstats.Stats(profiler).stats  # type: ignore[attr-defined]
+        graph = cls(_scope=scope)
+        frames = {key for key in raw if scope.contains(key[0])}
+        callees: set[FrameKey] = set()
+        entrypoints: set[FrameKey] = set()
+
+        for key in frames:
+            primitive_calls, num_calls, total_time, cumulative_time, callers = raw[key]
+            graph._totals[key] = (
+                primitive_calls,
+                num_calls,
+                total_time,
+                cumulative_time,
+            )
+            for caller in callers:
+                if caller in frames:
+                    graph._children.setdefault(caller, []).append(key)
+                    callees.add(key)
+                else:
+                    entrypoints.add(key)
+
+        # A frame is a root if nothing in scope called it, or if it was also
+        # entered from outside the scope.  The latter keeps external entry
+        # points into a recursive component (f -> g -> f) as roots, which
+        # ``frames - callees`` alone would drop, leaving the tree empty.
+        graph._roots = graph._by_cumulative((frames - callees) | entrypoints)
+        return graph
+
+    @property
+    def is_empty(self) -> bool:
+        """True if the profiler captured no in-scope frames at all."""
+        return not self._totals
+
+    def trees(self, *, max_children: int) -> list[CallNode]:
+        """Project the graph into call trees, hottest root first.
+
+        Args:
+            max_children: Maximum callees expanded under each node, ranked by
+                cumulative time.  The rest are counted in ``hidden_children``.
+
+        Raises:
+            ValueError: If ``max_children`` is negative, which would slice the
+                callee list from the end rather than cap it as documented.
+        """
+        if max_children < 0:
+            raise ValueError(f"max_children must be >= 0, got {max_children}")
+        return [
+            self._expand(root, ancestors=frozenset({root}), max_children=max_children)
+            for root in self._roots
+        ]
+
+    def _by_cumulative(self, keys: Iterable[FrameKey]) -> list[FrameKey]:
+        return sorted(keys, key=lambda key: self._totals[key][3], reverse=True)
+
+    def _expand(
+        self,
+        key: FrameKey,
+        *,
+        ancestors: frozenset[FrameKey],
+        max_children: int,
+    ) -> CallNode:
+        """Build the node for ``key``, expanding its hottest callees.
+
+        ``ancestors`` guards against (mutual) recursion: a callee already on the
+        current path is emitted as a leaf flagged ``recursive`` rather than
+        expanded again, which would otherwise never terminate.
+        """
+        callees = self._by_cumulative(self._children.get(key, []))
+        shown, hidden = callees[:max_children], callees[max_children:]
+        children = tuple(
+            self._node(child, recursive=True)
+            if child in ancestors
+            else self._expand(
+                child,
+                ancestors=ancestors | {child},
+                max_children=max_children,
+            )
+            for child in shown
+        )
+        return self._node(key, children=children, hidden_children=len(hidden))
+
+    def _node(
+        self,
+        key: FrameKey,
+        *,
+        children: tuple[CallNode, ...] = (),
+        hidden_children: int = 0,
+        recursive: bool = False,
+    ) -> CallNode:
+        filename, lineno, funcname = key
+        _primitive_calls, num_calls, total_time, cumulative_time = self._totals[key]
+        return CallNode(
+            funcname=funcname,
+            location=self._scope.location(filename, lineno),
+            num_calls=num_calls,
+            total_seconds=total_time,
+            cumulative_seconds=cumulative_time,
+            children=children,
+            hidden_children=hidden_children,
+            recursive=recursive,
+        )

dstrack/_benchmark/_report.py

@@ -0,0 +1,152 @@
+"""Renders benchmark runs to a Rich console.
+
+This is the only layer that knows what a benchmark looks like on screen.  It
+implements [BenchmarkObserver][dstrack._benchmark._runner.BenchmarkObserver], so
+the same object reports progress during a run and the tables after it.
+"""
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.table import Table
+
+from dstrack._benchmark._environment import EnvironmentInfo
+from dstrack._benchmark._profiling import CallGraph, CallNode
+from dstrack._benchmark._runner import BenchmarkResult, BenchmarkRun
+from dstrack.console import console as default_console
+
+_LAST_CONNECTOR = "└── "
+_MID_CONNECTOR = "├── "
+_LAST_GUIDE = "    "
+_MID_GUIDE = "│   "
+
+
+class ConsoleReporter:
+    """Prints a benchmark's progress and results as Rich tables.
+
+    Args:
+        console: Destination console.  Defaults to dstrack's shared console;
+            inject another to capture the output in tests.
+    """
+
+    def __init__(self, console: Console | None = None) -> None:
+        self._console = console or default_console
+
+    def generating_csv(self, path: Path, num_rows: int) -> None:
+        self._console.print(
+            f"Generating synthetic CSV at {path} ({num_rows:,} rows)..."
+        )
+
+    def building_metadata(self) -> None:
+        self._console.print("Building snapshot metadata...")
+
+    def computing_stats(self) -> None:
+        self._console.print("Computing snapshot statistics...")
+
+    def report(self, run: BenchmarkRun, *, profile_limit: int) -> None:
+        """Print the environment, the timings, and the profile call tree.
+
+        Args:
+            run: The finished benchmark run.
+            profile_limit: Max callees shown under each node of the call tree.
+        """
+        self._console.print(_environment_table(run.environment))
+        self._console.print(_results_table(run.result))
+        if run.call_graph is not None:
+            self._console.print(_call_tree_table(run.call_graph, profile_limit))
+
+    def csv_kept(self, path: Path) -> None:
+        """Report that the generated CSV was left on disk."""
+        self._console.print(f"Synthetic CSV kept at {path}")
+
+
+def _environment_table(env: EnvironmentInfo) -> Table:
+    table = Table(title="Environment")
+    table.add_column("Field")
+    table.add_column("Value")
+    table.add_row("OS", f"{env.os_name} {env.os_release}")
+    table.add_row("OS version", env.os_version)
+    table.add_row("Machine", env.machine)
+    table.add_row("CPU model", env.cpu_model)
+    table.add_row("CPU count", str(env.cpu_count) if env.cpu_count else "unknown")
+    table.add_row(
+        "Total memory",
+        f"{env.total_memory_gb:.2f} GB"
+        if env.total_memory_gb is not None
+        else "unknown",
+    )
+    table.add_row("Python", f"{env.python_implementation} {env.python_version}")
+    table.add_row("dstrack version", env.dstrack_version)
+    return table
+
+
+def _results_table(result: BenchmarkResult) -> Table:
+    table = Table(title="Snapshot benchmark")
+    table.add_column("Metric")
+    table.add_column("Value")
+    table.add_row("Rows generated", f"{result.num_rows:,}")
+    table.add_row("Columns", str(result.num_columns))
+    table.add_row("CSV size", f"{result.csv_size_bytes / (1024**2):.2f} MB")
+    table.add_row("CSV generation time", f"{result.generation_seconds:.3f} s")
+    table.add_row("Metadata build time", f"{result.metadata_seconds:.3f} s")
+    table.add_row("Stats compute time", f"{result.stats_seconds:.3f} s")
+    table.add_row("Total snapshot time", f"{result.total_snapshot_seconds:.3f} s")
+    table.add_row("Throughput", f"{result.rows_per_second:,.0f} rows/s")
+    table.add_row("schema_hash", result.schema_hash)
+    return table
+
+
+def _call_tree_table(graph: CallGraph, profile_limit: int) -> Table:
+    """Render dstrack's call tree, hottest root first.
+
+    Guide characters (``├──``, ``└──``, ``│``) are baked into the "Method" cell
+    as plain text so the Calls/Total/Cumulative columns line up as a normal
+    table regardless of tree depth.
+    """
+    table = Table(title="dstrack call tree (by cumulative time)")
+    table.add_column("Method", overflow="fold", ratio=1)
+    table.add_column("Calls", justify="right", no_wrap=True)
+    table.add_column("Total (s)", justify="right", no_wrap=True)
+    table.add_column("Cumulative (s)", justify="right", no_wrap=True)
+
+    if graph.is_empty:
+        table.add_row("(no dstrack frames captured)", "-", "-", "-")
+        return table
+
+    roots = graph.trees(max_children=profile_limit)
+    for i, root in enumerate(roots):
+        _add_node_rows(table, root, prefix="", is_last=i == len(roots) - 1)
+    return table
+
+
+def _add_node_rows(table: Table, node: CallNode, *, prefix: str, is_last: bool) -> None:
+    """Add a row for ``node`` and, recursively, for the callees under it."""
+    connector = _LAST_CONNECTOR if is_last else _MID_CONNECTOR
+    table.add_row(
+        f"{prefix}{connector}{_format_node(node)}",
+        str(node.num_calls),
+        f"{node.total_seconds:.4f}",
+        f"{node.cumulative_seconds:.4f}",
+    )
+
+    child_prefix = prefix + (_LAST_GUIDE if is_last else _MID_GUIDE)
+    for i, child in enumerate(node.children):
+        child_is_last = i == len(node.children) - 1 and not node.hidden_children
+        _add_node_rows(table, child, prefix=child_prefix, is_last=child_is_last)
+
+    if node.hidden_children:
+        table.add_row(
+            f"{child_prefix}{_LAST_CONNECTOR}[dim]... {node.hidden_children} more "
+            "(raise --profile-limit to see them)[/dim]",
+            "-",
+            "-",
+            "-",
+        )
+
+
+def _format_node(node: CallNode) -> str:
+    """Render a node's function name and source location."""
+    label = f"[bold]{node.funcname}[/bold] [dim]{node.location}[/dim]"
+    if node.recursive:
+        label += " [dim italic](recursive, not expanded)[/dim italic]"
+    return label