398 lines
7.1 KiB
Markdown
398 lines
7.1 KiB
Markdown
# Python AI Dev Template
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
A universal and adaptable **Python project template** designed for professional development and AI‑assisted coding workflows (OpenCode, AI agents, etc.).
|
||
|
||
License: MIT
|
||
|
||
This repository provides a clean and production‑ready starting point for building:
|
||
|
||
- CLI tools
|
||
- backend services
|
||
- automation scripts
|
||
- desktop applications
|
||
- internal developer tools
|
||
|
||
The template enforces **modern Python standards**, **clean architecture**, and **automated quality checks**.
|
||
|
||
---
|
||
|
||
# Requirements
|
||
|
||
- Python **3.11+**
|
||
- `pyenv` recommended for Python version management
|
||
|
||
Check Python version:
|
||
|
||
```bash
|
||
python --version
|
||
```
|
||
|
||
---
|
||
|
||
# Quick Start
|
||
|
||
Clone the template repository:
|
||
|
||
```bash
|
||
git clone <template-repository-url> new-project
|
||
cd new-project
|
||
```
|
||
|
||
Create a virtual environment:
|
||
|
||
```bash
|
||
python -m venv .venv
|
||
source .venv/bin/activate
|
||
```
|
||
|
||
Install development dependencies:
|
||
|
||
```bash
|
||
pip install --upgrade pip
|
||
pip install -e '.[dev]'
|
||
```
|
||
|
||
---
|
||
|
||
# Using the Makefile (Recommended)
|
||
|
||
This template includes a **Makefile** to simplify common development tasks.
|
||
|
||
### First time setup
|
||
|
||
To prepare the full development environment automatically:
|
||
|
||
```bash
|
||
make dev
|
||
```
|
||
|
||
This command will:
|
||
|
||
- create the `.venv` virtual environment
|
||
- install project dependencies
|
||
- install development tools
|
||
- configure `pre-commit` hooks
|
||
|
||
This is the **recommended command after cloning the repository**.
|
||
|
||
### Reinstall or update dependencies
|
||
|
||
If the virtual environment already exists and you only want to reinstall or update dependencies:
|
||
|
||
```bash
|
||
make install
|
||
```
|
||
|
||
### Development utilities
|
||
|
||
Some useful commands:
|
||
|
||
```bash
|
||
make fix # auto‑format and fix code issues
|
||
make quality # run full quality checks
|
||
make ci # simulate CI validation
|
||
make doctor # show environment and tool versions
|
||
make run # run the application
|
||
```
|
||
|
||
Using the Makefile ensures a consistent development workflow across machines.
|
||
|
||
---
|
||
|
||
# Environment Configuration
|
||
|
||
This template supports **environment-based configuration** using a `.env` file.
|
||
|
||
An example configuration file is provided:
|
||
|
||
```
|
||
.env.example
|
||
```
|
||
|
||
To create your local configuration, copy the example file:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
Then edit `.env` and adjust the values for your local environment.
|
||
|
||
Typical uses include:
|
||
|
||
- application settings
|
||
- API endpoints
|
||
- API keys
|
||
- database connection strings
|
||
- feature flags
|
||
|
||
⚠️ The `.env` file is **ignored by git** and should **never contain secrets in the repository**.
|
||
|
||
Only `.env.example` should be committed.
|
||
|
||
---
|
||
|
||
# Run the Application
|
||
|
||
```bash
|
||
python -m app.main
|
||
```
|
||
|
||
Expected output:
|
||
|
||
```
|
||
cd-browser is ready.
|
||
```
|
||
|
||
---
|
||
|
||
# Development Workflow
|
||
|
||
Before committing changes, always validate the project using the following steps.
|
||
|
||
### 1. Run the application
|
||
|
||
```bash
|
||
python -m app.main
|
||
```
|
||
|
||
### 2. Run tests
|
||
|
||
```bash
|
||
pytest
|
||
```
|
||
|
||
### 3. Format code
|
||
|
||
```bash
|
||
black src tests
|
||
```
|
||
|
||
### 4. Check formatting
|
||
|
||
```bash
|
||
black --check src tests
|
||
```
|
||
|
||
### 5. Lint code
|
||
|
||
```bash
|
||
ruff check src tests
|
||
```
|
||
|
||
### 6. Type checking
|
||
|
||
```bash
|
||
mypy src
|
||
```
|
||
|
||
If all commands succeed, the project is considered valid.
|
||
|
||
---
|
||
|
||
# Quick Quality Check
|
||
|
||
Run all checks quickly:
|
||
|
||
```bash
|
||
black src tests
|
||
ruff check src tests
|
||
mypy src
|
||
pytest
|
||
```
|
||
|
||
---
|
||
|
||
|
||
# Create a New Repository From This Template
|
||
|
||
If you downloaded or cloned this template and want to start a **new project repository**, follow these steps.
|
||
|
||
### 1. Clone the template
|
||
|
||
```bash
|
||
git clone https://gitea.sakydogalo.es/saky/python-ai-dev-template.git new-project
|
||
cd new-project
|
||
```
|
||
|
||
### Recommended: Initialize the project automatically
|
||
|
||
You can initialize a new project using the helper script:
|
||
|
||
```bash
|
||
./scripts/init_project.sh my-project-name
|
||
```
|
||
|
||
This script will:
|
||
|
||
- reset the git history
|
||
- prepare the repository for a fresh start
|
||
- keep the template structure intact
|
||
|
||
After running the script, create your new remote repository and push the code as described below.
|
||
|
||
---
|
||
|
||
### Manual initialization (alternative)
|
||
|
||
If you prefer to perform the steps manually, follow the instructions below.
|
||
|
||
### 2. Remove the original remote
|
||
|
||
```bash
|
||
git remote remove origin
|
||
```
|
||
|
||
### 3. Reset Git history (start clean)
|
||
|
||
```bash
|
||
rm -rf .git
|
||
git init
|
||
```
|
||
|
||
### 4. Update project metadata
|
||
|
||
Update these files to match your new project:
|
||
|
||
- `pyproject.toml` → project name and description
|
||
- `README.md`
|
||
- `src/app/config.py` → application name
|
||
|
||
### 5. Validate the project
|
||
|
||
```bash
|
||
make fix
|
||
make quality
|
||
```
|
||
|
||
### 6. Create your new repository
|
||
|
||
Create a new repository on your Git server (Gitea, GitHub, etc.).
|
||
|
||
Example:
|
||
|
||
```
|
||
https://gitea.sakydogalo.es/saky/new-project
|
||
```
|
||
|
||
### 7. Connect the new remote
|
||
|
||
```bash
|
||
git remote add origin <your-new-repository-url>
|
||
```
|
||
|
||
### 8. Create the first commit
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "Initial new-project from template"
|
||
```
|
||
|
||
### 9. Push to the new repository
|
||
|
||
```bash
|
||
git branch -M main
|
||
git push -u origin main
|
||
```
|
||
|
||
Your new project repository is now ready.
|
||
|
||
---
|
||
|
||
# Project Structure
|
||
|
||
```
|
||
new-project/
|
||
│
|
||
├── src/
|
||
│ └── app/
|
||
│ ├── main.py
|
||
│ ├── config.py
|
||
│ ├── logging_config.py
|
||
│ ├── services/
|
||
│ ├── domain/
|
||
│ ├── infrastructure/
|
||
│ └── utils/
|
||
│
|
||
├── tests/
|
||
│ └── test_smoke.py
|
||
│
|
||
├── scripts/
|
||
│
|
||
├── pyproject.toml
|
||
├── instructions-agent.md
|
||
├── README.md
|
||
└── .editorconfig
|
||
```
|
||
|
||
---
|
||
|
||
# Tooling
|
||
|
||
This template includes modern Python development tools:
|
||
|
||
| Tool | Purpose |
|
||
|-----|--------|
|
||
| pytest | testing framework |
|
||
| black | automatic code formatting |
|
||
| ruff | linting and static analysis |
|
||
| mypy | static type checking |
|
||
|
||
---
|
||
|
||
# Purpose of this Template
|
||
|
||
This repository is intentionally **generic and adaptable**.
|
||
|
||
It can evolve into:
|
||
|
||
- a CLI tool
|
||
- a web API
|
||
- a microservice
|
||
- a desktop application
|
||
- an automation system
|
||
|
||
The goal is to provide a **clean, maintainable, and AI‑friendly Python project foundation**.
|
||
|
||
---
|
||
|
||
# AI Agent Support
|
||
|
||
This repository includes:
|
||
|
||
instructions-agent.md
|
||
|
||
This file defines rules and expectations for AI coding agents such as:
|
||
|
||
- OpenCode
|
||
- AI IDE assistants
|
||
- autonomous coding agents
|
||
|
||
Agents should follow those instructions when modifying the project.
|
||
|
||
---
|
||
|
||
# License
|
||
|
||
This project is released under the **MIT License**, one of the most permissive open‑source licenses available.
|
||
|
||
You are free to:
|
||
|
||
- use this code for personal or commercial projects
|
||
- modify it
|
||
- distribute it
|
||
- include it in proprietary software
|
||
|
||
No special permission is required.
|
||
|
||
Copyright (c) 2025 Saky
|
||
|
||
This template was created by **Saky**, drawing on many years of professional software engineering experience and with the assistance of modern AI development tools.
|
||
|
||
The goal of this repository is to provide a practical, production‑ready starting point for Python projects while remaining as open and reusable as possible.
|