Skip to content

psiqdk.algorithms._mapping_expand

.. Copyright © 2026 PsiQuantum Corp. All rights reserved. PSIQUANTUM CORP. CONFIDENTIAL This file includes unpublished proprietary source code of PsiQuantum Corp. The copyright notice above does not evidence any actual or intended publication of such source code. Disclosure of this source code or any related proprietary information is strictly prohibited without the express written permission of PsiQuantum Corp.

Expand ``"*":`` wildcards: a **string** ending in ``.*`` is one legacy module; a **YAML list** of
such strings merges several modules into one flat curated namespace.

Under ``aliased``, the same wildcard shape is supported, but module specs are **fully qualified**
(e.g. ``psiqdk.workbench.arithmetic.*``) relative to the environment, not ``domains.old``.

When ``legacy_src_root`` is set (directory that **contains** a ``psiqworkbench/`` package
directory—typically the Workbench repository root, or ``src/`` after a ``src/`` layout migration),
public names are discovered by static analysis (AST) so rendering the mapping tables does not
import ``psiqworkbench`` (avoid heavy / optional deps).

Otherwise falls back to importing ``<domains.old>.<module>`` (same as runtime resolution).

assert_no_deprecated_root_blocks 

assert_no_deprecated_root_blocks(
    raw: dict[str, Any],
) -> None

Curated mapping must not use removed top-level root override blocks (use remapped['*'] only).

expand_star_wildcards 

expand_star_wildcards(
    node: dict[str, Any],
    domains_old: str,
    *,
    legacy_src_root: Path | None = None,
) -> dict[str, Any]

Recursively replace dicts that are only {"*": ...} (quote * in YAML):

  • "*": pkg.mod.* (string) → flat mapping from that one legacy module.
  • "*": [ "a.*", "b.*" ] (list) → union of those modules (collision if same export, different spec).

expand_remapped_module_redirects 

expand_remapped_module_redirects(
    node: dict[str, Any],
    domains_old: str,
    *,
    legacy_src_root: Path | None = None,
    parts: tuple[str, ...] = (),
) -> tuple[dict[str, Any], dict[str, str]]

Expand remapped module leaves into public-name exports and collect new-subpath → old-subpath redirects.

opcodes: ops.opcode_constants becomes the same export mapping as opcodes: {"*": ops.opcode_constants.*}, while also recording the module redirect used by the migration assistant for import psiqworkbench.ops.opcode_constants.

extract_remapped_star_to_root 

extract_remapped_star_to_root(
    remapped: dict[str, Any],
) -> tuple[dict[str, Any], dict[str, Any]]

Pop remapped['*'] (if present) into a flat root export map (export name → legacy spec).

extract_remapped_star_to_workbench_root 

extract_remapped_star_to_workbench_root(
    remapped: dict[str, Any],
    explicit_workbench_root: dict[str, Any] | None = None,
) -> tuple[dict[str, Any], dict[str, Any]]

Deprecated name for :func:extract_remapped_star_to_root.

explicit_workbench_root / workbench_root / algorithms_root YAML blocks are no longer supported; pass None or omit the second argument.

expand_aliased_star_wildcards 

expand_aliased_star_wildcards(
    node: dict[str, Any],
    *,
    legacy_src_root: Path | None = None,
) -> dict[str, Any]

Expand "*": under aliased like :func:expand_star_wildcards, but module specs are fully qualified (e.g. "*": psiqdk.workbench.utils.bit_utils.* or a YAML list of such strings).

expand_workbook_trees 

expand_workbook_trees(
    raw: dict[str, Any],
    *,
    legacy_src_root: Path | None = None,
) -> dict[str, Any]

Return a copy of the loaded mapping with remapped / renamed / aliased expanded.

default_legacy_src_root_next_to_mapping 

default_legacy_src_root_next_to_mapping(
    mapping_file: Path, domains_old: str = "psiqworkbench"
) -> Path | None

Find a directory containing <domains_old>/ by walking upward from the mapping file.

Also checks for a sibling psiq_workbench checkout (common when several repos are checked out side by side) and, as a last resort, an installed distribution for wildcard expansion. Falls back to the installed psiqworkbench location when domains_old is psiqworkbench and no directory match is found on-disk.