Files

Saky f03417f2f2 Initial release: cd-browser v0.1.0

2026-03-14 17:21:49 +01:00

7.1 KiB

Raw Blame History

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:

python --version

Quick Start

Clone the template repository:

git clone <template-repository-url> new-project
cd new-project

Create a virtual environment:

python -m venv .venv
source .venv/bin/activate

Install development dependencies:

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:

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:

make install

Development utilities

Some useful commands:

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:

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

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

python -m app.main

2. Run tests

pytest

3. Format code

black src tests

4. Check formatting

black --check src tests

5. Lint code

ruff check src tests

6. Type checking

mypy src

If all commands succeed, the project is considered valid.

Quick Quality Check

Run all checks quickly:

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

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:

./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

git remote remove origin

3. Reset Git history (start clean)

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

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

git remote add origin <your-new-repository-url>

8. Create the first commit

git add .
git commit -m "Initial new-project from template"

9. Push to the new repository

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.

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.

7.1 KiB Raw Blame History Unescape Escape