Discovery Functions

inspect_asset

Look up an asset by ware ID, macro name, or component name. Tries ware first, then macro, then component.

from x4_catalog import inspect_asset

result = inspect_asset("energycells", Path("./game.db"))
if result:
    print(result["ware_id"], result["price_avg"])

Signature:

def inspect_asset(asset_id: str, db_path: Path | str) -> dict[str, Any] | None: ...

Returns a dict with all known information or None if not found.

search_assets

Search across wares, macros, components, datatypes, and keywords by case-insensitive substring match. Wares are searchable by resolved English name (e.g., “Energy Cells”), ID, group, and tags.

from x4_catalog import search_assets

results = search_assets("fighter", Path("./game.db"), type_filter="macro")
for r in results:
    print(f"{r['type']:10s} {r['id']}")

Signature:

def search_assets(
    term: str,
    db_path: Path | str,
    *,
    type_filter: str | None = None,
) -> list[dict[str, str]]: ...

Each result dict has keys: id, type, path, detail.

extract_macro

Extract a macro file by ID, resolving its virtual path through the index.

from x4_catalog import extract_macro

result = extract_macro(
    "ship_arg_s_fighter_01_a_macro",
    Path("./game.db"),
    Path("/path/to/X4 Foundations"),
    Path("./output"),
)
if result:
    print(f"Extracted to {result}")

Signature:

def extract_macro(
    macro_id: str,
    db_path: Path | str,
    game_dir: Path,
    output_dir: Path,
) -> Path | None: ...

Returns the path to the extracted file, or None if the macro is not found.

---