Repository navigation
Six objects in the deprecated shims' __all__ are missing from the top-level quantecon namespace #853
Description
Summary
While refreshing the API-reference docs in #850, I found that six objects are listed in the deprecated compatibility shims' __all__ but were never re-exported into the top-level quantecon namespace. As a result, from quantecon import <name> raises ImportError for these six today — even though each shim's own DeprecationWarning explicitly tells users to import them "from the quantecon namespace."
The six objects
| Object | Shim (in its __all__) |
Implementation module | Re-exported in quantecon/__init__.py? |
|---|---|---|---|
ckron |
quantecon.ce_util |
_ce_util |
No |
gridmake |
quantecon.ce_util |
_ce_util |
No |
annotate_nodes |
quantecon.graph_tools |
_graph_tools |
No |
num_compositions_jit |
quantecon.gridtools |
_gridtools |
No |
simulate_linear_model |
quantecon.lss |
_lss |
No |
solve_discrete_riccati_system |
quantecon.matrix_eqn |
_matrix_eqn |
No |
The curation looks deliberate — sibling objects in the same modules are promoted while these are not: LinearStateSpace but not simulate_linear_model; solve_discrete_riccati but not solve_discrete_riccati_system; num_compositions but not num_compositions_jit. _ce_util is not imported into __init__.py at all. There is even a #->Propose Delete From Top Level block in __init__.py, so the top-level surface has clearly been managed by hand.
Why it matters
1. The deprecation guidance is currently broken for these six. Accessing one through its shim, e.g. quantecon.lss.simulate_linear_model, emits:
Please use
simulate_linear_modelfrom thequanteconnamespace, thequantecon.lssnamespace is deprecated. You can use the following instead:from quantecon import simulate_linear_model.
…but from quantecon import simulate_linear_model then raises ImportError. A user who follows the warning hits a dead end. This is independent of the docs — it's a package-level inconsistency.
2. It surfaced as a docs question in #850. That PR moves the base-level API pages from documenting the deprecated shim / private module to documenting the public objects in the quantecon namespace. Because these six aren't in that namespace, they can't be documented as quantecon.<name>. For reference, how each version represents them:
| Version | Rendered heading for these six |
|---|---|
Published latest (main) |
quantecon.lss.simulate_linear_model, quantecon.ce_util.ckron, … (deprecated shim namespace) |
| #850 head, earlier commit | quantecon._lss.simulate_linear_model, … (private implementation module) |
| #850 head, current commit | dropped from the docs (they don't resolve as quantecon.<name>) |
Options (from the #850 discussion)
- Promote to
quantecon.*— add the six toquantecon/__init__.py. The docs then renderquantecon.simulate_linear_modeletc. cleanly and consistently, and the shims' "import from thequanteconnamespace" guidance finally works. This expands the public API surface by six names. - Document via the implementation module — the docs generator falls back to
quantecon._lss.simulate_linear_modelfor just these six. No API change and nothing is dropped, but those six pages show a private_moduleheading. - Omit from the API reference — treat all six as internal. Cleanest public reference and no API change, but drops six functions that the currently-published docs still show.
For discussion
A per-object call may make sense rather than one blanket choice — e.g. num_compositions_jit reads as a deliberately-internal numba-jitted variant of the public num_compositions and is a natural "keep internal", whereas simulate_linear_model and solve_discrete_riccati_system look like reasonable public functions whose omission may simply be an oversight.
Whatever we decide, two cleanups fall out of it:
- Reconcile each shim's
__all__(and its deprecation message) with whatever the top-level namespace actually exports, so the guidance stops pointing at imports that don't exist. - DOC: Refresh contributing guide and fix stale docs build config #850 should not merge while it silently drops these six; the resolution here unblocks it.
Raised so the team can weigh in — happy to implement whichever direction we land on. Related: #850, #852.
Activity
mmcky commentedon Jul 23, 2026
Re-confirmed this while auditing the docs in #864. Three things turned up that I think narrow the decision.
None of the six has ever been in
quantecon/__init__.py.git log -S<name> -- quantecon/__init__.pyreturns no commits for any of them. So this is not a regression or an accidental omission — the shims'__all__mirrors the private implementation module's public surface, not the top-level namespace. Read that way, the__all__lists are over-broad rather than the namespace being under-populated, which slightly favours stripping over exporting.annotate_nodeshas no docstring at all. The other five do. Promoting an undocumented function to public API seems like the wrong direction, and it would render as an empty entry on thegraph_toolspage.Emptying
ce_util.__all__is not a clean option.write_base_moduleinqe_apidoc.pyfalls back to a plainautomoduledirective when__all__is empty or absent:For
ce_util, whose entire__all__is['ckron', 'gridmake'], stripping both would emit.. automodule:: quantecon.ce_util— re-importing the deprecated shim during the docs build and emittingDeprecationWarnings on every attribute access. That is exactly the behaviour #850 set out to eliminate. Sockronandgridmakemust either be exported or lose their page entirely; there is no quiet middle option for that module. The other four shims keep other entries, so stripping a single name fromgraph_tools,gridtools,lssormatrix_eqnleaves those pages intact.Suggested split, if it is useful as a starting point: export
ckron,gridmake,simulate_linear_modelandsolve_discrete_riccati_system— all documented, all genuinely user-facing, and all already reachable via the shim path the deprecation message points at. Stripannotate_nodes(undocumented) andnum_compositions_jit(a jit dispatcher, and an implementation detail alongside the already-publicnum_compositions) fromgraph_tools.__all__andgridtools.__all__.For context on urgency: these six are the only remaining warnings in the Sphinx build after #864, and
docs/source/tools/ce_util.rstcurrently renders with a title and no body. #864 deliberately leaves them untouched, and its CI docs job builds without-Wfor that reason — resolving this would let the build be made warning-clean.DOC: repo-wide documentation consistency audit (#864)