utils.meta package

Submodules

utils.meta.port_bands module

Read PORT_BANDS from group_vars/all/08_networks.yml.

The canonical bands map lives there as a single key. The CLI helpers and the lint test consult this module so the bands stay in one place.

exception utils.meta.port_bands.PortBandsError

Bases: ValueError

Raised when the PORT_BANDS map cannot be loaded or used.

utils.meta.port_bands.available_categories(scope: str) → list[str]
utils.meta.port_bands.load_port_bands() → dict[str, dict[str, dict[str, int]]]

Return the full PORT_BANDS map keyed by <scope>.<category>.

utils.meta.port_bands.lookup_band(scope: str, category: str) → tuple[int, int] | None

utils.meta.scan module

Walk the role tree to collect occupied ports and subnets.

Used by:

  • cli contributing network ports suggest gap-first port allocation suggestions

  • cli contributing network address suggest gap-first subnet allocation suggestions

  • tests/lint/… collision/band checks

Reads only roles/*/meta/{services,server}.yml files.

utils.meta.scan.host_bound_port_set() → dict[int, list[tuple[str, str, str, str]]]

Build the flat host-bound port map for the lint rule.

Returns {port: [(role, entity, scope, category), ...]}. Single-int local/public categories AND every integer in each relay span are included; internal is skipped.

utils.meta.scan.iter_port_assignments() → Iterable[tuple[str, str, str, str, int]]

Yield (role, entity, scope, category, port) for every single-int port.

internal is intentionally excluded — internal container ports live in per-container network namespaces and never collide.

utils.meta.scan.iter_relay_ranges() → Iterable[tuple[str, str, int, int]]

Yield (role, entity, start, end) for every public relay range.

utils.meta.scan.iter_role_dirs() → Iterable[Path]
utils.meta.scan.iter_subnets() → Iterable[tuple[str, ipaddress.IPv4Network]]

Yield (role, subnet) for every role that declares a local subnet.

utils.meta.scan.occupied_ports_for(scope: str, category: str) → list[int]

Return the sorted, de-duplicated list of host-bound ports in use for <scope>.<category>.

utils.meta.scan.occupied_relay_ranges() → list[tuple[int, int]]

Return the sorted list of (start, end) relay ranges in use.

utils.meta.scan.occupied_subnets(prefix_length: int) → list[IPv4Network]

Return all currently occupied subnets at the requested prefix length.

Module contents