Add pre-commit package for django app

.gitignore

@@ -49,7 +49,8 @@ src/django/*.xlsx
 
 
 # VSCode
-.vscode
+.vscode/*
+!.vscode/example-settings.json
 
 # PyCharm
 .idea/

.pre-commit-config.yaml

@@ -0,0 +1,85 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-docker
+        name: ruff (django via docker)
+        language: system
+        entry: docker
+        args:
+          - compose
+          - run
+          - --rm
+          - --no-deps
+          - -v
+          - .:/workspace
+          - -w
+          - /workspace
+          - --entrypoint
+          - ruff
+          - django
+          - check
+          - --fix
+          - --exit-non-zero-on-fix
+          - --config
+          - /workspace/pyproject.toml
+        files: ^src/django/.*\.py$
+
+      - id: isort-docker
+        name: isort (django via docker)
+        language: system
+        entry: docker
+        args:
+          - compose
+          - run
+          - --rm
+          - --no-deps
+          - -v
+          - .:/workspace
+          - -w
+          - /workspace
+          - --entrypoint
+          - isort
+          - django
+          - --settings-path
+          - /workspace/pyproject.toml
+        files: ^src/django/.*\.py$
+
+      - id: black-docker
+        name: black (django via docker)
+        language: system
+        entry: docker
+        args:
+          - compose
+          - run
+          - --rm
+          - --no-deps
+          - -v
+          - .:/workspace
+          - -w
+          - /workspace
+          - --entrypoint
+          - black
+          - django
+          - --config
+          - /workspace/pyproject.toml
+        files: ^src/django/.*\.py$
+
+      - id: flake8-docker
+        name: flake8 (django via docker)
+        language: system
+        entry: docker
+        args:
+          - compose
+          - run
+          - --rm
+          - --no-deps
+          - -v
+          - .:/workspace
+          - -w
+          - /workspace
+          - --entrypoint
+          - flake8
+          - django
+          - --config
+          - /workspace/src/django/.flake8
+        files: ^src/django/.*\.py$

.vscode/example-settings.json

@@ -0,0 +1,27 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "ruff.enable": true,
+  "ruff.importStrategy": "fromEnvironment",
+  "ruff.path": [
+    "${workspaceFolder}/.venv/bin/ruff"
+  ],
+  "black-formatter.path": [
+    "${workspaceFolder}/.venv/bin/black"
+  ],
+  "python.formatting.blackPath": "${workspaceFolder}/.venv/bin/black",
+  "[python]": {
+    "editor.formatOnSave": true,
+    "editor.defaultFormatter": "ms-python.black-formatter",
+    "editor.codeActionsOnSave": {
+      "source.fixAll": "always",
+      "source.fixAll.ruff": "always"
+    }
+  },
+  "python.formatting.provider": "black",
+  "python.formatting.blackArgs": [
+    "--line-length=88",
+    "--config",
+    "pyproject.toml"
+  ],
+  "python.linting.ruffEnabled": true
+}

README.md

@@ -9,15 +9,19 @@ Open Supply Hub (OS Hub) is a tool to identify every goods production facility w
   - [Kick-off & start local development](#kick-off--start-local-development)
   - [Restore the DB dump in the local Docker DB container](#restore-the-db-dump-in-the-local-docker-db-container)
   - [US County Tigerline Data Setup](#us-county-tigerline-data-setup)
+    - [Local Development](#local-development)
   - [Running ECS Management Commands](#running-ecs-management-commands)
   - [Creation of Superusers](#creation-of-superusers)
   - [Upload a list and process it](#upload-a-list-and-process-it)
   - [Hot Reloading 🔥](#hot-reloading-🔥)
   - [Debugging Django](#debugging-django)
   - [Embedded Maps](#embedded-maps)
   - [Ports](#ports)
+  - [Linting & git hooks for Django app](#linting--git-hooks-for-django-app)
 - [Scripts 🧰](#scripts-🧰)
 - [Tools ⚒️](#tools-⚒️)
+- [Running e2e (Playwright) and integration tests](#running-e2e-playwright-and-integration-tests)
+  - [Playwright Tests](#playwright-tests)
 
 
 ## Requirements
@@ -244,6 +248,24 @@ be available on their page, or you can visit http://localhost:6543/?embed=1&cont
 | React development server | [`6543`](http://localhost:6543) |
 | Gunicorn for Django app  | [`8081`](http://localhost:8081) |
 
+### Linting & git hooks for Django app
+
+- **Local virtual environment (`.venv`) setup**: The `.venv` virtual environment is **not created automatically** and must be set up manually for local editor tooling (Black, Ruff) and pre-commit. Note that `./scripts/start_local_dev` uses Docker and does not create `.venv`—create it separately for editor integration. To set up:
+  1. Create the virtual environment: `python3 -m venv .venv` (or `python -m venv .venv` on some systems)
+  2. Activate it:
+     - macOS/Linux: `source .venv/bin/activate`
+     - Windows: `.venv\Scripts\activate`
+  3. Install tools: `pip install pre-commit black ruff` (Note: `black` and `ruff` are already in `src/django/requirements.txt`; for minimal editor tooling, install them separately as shown, or install from `src/django/requirements.txt` if you need other Django dependencies in your `.venv`)
+  4. Enable pre-commit git hooks: `pre-commit install`
+- **Pre-commit setup**: Pre-commit orchestrates the hooks locally, but the hooks themselves execute inside the django Docker container to match CI. **Prerequisite**: Build the Docker image first (e.g., `docker compose build` or `./scripts/update`) so hooks can run successfully. To run hooks manually: `pre-commit run --all-files` (runs ruff --fix, isort, black, then flake8 inside the django container).
+- **Local first wall**: Enable on-save formatting/fixes in your editor (Black + Ruff) using the repo `.venv`. Configure your editor to use `.venv`'s Python interpreter and formatter binaries (not Docker).
+- Recommended VS Code/Cursor setup for on-save:
+  - Select interpreter: Command Palette → `Python: Select Interpreter` → `.venv/bin/python`.
+  - Install extensions: “Python” + “Ruff” + “Black Formatter (ms-python)”.
+  - Enable format on save and Ruff fixes (see `.vscode/settings.json` for reference): Black as default formatter, `source.fixAll` + `source.fixAll.ruff` on save, paths to `.venv/bin/black` and `.venv/bin/ruff` (not Docker binaries).
+-  Example settings file: `.vscode/example-settings.json`. Copy to `.vscode/settings.json` to apply.
+
+- Config lives in `.pre-commit-config.yaml` with settings in `pyproject.toml` and `src/django/.flake8` (excludes migrations, settings.py, manage.py).
 
 ## Scripts 🧰
 

pyproject.toml

@@ -0,0 +1,20 @@
+[tool.black]
+line-length = 88
+target-version = ["py38"]
+extend-exclude = "api/migrations/|settings\\.py|manage\\.py"
+
+[tool.isort]
+profile = "black"
+line_length = 88
+src_paths = ["src/django"]
+skip = ["api/migrations"]
+
+[tool.ruff]
+target-version = "py38"
+line-length = 88
+src = ["src/django"]
+extend-exclude = ["settings.py", "manage.py", "api/migrations/*"]
+
+[tool.ruff.lint]
+extend-ignore = ["E203"]
+

src/django/.flake8

@@ -0,0 +1,7 @@
+[flake8]
+# Keep local linting aligned with the CI invocation from scripts/run_be_code_quality
+# and .github/workflows/code_quality.yml.
+exclude = settings.py, manage.py, *.pyc, api/migrations/*
+max-line-length = 88
+extend-ignore = E203, W503
+

src/django/requirements.txt

@@ -22,6 +22,9 @@ django-ckeditor-5==0.2.19
 djangorestframework-gis==1.1.0
 djangorestframework==3.15.2
 flake8==7.1.0
+black==26.1.0
+isort==7.0.0
+ruff==0.14.14
 mccabe==0.7.0
 mercantile==1.2.1
 openpyxl==3.1.5