Resources

dotagents._resources

The package's own data, reachable from a plain install and from a .pyz.

Everything here is library code: the CLI and the helper modules both import it, and it imports nothing from dotagents.cli.

• :data:BASE_ROOT -- the bundled base overlay (_overlay/): the block templates, the bundled command modules and the harness hook scripts.
• :func:base_agents_text -- a base overlay's AGENTS.md block rendered for one store.
• _package_data_dir / _scratch_dir -- a package-data directory as a real filesystem path (extracted once from a zipapp), and the one per-process temp directory such extractions go to.

AGENTS_MD_PLACEHOLDER = '{{AGENTS_MD}}' module-attribute

BASE_AGENTS_TEMPLATE = 'dotagents/templates/AGENTS.md' module-attribute

BASE_PROJECT_TEMPLATE = 'dotagents/templates/PROJECT.md' module-attribute

BASE_ROOT = _package_data_dir('_overlay') or Path(__file__).resolve().parent / '_overlay' module-attribute

base_agents_text(src, dest, *, project=False)

The base AGENTS.md block for the store at dest: the template (<src>/dotagents/templates/AGENTS.md, or PROJECT.md for a project store when the base has one; falling back to <src>/AGENTS.md for a --from base that keeps it at its root) with {{AGENTS_MD}} rendered as the ACTUAL path of the file being written, so the block's "annotate that you read …" line names this store's file. Under the home directory it is written ~/…, so a store synced between machines whose home directories differ renders the same block on each.

Source code in src/dotagents/_resources.py

def base_agents_text(
    src: "str | os.PathLike[str]", dest: "str | os.PathLike[str]", *, project: bool = False
) -> str:
    """The base AGENTS.md block for the store at ``dest``: the template
    (``<src>/dotagents/templates/AGENTS.md``, or ``PROJECT.md`` for a project
    store when the base has one; falling back to ``<src>/AGENTS.md`` for a
    ``--from`` base that keeps it at its root) with ``{{AGENTS_MD}}`` rendered
    as the ACTUAL path of the file being written, so the block's "annotate that
    you read `…`" line names this store's file. Under the home directory it is
    written ``~/…``, so a store synced between machines whose home directories
    differ renders the same block on each."""
    src_path = Path(src)
    template = src_path / BASE_AGENTS_TEMPLATE
    if project and (src_path / BASE_PROJECT_TEMPLATE).is_file():
        template = src_path / BASE_PROJECT_TEMPLATE
    elif not template.is_file():
        template = src_path / "AGENTS.md"
    text = template.read_text(encoding="utf-8")
    agents_md = Path(dest).expanduser().resolve() / "AGENTS.md"
    return text.replace(AGENTS_MD_PLACEHOLDER, home_relative(agents_md))

home_relative(path)

path as POSIX text, written ~/<rest> when it is under the home directory and absolute otherwise.

Source code in src/dotagents/_resources.py

def home_relative(path: "str | os.PathLike[str]") -> str:
    """``path`` as POSIX text, written ``~/<rest>`` when it is under the home
    directory and absolute otherwise."""
    path = Path(path)
    try:
        rest = path.relative_to(Path.home().resolve())
    except (ValueError, RuntimeError):  # RuntimeError: no home directory
        return path.as_posix()
    return "~/" + rest.as_posix() if rest.parts else "~"

pyz_archive()

The .pyz this dotagents is imported from, or None for a plain install. Inside a zipapp a module's __file__ is a path INTO the archive (.../dotagents.pyz/dotagents/_resources.py), so the archive is the ancestor that is a file. It also holds the vendored runtime dependencies (duho, pathapi), importable from it by zipimport.

Source code in src/dotagents/_resources.py

def pyz_archive() -> "str | None":
    """The ``.pyz`` this dotagents is imported from, or None for a plain
    install. Inside a zipapp a module's ``__file__`` is a path INTO the
    archive (``.../dotagents.pyz/dotagents/_resources.py``), so the archive
    is the ancestor that is a file. It also holds the vendored runtime
    dependencies (duho, pathapi), importable from it by zipimport."""
    for parent in Path(__file__).parents:
        if parent.is_file():
            return str(parent)
    return None