Initial release: cd-browser v0.1.0
This commit is contained in:
397
README_TEMPLATE.md
Normal file
397
README_TEMPLATE.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user