mafw.devtools.toolchain.filtering

Tool filtering utility for the toolchain command group.

This module provides resolve_tools(), a shared function used by all CLI subcommands to determine which tools to process based on the --include-host, -i/--include, and -e/--exclude options. It enforces mutual exclusivity between include and exclude filters, warns on unrecognized tool names, and preserves the original registration order from the registry.

Functions

resolve_tools(registry, *[, include, ...])

Filter the registry based on CLI options.
mafw.devtools.toolchain.filtering.resolve_tools(registry: ToolRegistry, *, include: tuple[str, ...] = (), exclude: tuple[str, ...] = (), include_host: bool = False) → list[ToolChainTool][source]

Filter the registry based on CLI options.

The filtering pipeline proceeds in order:

  1. Reject mutually exclusive include and exclude arguments.

  2. Start with all tools from the registry (preserving insertion order).

  3. If include_host is False, remove tools with category "host".

  4. If include is non-empty, keep only tools whose name is in the set (emit a warning for each unrecognized name).

  5. If exclude is non-empty, remove tools whose name is in the set (emit a warning for each unrecognized name).

Parameters:

  • registry – The central tool registry to query.

  • include – Tool names to include exclusively. Only tools whose name matches one of these values will be returned.

  • exclude – Tool names to exclude. Tools whose name matches one of these values will be removed from the result.

  • include_host – When False (the default), tools with category="host" are excluded before any name-based filtering.

Returns:

A list of tools in their original registration order.

Raises:

DevtoolsError – If both include and exclude are non-empty (mutual exclusivity violation).