CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
"""Tests for the griffe → MDX API reference generator."""
import importlib.util
import sys
from pathlib import Path
import pytest
SCRIPT_PATH = Path(__file__).resolve().parents[1] / "build_api_reference.py"
def _load_module():
spec = importlib.util.spec_from_file_location("build_api_reference", SCRIPT_PATH)
assert spec and spec.loader, f"cannot load {SCRIPT_PATH}"
mod = importlib.util.module_from_spec(spec)
sys.modules["build_api_reference"] = mod
spec.loader.exec_module(mod)
return mod
def test_render_signature_includes_return_annotation():
mod = _load_module()
rendered = mod.render_signature(
name="run",
parameters=[("self", None, None), ("x", "int", None)],
returns="str",
)
assert "run(self, x: int) -> str" in rendered
def test_render_docstring_parses_google_sections():
mod = _load_module()
doc = (
"Summary line.\n\n"
"Args:\n"
" name (str): The name.\n\n"
"Returns:\n"
" bool: Whether it worked.\n"
)
out = mod.render_docstring(doc, ref_index={})
assert "Summary line." in out
assert "**Args**" in out
assert "`name`" in out
assert "**Returns**" in out
def test_rst_class_ref_links_when_in_index():
mod = _load_module()
ref_index = {"Tracer": "./cubeloop-tracing#tracer"}
out = mod._rst_to_mdx_refs(
"Build a :class:`Tracer`, attach it.", ref_index=ref_index
)
assert "[`Tracer`](./cubeloop-tracing#tracer)" in out
def test_rst_class_ref_falls_back_to_inline_code():
mod = _load_module()
out = mod._rst_to_mdx_refs(
"Wraps a :class:`SpanExporter` from OTel.", ref_index={}
)
# External name: inline code, no link
assert "`SpanExporter`" in out
assert "](" not in out
def test_rst_class_ref_with_tilde_shortens_display():
mod = _load_module()
ref_index = {"Tracer": "./cubeloop-tracing#tracer"}
out = mod._rst_to_mdx_refs(
"See :class:`~cubeloop.tracing.Tracer` for details.",
ref_index=ref_index,
)
# ~ prefix means show only the last component
assert "[`Tracer`]" in out
assert "[`cubeloop.tracing.Tracer`]" not in out
def test_rst_meth_ref_resolves_class_member():
mod = _load_module()
ref_index = {"Tracer.attach": "./cubeloop-tracing#tracer-attach"}
out = mod._rst_to_mdx_refs(
"Each :meth:`Tracer.attach` call wires…", ref_index=ref_index
)
assert "[`Tracer.attach`](./cubeloop-tracing#tracer-attach)" in out
def test_strip_rst_double_backticks():
mod = _load_module()
out = mod._strip_rst_role_inline_code("Set ``record_content=True`` for opt-in.")
assert "Set `record_content=True` for opt-in." == out
def test_rst_literal_block_marker_starts_code_fence():
mod = _load_module()
doc = (
"Use it like this::\n\n"
" from cubeloop import Agent\n"
" agent = Agent(...)\n"
)
out = mod.render_docstring(doc, ref_index={})
assert "```python" in out
assert "from cubeloop import Agent" in out
def test_rst_underline_heading_converts_to_bold():
mod = _load_module()
doc = (
"Summary.\n\n"
"Example\n"
"-------\n"
" x = 1\n"
)
out = mod.render_docstring(doc, ref_index={})
assert "**Example**" in out
# And the heading underline itself should NOT pass through
assert "-------" not in out
def test_anchor_lowercases_and_dehyphens():
mod = _load_module()
assert mod._anchor("Tracer") == "tracer"
assert mod._anchor("attach_async") == "attach-async"
assert mod._anchor("__init__") == "init"
def test_source_relpath_strips_worktree_prefix():
mod = _load_module()
path = (
"/home/chris/cubepi/.worktrees/2026-06-05-release-0.7-review/"
"cubeloop/agent/agent.py"
)
assert mod._source_relpath(path) == "cubeloop/agent/agent.py"
def test_build_ref_index_includes_class_members():
mod = _load_module()
# Fake griffe-like Class with .name and .members
class _FakeClass:
def __init__(self, name, members):
self.name = name
self.members = members
class _FakeMember:
pass
tracer = _FakeClass("Tracer", {"attach": _FakeMember(), "_private": _FakeMember()})
index = mod.build_ref_index({"cubeloop.tracing": [tracer]})
assert index["Tracer"] == "./cubeloop-tracing#tracer"
assert index["Tracer.attach"] == "./cubeloop-tracing#tracer-attach"
# Private members are skipped
assert "Tracer._private" not in index
def test_emit_module_writes_generated_marker(tmp_path):
mod = _load_module()
module_path = tmp_path / "cubeloop-utils.mdx"
mod.emit_module(
out_path=module_path,
module_name="cubeloop.utils",
sidebar_position=6,
symbols=[],
ref_index={},
source_ref="main",
)
body = module_path.read_text(encoding="utf-8")
assert body.startswith("---\n")
assert "title: cubeloop.utils" in body
assert "<!-- GENERATED by build_api_reference.py — DO NOT EDIT -->" in body