python-project-structure
Python project organization, module architecture, and public API design
by wshobsonFree
Description
python-project-structure is an agent skill from the wshobson/agents collection for organizing Python projects, their modules and their public interfaces. The aim is a layout where code is easy to find and changes are predictable. Its first core idea is module cohesion: group code that changes together, and give each module a single clear purpose. The skill covers defining a module's public API with __all__, so the parts meant for other code to use are explicit and everything else can change freely, and it helps decide between flat and nested directory structures as a project grows. It also covers where test files should live and how to organize a codebase that has become hard to navigate. The skill applies when starting a new Python project from scratch, reorganizing an existing codebase for clarity, defining public interfaces with __all__, choosing between flat and nested layouts, deciding how tests are placed, and creating reusable library packages. The layout advice fits both applications and libraries, and the right structure depends on the size and audience of the project, so the agent proposes a layout and the team confirms it. Reorganizing code moves files, so changes should be made in a separate commit and checked against the test suite. The skill is installed with the skills CLI from the wshobson/agents repository. Its skills.sh page showed about 14.4K installs and passing results from three security audits at the time of the scan.…
Highlights
- Module cohesion and single-purpose modules
- Explicit public APIs with __all__
- Flat versus nested directory layouts
- Test file placement
- Layouts for applications and libraries
- Installs with the skills CLI
Ratings & Reviews
No ratings yet
Be the first to rate python-project-structure.
People also visit
python-design-patterns
Fundamental design principles for writing maintainable, testable Python code
python-project-structure FAQ
What does this skill help with?
Organizing Python projects and modules so code is easy to find, and public interfaces are clear.
What is __all__ used for?
Defining a module's public API, so the parts meant for other code to use are explicit.
Does it cover tests?
Yes. It covers where test files should be placed.
Can it reorganize an existing project?
Yes. Reorganizing an existing codebase for clarity is one of the uses, and the moves should be checked against the test suite.
How do I install it?
Run npx skills add https://github.com/wshobson/agents --skill python-project-structure.
What security audits does it have?
skills.sh lists three audits: Gen Agent Trust Hub Pass, Socket Pass and Snyk Pass.
What are the best python-project-structure alternatives?
Popular alternatives to python-project-structure include python-design-patterns, golang-project-layout and django-patterns. See all python-project-structure alternatives