python-project-structure

Design Python project structures with explicit interfaces and cohesive modules.

2|2|Updated Jan 21, 2026

Search Tags:#python #project-structure #package-design #module-architecture #__all__

Ready to run

npx skills add https://github.com/NorkzYT/claude-code-autopilot --skill python-project-structure-norkzyt

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: python-project-structure
Source: https://github.com/NorkzYT/claude-code-autopilot/tree/main/.claude/skills/python-project-structure
Command: npx skills add https://github.com/NorkzYT/claude-code-autopilot --skill python-project-structure-norkzyt

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps teams design Python projects with clear module boundaries and explicit public interfaces, reducing onboarding time and maintenance overhead.

Core Features & Use Cases

One Concept Per File: Focused files promote readability and easier maintenance; split services, models, and APIs into separate modules.
Explicit Public APIs with all: Expose a clean public surface and keep internals private.
Flat Directory Structures: Favor shallow hierarchies to simplify imports and navigation.
Test File Organization: Choose colocated or parallel tests and apply consistently.

Quick Start

Create a new Python project layout with a top-level src/ package named after your project, a tests/ directory for tests, and a pyproject.toml or setup.cfg for configuration. Example structure: myproject/ ├── src/ │ └── myproject/ │ ├── init.py │ ├── services/ │ ├── models/ │ └── api/ ├── tests/ ├── pyproject.toml └── README.md

Frequently Asked Questions about python-project-structure

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

What is the best way to structure a Python project to keep modules cohesive?▼

To structure a Python project, you should enforce explicit interfaces and cohesive modules by placing one concept per file, favoring flat directory hierarchies with a top-level src/ layout, and defining public APIs using __all__.

How do I define a public API in a Python package?▼

To define a public API in a Python package, use the __all__ variable within your modules to expose a clean public surface, which explicitly declares accessible classes and functions while keeping internal implementation details private.

How do I set up a new Python project layout with pyproject.toml?▼

To set up a Python project layout, create a top-level src/ directory containing a package named after your project, a tests/ directory, and a pyproject.toml file, separating services, models, and APIs into focused modules under the src/ folder.

Should I colocate Python test files or use a parallel tests directory?▼

When organizing Python test files, you should choose either colocated tests or a parallel tests/ directory and apply the chosen convention consistently across the codebase to ensure the structure remains predictable and maintainable.

Why use a flat directory structure for Python modules?▼

You should use a flat directory structure for Python modules to simplify imports and navigation, which reduces onboarding time and maintenance overhead by keeping hierarchies shallow and promoting focused, single-concept files.