Python同层级subpackage相互依赖时的包结构设计疑问

Great question—this is a super common dilemma when structuring Python packages, and there’s no one-size-fits-all answer, but there are some Pythonic guidelines to help you make the right call.

When to Keep Them as Independent Subpackages #

• Clear functional boundaries: If the two subpackages handle distinct, separate tasks (even if one relies on the other’s output), keep them split. For example, a data_processing subpackage that cleans raw data, and a visualization subpackage that turns that cleaned data into charts—their core jobs are unrelated, so splitting makes them easier to maintain and reuse individually.
• Future flexibility: If you anticipate either subpackage might be pulled out into its own standalone package or used by other projects independently, keeping them separate lowers the barrier to that kind of refactor later.
• Solvable circular dependencies: If the mutual dependency is mild (e.g., one uses a utility function from the other, and vice versa), you can often fix circular imports with lazy imports (importing inside functions instead of at the top of modules). If that works cleanly, there’s no need to merge—Python lets you handle this without sacrificing structure.

When to Merge into a Single Subpackage #

• Deep core coupling: If the two subpackages are so intertwined that you can’t meaningfully run one without the other, merging makes sense. For example, a parser subpackage that tokenizes text and an ast subpackage that builds abstract syntax trees from those tokens—changing one almost always requires changes to the other, so splitting them just creates unnecessary friction.
• Unresolvable circular dependencies: If lazy imports or other tricks don’t fix the circular import issue, and you’re forced to write messy, hacky code to make the split work, merge them. Python’s philosophy prioritizes readability over cleverness, so avoiding ugly import hacks is more Pythonic than forcing an artificial split.
• Unified external API: If the two subpackages are meant to be used together as a single feature (e.g., auth and sessions for user authentication), merging them gives users a cleaner, more intuitive API. No one wants to import from two separate subpackages just to use a single cohesive feature.

Additional Tips #

• Extract common code: If the mutual dependency comes from shared logic (like constants, helper functions, or base classes), pull that code into a top-level common or utils subpackage. This lets both sibling subpackages depend on the common code instead of each other, keeping them independent while reducing coupling.
• Follow the "Principle of Least Surprise": Ask yourself: would another developer looking at your package structure immediately understand what each subpackage does? If they have to jump back and forth between the two to follow logic, merging might be the clearer choice.

内容的提问来源于stack exchange，提问作者matt murray