beehave-bt 0.1.0__py3-none-any.whl

beehave/__init__.py

@@ -0,0 +1,80 @@
+"""Beehave: the small branch that matters.
+
+Beehave reads a behavior tree and gives back only the actions the robot can
+take, in order, with the conditions that lead to each one.
+
+Example:
+    >>> import beehave
+    >>> result = beehave.analyze("mission.xml")  # doctest: +SKIP
+    >>> print(beehave.to_text(result.graph))  # doctest: +SKIP
+    START --[not IsBatteryCritical]--> Arm
+    ...
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from beehave.api import Analysis, analyze, analyze_py_trees
+from beehave.config import Config, load_config
+from beehave.errors import (
+    BeehaveError,
+    ConfigError,
+    FlattenError,
+    ParseError,
+    TreeSelectionError,
+    UnsupportedFormatError,
+)
+from beehave.flatten import FlatTree, flatten
+from beehave.graph import ActionGraph, Condition, Edge, Literal, Outcome, Vertex, VertexKind
+from beehave.ids import IdScheme, NodeRef, RuntimeNode, node_refs, runtime_ids
+from beehave.parsers import parse_file, parse_string
+from beehave.parsers.pytrees import from_py_trees, load_py_trees
+from beehave.render import to_dot, to_json, to_mermaid, to_text
+from beehave.stats import Stats, compute_stats
+from beehave.walk import build_graph
+
+try:
+    __version__ = version("beehave-bt")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "ActionGraph",
+    "Analysis",
+    "BeehaveError",
+    "Condition",
+    "Config",
+    "ConfigError",
+    "Edge",
+    "FlatTree",
+    "FlattenError",
+    "IdScheme",
+    "Literal",
+    "NodeRef",
+    "Outcome",
+    "ParseError",
+    "RuntimeNode",
+    "Stats",
+    "TreeSelectionError",
+    "UnsupportedFormatError",
+    "Vertex",
+    "VertexKind",
+    "__version__",
+    "analyze",
+    "analyze_py_trees",
+    "build_graph",
+    "compute_stats",
+    "flatten",
+    "from_py_trees",
+    "load_config",
+    "load_py_trees",
+    "node_refs",
+    "parse_file",
+    "parse_string",
+    "runtime_ids",
+    "to_dot",
+    "to_json",
+    "to_mermaid",
+    "to_text",
+]

beehave/__main__.py

@@ -0,0 +1,9 @@
+"""Allow ``python -m beehave``."""
+
+from __future__ import annotations
+
+import sys
+
+from beehave.cli import main
+
+sys.exit(main())

beehave/api.py

@@ -0,0 +1,105 @@
+"""One call to run the whole pipeline: read, flatten, walk."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from functools import cached_property
+from typing import TYPE_CHECKING
+
+from beehave.flatten import FlatTree, flatten
+from beehave.parsers import parse_file
+from beehave.parsers.pytrees import from_py_trees
+from beehave.stats import Stats, compute_stats
+from beehave.walk import DEFAULT_MAX_PATHS, build_graph
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from beehave.config import Config
+    from beehave.graph import ActionGraph
+    from beehave.model import Document
+
+
+@dataclass(frozen=True)
+class Analysis:
+    """Everything Beehave computed for one tree.
+
+    Attributes:
+        document: All trees loaded from the input files.
+        tree: The selected tree, with subtrees inlined.
+        graph: Its action graph. Its diagnostics include the ones found while loading.
+    """
+
+    document: Document
+    tree: FlatTree
+    graph: ActionGraph
+
+    @cached_property
+    def stats(self) -> Stats:
+        """The pilot metrics for this tree."""
+        return compute_stats(self.tree, self.graph)
+
+
+def analyze(
+    *paths: str | Path,
+    tree: str | None = None,
+    config: Config | None = None,
+    max_paths: int = DEFAULT_MAX_PATHS,
+) -> Analysis:
+    """Load tree files and build the action graph of one tree.
+
+    Args:
+        *paths: BT.CPP XML files. Trees from all of them are merged.
+        tree: The tree to analyse; defaults to the main tree.
+        config: Project settings (which custom nodes are conditions).
+        max_paths: Cap on guarded transitions per action outcome.
+
+    Returns:
+        The document, the flattened tree and its action graph.
+
+    Raises:
+        beehave.BeehaveError: If the input cannot be read or analysed.
+
+    Example:
+        >>> import beehave
+        >>> result = beehave.analyze("mission.xml")  # doctest: +SKIP
+        >>> print(beehave.to_mermaid(result.graph))  # doctest: +SKIP
+    """
+    return _analyze(parse_file(*paths, config=config), tree, max_paths)
+
+
+def analyze_py_trees(
+    tree: object,
+    *,
+    config: Config | None = None,
+    max_paths: int = DEFAULT_MAX_PATHS,
+) -> Analysis:
+    """Build the action graph of a live py_trees tree.
+
+    The tree is only read: no behaviour is set up or ticked. Use
+    :func:`beehave.load_py_trees` to import a tree from a module first.
+
+    Args:
+        tree: The root ``Behaviour``, or a ``BehaviourTree``.
+        config: Project settings (which behaviour classes are conditions).
+        max_paths: Cap on guarded transitions per action outcome.
+
+    Returns:
+        The document, the tree and its action graph.
+
+    Raises:
+        beehave.BeehaveError: If the tree cannot be read, or py_trees is missing.
+
+    Example:
+        >>> import beehave
+        >>> result = beehave.analyze_py_trees(create_root())  # doctest: +SKIP
+        >>> print(beehave.to_mermaid(result.graph))  # doctest: +SKIP
+    """
+    return _analyze(from_py_trees(tree, config=config), None, max_paths)
+
+
+def _analyze(document: Document, tree: str | None, max_paths: int) -> Analysis:
+    flat = flatten(document, tree)
+    graph = build_graph(flat, max_paths=max_paths)
+    graph = replace(graph, diagnostics=document.diagnostics + graph.diagnostics)
+    return Analysis(document, flat, graph)

beehave/cli.py

@@ -0,0 +1,271 @@
+"""The ``beehave`` command line.
+
+Examples::
+
+    beehave graph mission.xml                 # transitions as text
+    beehave graph mission.xml -f mermaid -o mission.mmd
+    beehave stats mission.xml                 # size, reduction, breakage
+    beehave trees mission.xml                 # list the trees in the files
+    beehave ids mission.xml                   # runtime ids and paths of every node
+    beehave graph --py-trees robot.trees:create_root   # a py_trees tree (runs that code)
+    beehave graph behavior_trees/ -t NavigateToPose     # every tree in a folder
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import replace
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from beehave import __version__
+from beehave.api import analyze, analyze_py_trees
+from beehave.config import Config, find_config, load_config
+from beehave.errors import BeehaveError
+from beehave.ids import IdScheme, runtime_ids
+from beehave.parsers import parse_file
+from beehave.parsers.pytrees import from_py_trees, load_py_trees
+from beehave.render import FORMATS
+from beehave.render.json import node_ref
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from beehave.api import Analysis
+    from beehave.diagnostics import Diagnostic
+    from beehave.model import Document
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line and return the exit code.
+
+    Exit codes: 0 on success, 1 when the input cannot be analysed, 2 on a usage error.
+    """
+    args = _parser().parse_args(argv)
+    _check_inputs(args)
+    try:
+        return int(args.run(args))
+    except BeehaveError as exc:
+        print(f"beehave: error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="beehave",
+        description="Show only the actions a behavior tree can take, and what runs next.",
+    )
+    parser.add_argument("--version", action="version", version=f"beehave {__version__}")
+    commands = parser.add_subparsers(title="commands", required=True, metavar="COMMAND")
+
+    graph = commands.add_parser("graph", help="build the action graph of a tree")
+    _common(graph)
+    graph.set_defaults(parser=graph)
+    graph.add_argument(
+        "-f",
+        "--format",
+        choices=sorted(FORMATS),
+        default="text",
+        help="output format (default: text)",
+    )
+    graph.add_argument("-o", "--output", type=Path, help="write to a file instead of stdout")
+    graph.set_defaults(run=_graph)
+
+    stats = commands.add_parser("stats", help="print size, reduction and breakage metrics")
+    _common(stats)
+    stats.set_defaults(parser=stats)
+    stats.add_argument("--json", action="store_true", help="print the metrics as JSON")
+    stats.set_defaults(run=_stats)
+
+    ids = commands.add_parser(
+        "ids", help="list every node with its runtime id, path and action vertex"
+    )
+    _common(ids)
+    ids.set_defaults(parser=ids)
+    ids.add_argument(
+        "--scheme",
+        choices=[scheme.value for scheme in IdScheme],
+        default=IdScheme.BTCPP_V4.value,
+        help="btcpp-v4: from 1, like BT.CPP v4 UIDs (default); preorder: from 0",
+    )
+    ids.add_argument("--json", action="store_true", help="print the nodes as JSON")
+    ids.set_defaults(run=_ids)
+
+    trees = commands.add_parser("trees", help="list the trees defined in the files")
+    _inputs(trees)
+    trees.set_defaults(run=_trees, parser=trees)
+    return parser
+
+
+def _inputs(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "files",
+        nargs="*",
+        type=Path,
+        metavar="FILE",
+        help="BT.CPP XML files, or folders: every .xml file directly in a folder is read",
+    )
+    parser.add_argument(
+        "--py-trees",
+        metavar="SPEC",
+        help="read a py_trees tree instead: module:function or file.py:function. "
+        "This imports the module and calls the function, so it runs that code",
+    )
+    parser.add_argument(
+        "--kwargs", metavar="JSON", help="arguments for the --py-trees function, as a JSON object"
+    )
+    parser.add_argument(
+        "-c", "--config", type=Path, help="project config (default: ./beehave.yaml)"
+    )
+    parser.add_argument(
+        "--package",
+        action="append",
+        default=[],
+        metavar="NAME=DIR",
+        help='where <include ros_pkg="NAME"> finds the package; repeat for several',
+    )
+
+
+def _common(parser: argparse.ArgumentParser) -> None:
+    _inputs(parser)
+    parser.add_argument("-t", "--tree", help="tree to analyse (default: the main tree)")
+    parser.add_argument("-q", "--quiet", action="store_true", help="do not print warnings")
+
+
+def _check_inputs(args: argparse.Namespace) -> None:
+    error = args.parser.error
+    for value in args.package:
+        name, _, directory = value.partition("=")
+        if not name or not directory:
+            error("--package takes NAME=DIR, for example --package my_robot_bt=src/my_robot_bt")
+    if args.files and args.py_trees:
+        error("give tree files or --py-trees, not both")
+    if not args.files and not args.py_trees:
+        error("give tree files or --py-trees")
+    if args.py_trees and getattr(args, "tree", None):
+        error("--tree does not apply to --py-trees")
+    if args.kwargs is None:
+        return
+    if not args.py_trees:
+        error("--kwargs needs --py-trees")
+    try:
+        kwargs = json.loads(args.kwargs)
+    except json.JSONDecodeError:
+        kwargs = None
+    if not isinstance(kwargs, dict):
+        error("--kwargs must be a JSON object")
+    args.kwargs = kwargs
+
+
+def _config(args: argparse.Namespace) -> Config:
+    path = args.config or find_config()
+    config = load_config(path) if path else Config()
+    if not args.package:
+        return config
+    packages = dict(config.packages)
+    for value in args.package:
+        name, _, directory = value.partition("=")
+        packages[name] = Path(directory)
+    return replace(config, packages=packages)
+
+
+def _analysis(args: argparse.Namespace) -> Analysis:
+    if args.py_trees:
+        tree = load_py_trees(args.py_trees, **(args.kwargs or {}))
+        return analyze_py_trees(tree, config=_config(args))
+    return analyze(*args.files, tree=args.tree, config=_config(args))
+
+
+def _document(args: argparse.Namespace) -> Document:
+    if args.py_trees:
+        tree = load_py_trees(args.py_trees, **(args.kwargs or {}))
+        return from_py_trees(tree, config=_config(args))
+    return parse_file(*args.files, config=_config(args))
+
+
+def _graph(args: argparse.Namespace) -> int:
+    result = _analysis(args)
+    _warn(result.graph.diagnostics, quiet=args.quiet)
+    output = FORMATS[args.format](result.graph)
+    if args.output:
+        args.output.write_text(output, encoding="utf-8")
+    else:
+        sys.stdout.write(output)
+    return 0
+
+
+def _stats(args: argparse.Namespace) -> int:
+    result = _analysis(args)
+    _warn(result.graph.diagnostics, quiet=args.quiet)
+    if args.json:
+        sys.stdout.write(json.dumps(result.stats.to_dict(), indent=2) + "\n")
+    else:
+        sys.stdout.write(result.stats.to_text())
+    return 0
+
+
+def _ids(args: argparse.Namespace) -> int:
+    result = _analysis(args)
+    _warn(result.graph.diagnostics, quiet=args.quiet)
+    scheme = IdScheme(args.scheme)
+    nodes = runtime_ids(result.tree, scheme)
+    vertices = {v.node.path: v.id for v in result.graph.actions if v.node}
+    if args.json:
+        data = {
+            "schema": "beehave.runtime-ids",
+            "version": 1,
+            "tree": result.tree.id,
+            "source_format": result.tree.format,
+            "scheme": scheme.value,
+            "nodes": [
+                {
+                    "id": node.id,
+                    "parent": node.parent,
+                    "kind": node.kind.value,
+                    "type": node.type,
+                    "name": node.name,
+                    "subtree": node.subtree,
+                    "vertex": vertices.get(node.ref.path),
+                    **(node_ref(node.ref) or {}),
+                    "location": None
+                    if node.location is None
+                    else {"file": node.location.file, "line": node.location.line},
+                }
+                for node in nodes.values()
+            ],
+        }
+        sys.stdout.write(json.dumps(data, indent=2, ensure_ascii=False) + "\n")
+        return 0
+    rows = [("ID", "KIND", "VERTEX", "RUNTIME PATH", "PATH")]
+    rows += [
+        (
+            str(node.id),
+            node.kind.value,
+            vertices.get(node.ref.path, "-"),
+            node.ref.runtime_path or "-",
+            node.ref.path,
+        )
+        for node in nodes.values()
+    ]
+    widths = [max(len(row[i]) for row in rows) for i in range(4)]
+    for row in rows:
+        cells = [cell.ljust(width) for cell, width in zip(row, widths, strict=False)]
+        sys.stdout.write("  ".join([*cells, row[4]]) + "\n")
+    return 0
+
+
+def _trees(args: argparse.Namespace) -> int:
+    document = _document(args)
+    for tree_id in document.trees:
+        suffix = " (main)" if tree_id == document.main_tree else ""
+        sys.stdout.write(f"{tree_id}{suffix}\n")
+    return 0
+
+
+def _warn(diagnostics: Sequence[Diagnostic], *, quiet: bool) -> None:
+    if quiet:
+        return
+    for diagnostic in diagnostics:
+        print(f"beehave: {diagnostic}", file=sys.stderr)

beehave/config.py

@@ -0,0 +1,140 @@
+"""Per-project configuration.
+
+Beehave works on any tree without configuration. A project only needs a config
+file to say which of its custom nodes are conditions "in disguise" (for example
+an action that only checks something), or to force a node to be an action::
+
+    # beehave.yaml
+    conditions:
+      - BatteryOK
+      - IsEmergency
+    actions:
+      - Probe
+    packages:              # where <include ros_pkg="..."> finds a package
+      my_robot_bt: src/my_robot_bt
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import yaml
+
+from beehave.errors import ConfigError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+DEFAULT_CONFIG_NAMES = ("beehave.yaml", ".beehave.yaml")
+_KNOWN_KEYS = frozenset({"conditions", "actions", "packages"})
+
+
+@dataclass(frozen=True)
+class Config:
+    """Project settings that change how nodes are classified.
+
+    Attributes:
+        conditions: Node types to treat as conditions, whatever the XML says.
+        actions: Node types to treat as actions, whatever the XML says.
+        packages: ROS package directories, by package name, for
+            ``<include ros_pkg="...">``. They win over a sourced workspace.
+    """
+
+    conditions: frozenset[str] = frozenset()
+    actions: frozenset[str] = frozenset()
+    packages: Mapping[str, Path] = field(default_factory=dict, hash=False)
+
+    def __post_init__(self) -> None:
+        both = self.conditions & self.actions
+        if both:
+            names = ", ".join(sorted(both))
+            msg = f"listed as both a condition and an action: {names}"
+            raise ConfigError(msg)
+
+
+def load_config(path: str | Path) -> Config:
+    """Read a YAML config file.
+
+    Args:
+        path: The file to read.
+
+    Returns:
+        The parsed configuration.
+
+    Raises:
+        ConfigError: If the file cannot be read or is not a valid config.
+    """
+    path = Path(path)
+    try:
+        data: Any = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        msg = f"cannot read config file {path}: {exc.strerror}"
+        raise ConfigError(msg) from exc
+    except yaml.YAMLError as exc:
+        msg = f"{path} is not valid YAML: {exc}"
+        raise ConfigError(msg) from exc
+    return config_from_dict(data, source=str(path), base_dir=path.parent)
+
+
+def config_from_dict(
+    data: Any, *, source: str = "config", base_dir: str | Path | None = None
+) -> Config:
+    """Build a :class:`Config` from already-parsed data.
+
+    Args:
+        data: The mapping read from YAML (``None`` means an empty file).
+        source: A name for error messages.
+        base_dir: What relative package directories are relative to: the
+            config file's folder. Defaults to the current directory.
+
+    Returns:
+        The configuration.
+
+    Raises:
+        ConfigError: If the data has the wrong shape.
+    """
+    if data is None:
+        return Config()
+    if not isinstance(data, dict):
+        msg = f"{source}: expected a mapping at the top level"
+        raise ConfigError(msg)
+    unknown = sorted(set(data) - _KNOWN_KEYS)
+    if unknown:
+        msg = f"{source}: unknown key(s): {', '.join(map(str, unknown))}"
+        raise ConfigError(msg)
+    return Config(
+        conditions=_names(data.get("conditions"), "conditions", source),
+        actions=_names(data.get("actions"), "actions", source),
+        packages=_packages(data.get("packages"), source, Path(base_dir or ".")),
+    )
+
+
+def find_config(directory: str | Path = ".") -> Path | None:
+    """Return the default config file in ``directory``, if there is one."""
+    for name in DEFAULT_CONFIG_NAMES:
+        candidate = Path(directory) / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _names(value: Any, key: str, source: str) -> frozenset[str]:
+    if value is None:
+        return frozenset()
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        msg = f"{source}: '{key}' must be a list of node names"
+        raise ConfigError(msg)
+    return frozenset(value)
+
+
+def _packages(value: Any, source: str, base_dir: Path) -> dict[str, Path]:
+    if value is None:
+        return {}
+    if not isinstance(value, dict) or not all(
+        isinstance(k, str) and isinstance(v, str) for k, v in value.items()
+    ):
+        msg = f"{source}: 'packages' must map package names to directories"
+        raise ConfigError(msg)
+    return {name: base_dir / directory for name, directory in value.items()}

beehave/diagnostics.py

@@ -0,0 +1,41 @@
+"""Non-fatal findings reported alongside a result."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from beehave.model import SourceLocation
+
+
+class Severity(str, Enum):
+    """How much a diagnostic matters."""
+
+    INFO = "info"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """Something worth telling the user that does not stop the analysis.
+
+    Attributes:
+        code: A stable, machine-readable identifier such as ``"approximated"``.
+        message: A plain-English explanation.
+        severity: How much it matters.
+        node_type: The node type the diagnostic is about, if any.
+        location: Where in the source it was found, if known.
+    """
+
+    code: str
+    message: str
+    severity: Severity = Severity.WARNING
+    node_type: str | None = None
+    location: SourceLocation | None = field(default=None, compare=False)
+
+    def __str__(self) -> str:
+        where = f"{self.location}: " if self.location else ""
+        return f"{where}{self.severity.value}: {self.message} [{self.code}]"

beehave/errors.py

@@ -0,0 +1,37 @@
+"""Exceptions raised by Beehave."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from beehave.model import SourceLocation
+
+
+class BeehaveError(Exception):
+    """Base class for every error Beehave raises on bad input."""
+
+    def __init__(self, message: str, location: SourceLocation | None = None) -> None:
+        self.message = message
+        self.location = location
+        super().__init__(f"{location}: {message}" if location else message)
+
+
+class ParseError(BeehaveError):
+    """A tree file could not be read."""
+
+
+class UnsupportedFormatError(ParseError):
+    """A tree file is in a format this version of Beehave cannot read yet."""
+
+
+class ConfigError(BeehaveError):
+    """A Beehave configuration file is invalid."""
+
+
+class FlattenError(BeehaveError):
+    """Subtrees could not be inlined (missing or recursive subtree)."""
+
+
+class TreeSelectionError(BeehaveError):
+    """No tree, or an unknown tree, was selected for analysis."""