README.md

metadata

title: Python Project Template
emoji: 🟧
colorFrom: yellow
colorTo: purple
sdk: docker
tags:
  - Python
fullwidth: true
license: mit
app_port: 8080

Python Project Template

A modern Python project template with best practices for development, testing, and deployment.

Features

• Modern Python (3.11+) project structure
• Development tools configuration (pytest, black, isort, mypy, ruff)
• Docker support
• GitHub Actions ready
• Comprehensive documentation structure
• Jupyter notebook support

Project Structure

.
├── docs/               # Documentation files
├── notebooks/         # Jupyter notebooks
├── src/               # Source code
│   ├── common/        # Common utilities and shared code
│   ├── modules/       # Feature modules
│   │   └── api/       # API related code
│   ├── shared/        # Shared resources
│   └── utils/         # Utility functions
└── tests/             # Test files

Getting Started

Prerequisites

• Python 3.11 or higher
• uv for dependency management

Installation

1. Clone the repository:

git clone https://github.com/yourusername/template-python.git
cd template-python

2. Create a virtual environment and install dependencies:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

3. Copy the environment file and adjust as needed:

cp .env.example .env

Development

This project uses several development tools:

• pytest: Testing framework
• black: Code formatting
• isort: Import sorting
• mypy: Static type checking
• ruff: Fast Python linter

Run tests:

pytest

Format code:

black .
isort .

Run type checking:

mypy src tests

Run linting:

ruff check .

Docker

Build the Docker image:

make build

Run the container:

make run

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.