Multi-Board Libraries

Library rows can live at three scopes: global (user-wide), container (multi-board project), and per-sub-project. The methods here manage container-scope rows; cascades to every sub-project's lib-table happen automatically.

get_library_report()

Read all library tables across the container and its sub-projects.

mbs = kicad.get_mbs_schematic()
report = mbs.multi_board.get_library_report()

# User-wide tables
for row in report.global_rows:
    print(f"[global {row.kind}] {row.nickname}: {row.uri}")

# Container-scoped tables
for row in report.container_rows:
    print(f"[container {row.kind}] {row.nickname}: {row.uri}")

# Per-sub-project tables
for sub in report.sub_projects:
    print(f"\n{sub.name}:")
    for row in sub.rows:
        print(f"  [{row.kind}] {row.nickname} — {row.status}")

kind is symbol or footprint; status is SHARED, LOCAL, or CONFLICT. Sub-project tables are read directly from each sub-project's sym-lib-table / fp-lib-table regardless of whether it's open.

add_library(kind, nickname, uri, ...)

Add a row at the container scope. Replicates to every sub-project.

mbs.multi_board.add_library(
    kind="symbol",
    nickname="Project_Symbols",
    uri="${KIPRJMOD}/lib/project.kicad_sym",
    description="Project-specific symbols",
)

mbs.multi_board.add_library(
    kind="footprint",
    nickname="Project_Footprints",
    uri="${KIPRJMOD}/lib/project.pretty",
)

Optional kwargs: type, description, options, enabled (default True), visible (default True).

If a sub-project already has a non-shared local row with the same nickname AND matching URI/options, that row is promoted to shared in place; otherwise a conflict marker is set on that peer.

Returns: added, peers_replicated, peers_with_conflict.

delete_library(kind, nickname)

Remove a row from the container; cascades to every sub-project.

mbs.multi_board.delete_library("symbol", "Project_Symbols")

Returns deleted and peers_cleared. Idempotent: deleted=False when the row wasn't on the container.

share_library(kind, nickname, ...)

Promote a sub-project's local row to container scope.

mbs.multi_board.share_library(
    kind="footprint",
    nickname="Connectors",
    source_sub_project_path="/path/to/sub/project.kicad_pro",
)

Identify the source sub-project by source_sub_project_uuid or source_sub_project_path (UUID wins if both are passed). The sub-project must be loaded.

Returns shared, peers_replicated, peers_with_conflict.