gh-jwplatta-prompt-library-claude-plugins-pythonic/skills/python-project-setup/project-structure-template.md

Python Project Structure Template

Standard Directory Layout

project_name/
├── .vscode/                    # VSCode editor configuration
│   ├── settings.json          # Python, ruff, mypy settings
│   └── launch.json            # Debug configurations
├── src/                       # Source code directory
│   └── project_name/          # Main package (use underscores)
│       ├── __init__.py        # Package initialization
│       ├── main.py            # Entry point (if applicable)
│       ├── models/            # Data models (Pydantic)
│       ├── services/          # Business logic
│       ├── api/               # API routes (if using FastAPI)
│       └── utils/             # Utility functions
├── tests/                     # Test directory
│   ├── __init__.py
│   ├── conftest.py            # Pytest fixtures
│   ├── test_main.py           # Test files (prefix with test_)
│   └── integration/           # Integration tests
├── docs/                      # Documentation
│   ├── index.md
│   └── api/                   # API documentation
├── .github/                   # GitHub configuration
│   ├── workflows/             # CI/CD workflows
│   │   └── test.yml
│   └── dependabot.yml         # Dependency updates
├── .gitignore                 # Git ignore patterns
├── .python-version            # Python version for pyenv
├── pyproject.toml             # Project metadata and dependencies
├── README.md                  # Project documentation
└── uv.lock                    # Locked dependencies (generated)

File Naming Conventions

• Python packages: Use underscores (e.g., my_package)
• Project names: Use underscores (e.g., my_project)
• Test files: Prefix with test_ (e.g., test_models.py)
• Private modules: Prefix with _ (e.g., _internal.py)

Directory Purpose

src/project_name/

Main application code organized by function:

• models/ - Data classes, Pydantic models, database models
• services/ - Business logic and service layer
• api/ - API endpoints and route handlers (FastAPI)
• utils/ - Helper functions and utilities
• config/ - Configuration management

tests/

Test files mirroring the structure of src/:

• Unit tests for each module
• Integration tests in integration/ subdirectory
• conftest.py for shared fixtures
• Use pytest conventions

docs/

Project documentation:

• User guides
• API documentation
• Architecture decisions
• Setup instructions

Module Organization

Each Python module should follow this pattern:

# frozen_string_literal equivalent in Python
"""Module docstring describing purpose."""

from typing import Any, Optional

import third_party_package

from project_name import local_module


class MyClass:
    """Class docstring."""

    def __init__(self, param: str) -> None:
        """Initialize with param."""
        self.param = param

    def method(self) -> str:
        """Method docstring."""
        return self.param


def public_function() -> None:
    """Public function docstring."""
    pass


def _private_function() -> None:
    """Private helper function."""
    pass

Best Practices

1. Use src/ layout: Prevents accidental imports of local code
2. Type hints everywhere: Add type annotations to all functions
3. Docstrings: Document all public classes and functions
4. Test organization: Mirror source structure in tests
5. Configuration: Use environment variables or config files, never hardcode
6. Dependencies: Separate dev dependencies from runtime dependencies