refactor: one lazy import left, and it is the only real cycle

[FBumann]

Stacked on #107. Retarget to main once that merges; the diff below is this PR's own.

The package had eight in-function linopy_yaml imports. One broke a genuine cycle. The other seven broke nothing — and made that one impossible to spot.

The one real cycle went through a private name

piecewise.py and lowering.py imported each other lazily, and piecewise reached for lowering._lower_expr, using it as a predicate and discarding the result:

def _expr_dims(schema, text, ctx):
    from linopy_yaml.lowering import _lower_expr   # private, in-function
    ...
    _lower_expr(resolved, schema, ctx)             # called for its exceptions only
    return dims_of(resolved, schema, ctx)

The dependency is real and its direction is right: a formulation sits above lowering, and it needs to know whether a link expression is in the streaming subset. So lowering now offers a public name for exactly that —

def check_core_subset(node, schema, context) -> None:
    """The subset test *is* the lowering — there is no second definition of
    what the engine accepts, which is what stops the two from drifting."""
    _lower_expr(node, schema, context)

— piecewise imports it at module level, and only the reverse edge stays lazy. It is now the sole entry in DELIBERATE_LAZY_IMPORTS, with the reason written down.

That guard was load-bearing, and untested

I checked whether it could just go (by removing the call, not by monkeypatching — the first attempt patched lowering._lower_expr globally, which also disabled lowering's own use and falsely reported the guard as dead).

With it removed, p ** 2 and p * p in a piecewise: link are still refused — by lowering, on the expanded declarations:

LanguageError: constraint 'cost_curve_link0': operator '**' is not in the language

cost_curve_link0 is a declaration the formulation generated. The user wrote cost_curve, link 0. The guard exists to keep the message pointing at the file. Two tests now pin that, so the next person to find this "redundant" call has the reason in front of them.

The other six were leftovers

resolution.py imported errors, where_parser and helpers in-function while already importing them at the top; dimensions.py and validation.py deferred imports of modules with no path back. All hoisted.

A new architecture test keeps it that way, and fails in both directions — an undeclared in-function import, or a declaration for an import that no longer exists:

DELIBERATE_LAZY_IMPORTS = {
    ('lowering.py', 'linopy_yaml.piecewise'): (
        'formulations expand before lowering, and expanding needs the subset '
        'test that lowering defines — piecewise imports lowering at module '
        'level, so this direction has to stay lazy'
    ),
}

ARCHITECTURE.md gains this as hard rule 0, since it is the mechanical form of "the layers are ordered".

It earned itself on the rebase. #104 landed while this was open and added a ninth in-function import — piecewise.py → relational.arrow. The test failed on rebase and named it. It turned out to be hoistable (arrow.py imports pyarrow lazily itself, so module-level costs nothing), so that is a tenth import gone rather than a second declaration.

tidy_sources → sources.py

Rebased onto #104's Arrow rewrite of that function, so sources.py carries the new body, not the pandas one. It was in lowering.py, sharing no code and no concept with anything there: lowering turns an AST into a plan and touches no data; that function touches only data and knows nothing about expressions. They were in one file because api.build calls them on consecutive lines, which is not a reason.

Verification

uv run pytest — 311 passed, 1 xfailed (3 new) · ruff check and ruff format --check clean · pyrefly check 0 errors.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8118e0a0-5a71-43dc-ad36-821dd37e018b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/untangle-language-layer

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}