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).
• Use Semantic Versioning for tagging releases.

Reference:

• PEP 440 – Version Identification and Dependency Specification

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, PDM, Conda

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

Reference:

• Python Packaging User Guide – Creating and Using Virtual Environments

---

3. Dependency Management and Locking

Explicitly declare and lock dependencies.

Options

• pyproject.toml (modern, PEP 621)
• requirements.txt (legacy but widely supported)
• Pipfile / Pipfile.lock (for Pipenv)

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

Example:

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

---

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)
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

---

6. Testing and Quality Assurance

Automate tests and integrate them early.

Best Practices

• Use pytest 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
• Testing Guidelines – Pytest Documentation

Example CI Integration (GitHub Actions):

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
Linting	Ruff or Flake8
Import sorting	isort
Type checking	mypy

Reference:

• PEP 8 – Style Guide for Python Code
• PEP 484 – Type Hints

Example pre-commit configuration:

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.
• Use reStructuredText or Markdown for documentation.
• Consider Sphinx or MkDocs 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
• Python Packaging Authority – Publishing Projects

---

10. Project Metadata and Packaging

Provide standardized metadata using pyproject.toml.

Example:

[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
• PEP 517 – Build System Interface

---

11. Optional Enhancements

Enhancement	Purpose	Recommended Tools
Containerization	Reproducible environments	Docker, Podman
Task Automation	Streamline workflows	Makefile, Taskfile
Secrets Management	Secure configuration	.env, python-dotenv
Static Analysis	Detect potential issues	Bandit
Code Metrics	Assess maintainability	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
• PEP 257 – Docstring Conventions
• PEP 484 – Type Hints
• PEP 517 & 518 – Build System Interface
• PEP 621 – Project Metadata in pyproject.toml
• Python Packaging User Guide
• Pytest Good Practices

---

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