blockpath 0.1.0__py3-none-any.whl

blockpath/cli.py

@@ -0,0 +1,144 @@
+"""Command-line interface.
+
+    blockpath check .            static analysis; exit 0 clean, 1 findings, 2 error
+    blockpath verify -- pytest   runtime cross-check (stage 7)
+    blockpath compare            static predictions against runtime observation (stage 7)
+
+Exit codes are the contract with CI: 1 means "there are findings", which fails a build, and 2 is
+reserved for the tool itself failing so a crash is never mistaken for a clean run.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from blockpath.check import check as run_check
+from blockpath.config import DEFAULT, Config, load_config
+from blockpath.model import Severity
+from blockpath.report import render_json, render_text
+
+EXIT_CLEAN = 0
+EXIT_FINDINGS = 1
+EXIT_ERROR = 2
+
+
+@click.group()
+@click.version_option(package_name="blockpath")
+def main() -> None:
+    """Find blocking calls reachable from a coroutine, across files and modules."""
+
+
+@main.command()
+@click.argument(
+    "root",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=".",
+)
+@click.option(
+    "--strict",
+    is_flag=True,
+    help="also report blocking calls handed to an unresolved callee (BLK003)",
+)
+@click.option(
+    "--tier",
+    "tiers",
+    multiple=True,
+    type=click.Choice([s.value for s in Severity]),
+    help="oracle tiers to enable; repeatable. Default: error",
+)
+@click.option("--json", "as_json", is_flag=True, help="emit findings as JSON")
+@click.option(
+    "--no-config", is_flag=True, help="ignore [tool.blockpath] in the project's pyproject.toml"
+)
+def check(root: Path, strict: bool, tiers: tuple[str, ...], as_json: bool, no_config: bool) -> None:
+    """Statically analyse ROOT for blocking calls reachable from a coroutine."""
+    console = Console()
+    try:
+        config = DEFAULT if no_config else load_config(root)
+        config = _apply_flags(config, strict=strict, tiers=tiers)
+        result = run_check(root, config)
+    except Exception as exc:  # a crash must never be mistaken for a clean run
+        console.print(f"[bold red]blockpath failed:[/] {type(exc).__name__}: {exc}")
+        sys.exit(EXIT_ERROR)
+
+    if as_json:
+        click.echo(render_json(result, root.resolve()))
+    else:
+        render_text(result, root.resolve(), console)
+    sys.exit(EXIT_FINDINGS if result.findings else EXIT_CLEAN)
+
+
+def _apply_flags(config: Config, *, strict: bool, tiers: tuple[str, ...]) -> Config:
+    if strict:
+        config = replace(config, strict=True)
+    if tiers:
+        config = replace(config, enabled_tiers=frozenset(Severity(t) for t in tiers))
+    return config
+
+
+@main.command(context_settings={"ignore_unknown_options": True})
+@click.argument("command", nargs=-1, required=True)
+@click.option("--root", type=click.Path(exists=True, file_okay=False, path_type=Path), default=".")
+@click.option(
+    "--out",
+    type=click.Path(path_type=Path),
+    default=Path("observed.json"),
+    help="where to write the observations",
+)
+def verify(command: tuple[str, ...], root: Path, out: Path) -> None:
+    """Run COMMAND with the monitor attached and record what ran on the loop.
+
+    Example: blockpath verify -- pytest -q
+    """
+    from blockpath.runtime.verify import run_verify
+
+    console = Console()
+    try:
+        result = run_verify(command, root, out.resolve())
+    except Exception as exc:  # a crash must never be mistaken for a clean run
+        console.print(f"[bold red]blockpath verify failed:[/] {type(exc).__name__}: {exc}")
+        sys.exit(EXIT_ERROR)
+    console.print(
+        f"observed [bold]{result.observed}[/] project function(s) running on the loop "
+        f"-> {result.observations_path}"
+    )
+    sys.exit(result.exit_code)
+
+
+@main.command()
+@click.option("--root", type=click.Path(exists=True, file_okay=False, path_type=Path), default=".")
+@click.option(
+    "--observed",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=Path("observed.json"),
+)
+def compare(root: Path, observed: Path) -> None:
+    """Compare static findings against what `verify` actually observed."""
+    from blockpath.runtime.verify import compare as run_compare
+    from blockpath.runtime.verify import load_observations
+
+    console = Console()
+    try:
+        comparison = run_compare(root, load_observations(observed), load_config(root))
+    except Exception as exc:  # a crash must never be mistaken for a clean run
+        console.print(f"[bold red]blockpath compare failed:[/] {type(exc).__name__}: {exc}")
+        sys.exit(EXIT_ERROR)
+
+    console.print(f"confirmed by the runtime : {len(comparison.confirmed)}")
+    console.print(f"never exercised by tests : {len(comparison.unexercised)}")
+    console.print(f"missed by static analysis: {len(comparison.missed)}")
+    for path, name in comparison.missed:
+        console.print(f"  [yellow]missed[/] {path}::{name}")
+    bound = comparison.recall_lower_bound
+    if bound is not None:
+        console.print(f"\nrecall lower bound: [bold]{bound:.0%}[/]")
+    console.print(
+        "[dim]A lower bound only: the runtime sees just the paths the tests executed, so it can "
+        "prove a miss but never completeness, and it says nothing about precision.[/]"
+    )
+    sys.exit(EXIT_FINDINGS if comparison.missed else EXIT_CLEAN)

blockpath/collect.py

@@ -0,0 +1,206 @@
+"""Layer 1: walk a project tree and parse every module, without importing a line of it.
+
+``collect`` yields a :class:`Module` per parseable ``.py`` file, plus the alias map the resolver
+needs -- the dotted names by which one module can import another. Two things make this more than
+a glob:
+
+* **It never executes the target.** Everything downstream works from the AST. A project that
+  raises on import, or needs a database to import, is analysed all the same.
+* **It resolves a file to the name(s) other files import it by.** A file at ``src/app/geo.py``
+  is imported as ``app.geo`` (src-layout), and a package ``app/`` re-exports through its
+  ``__init__``. Both the src-stripped canonical name and the walk-up-through-``__init__`` name
+  are registered, so an import written either way resolves. When two files claim the same name,
+  the name is marked ambiguous and the resolver refuses to guess which one an import meant.
+
+Ignored paths (``.gitignore`` plus a default set of vendored/generated dirs) are skipped so the
+analyser never wanders into ``.venv`` or ``node_modules``. See ADR 0005.
+"""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+
+import pathspec
+
+#: Always skipped, whether or not they appear in .gitignore: vendored code and tool caches that
+#: are never the project's own source.
+DEFAULT_IGNORE_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".hg",
+        ".svn",
+        "__pycache__",
+        ".venv",
+        "venv",
+        "env",
+        ".env",
+        "node_modules",
+        "site-packages",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".pytest_cache",
+        ".tox",
+        ".nox",
+        "build",
+        "dist",
+        ".eggs",
+    }
+)
+
+#: Generated Python that is not hand-written source.
+IGNORE_SUFFIXES: tuple[str, ...] = ("_pb2.py", "_pb2_grpc.py", "_pb2.pyi")
+
+
+@dataclass(frozen=True, slots=True)
+class Module:
+    """One parsed source file. ``qualname`` is the canonical (src-stripped) dotted path."""
+
+    qualname: str
+    path: Path
+    relpath: str
+    source: str
+    tree: ast.Module
+    is_package: bool  # an __init__.py
+
+
+@dataclass(frozen=True, slots=True)
+class Collection:
+    """The result of walking a project: the modules, and how to resolve a name to one."""
+
+    root: Path
+    modules: tuple[Module, ...]
+    #: import alias (``app.services.geo``) -> the module it names. Excludes ambiguous names.
+    by_alias: dict[str, Module]
+    #: aliases claimed by two or more distinct files: the resolver must not resolve into these.
+    ambiguous_aliases: frozenset[str]
+    #: the set of top-level import roots that belong to this project (``app`` for ``app.geo``),
+    #: so the resolver can tell an internal call from a third-party or stdlib one.
+    internal_roots: frozenset[str]
+    unparsed: tuple[Path, ...]
+
+
+def _canonical_qualname(rel: PurePosixPath) -> str:
+    """Repo-root-relative dotted path, with a leading ``src`` stripped so src-layout resolves."""
+    parts = list(rel.parts)
+    if parts and parts[0] == "src":
+        parts = parts[1:]
+    if not parts:
+        return ""
+    if parts[-1] == "__init__.py":
+        parts = parts[:-1]
+    else:
+        parts[-1] = parts[-1].removesuffix(".py")
+    return ".".join(parts)
+
+
+def _initwalk_qualname(path: Path, root: Path) -> str:
+    """The name a file has when reached by walking up while ``__init__.py`` exists.
+
+    Guards the bare-stem hijack: a loose module in a non-package directory (``tools/foo.py``
+    where ``tools/`` has no ``__init__.py``) is not importable as ``foo``, and registering that
+    alias would let a repo file shadow the stdlib module of the same name. Such files get no
+    initwalk alias; their canonical name still stands.
+    """
+    if (
+        path.name != "__init__.py"
+        and path.parent != root
+        and not (path.parent / "__init__.py").exists()
+    ):
+        return ""
+    parts = [path.stem] if path.name != "__init__.py" else []
+    cur = path.parent
+    while cur != root and (cur / "__init__.py").exists():
+        parts.insert(0, cur.name)
+        cur = cur.parent
+    return ".".join(parts)
+
+
+def _load_gitignore(root: Path) -> pathspec.GitIgnoreSpec | None:
+    """The root .gitignore as a matcher. GitIgnoreSpec, not a plain PathSpec, so negation
+    (``!keep.py``) and directory anchoring follow real gitignore semantics."""
+    gi = root / ".gitignore"
+    if not gi.is_file():
+        return None
+    try:
+        return pathspec.GitIgnoreSpec.from_lines(gi.read_text().splitlines())
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def _iter_py_files(root: Path, *, respect_gitignore: bool) -> list[Path]:
+    spec = _load_gitignore(root) if respect_gitignore else None
+    out: list[Path] = []
+    # Manual walk so an ignored directory is pruned, not descended into.
+    stack = [root]
+    while stack:
+        current = stack.pop()
+        try:
+            entries = sorted(current.iterdir())
+        except OSError:
+            continue
+        for entry in entries:
+            rel = PurePosixPath(entry.relative_to(root).as_posix())
+            if entry.is_dir():
+                if entry.name in DEFAULT_IGNORE_DIRS:
+                    continue
+                if spec is not None and spec.match_file(f"{rel}/"):
+                    continue
+                stack.append(entry)
+            elif entry.suffix == ".py":
+                if entry.name.endswith(IGNORE_SUFFIXES):
+                    continue
+                if spec is not None and spec.match_file(str(rel)):
+                    continue
+                out.append(entry)
+    return sorted(out)
+
+
+def collect(root: Path, *, respect_gitignore: bool = True) -> Collection:
+    """Walk ``root`` and return its parsed modules and the resolver's alias map."""
+    root = root.resolve()
+    modules: list[Module] = []
+    by_alias: dict[str, Module] = {}
+    ambiguous: set[str] = set()
+    unparsed: list[Path] = []
+
+    for path in _iter_py_files(root, respect_gitignore=respect_gitignore):
+        rel = PurePosixPath(path.relative_to(root).as_posix())
+        try:
+            source = path.read_text(encoding="utf-8")
+            tree = ast.parse(source, filename=str(path))
+        except (OSError, UnicodeDecodeError, SyntaxError, ValueError, RecursionError):
+            unparsed.append(path)
+            continue
+
+        canonical = _canonical_qualname(rel)
+        if not canonical:
+            continue
+        module = Module(
+            qualname=canonical,
+            path=path,
+            relpath=str(rel),
+            source=source,
+            tree=tree,
+            is_package=rel.name == "__init__.py",
+        )
+        modules.append(module)
+        for alias in {canonical, _initwalk_qualname(path, root)}:
+            if not alias:
+                continue
+            existing = by_alias.get(alias)
+            if existing is not None and existing.relpath != module.relpath:
+                ambiguous.add(alias)
+            else:
+                by_alias[alias] = module
+
+    internal_roots = frozenset(alias.split(".")[0] for alias in by_alias)
+    return Collection(
+        root=root,
+        modules=tuple(modules),
+        by_alias=by_alias,
+        ambiguous_aliases=frozenset(ambiguous),
+        internal_roots=internal_roots,
+        unparsed=tuple(unparsed),
+    )

blockpath/config.py

@@ -0,0 +1,75 @@
+"""Configuration for a check run: where it comes from and what it controls.
+
+Read from a ``[tool.blockpath]`` table in the project's own ``pyproject.toml`` and nowhere else
+(ADR 0008), because every other Python tool already lives there and a second dotfile is a tax on
+the user. Command-line flags override the file; ``--no-config`` ignores it entirely, which the
+corpus benchmark needs so a third-party project's settings cannot bend our measurements.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+
+from blockpath.model import Severity
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+    """Everything the analyzer needs to know beyond the source tree itself."""
+
+    #: Framework decorators that mark an async entry point even on a plain ``def`` handler
+    #: (aiogram ``router.message``, aiohttp ``routes.get``, ...). Matched against the decorator
+    #: as written, exactly or by dotted suffix. FastAPI's ``async def`` routes need no help.
+    entry_decorators: frozenset[str] = field(default_factory=frozenset)
+    #: Oracle tiers that are switched on. ``error`` is the default; the rest are opt-in.
+    enabled_tiers: frozenset[Severity] = field(default_factory=lambda: frozenset({Severity.ERROR}))
+    #: Under strict mode, a blocking callable handed to an unresolved callee is reported (BLK003).
+    strict: bool = False
+    #: Import-resolution depth ceiling, a guard against pathological re-export chains.
+    max_import_depth: int = 8
+
+
+DEFAULT = Config()
+
+
+def load_config(root: Path) -> Config:
+    """Read ``[tool.blockpath]`` from ``root/pyproject.toml``; missing or empty means defaults."""
+    pyproject = root / "pyproject.toml"
+    if not pyproject.is_file():
+        return DEFAULT
+    try:
+        with pyproject.open("rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError):
+        return DEFAULT
+    tool = data.get("tool")
+    if not isinstance(tool, dict):
+        return DEFAULT
+    table = tool.get("blockpath")
+    if not isinstance(table, dict):
+        return DEFAULT
+    return _from_table(table)
+
+
+def _from_table(table: dict[str, object]) -> Config:
+    config = DEFAULT
+    strict = table.get("strict")
+    if isinstance(strict, bool):
+        config = replace(config, strict=strict)
+
+    tiers = table.get("tiers")
+    if isinstance(tiers, list):
+        parsed = {Severity(str(t)) for t in tiers if str(t) in {s.value for s in Severity}}
+        if parsed:
+            config = replace(config, enabled_tiers=frozenset(parsed))
+
+    decorators = table.get("entry-decorators", table.get("entry_decorators"))
+    if isinstance(decorators, list):
+        config = replace(config, entry_decorators=frozenset(str(d) for d in decorators))
+
+    depth = table.get("max-import-depth", table.get("max_import_depth"))
+    if isinstance(depth, int) and depth > 0:
+        config = replace(config, max_import_depth=depth)
+    return config

blockpath/model.py

@@ -0,0 +1,112 @@
+"""The data model every layer of the pipeline produces or consumes.
+
+Deliberately small and frozen. A ``Finding`` is what the tool exists to print: not "there is a
+blocking call in file X" but the whole path from an async entry point down to the blocking leaf,
+frame by frame, with the file, line and column of each hop. Everything else in the package is in
+service of building one of these correctly.
+
+Diagnostic codes:
+  BLK001  a blocking call is reachable from a coroutine (the main finding)
+  BLK002  a function was CALLED where it should have been PASSED to an executor,
+          e.g. ``run_in_executor(None, fetch())`` instead of ``run_in_executor(None, fetch)``
+  BLK003  a path exists but at least one edge could not be resolved; emitted only under --strict
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+class Code(enum.Enum):
+    """Diagnostic codes. The value is what gets printed."""
+
+    BLK001 = "BLK001"
+    BLK002 = "BLK002"
+    BLK003 = "BLK003"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class Severity(enum.Enum):
+    """Oracle tiers. ``error`` blocks CI; ``warning`` and ``off`` do not, by default."""
+
+    ERROR = "error"
+    WARNING = "warning"
+    OFF = "off"
+
+
+@dataclass(frozen=True, slots=True)
+class Position:
+    """A point in a source file. Columns are 0-based, as ``ast`` reports them."""
+
+    path: Path
+    line: int
+    col: int
+
+    def __str__(self) -> str:
+        return f"{self.path}:{self.line}:{self.col}"
+
+
+@dataclass(frozen=True, slots=True)
+class Frame:
+    """One hop on a witness path: a call site and the function it lands in.
+
+    ``qualname`` is the function whose body this frame represents; ``position`` is where the
+    *previous* frame called into it (or, for the entry frame, where the function is defined).
+    ``source_line`` is the raw text of that line, kept so the reporter can show it without
+    re-reading the file.
+    """
+
+    qualname: str
+    position: Position
+    source_line: str
+    #: For the entry frame: what makes this an async entry point (an ``async def``, a framework
+    #: decorator, a task factory). Empty for interior frames.
+    entry_reason: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class Finding:
+    """A blocking call reachable from a coroutine, with the full path to it."""
+
+    code: Code
+    severity: Severity
+    #: The blocking callee, fully qualified, e.g. ``requests.get`` or ``time.sleep``.
+    callee: str
+    #: The category from the oracle: network, subprocess, sleep, db, ...
+    category: str
+    #: From the async entry point (first) down to the blocking leaf (last). Never empty; a
+    #: depth-1 finding has a single frame that is both entry and leaf.
+    witness: tuple[Frame, ...]
+    #: A ready-to-print remediation, e.g. "await asyncio.to_thread(resolve_address, addr)".
+    hint: str = ""
+
+    @property
+    def entry(self) -> Frame:
+        return self.witness[0]
+
+    @property
+    def leaf(self) -> Frame:
+        return self.witness[-1]
+
+    @property
+    def depth(self) -> int:
+        """Number of frames from entry to leaf. Depth 1 = the call is in the coroutine body."""
+        return len(self.witness)
+
+
+@dataclass(frozen=True, slots=True)
+class CheckResult:
+    """The outcome of analysing one project."""
+
+    findings: tuple[Finding, ...]
+    #: Files that failed to parse, reported rather than silently skipped.
+    unparsed: tuple[Path, ...] = field(default_factory=tuple)
+
+    @property
+    def exit_code(self) -> int:
+        """0 clean, 1 findings, matching the CLI contract. 2 (error) is set by the CLI itself."""
+        return 1 if self.findings else 0

blockpath/oracle.py

@@ -0,0 +1,143 @@
+"""Layer 5: which external calls block, and which primitives hand work to another thread.
+
+The knowledge lives in ``oracle.yaml`` as *data*, so the list can be read and argued with
+without reading Python. This module only loads it and answers two questions:
+
+* ``verdict(dotted)`` -- does calling this name stall the loop, in which category, at which
+  severity tier. Unknown names get no verdict at all: the tool does not guess that an unfamiliar
+  third-party call blocks.
+* ``blk002(consumer, arg_index)`` -- was a function *called* in the argument slot where an
+  offload primitive expected it to be *passed*? ``run_in_executor(None, fetch())`` runs ``fetch``
+  on the loop before the executor sees anything, which is the exact inversion of the fix people
+  reach for, and it gets its own diagnostic.
+
+Severity tiers exist so the default is quiet: ``error`` (unbounded stalls) is on, ``warning``
+(CPU-bound by design) and ``off`` (local disk I/O) are opt-in. Turning disk I/O on by default
+would fire on every ``json.load(open(path))``, and a tool that cries wolf gets switched off.
+"""
+
+from __future__ import annotations
+
+import importlib.resources
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+import yaml
+
+from blockpath.model import Severity
+
+_DEFAULT_RESOURCE = "oracle.yaml"
+
+
+def _severity(value: object) -> Severity:
+    """Parse a severity, surviving YAML 1.1's booleans.
+
+    ``severity: off`` unquoted is parsed by PyYAML as the boolean ``False`` (YAML 1.1 treats
+    off/on/yes/no as booleans). The bundled file quotes it, but an edit that forgets the quotes
+    must not silently mangle the oracle, so both spellings are accepted.
+    """
+    if value is False:
+        return Severity.OFF
+    if value is True:
+        return Severity.ERROR  # `severity: on` -- nobody should write it, but do not crash
+    return Severity(str(value))
+
+
+@dataclass(frozen=True, slots=True)
+class BlockingCall:
+    """One claim: calling ``name`` from a coroutine stalls the loop."""
+
+    name: str
+    category: str
+    severity: Severity
+    note: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class Offload:
+    """A primitive that runs a callable on another thread."""
+
+    match: tuple[str, ...]
+    func_arg: int
+    note: str = ""
+
+    def matches(self, consumer: str) -> bool:
+        return any(consumer == m or consumer.endswith(f".{m}") for m in self.match)
+
+
+class Oracle:
+    def __init__(self, entries: list[BlockingCall], offloads: list[Offload]) -> None:
+        self._by_name = {entry.name: entry for entry in entries}
+        self._offloads = offloads
+
+    # -- construction -------------------------------------------------------------------------
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> Oracle:
+        """Load the bundled oracle, or an alternative file."""
+        if path is None:
+            text = importlib.resources.files("blockpath").joinpath(_DEFAULT_RESOURCE).read_text()
+        else:
+            text = path.read_text()
+        return cls.from_yaml(text)
+
+    @classmethod
+    def from_yaml(cls, text: str) -> Oracle:
+        raw = cast(dict[str, object], yaml.safe_load(text))
+        entries: list[BlockingCall] = []
+        for item in cast(list[dict[str, str]], raw.get("entries", [])):
+            entries.append(
+                BlockingCall(
+                    name=item["name"],
+                    category=item["category"],
+                    severity=_severity(item["severity"]),
+                    note=item.get("note", ""),
+                )
+            )
+        offloads: list[Offload] = []
+        for item2 in cast(list[dict[str, object]], raw.get("offloads", [])):
+            offloads.append(
+                Offload(
+                    match=tuple(cast(list[str], item2["match"])),
+                    func_arg=int(cast(int, item2["func_arg"])),
+                    note=cast(str, item2.get("note", "")),
+                )
+            )
+        return cls(entries, offloads)
+
+    # -- queries -----------------------------------------------------------------------------
+
+    def verdict(self, dotted: str) -> BlockingCall | None:
+        """The blocking claim for this external name, or None if we make no claim about it."""
+        return self._by_name.get(dotted)
+
+    def blocks(self, dotted: str, enabled: frozenset[Severity]) -> BlockingCall | None:
+        """As :meth:`verdict`, but only if the entry's tier is switched on."""
+        entry = self._by_name.get(dotted)
+        if entry is None or entry.severity not in enabled:
+            return None
+        return entry
+
+    def offload_for(self, consumer: str | None) -> Offload | None:
+        if consumer is None:
+            return None
+        for offload in self._offloads:
+            if offload.matches(consumer):
+                return offload
+        return None
+
+    def blk002(self, consumer: str | None, arg_index: int | None) -> Offload | None:
+        """The offload whose callable slot was *called* instead of passed, if this is that bug."""
+        offload = self.offload_for(consumer)
+        if offload is None or arg_index is None:
+            return None
+        return offload if arg_index == offload.func_arg else None
+
+    @property
+    def entries(self) -> list[BlockingCall]:
+        return list(self._by_name.values())
+
+    @property
+    def offloads(self) -> list[Offload]:
+        return list(self._offloads)