The decision needed
The _module.py private-plus-public-shim convention was applied to 21 of 23 top-level modules and to zero subpackage modules. A contributor cannot infer from the layout whether quantecon.markov.core is a supported import path or an implementation detail.
| Layer |
State |
| Top level, converted (21) |
_arma.py private + arma.py shim — consistent |
| Top level, not converted (2) |
distributions.py, quad.py — real public modules, no shim |
markov/ |
core, ddp, approximation, estimate, gth_solve, random, utilities — all public names |
game_theory/ |
15 public module names |
optimize/ |
7 public module names |
| One exception |
markov/_ddp_linprog_simplex.py is private, inconsistent with its siblings |
quad.py is the sharpest illustration: at 1,230 lines it is the single largest module in the package, fully public with no shim, directly contradicting the pattern applied to its 21 smaller neighbours.
Questions for the team
- Is
quantecon.markov.core a supported import path or an implementation detail?
- Was the December 2022 conversion intended to reach the subpackages, or was the top level always the whole scope?
- Do
distributions and quad join the converted set, or are they deliberately public?
- Is
markov/_ddp_linprog_simplex.py correctly private, or accidentally so?
This needs a written decision more than it needs code — recording it in the contributing guide is worth more than any refactor; the current state is not wrong so much as unstated. If the answer is "finish the convention", the execution should be a separate refactor issue and should land alongside the shim removal decided in #865, so users absorb one round of import churn rather than two. Close this thread with a summarised decision and spawn the concrete follow-up.
From the July 2026 technical-debt audit (AI-assisted; claims verified against 28d4b3b on 2026-07-25).
The decision needed
The
_module.pyprivate-plus-public-shim convention was applied to 21 of 23 top-level modules and to zero subpackage modules. A contributor cannot infer from the layout whetherquantecon.markov.coreis a supported import path or an implementation detail._arma.pyprivate +arma.pyshim — consistentdistributions.py,quad.py— real public modules, no shimmarkov/core,ddp,approximation,estimate,gth_solve,random,utilities— all public namesgame_theory/optimize/markov/_ddp_linprog_simplex.pyis private, inconsistent with its siblingsquad.pyis the sharpest illustration: at 1,230 lines it is the single largest module in the package, fully public with no shim, directly contradicting the pattern applied to its 21 smaller neighbours.Questions for the team
quantecon.markov.corea supported import path or an implementation detail?distributionsandquadjoin the converted set, or are they deliberately public?markov/_ddp_linprog_simplex.pycorrectly private, or accidentally so?This needs a written decision more than it needs code — recording it in the contributing guide is worth more than any refactor; the current state is not wrong so much as unstated. If the answer is "finish the convention", the execution should be a separate refactor issue and should land alongside the shim removal decided in #865, so users absorb one round of import churn rather than two. Close this thread with a summarised decision and spawn the concrete follow-up.
From the July 2026 technical-debt audit (AI-assisted; claims verified against
28d4b3bon 2026-07-25).