# devcontainer-python-uv-template

**Repository Path**: wrl-gz/devcontainer-python-uv-template

## Basic Information

- **Project Name**: devcontainer-python-uv-template
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-08
- **Last Updated**: 2025-12-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Python project-template with VSCode Devcontainer

> Reproducible, robust, and yet simple development setup for Python.
> Developing in [VSCode Dev Containers](https://code.visualstudio.com/docs/containers/quickstart-python).

## Prerequisites

- [Git](https://git-scm.com/downloads)
- [Docker](https://docs.docker.com/get-docker/)
- [VSCode](https://code.visualstudio.com/download) with [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)

## Getting started

Takes only three steps.

1. **Clone the repo**

```bash
# Clone the repo
# Or use GitHub's "Use this template" button
# Or use GitHub CLI: gh repo create <your-project-name> --template <this-repo>
git clone <this-repo> <your-project-name>
cd <your-project-name>
# change remote url to your repo
git remote set-url origin git://new.url.here
```
e
2. **Replace Placeholders**
- Search and replace `my-project` in `docker-compose.yml` and `python-project-template` in `pyproject.toml` with your project name
- Update `name`, `version` in `pyproject.toml`
- Update the year and copyright holder in `LICENSE`
- update this `README.md` for your project.

3. **Open in VS Code & Dev Container**

```bash
# Open project folder in VS Code
code .
# When prompted, or using the Command Palette (Ctrl+Shift+P), select:
# > Dev Containers: Open Folder in Container (or similar)

# after build you should see
# CTRL+p > Python: Select Interpreter > /usr/.venv/bin/python (as defined in `Dockerfile`)
```

- Add dependencies: `uv add <package-name>` (runs inside the container)
- `pre-commit` (linting, formatting, testing) runs automatically on commit
- want to ignore files that are specific to *you* without using `.gitignore`? Add them to `.git/info/exclude`


## Azure CLI setup

Want to use an already authenticated `az cli` from the host?
Add this to the following files:

```json
// .devcontainer/devcontainer.json
"features": {
        ...
        // ADD THIS
        "ghcr.io/devcontainers/features/azure-cli:1": {}
    }
```

```yaml
# .devcontainer/docker-compose.extend.yml
    volumes:
      ...
      // ADD THIS
      - ${HOME}/.azure:/root/.azure:rw
```



## Background

This template uses VSCode's [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) (devcontainers) to provide a consistent, isolated development environment. The setup leverages Docker Compose with an extension pattern:

- `docker-compose.yml` defines the base service configuration
- `.devcontainer/docker-compose.extend.yml` extends the base configuration specifically for development
- The extension mounts your local project directory to `/app` in the container, enabling real-time file synchronization
- This allows you to work on code locally in VSCode while running it in a container environment

This approach ensures that all developers work with identical dependencies and configurations, regardless of their local setup, while maintaining the ability to edit files directly on the host system.

### TLDR code & design rules

* Simplicity first: keep functions small, clear, and free of bloat.
* Clarity > cleverness: readable names and explicit logic beat tricks.
* YAGNI: implement only today’s requirements; postpone “nice-to-haves.”
* Single responsibility: one purpose per module, class, and function.
* Composition over inheritance: favour plain objects; if an interface is needed, use an `ABC`, not a `Protocol`.
* Pythonic, not painful: embrace idioms without overcomplicating code.
* Fail fast & loud: validate inputs early and raise clear errors.
* Typed & documented: PEP 484 type hints + Google-style docstrings.
* Testable by design: write pytest-ready, side-effect-free units.
* Immutable by default: fewer surprises, safer concurrency.
* Dependency discipline: keep `pyproject.toml` lean and current.
* Secure defaults: load secrets from env vars; least-privilege access.
* Measure before tuning: profile first, optimise real hotspots only.
* Continuous refactor: pay technical-debt in small, frequent steps.

### Tooling

- [`uv`](https://github.com/astral-sh/uv) for dependency management
- VS Code devcontainers with `docker compose`-file
- Multi-stage build with `builder`, also used for development, and `production`
- debugging: `debugpy`
- testing: `pytest`
- linting & formatting: `ruff`
- type-checking: `mypy`
- environment variables: `python-dotenv`
- `pre-commit` hooks

### Development practices & style

- write commits following [The seven rules of a great commit message](https://cbea.ms/git-commit/): *What- and *why- in imperative mood instead of *how*
- follow [12-factor principles](https://12factor.net/)
- agree on git workflow, for example [trunk-based development](https://trunkbaseddevelopment.com/)
- Use [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/) to structure docker images and only include the needed runtime dependencies for smaller image size and faster builds
- Follow a styleguide like [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
- Tag releases with [SemVer:2.0.0](https://semver.org/spec/v2.0.0.html) or [CalVer](https://calver.org/)
- For a changelog, adapt principles of [common-changelog](https://common-changelog.org/), written by humans for humans, a clean git history as foundation
- release with tags and changelog using [`git-release`](https://github.com/anton-yurchenko/git-release)
- `AGENTS.md`: Best practices on [writing customer instructions for Github Copilot](https://github.blog/ai-and-ml/github-copilot/5-tips-for-writing-better-custom-instructions-for-copilot/)