python-skills 1.0.0__py3-none-any.whl

skills/engineering/pyproject_toml.md

@@ -0,0 +1,302 @@
+# Engineering: pyproject.toml
+
+**Purpose**: Modern Python project configuration (PEP 621, 517, 518, 660).
+
+**When to use**: All Python projects. Single source of truth for project metadata.
+
+---
+
+## Core Rules
+
+### Minimal Structure
+```toml
+[project]
+name = "my-package"
+version = "1.0.0"
+description = "Short description"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.31",
+    "pydantic>=2.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "regex"
+regex = '^__version__ = "(.+)"$'
+path = "src/my_package/_version.py"
+```
+
+### Project Metadata (PEP 621)
+```toml
+[project]
+name = "my-package"
+version = "1.0.0"
+description = "One-line description"
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Author Name", email = "author@example.com"}
+]
+maintainers = [
+    {name = "Maintainer", email = "maint@example.com"}
+]
+keywords = ["cli", "api", "utility"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.31,<3",
+    "pydantic>=2.0,<3",
+]
+urls = {
+    Homepage = "https://github.com/user/repo",
+    Repository = "https://github.com/user/repo",
+    Issues = "https://github.com/user/repo/issues",
+    Documentation = "https://docs.example.com",
+}
+```
+
+### Optional Dependencies
+```toml
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "ruff>=0.1",
+    "mypy>=1.0",
+]
+test = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+docs = [
+    "sphinx>=7.0",
+    "furo>=2023",
+]
+async = [
+    "aiohttp>=3.8",
+]
+```
+
+### Dynamic Fields (Setuptools/Hatch)
+```toml
+[project]
+dynamic = ["version", "description"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.version]
+source = "regex"
+regex = '^__version__ = "(.+)"$'
+path = "src/my_package/_version.py"
+```
+
+### Tool Configuration
+
+#### Ruff (Linting + Formatting)
+```toml
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+select = [
+    "E", "F", "I", "N", "UP", "W", "C4", "DTZ", "T10", "PTH", "S", "B", "A", "C", "Q", "TID", "RUF"
+]
+ignore = []
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "lf"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "D100", "D103"]
+"src/**/__init__.py" = ["D104"]
+```
+
+#### MyPy (Type Checking)
+```toml
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+strict_optional = true
+show_error_codes = true
+namespace_packages = true
+
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+```
+
+#### Pytest
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --strict-markers --strict-config"
+markers = [
+    "slow: marks tests as slow",
+    "integration: marks tests as integration",
+    "unit: marks tests as unit",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+```
+
+#### Coverage
+```toml
+[tool.coverage.run]
+source = ["src"]
+omit = ["tests/*", "*/__main__.py"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if __name__ == .__main__.:",
+]
+```
+
+#### Bandit (Security)
+```toml
+[tool.bandit]
+exclude_dirs = ["tests", "docs"]
+skips = ["B101", "B601"]  # assert, shell=True (if justified)
+```
+
+---
+
+## Dependency Versioning
+
+| Specifier | Meaning |
+|-----------|---------|
+| `>=1.0,<2` | Compatible release (preferred) |
+| `~=1.0` | `>=1.0,==1.*` (compatible) |
+| `==1.0.*` | Any 1.0.x |
+| `>=1.0` | Minimum version (avoid upper bound) |
+| `===1.0` | Exact version (rare) |
+
+**Prefer**: `"package>=1.0,<2"` or `"package~=1.0"`
+
+---
+
+## Build Backends
+
+| Backend | Config | Use Case |
+|---------|--------|----------|
+| `hatchling` | `[tool.hatch]` | Modern, fast, feature-rich |
+| `setuptools` | `[tool.setuptools]` | Legacy compatibility |
+| `flit` | `[tool.flit]` | Pure Python, simple |
+| `pdm` | `[tool.pdm]` | PDM-managed projects |
+| `poetry` | `[tool.poetry]` | Poetry-managed (legacy) |
+
+---
+
+## Decision Rules
+
+| Need | Config |
+|------|--------|
+| Simple pure Python lib | `flit` or `hatchling` |
+| Complex build (C extensions) | `setuptools` or `meson-python` |
+| Monorepo | `hatch` with `[tool.hatch.envs]` |
+| Existing Poetry/PDM | Keep current backend |
+| New project | `hatchling` (recommended) |
+
+---
+
+## Preferred Patterns
+
+```toml
+# Complete example for typical project
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "my-package"
+dynamic = ["version"]
+description = "Description"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.31,<3",
+    "pydantic>=2.0,<3",
+]
+optional-dependencies = {
+    dev = ["pytest", "ruff", "mypy", "pytest-asyncio"],
+    test = ["pytest", "pytest-cov"],
+}
+
+[tool.hatch.version]
+source = "regex"
+regex = '^__version__ = "(.+)"$'
+path = "src/my_package/_version.py"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+```
+
+---
+
+## Avoid
+
+- `setup.py` / `setup.cfg` for new projects (legacy)
+- Hardcoding version in multiple places
+- Missing `requires-python`
+- Overly restrictive upper bounds (`<2.0.0` instead of `<3`)
+- No lock file for applications (use `pip-tools`, `uv`, `poetry.lock`, `pdm.lock`)
+
+---
+
+## Validation Considerations
+
+- `pip install -e .` works
+- `pipx run build` produces wheel
+- `hatch version` shows correct version
+- `mypy --config-file pyproject.toml` passes
+- `ruff check --config pyproject.toml` passes
+
+---
+
+## Related Skills
+
+- `engineering/project_structure.md`
+- `engineering/dependency_management.md`
+- `engineering/packaging.md`
+- `engineering/virtual_environments.md`

skills/engineering/virtual_environments.md

@@ -0,0 +1,206 @@
+# Engineering: Virtual Environments
+
+**Purpose**: Isolated Python environments for development and deployment.
+
+**When to use**: All Python development. Never install packages globally.
+---
+---
+name: engineering_virtual_environments
+purpose: Isolated Python environments for development and deployment
+category: engineering
+triggers:
+  - virtualenv
+  - venv
+  - uv
+  - poetry
+  - pdm
+  - conda
+  - environment
+  - isolation
+dependencies:
+  - engineering/dependency_management.md
+  - engineering/pyproject_toml.md
+  - engineering/packaging.md
+  - engineering/cli_apps.md
+priority: primary
+estimated_tokens: 1800
+---
+
+## Core Rules
+
+### Tool Selection
+| Tool | Use Case |
+|------|----------|
+| `venv` (stdlib) | Simple, no dependencies |
+| `virtualenv` | Faster, more features |
+| `uv` | Fast, modern, replaces pip/venv |
+| `poetry` | Full project management |
+| `pdm` | PEP 621 native, good for libs |
+| `hatch` | Environments + build + publish |
+| `conda` | Data science, non-Python deps |
+
+### Creating Environments
+```bash
+# uv (recommended - fast)
+uv venv
+uv venv --python 3.11
+uv venv .venv --seed
+
+# venv (stdlib)
+python -m venv .venv
+python3.11 -m venv .venv
+
+# virtualenv
+virtualenv .venv -p python3.11
+
+# Activate
+source .venv/bin/activate  # Unix
+.venv\Scripts\activate     # Windows
+```
+
+### Dependency Installation
+```bash
+# uv (fastest)
+uv pip install -e .           # Editable install
+uv pip install -e ".[dev]"    # With optional deps
+uv sync                       # From lock file
+
+# pip
+pip install -e .
+pip install -e ".[dev]"
+
+# From requirements.txt
+uv pip install -r requirements.txt
+pip install -r requirements.txt
+```
+
+### Lock Files
+```bash
+# uv
+uv pip compile pyproject.toml -o requirements.txt
+uv pip compile pyproject.toml --extra dev -o requirements-dev.txt
+uv sync  # Uses uv.lock if exists
+
+# pip-tools
+pip-compile pyproject.toml -o requirements.txt
+pip-sync requirements.txt
+
+# poetry
+poetry lock
+poetry install
+
+# pdm
+pdm lock
+pdm install
+```
+
+### Environment Management
+```bash
+# uv - multiple environments
+uv python install 3.10 3.11 3.12
+uv venv --python 3.10 .venv310
+uv venv --python 3.11 .venv311
+
+# direnv (auto-activate)
+# .envrc
+layout uv
+# or
+layout python python3.11
+```
+
+### In Docker
+```dockerfile
+# Use uv for fast installs
+FROM python:3.12-slim
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
+
+WORKDIR /app
+COPY pyproject.toml uv.lock ./
+RUN uv sync --frozen --no-dev
+
+COPY src/ ./src/
+RUN uv pip install --no-deps -e .
+
+# Or simpler with pip
+FROM python:3.12-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY src/ ./src/
+RUN pip install --no-cache-dir -e .
+```
+
+---
+
+## Decision Rules
+
+| Situation | Tool |
+|-----------|------|
+| New project, want speed | `uv` |
+| Existing Poetry/PDM | Keep current |
+| Simple script | `venv` |
+| Data science | `conda` / `micromamba` |
+| CI/CD | `uv` (fastest) |
+| Multiple Python versions | `uv` + `direnv` |
+
+---
+
+## Preferred Patterns
+
+```bash
+# Project setup script (bin/setup or Makefile)
+#!/bin/bash
+set -euo pipefail
+
+# Install uv if not present
+if ! command -v uv &> /dev/null; then
+    pipx install uv
+fi
+
+# Create venv and install
+uv venv
+uv sync --extra dev
+
+# Install pre-commit
+uv run pre-commit install
+
+echo "Setup complete. Activate with: source .venv/bin/activate"
+```
+
+### pyproject.toml for uv
+```toml
+[tool.uv]
+dev-dependencies = [
+    "pytest>=7.4",
+    "ruff>=0.5",
+    "mypy>=1.10",
+]
+```
+
+---
+
+## Avoid
+
+- Global package installation (`pip install package`)
+- No virtual environment
+- Committing `.venv/` to git
+- Mixing package managers in one env
+- Not using lock files for applications
+
+---
+
+## Validation Considerations
+
+- `uv pip check` / `pip check` — no conflicts
+- `uv pip list` — correct versions
+- Reproducible: fresh env + lock file = same result
+- CI uses same lock file
+
+---
+
+## Related Skills
+
+- `engineering/dependency_management.md`
+- `engineering/pyproject_toml.md`
+- `engineering/packaging.md`
+- `engineering/cli_apps.md`