kaizen-agentic/context/PythonVibes.md

PythonVibes is a repository template to build vibe coding projects from. 
It roughly follows the following best practices for organizing python repositories.

# Python Project Repository Best Practice Guide

> **Purpose**  
> This guide defines the best practices for structuring, documenting, and maintaining Python repositories.  
> It is based on official Python standards (PEPs) and widely adopted community conventions.

---

## 1. Version Control as a Foundation

**Use Git for all projects.**

### Key Practices
- Initialize every project with Git (`git init` or `gh repo create`).
- Commit logical units of work with meaningful messages.
- Exclude irrelevant files using a `.gitignore` (e.g., from [GitHub’s Python.gitignore](https://github.com/github/gitignore)).
- Use [Semantic Versioning](https://semver.org/) for tagging releases.

**Reference:**  
- [PEP 440 – Version Identification and Dependency Specification](https://peps.python.org/pep-0440/)

**Rationale:**  
Version control ensures traceability, collaboration, and reproducibility — the foundation for CI/CD and team workflows.

---

## 2. Environment Isolation

**Always develop inside a virtual environment.**

### Recommended Tools
- Standard library: `python -m venv .venv`
- Modern environment managers: [Poetry](https://python-poetry.org/), [PDM](https://pdm.fming.dev/), [Conda](https://docs.conda.io/)

**Rationale:**  
Virtual environments prevent dependency conflicts and ensure consistent behavior across systems.

**Reference:**  
- [Python Packaging User Guide – Creating and Using Virtual Environments](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/)

---

## 3. Dependency Management and Locking

**Explicitly declare and lock dependencies.**

### Options
- `pyproject.toml` (modern, [PEP 621](https://peps.python.org/pep-0621/))
- `requirements.txt` (legacy but widely supported)
- `Pipfile` / `Pipfile.lock` (for Pipenv)

**Rationale:**  
Explicit dependency declaration ensures anyone can reproduce the project environment exactly.

**Example:**  
```bash
pip install --no-cache-dir -r requirements.txt
```

---

## 4. Recommended Directory Layout

**Follow a clear, standardized project structure.**

```
project-name/
├── src/
│   └── project_name/
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   └── test_core.py
├── docs/
├── .github/
│   └── workflows/
├── .gitignore
├── LICENSE
├── pyproject.toml
├── README.md
└── requirements.txt
```

**Reference:**  
- [The Hitchhiker’s Guide to Python – Structuring Your Project](https://docs.python-guide.org/writing/structure/)

---

## 5. Essential Repository Files

| File | Purpose |
|------|----------|
| `README.md` | Overview, installation, usage, and examples |
| `LICENSE` | Defines distribution and usage rights |
| `.gitignore` | Prevents committing build and environment artifacts |
| `pyproject.toml` | Declares project metadata and dependencies |
| `CHANGELOG.md` | Documents version history ([Keep a Changelog](https://keepachangelog.com/en/1.1.0/)) |
| `CONTRIBUTING.md` | Provides guidelines for contributors |

**Optional:**
- `CODE_OF_CONDUCT.md` — defines community expectations  
- `Makefile` — simplifies common commands  
- `.env.example` — documents environment variables  

**Reference:**  
- [PEP 518 – pyproject.toml Build System Configuration](https://peps.python.org/pep-0518/)

---

## 6. Testing and Quality Assurance

**Automate tests and integrate them early.**

### Best Practices
- Use [pytest](https://docs.pytest.org/) for tests and fixtures.
- Maintain a `tests/` directory at the root of the repository.
- Measure coverage with `pytest --cov=package_name`.

**Reference:**  
- [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/#programming-recommendations)
- [Testing Guidelines – Pytest Documentation](https://docs.pytest.org/en/stable/goodpractices.html)

**Example CI Integration (GitHub Actions):**
```yaml
name: Python CI

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install -r requirements.txt
      - run: pytest --maxfail=1 --disable-warnings -q
```

---

## 7. Code Style, Linting, and Type Checking

**Maintain a consistent, readable, and typed codebase.**

### Tools
| Task | Recommended Tool |
|------|------------------|
| Code formatting | [Black](https://black.readthedocs.io/en/stable/) |
| Linting | [Ruff](https://docs.astral.sh/ruff/) or [Flake8](https://flake8.pycqa.org/en/latest/) |
| Import sorting | [isort](https://pycqa.github.io/isort/) |
| Type checking | [mypy](https://mypy.readthedocs.io/en/stable/) |

**Reference:**  
- [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/)
- [PEP 484 – Type Hints](https://peps.python.org/pep-0484/)

**Example pre-commit configuration:**
```yaml
repos:
  - repo: https://github.com/psf/black
    rev: 24.3.0
    hooks: [{ id: black }]
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.0
    hooks: [{ id: ruff }]
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks: [{ id: mypy }]
```

---

## 8. Documentation and Docstrings

**Write documentation that grows with your codebase.**

### Recommendations
- Use descriptive docstrings following [PEP 257](https://peps.python.org/pep-0257/).
- Use [reStructuredText](https://docutils.sourceforge.io/rst.html) or Markdown for documentation.
- Consider [Sphinx](https://www.sphinx-doc.org/) or [MkDocs](https://www.mkdocs.org/) for documentation sites.
- Use type hints for better auto-documentation and IDE support.

**Rationale:**  
Readable, up-to-date documentation enhances maintainability and team onboarding.

---

## 9. Continuous Integration and Deployment (CI/CD)

**Automate quality checks and deployments.**

### Best Practices
- Use CI workflows to run tests, linting, and builds automatically.
- Enforce required checks before merging pull requests.
- Use environment variables for secrets; avoid storing credentials in code.
- Optionally integrate publishing with PyPI (`twine upload dist/*`).

**Reference:**  
- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [Python Packaging Authority – Publishing Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/)

---

## 10. Project Metadata and Packaging

**Provide standardized metadata using `pyproject.toml`.**

Example:
```toml
[project]
name = "example-project"
version = "0.1.0"
description = "A well-structured Python project template"
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
authors = [{ name = "Example Author", email = "author@example.com" }]
dependencies = ["requests", "pytest"]

[tool.black]
line-length = 88
```

**References:**  
- [PEP 621 – Project Metadata in pyproject.toml](https://peps.python.org/pep-0621/)
- [PEP 517 – Build System Interface](https://peps.python.org/pep-0517/)

---

## 11. Optional Enhancements

| Enhancement | Purpose | Recommended Tools |
|--------------|----------|--------------------|
| Containerization | Reproducible environments | Docker, Podman |
| Task Automation | Streamline workflows | Makefile, [Taskfile](https://taskfile.dev) |
| Secrets Management | Secure configuration | `.env`, [python-dotenv](https://pypi.org/project/python-dotenv/) |
| Static Analysis | Detect potential issues | [Bandit](https://bandit.readthedocs.io/) |
| Code Metrics | Assess maintainability | [Radon](https://pypi.org/project/radon/) |

---

## 12. Checklist for a High-Quality Python Repository

| Category | Practice | Tools / Standards |
|-----------|-----------|-------------------|
| Version Control | Git, semantic versioning | Git, SemVer |
| Environment Isolation | Virtual environments | venv, Poetry |
| Dependencies | Explicit, reproducible | pyproject.toml |
| Structure | Clear, modular | src layout |
| Testing | Automated | pytest, coverage |
| Style | Consistent, typed | Black, Ruff, mypy |
| Documentation | Comprehensive | Sphinx, Markdown |
| CI/CD | Automated validation | GitHub Actions |
| Metadata | Standardized | PEP 621 |
| Licensing | Defined rights | OSI-approved licenses |

---

**References (Summary):**
- [PEP 8 – Style Guide for Python Code](https://peps.python.org/pep-0008/)
- [PEP 257 – Docstring Conventions](https://peps.python.org/pep-0257/)
- [PEP 484 – Type Hints](https://peps.python.org/pep-0484/)
- [PEP 517 & 518 – Build System Interface](https://peps.python.org/pep-0517/)
- [PEP 621 – Project Metadata in pyproject.toml](https://peps.python.org/pep-0621/)
- [Python Packaging User Guide](https://packaging.python.org/)
- [Pytest Good Practices](https://docs.pytest.org/en/stable/goodpractices.html)

---

> **Summary:**  
> A Python project repository should be *structured, reproducible, testable, documented, and automated*.  
> Following these conventions ensures maintainability, scalability, and professional collaboration across teams and time.

xxx