Python project organization, module architecture, and public API design. Use when setting up new projects, organizing modules, defining public interfaces with __all__, or planning directory layouts.

Python Project Structure & Module Architecture Design well organized Python projects with clear module boundaries, explicit public interfaces, and maintainable directory structures. Good organization makes code discoverable and changes predictable. When to Use This Skill Starting a new Python project from scratch Reorganizing an existing codebase for clarity Defining module public APIs with all Deciding between flat and nested directory structures Determining test file placement strategies Creating reusable library packages Core Concepts 1. Module Cohesion Group related code that changes together. A module should have a single, clear purpose. 2. Explicit Interfaces Define what's public with all . Everything not listed is an internal implementation detail. 3. Flat Hierarchies Prefer shallow directory structures. Add depth only for genuine sub domains. 4. Consistent Conventions Apply naming and organization patterns uniformly across the project. Quick Start Fundamental Patterns Pattern 1: One Concept Per File Each file should focus on a single concept or closely related set of functions. Consider splitting when a file: Handles multiple unrelated responsibilities Grows beyond 300 500 lines (varies by complexity) Contains classes that change for different reasons Pattern 2: Explicit Public APIs with all Define the public interface for every module. Unlisted members are internal implementation details. Pattern 3: Flat Directory Structure Prefer minimal nesting. Deep hierarchies make imports verbose and navigation difficult. Add sub packages only when there's a genuine sub domain requiring isolation. Pattern 4: Test File Organization Choose one approach and apply it consistently throughout the project. Option A: Colocated Tests Benefits: Tests live next to the code they verify. Easy to see coverage gaps. Option B: Parallel Test Directory Benefits: Clean separation between production and test code. Standard for larger projects. Advanced Patterns Pattern 5: Package Initialization Use init .py to provide a clean public interface for package consumers. Consumers can then import directly from the package: Pattern 6: Layered Architecture Organize code by architectural layer for clear separation of concerns. Each layer should only depend on layers below it, never above. Pattern 7: Domain Driven Structure For complex applications, organize by business domain rather than technical layer. File and Module Naming Conventions Use snake case for all file and module names: user repository.py Avoid abbreviations that obscure meaning: user repository.py not usr repo.py Match class names to file names: UserService in user service.py Import Style Use absolute imports for clarity and reliability: Relative imports can break when modules are moved or reorganized. Best Practices Summary 1. Keep files focused One concept per file, consider splitting at 300 500 lines (varies by complexity) 2. Define all explicitly Make public interfaces clear 3. Prefer flat structures Add depth only for genuine sub domains 4. Use absolute imports More reliable and clearer 5. Be consistent Apply patterns uniformly across the project 6. Match names to content File names should describe their purpose 7. Separate concerns Keep layers distinct and dependencies flowing one direction 8. Document your structure Include a README explaining the organization

python-project-structure