Skill: tenequm/python-dev (version 0.2.1)

--- name: python-dev description: Opinionated Python development setup with uv + ty + ruff + pytest + just. Use when creating new Python projects, setting up pyproject.toml, configuring linting, type checking, testing, or build tooling. Triggers on "python project", "uv init", "pyproject.toml", "ruff config", "ty check", "pytest setup", "justfile", "python linting", "python formatting", "type checking python". metadata: version: "0.2.1" upstream: "uv@0.11.8, ty@0.0.33, ruff@0.15.12, ruff-pre-commit@0.15.12, pytest@9.0.3, pytest-asyncio@1.3.0, pre-commit@4.6.0, pre-commit-hooks@6.0.0" --- # Python Development Setup Opinionated, production-ready Python development stack. No choices to make - just use this. ## When to Use - Starting a new Python project - Modernizing an existing project (migrating from pip/poetry/mypy/black/flake8) - Setting up linting, formatting, type checking, or testing - Creating a Justfile for project commands - Configuring pyproject.toml as the single source of truth ## The Stack | Tool | Role | Replaces | |------|------|----------| | [uv](https://docs.astral.sh/uv/) 0.11+ | Package manager, Python versions, runner | pip, poetry, pyenv, virtualenv | | [ty](https://docs.astral.sh/ty/) (beta) | Type checker (Astral, Rust) | mypy, pyright | | [ruff](https://docs.astral.sh/ruff/) | Linter + formatter | flake8, black, isort, pyupgrade | | [pytest](https://docs.pytest.org/) | Testing | unittest | | [just](https://just.systems/) | Command runner | make | > **Note on ty**: ty is in beta (0.0.x). It's fast and improving rapidly, but still missing features and may produce false positives on heavy-typing libraries (Pydantic, Django, SQLAlchemy). For projects that need rock-solid type checking today, swap `ty` for `pyright` and keep the rest of the stack unchanged. ## Quick Start: New Project ```bash # 1. Create project with src layout uv init --package my-project cd my-project # 2. Pin Python version uv python pin 3.13 # 3. Add dev dependencies uv add --dev ruff ty pytest pytest-asyncio pre-commit # 4. Create Justfile (see template below) # 5. Configure pyproject.toml (see template below) # 6. Run checks just check ``` ## pyproject.toml Template This is the single config file. Copy this and adjust `[project]` fields. ```toml [project] name = "my-project" version = "0.1.0" description = "Project description" readme = "README.md" requires-python = ">=3.13" license = {text = "MIT"} dependencies = [] [project.scripts] my-project = "my_project:main" # CLI: `uv run my-project` -> main() in src/my_project/__init__.py [dependency-groups] dev = [ "ruff>=0.15.0", "ty>=0.0.30", "pytest>=9.0.0", "pytest-asyncio>=1.3.0", "pre-commit>=4.0.0", ] [build-system] requires = ["hatchling"] build-backend = "hatchling.build" [tool.hatch.build.targets.wheel] packages = ["src/my_project"] # ============================================================================= # RUFF - Loose, helpful rules only # ============================================================================= [tool.ruff] target-version = "py313" line-length = 100 [tool.ruff.lint] select = [ "E", # pycodestyle errors - syntax issues "F", # pyflakes - undefined vars, unused imports "I", # isort - import sorting "UP", # pyupgrade - modern Python syntax ] ignore = [ "E501", # line too long - formatter handles it "E741", # ambiguous variable name - sometimes makes sense "UP007", # X | Y unions - Optional[X] is more readable ] exclude = [".git", ".venv", "__pycache__", "build", "dist"] [tool.ruff.format] quote-style = "double" indent-style = "space" line-ending = "lf" # ============================================================================= # TY - Type Checker # ============================================================================= [tool.ty.environment] python-version = "3.13" [tool.ty.src] include = ["src"] # ============================================================================= # PYTEST # ============================================================================= [tool.pytest.ini_options] testpaths = ["tests"] python_files = ["test_*.py"] python_classes = ["Test*"] python_functions = ["test_*"] asyncio_mode = "auto" addopts = [ "--strict-markers", "--strict-config", "-ra", ] ``` ## Justfile Template ```just # Check types and lint check: uv run ty check uv run ruff check --fix && uv run ruff format # Run tests test *ARGS: uv run pytest {{ARGS}} # Run tests with coverage test-cov: uv run pytest --cov=src --cov-report=term-missing # Auto-fix and format fix: uv run ruff check --fix uv run ruff format # Install/sync all dependencies install: uv sync --all-groups # Update all dependencies update: uv lock --upgrade uv sync --all-groups # Clean build artifacts clean: rm -rf dist/ build/ .pytest_cache/ .ruff_cache/ htmlcov/ find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true ``` ## Pre-commit Config Create `.pre-commit-config.yaml`: ```yaml repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 hooks: - id: check-added-large-files args: ['--maxkb=1000'] exclude: ^uv\.lock$ - id: detect-private-key - id: check-merge-conflict - id: check-yaml - id: check-toml - id: end-of-file-fixer - id: trailing-whitespace - id: mixed-line-ending args: ['--fix=lf'] - repo: https://github.com/astral-sh/ruff-pre-commit rev: v0.15.12 hooks: - id: ruff args: [--fix] - id: ruff-format exclude: | (?x)^( \.venv/.*| \.git/.*| __pycache__/.*| build/.*| dist/.*| uv\.lock )$ ``` Then run: `uv run pre-commit install` ## Project Structure Always use src layout: ``` my-project/ src/ my_project/ __init__.py cli.py models.py tests/ conftest.py test_models.py pyproject.toml Justfile uv.lock .python-version .pre-commit-config.yaml .gitignore ``` ## Daily Workflow ```bash just check # Type check + lint + format just test # Run tests just test -x # Stop on first failure just fix # Auto-fix lint issues uv add httpx # Add a dependency uv add --dev hypothesis # Add dev dependency uv sync # main deps + dev (dev is in default-groups) uv sync --all-groups # everything in [dependency-groups] uv run python -m my_project # Run the project ``` ## CI (GitHub Actions) Mirror `just check` + `just test` in CI. Drop this in `.github/workflows/ci.yml`: ```yaml name: CI on: [push, pull_request] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: astral-sh/setup-uv@v6 with: enable-cache: true - run: uv sync --all-groups - run: uv run ty check - run: uv run ruff check --output-format github - run: uv run ruff format --check - run: uv run pytest ``` `astral-sh/setup-uv` installs uv, manages the Python install requested by `.python-version`, and caches the resolver. No separate `setup-python` step needed. ## Existing Project Migration ```bash # 1. Install uv if not present brew install uv # 2. Convert requirements.txt to pyproject.toml deps uv add -r requirements.txt # 3. Replace mypy with ty uv remove --dev mypy uv add --dev ty # 4. Replace black/flake8/isort with ruff uv remove --dev black flake8 isort uv add --dev ruff # 5. Apply pyproject.toml config sections from template above # 6. Create Justfile from template above # 7. Run: just check ``` ## Reference Docs Detailed guides for each tool in `references/`: - **uv-reference.md** - Project init, dependencies, lock/sync, Python versions, build/publish - **ty-reference.md** - Configuration, rules, CLI flags, known limitations - **ruff-reference.md** - Rule sets, formatter options, per-file ignores, CI integration - **pytest-reference.md** - Plugins, fixtures, async testing, conftest patterns - **justfile-reference.md** - Syntax, variables, parameters, shebang recipes, settings ## Resources - [uv docs](https://docs.astral.sh/uv/) | [uv GitHub](https://github.com/astral-sh/uv) - [ty docs](https://docs.astral.sh/ty/) | [ty GitHub](https://github.com/astral-sh/ty) - [ruff docs](https://docs.astral.sh/ruff/) | [ruff GitHub](https://github.com/astral-sh/ruff) - [pytest docs](https://docs.pytest.org/en/stable/) - [just manual](https://just.systems/man/en/)


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)