113 lines
3.7 KiB
Markdown
113 lines
3.7 KiB
Markdown
# 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:
|
|
|
|
```python
|
|
# 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
|