__init__.py — the public façade

Part 1 · What is an __init__.py even for?

The one job: "When someone types from circuitgenome.recognizer import parse, what do they get — and what stays hidden?"

A Python package is a folder. Import the folder and Python runs its __init__.py.

This file has no algorithms. It's a storefront window: it reaches into the back rooms (the five modules you've just studied) and arranges the best items where customers can reach them.

Two moves, and that's the entire file:

• Re-import the useful names up to the package's top level.
• Declare __all__ — the curated list that defines the public API and what from … import * exposes.

Because you've read every other page, this file now reads like a table of contents you already know by heart. That's exactly why it comes last.

Part 2 · The whole public surface, on one screen

Every name the package exports, and where it really lives:

Part 3 · Four verbs, one pipeline

The four exported functions are the three-layer pipeline — this is the whole package in four calls:

Read the Returns column top to bottom and you're reading the data-flow map from the models page — every output type feeds the next verb's input. The façade makes that pipeline literally the shape of the API.

Part 4 · Why re-export instead of making callers dig?

Without this file, a caller would have to know the internal file layout:

# painful: couples callers to the private module structure
from circuitgenome.recognizer.netlist_parser import parse
from circuitgenome.recognizer.subcircuit_recognizer import recognize

With it, one flat, stable surface:

# clean: the package's public contract
from circuitgenome.recognizer import parse, recognize, assign_slots

The real payoff: the maintainer is now free to rename, split, or merge the internal modules — as long as __init__.py keeps re-exporting the same eleven names, no caller breaks. The façade is a seam between the public promise and the private implementation.

Why is it called __all__? I like this name.

It's literally "all the things this module means to offer." It does double duty: it documents the public API for a human reader, and it tells from recognizer import * exactly which names to bind. Naming the export list all makes both jobs self-evident.

Part 5 · A full run, end to end

Everything you've read across six pages, in one worked call sequence:

from circuitgenome.recognizer import parse, recognize, group_by_category

# Layer 0 — text → structured netlist
netlist = parse(spice_text)

# Layer 1 — netlist → every candidate structure (overlaps and all)
sr = recognize(netlist)

# Layer 2 (topology-free) — candidates → ranked functional groups
fbr = group_by_category(sr, netlist)

for block, cats in fbr.groups.items():
    for cat, structs in cats.items():
        print(block, cat, structs[0].name)   # best guess per category

Part 6 · The hidden idea

A good __init__.py encodes an architectural claim without a single statement of logic:

Look at what it omits: no hooks, no load_patterns, no private helpers. That silence is the design. Hooks are reached only indirectly, by the "module:function" strings inside pattern YAML — so they're an extension point, not a public function. By exporting exactly the eleven names that make up the layered contract, the file draws a crisp line between "the promise" and "how it's kept."

And it's the perfect capstone for the whole tour: the very structure of __all__ — seven nouns, four verbs, three layers — is the summary of everything the package does.

In one sentence: __init__.py is a logic-free storefront window that curates eleven names — the pipeline's seven data shapes and four verbs — into one stable public API, hiding every private helper and hook behind it.

You've finished the tour. Head back to the Overview for the whole-package map, or revisit any layer from the nav above.