cli.meta.roles.applications.bond package¶

Submodules¶

cli.meta.roles.applications.bond.cli module¶

Serve the editable bond matrix, or export it as a static file.

cli.meta.roles.applications.bond.cli.build_parser() → ArgumentParser¶

cli.meta.roles.applications.bond.cli.main(argv: list[str] | None = None) → int¶

cli.meta.roles.applications.bond.edit module¶

Write a single bond scalar back into a role’s meta/services.yml.

The file is edited line by line rather than parsed and re-dumped: these files carry # nocheck: directives and hand-tuned ordering that a YAML round-trip would drop.

exception cli.meta.roles.applications.bond.edit.EditError¶

Bases: Exception

Raised when the requested bond cannot be written.

cli.meta.roles.applications.bond.edit.parse_bond(raw: str) → float | None¶: Return the bond a user typed, or None when they cleared the field.

cli.meta.roles.applications.bond.edit.set_bond(roles_dir: Path, role: str, service_key: str, bond: float | None) → str¶

Set, or with bond=None remove, <service_key>.bond in role.

Parameters:

roles_dir – directory holding the role directories.
role – the consumer role whose file declares the bond.
service_key – the top-level key inside that role’s services file.
bond – the new value, or None to drop the declaration entirely.

Returns:

The value as it now stands in the file, or “” when it was removed.

cli.meta.roles.applications.bond.matrix module¶

Read every services.<key>.bond and resolve it to a role-to-role edge.

bond states how tightly a role couples to the service it declares: >= 1 keeps the partner on the same host, < 1 lets it live on its own. The value sits on the consumer’s side of the relation, so the pair is directed and the two directions of one pair need not agree.

cli.meta.roles.applications.bond.matrix.collect_edges(roles_dir: Path) → dict[tuple[str, str], dict[str, Any]]¶

Return {(consumer, provider): {bond, service_key, enabled}}.

A role’s entry for its own entity is skipped: a role does not bond to itself, and those entries carry unrelated topics such as users or domains.

cli.meta.roles.applications.bond.matrix.participants(edges: dict[tuple[str, str], dict[str, Any]]) → list[str]¶: Return every role on either end of a bond, in stable order.

cli.meta.roles.applications.bond.render module¶

Render the bond matrix as an HTML page, optionally editable.

Every cell carries both directions of one pair, row-to-column above column-to-row, because a bond is declared on the consumer’s side and the two need not agree. Brightness is the bond: black for none, white for 1.

cli.meta.roles.applications.bond.render.render(edges: dict[tuple[str, str], dict[str, Any]], roles: list[str], *, editable: bool = False) → str¶

Return the full HTML page for the given edges.

Parameters:

edges – the collected {(consumer, provider): edge} mapping.
roles – every participating role, in the order rows and columns take.
editable – wire the cells to the server’s write endpoint.

cli.meta.roles.applications.bond.render.render_json(edges: dict[tuple[str, str], dict[str, Any]]) → str¶: Return the same data as JSON, for a caller that wants to post-process.

cli.meta.roles.applications.bond.render.shade(bond: float) → tuple[str, str]¶: Return the (background, foreground) pair for a bond between 0 and 1.

cli.meta.roles.applications.bond.serve module¶

Serve the bond matrix on localhost and write every cell edit back to disk.

The edge map is built once at startup and kept in step with the writes this server performs, so a role file edited by hand elsewhere needs a restart.

cli.meta.roles.applications.bond.serve.serve(roles_dir: Path, edges: dict[tuple[str, str], dict[str, Any]], port: int) → tuple[ThreadingHTTPServer, str]¶

Return a server bound to loopback and the URL it listens on.

Parameters:

roles_dir – directory the writes land in.
edges – the collected edge map, mutated in place as edits arrive.
port – the port to bind, or 0 to let the OS pick one.

Module contents¶

Render the bond matrix: which roles couple to which, and how tightly.