{"id":34595991,"url":"https://github.com/a5chin/python-uv","last_synced_at":"2026-03-13T08:32:10.102Z","repository":{"id":232096645,"uuid":"782518658","full_name":"a5chin/python-uv","owner":"a5chin","description":"A production-ready Python development environment template using modern tools: uv for blazing-fast package management, Ruff for lightning-fast linting and formatting, ty for fast and reliable type checking, and VSCode Dev Containers for reproducible development environments.","archived":false,"fork":false,"pushed_at":"2026-03-06T05:47:27.000Z","size":7453,"stargazers_count":354,"open_issues_count":6,"forks_count":69,"subscribers_count":4,"default_branch":"develop","last_synced_at":"2026-03-06T09:58:21.451Z","etag":null,"topics":["codecov","codespaces","devcontainer","devcontainers","docker","nox","pre-commit","precommit","pydantic","pydantic-v2","pytest","python","python314","ruff","template","test","ty","uv","zed"],"latest_commit_sha":null,"homepage":"https://a5chin.github.io/python-uv/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/a5chin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-04-05T13:04:20.000Z","updated_at":"2026-03-06T05:46:33.000Z","dependencies_parsed_at":"2024-04-11T16:45:42.508Z","dependency_job_id":"389a7801-8932-4a6c-bcc5-f4467693df3c","html_url":"https://github.com/a5chin/python-uv","commit_stats":null,"previous_names":["a5chin/python","a5chin/python-rye","a5chin/python-uv"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/a5chin/python-uv","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a5chin%2Fpython-uv","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a5chin%2Fpython-uv/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a5chin%2Fpython-uv/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a5chin%2Fpython-uv/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/a5chin","download_url":"https://codeload.github.com/a5chin/python-uv/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/a5chin%2Fpython-uv/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30462272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T06:34:02.089Z","status":"ssl_error","status_checked_at":"2026-03-13T06:33:49.182Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["codecov","codespaces","devcontainer","devcontainers","docker","nox","pre-commit","precommit","pydantic","pydantic-v2","pytest","python","python314","ruff","template","test","ty","uv","zed"],"created_at":"2025-12-24T11:40:06.498Z","updated_at":"2026-03-13T08:32:10.088Z","avatar_url":"https://github.com/a5chin.png","language":"Python","readme":"# Python Development with uv and Ruff\n\n\u003cdiv align=\"center\"\u003e\n\n[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![ty](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ty/main/assets/badge/v0.json)](https://github.com/astral-sh/ty)\n\n[![Versions](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13%20|%203.14%20-green.svg)](https://github.com/a5chin/python-uv)\n[![codecov](https://codecov.io/github/a5chin/python-uv/graph/badge.svg?token=M9JIB8T6R4)](https://codecov.io/github/a5chin/python-uv)\n\n[![Docker](https://github.com/a5chin/python-uv/actions/workflows/docker.yml/badge.svg)](https://github.com/a5chin/python-uv/actions/workflows/docker.yml)\n[![Format](https://github.com/a5chin/python-uv/actions/workflows/format.yml/badge.svg)](https://github.com/a5chin/python-uv/actions/workflows/format.yml)\n[![Lint](https://github.com/a5chin/python-uv/actions/workflows/lint.yml/badge.svg)](https://github.com/a5chin/python-uv/actions/workflows/lint.yml)\n\n\u003c/div\u003e\n\nA production-ready Python development environment template using modern tools: **uv** for blazing-fast package management, **Ruff** for lightning-fast linting and formatting, **ty** for fast and reliable type checking, and **VSCode Dev Containers** for reproducible development environments.\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"docs/img/ruff.gif\" width=\"49%\"\u003e \u003cimg src=\"docs/img/jupyter.gif\" width=\"49%\"\u003e\n\u003c/div\u003e\n\n---\n\n## 📋 Table of Contents\n\n- [Python Development with uv and Ruff](#python-development-with-uv-and-ruff)\n  - [📋 Table of Contents](#-table-of-contents)\n  - [✨ Features](#-features)\n  - [🚀 Quick Start](#-quick-start)\n    - [Using Dev Container (Recommended)](#using-dev-container-recommended)\n    - [Using Docker Only](#using-docker-only)\n    - [Local Setup (Without Docker)](#local-setup-without-docker)\n  - [📚 Development Workflow](#-development-workflow)\n    - [Installing Dependencies](#installing-dependencies)\n    - [Running Tasks](#running-tasks)\n    - [Pre-commit Hooks](#pre-commit-hooks)\n    - [Documentation](#documentation)\n  - [🏗️ Project Structure](#️-project-structure)\n    - [Built-in Utility Modules](#built-in-utility-modules)\n      - [**Logger** - Dual-mode logging system](#logger---dual-mode-logging-system)\n      - [**Configuration** - Environment-based settings](#configuration---environment-based-settings)\n      - [**Timer** - Performance monitoring](#timer---performance-monitoring)\n  - [⚙️ Configuration](#️-configuration)\n    - [Ruff Configuration](#ruff-configuration)\n    - [ty Configuration](#ty-configuration)\n    - [Pytest Configuration](#pytest-configuration)\n  - [🔄 CI/CD](#-cicd)\n  - [🎨 VSCode Configuration](#-vscode-configuration)\n  - [🍪 Cookiecutter Templates](#-cookiecutter-templates)\n  - [📖 Documentation](#-documentation)\n  - [🌿 Branches](#-branches)\n  - [📄 License](#-license)\n  - [🙏 Acknowledgments](#-acknowledgments)\n\n---\n\n## ✨ Features\n\n- 🚀 **Ultra-fast package management** with [uv](https://github.com/astral-sh/uv) (10-100x faster than pip)\n- ⚡ **Lightning-fast linting \u0026 formatting** with [Ruff](https://github.com/astral-sh/ruff) (replacing Black, isort, Flake8, and more)\n- 🐳 **Dev Container ready** - Consistent development environment across all machines\n- 🔍 **Type checking** with ty\n- ✅ **Pre-configured testing** with pytest (75% coverage requirement)\n- 🔄 **Automated CI/CD** with GitHub Actions\n- 📦 **Reusable utilities** - Logger, configuration management, and performance tracing tools\n- 🎯 **Task automation** with nox\n- 🪝 **Pre-commit hooks** for automatic code quality checks\n\n## 🚀 Quick Start\n\n### Using Dev Container (Recommended)\n\n1. **Prerequisites**: Install [Docker](https://www.docker.com/) and [VSCode](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)\n\n2. **Open in container**:\n   ```bash\n   git clone https://github.com/a5chin/python-uv.git\n   cd python-uv\n   code .\n   ```\n   When prompted, click \"Reopen in Container\"\n\n3. **Start developing**:\n   ```bash\n   # Install dependencies\n   uv sync\n\n   # Run tests\n   uv run nox -s test\n\n   # Format and lint\n   uv run nox -s fmt\n   uv run nox -s lint -- --ruff --ty\n   ```\n\n### Using Docker Only\n\n```bash\n# Build the image\ndocker build -t python-uv .\n\n# Run container\ndocker run -it --rm -v $(pwd):/workspace python-uv\n```\n\n### Local Setup (Without Docker)\n\n**Prerequisites**: Python 3.11+ and [uv](https://github.com/astral-sh/uv)\n\n```bash\n# Install uv (if not already installed)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone and setup\ngit clone https://github.com/a5chin/python-uv.git\ncd python-uv\n\n# Install dependencies\nuv sync\n\n# Install pre-commit hooks (optional)\nuv run pre-commit install\n```\n\n## 📚 Development Workflow\n\n### Installing Dependencies\n\n```bash\n# Install all dependencies (including dev dependencies)\nuv sync\n\n# Install without dev dependencies\nuv sync --no-dev\n\n# Add new dependencies\nuv add requests pandas\n\n# Add dev dependencies\nuv add --dev pytest-mock\n```\n\n### Running Tasks\n\nThis project uses **nox** for task automation. All common development tasks are available as nox sessions:\n\n```bash\n# Format code with Ruff\nuv run nox -s fmt\n\n# Run linters (Ruff + ty)\nuv run nox -s lint -- --ruff --ty\n\n# Run only ty\nuv run nox -s lint -- --ty\n\n# Run only Ruff linter\nuv run nox -s lint -- --ruff\n\n# Run tests with coverage (75% minimum required)\nuv run nox -s test\n\n# Run tests with JUnit XML output (for CI)\nuv run nox -s test -- --cov_report xml --junitxml junit.xml\n```\n\nYou can also run tools directly:\n\n```bash\n# Run pytest directly\nuv run pytest\n\n# Run specific test file\nuv run pytest tests/tools/test__logger.py\n\n# Format with Ruff\nuv run ruff format .\n\n# Lint with Ruff\nuv run ruff check . --fix\n\n# Type check with ty\nuv run ty check\n```\n\n### Pre-commit Hooks\n\nPre-commit hooks automatically run code quality checks before each commit:\n\n```bash\n# Install hooks\nuv run pre-commit install\n\n# Run manually on all files\nuv run pre-commit run --all-files\n```\n\nConfigured hooks:\n- Ruff formatting and linting\n- JSON, YAML, TOML validation\n- Trailing whitespace removal\n- End-of-file fixer\n- Private key detection\n- Dockerfile linting with hadolint\n\n### Documentation\n\nGenerate and serve documentation with MkDocs:\n\n```bash\n# Serve locally at http://127.0.0.1:8000\nuv run mkdocs serve\n\n# Build static site\nuv run mkdocs build\n\n# Deploy to GitHub Pages\nuv run mkdocs gh-deploy\n```\n\n## 🏗️ Project Structure\n\n```\n.\n├── tools/                  # Reusable utility modules\n│   ├── config/             # Configuration management (Settings, FastAPI config)\n│   ├── logger/             # Logging utilities (Local \u0026 Google Cloud formatters)\n│   └── tracer/             # Performance tracing (Timer decorator/context manager)\n├── tests/                  # Test suite (mirrors tools/ structure)\n│   └── tools/              # Unit tests for utility modules\n├── docs/                   # MkDocs documentation\n│   ├── getting-started/    # Setup guides\n│   ├── guides/             # Tool usage guides\n│   ├── configurations/     # Configuration references\n│   └── usecases/           # Real-world examples\n├── .devcontainer/          # Dev Container configuration\n├── .github/                # GitHub Actions workflows, PR templates, and review checklists\n├── CODE_OF_CONDUCT.md      # Community Code of Conduct\n├── CONTRIBUTING.md         # Contribution guidelines\n├── CLAUDE.md               # Claude Code development guidance\n├── noxfile.py              # Task automation configuration (test, lint, fmt)\n├── pyproject.toml          # Project metadata and dependencies (uv)\n├── ruff.toml               # Ruff linter/formatter configuration\n└── pytest.ini              # Pytest configuration (75% coverage requirement)\n```\n\n### Built-in Utility Modules\n\nThe `tools/` package provides production-ready utilities that can be used in your projects:\n\n#### **Logger** - Dual-mode logging system\n\nEnvironment-aware logging with support for local development and cloud environments:\n\n```python\nfrom tools.logger import Logger, LogType\n\n# Local development (colored console output)\nlogger = Logger(__name__, log_type=LogType.LOCAL)\n\n# Google Cloud (structured JSON logging)\nlogger = Logger(__name__, log_type=LogType.GOOGLE_CLOUD, project=\"my-project\")\n\nlogger.info(\"Application started\")\n```\n\n#### **Configuration** - Environment-based settings\n\nType-safe configuration management using Pydantic:\n\n```python\nfrom tools.config import Settings\n\nsettings = Settings()  # Loads from .env and .env.local\napi_url = settings.api_prefix_v1\nis_debug = settings.DEBUG\n```\n\n#### **Timer** - Performance monitoring\n\nAutomatic execution time logging for functions and code blocks:\n\n```python\nfrom tools.tracer import Timer\n\n# As context manager\nwith Timer(\"database_query\"):\n    result = db.query()  # Logs execution time automatically\n\n# As decorator\n@Timer(\"process_data\")\ndef process_data(data):\n    return transform(data)  # Logs execution time when function completes\n```\n\n## ⚙️ Configuration\n\n### Ruff Configuration\n\nRuff replaces multiple tools (Black, isort, Flake8, pydocstyle, pyupgrade, autoflake) with a single, fast tool.\n\n**Key settings in `ruff.toml`:**\n- **Line length**: 88 (Black-compatible)\n- **Target Python**: 3.14\n- **Rules**: ALL enabled by default with specific exclusions\n- **Test files**: Exempt from `INP001` (namespace packages) and `S101` (assert usage)\n\n\u003e See [Ruff documentation](https://docs.astral.sh/ruff/) for customization options.\n\n### ty Configuration\n\nStatic type checking for Python code.\n\n**Key settings in `ty.toml`:**\n- **Include**: `tools/` and `tests/` packages\n- **Exclude**: Cache directories (`__pycache__`, `.pytest_cache`, `.ruff_cache`, `.venv`)\n\n\u003e See [ty documentation](https://github.com/astral-sh/ty) for advanced configuration.\n\n### Pytest Configuration\n\nTesting framework with coverage enforcement.\n\n**Key settings in `pytest.ini`:**\n- **Coverage requirement**: 75% minimum (including branch coverage)\n- **Test file pattern**: `test__*.py` (double underscore)\n- **Coverage reports**: HTML and terminal\n- **Import mode**: importlib\n\n\u003e See [pytest documentation](https://docs.pytest.org/) for additional options.\n\n## 🔄 CI/CD\n\nAutomated workflows ensure code quality and consistency. All workflows run on push and pull requests.\n\n**Available workflows in `.github/workflows/`:**\n\n| Workflow                   | Purpose                              | Tools Used       |\n| -------------------------- | ------------------------------------ | ---------------- |\n| `docker.yml`               | Validate Docker build                | Docker           |\n| `devcontainer.yml`         | Validate Dev Container configuration | devcontainer CLI |\n| `format.yml`               | Check code formatting                | Ruff             |\n| `labeler.yml`              | Add label in GitHub                  | GitHub           |\n| `lint.yml`                 | Run static analysis                  | Ruff, ty         |\n| `test.yml`                 | Run test suite with coverage         | pytest, coverage |\n| `gh-deploy.yml`            | Deploy documentation to GitHub Pages | MkDocs           |\n| `pr-agent.yml`             | Automated PR reviews                 | Qodo AI PR Agent |\n| `publish-devcontainer.yml` | Publish Dev Container image          | Docker, GHCR     |\n\n## 🎨 VSCode Configuration\n\nThe Dev Container includes pre-configured extensions and settings for optimal Python development.\n\n**Python Development:**\n- **Ruff** - Fast linting and formatting\n- **ty** - Static type checking\n- **Python** - Core Python support\n- **autodocstring** - Automatic docstring generation\n- **python-indent** - Correct Python indentation\n\n**Code Quality:**\n- **GitLens** - Enhanced Git integration\n- **Error Lens** - Inline error highlighting\n- **indent-rainbow** - Visual indentation guide\n- **trailing-spaces** - Highlight trailing whitespace\n\n**File Support:**\n- **YAML**, **TOML**, **Markdown** - Configuration file support\n- **Docker** - Dockerfile and docker-compose support\n- **Material Icon Theme** - File icons\n\n**Editor Settings:**\n- ✅ Format on save (Python, JSON, YAML, TOML, Dockerfile)\n- ✅ Auto-trim trailing whitespace\n- ✅ Auto-insert final newline\n- ✅ Organize imports on save\n\n\u003e **Troubleshooting**: If Ruff formatting doesn't work, reload the window: `Cmd+Shift+P` → \"Developer: Reload Window\"\n\n## 🍪 Cookiecutter Templates\n\nThis repository can be used as a base template for various Python projects. Combine it with Cookiecutter to bootstrap project-specific setups:\n\n```bash\n# Install cookiecutter\nuv add --dev cookiecutter\n\n# Use a template\nuv run cookiecutter \u003ctemplate-url\u003e\n```\n\n**Recommended templates:**\n\n- **Data Science**: [cookiecutter-data-science](https://github.com/drivendataorg/cookiecutter-data-science) - Standardized data science project structure\n- **FastAPI**: [full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template) - Full-stack web applications\n- **Django**: [cookiecutter-django](https://github.com/cookiecutter/cookiecutter-django) - Production-ready Django projects\n- **Flask**: [cookiecutter-flask](https://github.com/cookiecutter-flask/cookiecutter-flask) - Flask web applications\n\n## 📖 Documentation\n\nComprehensive documentation is available at **[https://a5chin.github.io/python-uv](https://a5chin.github.io/python-uv)**\n\n**Topics covered:**\n- 🚀 **Getting Started** - Docker, VSCode, Dev Containers setup\n- ⚙️ **Tool Configurations** - uv, Ruff, ty, pre-commit\n- 🧪 **Testing Strategies** - pytest, coverage, and best practices\n- 🛠️ **Utility Modules** - Config, logger, and tracer guides\n- 💡 **Use Cases** - Jupyter, FastAPI, OpenCV examples\n\n## 🌿 Branches\n\nThis repository maintains multiple branches for different use cases:\n\n- **[main](https://github.com/a5chin/python-uv/tree/main)** - Current production-ready template (recommended)\n- **[jupyter](https://github.com/a5chin/python-uv/tree/jupyter)** - Archived: Jupyter-specific configuration\n- **[rye](https://github.com/a5chin/python-uv/tree/rye)** - Archived: Rye package manager version (replaced by uv)\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\nThis template is built on top of excellent open-source tools:\n\n- **[uv](https://github.com/astral-sh/uv)** by Astral - Ultra-fast Python package manager\n- **[Ruff](https://github.com/astral-sh/ruff)** by Astral - Lightning-fast linter and formatter\n- **[ty](https://github.com/astral-sh/ty)** by Astral - Static type checker for Python\n- **[nox](https://nox.thea.codes/)** - Flexible task automation for Python\n- **[pytest](https://pytest.org/)** - Testing framework for Python\n- **[MkDocs](https://www.mkdocs.org/)** - Documentation site generator\n\nSpecial thanks to the open-source community for making these tools available!\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa5chin%2Fpython-uv","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fa5chin%2Fpython-uv","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fa5chin%2Fpython-uv/lists"}