Merge pull request #13 from h-holm/feature/add-dev-container-setup

[Feature] Add dev container setup

.devcontainer/Dockerfile

@@ -0,0 +1,18 @@
+# syntax=docker.io/docker/dockerfile:1
+
+FROM python:3.13-alpine
+
+WORKDIR /usr/src/app
+
+# Install `git`.
+RUN apk add --no-cache git
+
+# Install `pipx` in order to install Hatch.
+RUN apk add --no-cache pipx
+RUN pipx ensurepath --global
+
+# Install Hatch via `pipx`.
+RUN pipx install hatch
+
+# Add `/root/.local/bin` to `$PATH` to ensure Hatch can be detected.
+ENV PATH="$PATH:/root/.local/bin"

.devcontainer/devcontainer.json

@@ -0,0 +1,10 @@
+{
+    "name": "Python Project",
+    "build": { "dockerfile": "Dockerfile" },
+
+    // Features to add to the dev container. More info: https://containers.dev/features.
+    // "features": {},
+
+    // Use 'postCreateCommand' to run commands after the container is created.
+    "postCreateCommand": "pipx install hatch && hatch env create && hatch env create lint && hatch env create test"
+}

.pre-commit-config.yaml

@@ -9,14 +9,20 @@ repos:
       - id: check-docstring-first
       - id: debug-statements
       - id: check-ast
-      - id: check-json
       - id: check-toml
       - id: check-xml
       - id: check-yaml
       - id: end-of-file-fixer
       - id: mixed-line-ending
         args: ["--fix=auto"] # Replace "auto" with "lf" to enforce Linux/Mac line endings or "crlf" for Windows
 
+  # The built-in `check-json` hook does not support JSON5 files (~= JSON with comments and trailing commas). To lint
+  # JSON5 files, use the `check-json5` hook instead.
+  - repo: https://gitlab.com/bmares/check-json5
+    rev: v1.0.0
+    hooks:
+      - id: check-json5
+
   - repo: local
     hooks:
       - id: hatch-lint

.vscode/extensions.json

@@ -6,6 +6,7 @@
         "editorconfig.editorconfig",
         "esbenp.prettier-vscode",
         "matangover.mypy",
+        "ms-azuretools.vscode-docker",
         "ms-python.python",
         "ms-python.vscode-pylance",
         "njpwerner.autodocstring",

README.md

@@ -6,20 +6,25 @@ A GitHub template repo for a containerized Python application.
 
 ## Features ✅
 
-* [Hatch](https://hatch.pypa.io/latest) is used to manage the development environments and production build.
-* Primary dependencies and configurations are handled in the [pyproject.toml](./pyproject.toml) file.
-* All (sub-)dependencies are locked via `requirements.txt` files using [`hatch-pip-compile`](https://github.com/juftin/hatch-pip-compile).
-* Hatch is configured to automatically set up [`pre-commit` hooks](https://github.com/pre-commit/pre-commit) that are synced with the `lint` Hatch environment.
-* The application logic is defined under [src/python_project](src/python_project).
-* Logging is configured in a single [logging.conf](./src/python_project/logging.conf) file.
-* Optionally, uniform formatting can further be ensured via the [.editorconfig](./.editorconfig) and [.vscode](./.vscode) configs.
-
-The repository contains an example [GitHub Actions CI pipeline](./.github/workflows/) that:
-
-* runs [`ruff`](https://github.com/astral-sh/ruff)-based linting and formatting,
-* runs [`mypy`](https://github.com/python/mypy)-based static type checking,
-* runs [`pytest`](https://docs.pytest.org)-based unit testing,
-* performs a CodeQL vulnerability scan,
+* Seamless environment management via [Hatch](https://hatch.pypa.io/latest)
+* Lightning-fast dependency resolution via [uv](https://github.com/astral-sh/uv)
+* Primary dependencies and tooling configuration in the [PEP](https://peps.python.org/pep-0621)-recommended [pyproject.toml](./pyproject.toml) file
+* (Sub-)dependency locking in `requirements.txt` files via [hatch-pip-compile](https://github.com/juftin/hatch-pip-compile)
+* Linting and formatting using [ruff](https://github.com/astral-sh/ruff)
+* Static type checking using [mypy](https://github.com/python/mypy)
+* [pytest](https://docs.pytest.org) for unit tests with [coverage](https://coverage.readthedocs.io/en/7.6.7)-based reporting
+* Automatic set up of [pre-commit](https://github.com/pre-commit/pre-commit) hooks via the `lint` Hatch environment
+* [./src layout](https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout) to separate application logic from tests and project metadata
+* Sane logging configured in a single [logging.conf](./src/python_project/logging.conf) file
+* Optional quality-of-life add-ons:
+  * (further) enforcing of uniform formatting via an [.editorconfig](./.editorconfig)
+  * recommended [VS Code](https://code.visualstudio.com) settings and extensions through a [.vscode](./.vscode) subdirectory
+  * a [Dev Container](https://code.visualstudio.com/docs/devcontainers/containers)-based development environment
+
+The repository contains an example [GitHub Actions](./.github/workflows/) CI pipeline that:
+
+* runs [ruff](https://github.com/astral-sh/ruff)-based linting and formatting, [mypy](https://github.com/python/mypy)-based static type checking, [pytest](https://docs.pytest.org)-based unit testing,
+* performs a [CodeQL](https://codeql.github.com) vulnerability scan,
 * builds and pushes a well-labeled container image to [Google Cloud Artifact Registry](https://cloud.google.com/artifact-registry/docs),
 * executes a simple integration test on [Google Cloud Run](https://cloud.google.com/run?hl=en).
 
@@ -31,19 +36,16 @@ Ensure [Hatch](https://hatch.pypa.io/latest) is [installed](https://hatch.pypa.i
 
 ### Running the Code
 
-Run the [main.py](./src/python_project/main.py) entrypoint via the default Hatch environment with the `--help` flag for an explanation to the application logic:
-
-```shell
-hatch run python src/python_project/main.py --help
-```
+Run the [main.py](./src/python_project/main.py) entrypoint with the `--help` flag for an explanation to the application logic:
 
 ```shell
+hatch run python src/python_project/main.py --help          # Uses the "default" Hatch environment.
 hatch run default:python src/python_project/main.py --help  # Equivalent to not specifying "default:".
 ```
 
 ### Unit Tests
 
-Run the `test` script of the "test" Hatch environment to execute the unit tests and generate a coverage report using [`pytest`](https://docs.pytest.org/en/stable).
+Run the `test` script of the "test" Hatch environment to execute the [`pytest`](https://docs.pytest.org/en/stable)-backed unit tests and generate a [coverage](https://coverage.readthedocs.io/en/7.6.7) report:
 
 ```shell
 hatch run test:test

pyproject.toml

@@ -190,7 +190,7 @@ extra-dependencies = [
   "pre-commit~=4.0.1",
   "pydantic~=2.9.2",
   "pytest~=8.3.3",
-  "ruff~=0.7.3",
+  "ruff~=0.7.4",
 ]
 post-install-commands = ["hatch run lint:pre-commit install"]
 

requirements/requirements-lint.txt

@@ -9,7 +9,7 @@
 # - pre-commit~=4.0.1
 # - pydantic~=2.9.2
 # - pytest~=8.3.3
-# - ruff~=0.7.3
+# - ruff~=0.7.4
 #
 
 annotated-types==0.7.0 \
@@ -282,25 +282,25 @@ rich==13.9.4 \
     # via
     #   -c requirements.txt
     #   typer
-ruff==0.7.3 \
-    --hash=sha256:10ebce7696afe4644e8c1a23b3cf8c0f2193a310c18387c06e583ae9ef284de2 \
-    --hash=sha256:1713e2c5545863cdbfe2cbce21f69ffaf37b813bfd1fb3b90dc9a6f1963f5a8c \
-    --hash=sha256:34f2339dc22687ec7e7002792d1f50712bf84a13d5152e75712ac08be565d344 \
-    --hash=sha256:37d0b619546103274e7f62643d14e1adcbccb242efda4e4bdb9544d7764782e9 \
-    --hash=sha256:3f36d56326b3aef8eeee150b700e519880d1aab92f471eefdef656fd57492aa2 \
-    --hash=sha256:44eb93c2499a169d49fafd07bc62ac89b1bc800b197e50ff4633aed212569299 \
-    --hash=sha256:4ba81a5f0c5478aa61674c5a2194de8b02652f17addf8dfc40c8937e6e7d79fc \
-    --hash=sha256:588a9ff2fecf01025ed065fe28809cd5a53b43505f48b69a1ac7707b1b7e4088 \
-    --hash=sha256:5d024301109a0007b78d57ab0ba190087b43dce852e552734ebf0b0b85e4fb16 \
-    --hash=sha256:5d59f0c3ee4d1a6787614e7135b72e21024875266101142a09a61439cb6e38a5 \
-    --hash=sha256:61b46049d6edc0e4317fb14b33bd693245281a3007288b68a3f5b74a22a0746d \
-    --hash=sha256:6b6224af8b5e09772c2ecb8dc9f3f344c1aa48201c7f07e7315367f6dd90ac29 \
-    --hash=sha256:6d0242ce53f3a576c35ee32d907475a8d569944c0407f91d207c8af5be5dae4e \
-    --hash=sha256:7f3eff9961b5d2644bcf1616c606e93baa2d6b349e8aa8b035f654df252c8c67 \
-    --hash=sha256:b8963cab06d130c4df2fd52c84e9f10d297826d2e8169ae0c798b6221be1d1d2 \
-    --hash=sha256:c50f95a82b94421c964fae4c27c0242890a20fe67d203d127e84fbb8013855f5 \
-    --hash=sha256:e1d1ba2e40b6e71a61b063354d04be669ab0d39c352461f3d789cac68b54a313 \
-    --hash=sha256:fb397332a1879b9764a3455a0bb1087bda876c2db8aca3a3cbb67b3dbce8cda0
+ruff==0.7.4 \
+    --hash=sha256:00b4cf3a6b5fad6d1a66e7574d78956bbd09abfd6c8a997798f01f5da3d46a05 \
+    --hash=sha256:0d06218747d361d06fd2fdac734e7fa92df36df93035db3dc2ad7aa9852cb109 \
+    --hash=sha256:0e92dfb5f00eaedb1501b2f906ccabfd67b2355bdf117fea9719fc99ac2145bc \
+    --hash=sha256:11bff065102c3ae9d3ea4dc9ecdfe5a5171349cdd0787c1fc64761212fc9cf1f \
+    --hash=sha256:2e32829c429dd081ee5ba39aef436603e5b22335c3d3fff013cd585806a6486a \
+    --hash=sha256:3bd726099f277d735dc38900b6a8d6cf070f80828877941983a57bca1cd92172 \
+    --hash=sha256:63a569b36bc66fbadec5beaa539dd81e0527cb258b94e29e0531ce41bacc1f20 \
+    --hash=sha256:662a63b4971807623f6f90c1fb664613f67cc182dc4d991471c23c541fee62dd \
+    --hash=sha256:745775c7b39f914238ed1f1b0bebed0b9155a17cd8bc0b08d3c87e4703b990d6 \
+    --hash=sha256:75c53f54904be42dd52a548728a5b572344b50d9b2873d13a3f8c5e3b91f5cac \
+    --hash=sha256:7dbdc7d8274e1422722933d1edddfdc65b4336abf0b16dfcb9dedd6e6a517d06 \
+    --hash=sha256:80094ecd4793c68b2571b128f91754d60f692d64bc0d7272ec9197fdd09bf9ea \
+    --hash=sha256:876f5e09eaae3eb76814c1d3b68879891d6fde4824c015d48e7a7da4cf066a3a \
+    --hash=sha256:997512325c6620d1c4c2b15db49ef59543ef9cd0f4aa8065ec2ae5103cedc7e7 \
+    --hash=sha256:a4919925e7684a3f18e18243cd6bea7cfb8e968a6eaa8437971f681b7ec51478 \
+    --hash=sha256:cd12e35031f5af6b9b93715d8c4f40360070b2041f81273d0527683d5708fce2 \
+    --hash=sha256:cfb365c135b830778dda8c04fb7d4280ed0b984e1aec27f574445231e20d6c63 \
+    --hash=sha256:e0cea28d0944f74ebc33e9f934238f15c758841f9f5edd180b5315c203293452
     # via hatch.envs.lint
 shellingham==1.5.4 \
     --hash=sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686 \