A production-ready Python project template with a modern project structure and best practices. This template follows the src layout pattern and is designed to serve as a foundation for data science, machine learning, and general Python applications.
A well-structured Python repository is like a neat kitchen:
- Anyone can walk in and start cooking (coding)
- It's easy to find ingredients (code, data, configs)
- New chefs (team members) can contribute smoothly
- It helps with debugging, testing, scaling, and deploying
Modern AI and data science projects can become complex quickly, so a standardized structure prevents chaos as the codebase grows.
The src layout places your actual package code in a src directory separate from the project root.
Benefits of the src Layout:
- Prevents import confusion: Python's interpreter includes the current working directory in the import path. The src layout ensures you're always using the installed version of your package, not the development files.
- Cleaner installation: Only files meant to be importable are available after installation.
- Forces proper packaging: You must install your package to use it, ensuring your package configuration works correctly.
- Ideal for medium to large projects: Provides better separation and organization for growing codebases.
The flat layout places package code directly at the project root level, without a src directory.
Benefits of the Flat Layout:
- Simplicity: Easier to understand for beginners
- Less nesting: Fewer directory levels to navigate
- Direct imports: Can import modules without installation during development
- Best for small projects: Quick setup for simpler applications
| Layout | Best for | Pros | Cons |
|---|---|---|---|
| src layout | Medium to large projects, AI/ML | Safe imports, scalable, avoids bugs | Slightly more setup |
| flat layout | Small/simple scripts & packages | Simple, fast setup | Can become messy as project grows |
- Modern Python packaging with
pyproject.toml - Testing setup with pytest
- Code formatting with Black and isort
- Type checking with mypy
- Linting with flake8
- Docker support
- Makefile for common commands
- Structured for data science/ML projects
- CI/CD ready
- FastAPI integration for REST API development
project/
├── src/ # Source code (main package)
│ ├── __init__.py
│ ├── api/ # FastAPI application
│ │ ├── __init__.py
│ │ ├── app.py # FastAPI app and endpoints
│ │ └── server.py # Server startup functionality
│ ├── data/ # Data processing modules
│ ├── models/ # ML/AI model implementations
│ └── utils/ # Helper functions
├── tests/ # Unit and integration tests
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── data/ # Data files (often gitignored)
│ ├── raw/
│ └── processed/
├── notebooks/ # Jupyter notebooks for exploration
├── config/ # Configuration files
├── scripts/ # Utility scripts
├── Dockerfile # Containerization instructions
├── Makefile # Common automation commands
├── .gitignore # Specifies intentionally untracked files
├── pyproject.toml # Modern Python packaging config
└── README.md # Project overview and instructions
- Separation of Concerns: Code, tests, data, and configuration are clearly separated
- Modular Design: Each directory has a specific purpose, making navigation intuitive
- Scalability: The structure can grow with your project without becoming unwieldy
- Standardization: Follows modern Python best practices, making it familiar to other developers
- Ease of Testing: Dedicated test directories for different testing levels
- Configuration Management: Separates code from configuration
-
Clone the repository:
git clone https://github.com/yourusername/python-project-template.git cd python-project-template -
Install the package and development dependencies:
make install
-
Run the tests:
make test -
Run the example:
python -m src.hello
-
Run the API server:
python -m src.api.server
Then visit http://127.0.0.1:8000/docs to see the API documentation.
- Format code:
make format - Run linters:
make lint - Run tests:
make test - Clean build files:
make clean
The template includes a FastAPI application with the following endpoints:
- GET / - Root endpoint with API information
- POST /greeting - Create a personalized greeting
- GET /config - Get the application configuration
Access the interactive API documentation at http://127.0.0.1:8000/docs when the server is running.
Build and run the Docker container:
docker build -t python-project .
docker run -p 8000:8000 python-projectThis template implements several Python best practices:
- Proper Packaging: Uses pyproject.toml for modern Python packaging
- Type Hints: Encourages the use of Python type annotations
- Automated Testing: Setup for pytest and test organization
- Code Quality Tools: Black, isort, flake8, and mypy for code quality
- Dependency Management: Clear specification of dependencies
- Environment Isolation: Docker support for consistent environments
- Documentation: Comprehensive README and docstrings
- API Design: FastAPI for modern, type-safe API development with automatic documentation
This template is designed to be adaptable. Here are some ways you might extend it:
- Add CI/CD: Integration with GitHub Actions, GitLab CI, or other CI/CD systems
- Database Integration: Add SQLAlchemy or ORM of choice
- Authentication: Add authentication to the API endpoints
- Logging: Implement structured logging
- Monitoring: Add instrumentation for performance monitoring
- Documentation: Extend with Sphinx for auto-generated documentation
This project is licensed under the MIT License - see the LICENSE file for details.