Python Design Modularity

Python Design and Modularity

Overview

Readability-first design with explicit module contracts. Keep control flow, data movement, and ownership boundaries visible so code stays maintainable and safe to change.

Treat these recommendations as preferred defaults. When a default conflicts with project constraints, suggest a better-fit alternative and call out tradeoffs and compensating controls (tests, observability, migration, rollback).

When to Use

• Restructuring modules, packages, or ownership boundaries
• Breaking apart god classes or deeply nested hierarchies
• Choosing between composition and inheritance
• Applying Functional Core / Imperative Shell separation
• Planning a refactor that touches multiple modules
• Reviewing code for readability or architectural clarity

When NOT to use:

• Pure performance optimization — see python-concurrency-performance
• Error handling and resilience patterns — see python-errors-reliability
• Type contracts and protocol design — see python-types-contracts
• One-off script or throwaway code with no maintenance horizon

Quick Reference

• Keep control flow and data movement explicit.
• Keep module ownership and invariants explicit.
• Prefer composition by default.
• Apply Functional Core / Imperative Shell where it improves testability and separation of concerns.
• Separate behavior changes from structural refactors — never mix in the same commit.

Common Mistakes

• Refactoring behavior and structure simultaneously — conflates two kinds of risk, makes rollback harder, and obscures review.

Do one, then the other.

• Reaching for inheritance first — deep hierarchies couple unrelated concerns and make reasoning non-local.

Default to composition; inherit only when the "is-a" relationship is genuinely stable.

• Hidden module coupling — importing implementation details across boundaries creates invisible contracts.

Expose explicit public APIs and keep internals private.

• Premature abstraction — extracting a shared interface before the second or third concrete use leads to wrong abstractions that are expensive to undo.

Wait for duplication to reveal the real seam.

• Ignoring the Functional Core / Imperative Shell split — mixing I/O with business logic makes unit testing painful and increases the blast radius of changes.

Push side effects to the edges.

Scope Note

• Treat these recommendations as preferred defaults for common cases, not universal rules.
• If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
• When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

Invocation Notice

• Inform the user when this skill is being invoked by name: python-design-modularity.

References

• references/design-rules.md
• references/readability-and-complexity.md
• references/module-boundaries.md
• references/functional-core-shell.md
• references/refactor-guidelines.md

Code Design and Readability

Outcome

Code that is easy to reason about, modify, and test under change.

Primary Rules

• Prefer explicit control flow and explicit data movement.
• Keep naming domain-first and keep functions narrowly purposeful.
• Keep module boundaries strict; avoid architectural leakage and shared "common/utils" dumping.
• Bias toward simple, golden-path implementations before adding defensive complexity.

Reference Map

• readability-and-complexity.md
• module-boundaries.md
• functional-core-shell.md
• refactor-guidelines.md

Functional Core and Imperative Shell

Outcome

Business rules are deterministic and side effects are isolated.

Core Rules

• Keep core logic pure: deterministic input -> output transformations.
• Do not perform I/O, logging, env reads, time/random calls, or network in core functions.
• Pass external values (time, IDs, configuration, randomness) into the core as parameters.
• Return plain data and decisions from the core; avoid framework-bound return types.

Shell Rules

• Shell code adapts external input into core input.
• Shell orchestrates side effects: persistence, network, logging, messaging.
• Shell applies effects produced by core decisions.
• Shell should translate and route; core should decide.

Testing Split

• Unit-test core logic heavily with no mocks by default.
• Keep shell tests thin and focused on integration contracts.
• Verify boundary adapters preserve context and type expectations.

Module Boundaries and Ownership

Outcome

Modules remain independently understandable and safely evolvable.

Ownership Rules

• Each module owns its data, invariants, and internal structures.
• Keep persistence models and storage details private to the owning module.
• Cross-module interaction must use explicit public interfaces.

Data Sharing Rules

• Share only the minimum data required for the use case.
• Prefer immutable DTO/value-style payloads for cross-module exchange.
• Do not expose mutable internal state across boundaries.

Consistency Rules

• Treat each module as the unit of immediate consistency.
• Do not span transactions across module boundaries.
• Use events, jobs, or queued commands for cross-module workflows.
• Design cross-module flows for eventual consistency by default.

Service Interaction Rules

• Avoid direct service-to-service domain call chains in request handling.
• During request handling, allow orchestration interactions only:
• event publication
• job/command enqueueing
• infrastructure services (auth, logging, metrics)
• Keep business decisions local to the handling module.

Architectural Intent

• Prefer a modular monolith with strict boundaries over premature microservice splits.
• Use service decomposition only when team/org scaling needs exceed module-level separation.

Readability and Complexity

Outcome

Implementations are simple to explain, review, and evolve.

Readability Rules

• Prefer explicit over implicit behavior.
• Keep control flow flat where possible; extract helpers when nesting obscures intent.
• Favor one obvious implementation path over multiple equivalent styles in the same module.
• Use names that expose business meaning, not framework or transport details.

Simplicity and Defense

• Start with the minimal golden path that satisfies the contract.
• Add defensive checks when failure modes are realistic and tested.
• Avoid speculative abstractions for hypothetical reuse.
• If a design is hard to explain in a short review comment, simplify before extending.

Reuse and Composition

• Prefer composition for combining capabilities.
• Use inheritance when true subtype substitution improves usability and reduces glue code.
• Avoid heavy decorator layers when plain functions, context managers, or partials are clearer.

Refactor Guidelines

Safe Refactoring Rules

• Preserve externally visible behavior unless change is intentional.
• Add or confirm characterization tests before risky refactors.
• Refactor in small, behavior-preserving increments.
• Keep each increment reversible.
• Verify each increment with local checks.

Sequencing Rules

• Separate behavior changes from structural refactors whenever possible.
• If separation is impossible, isolate intent with small commits and explicit notes.
• Move/rename first, then change logic.
• Avoid broad renames and logic rewrites in one step.

Anti-Patterns to Avoid

• Premature abstraction.
• Deep utility dumping (utils/common/shared) without ownership.
• Mixing architecture migration with feature delivery in one step.
• Large renames plus behavior changes without clear isolation.
• Mechanical churn that does not improve readability, boundaries, or correctness.