Stop tracking compiled Python files and forbid committing them

.gitignore

@@ -1,8 +1,6 @@
-# Ignore PyCaches
-koopmanrl/__pycache__/
-koopmanrl/environments/__pycache__/
-tests/__pycache__/
-koopmanrl_utils/movies/__pycache__/
+# Ignore PyCaches and compiled Python files, in every directory
+__pycache__/
+*.py[cod]
 
 # Ignore simulation results
 runs/
@@ -18,7 +16,6 @@ tsne_koopman_tensor_results/
 skvi_policy_checks_results/
 skvi_sensitivity_checks_results/
 koopman_prediction_validation_results/
-koopmanrl_utils/__pycache__/
 
 # Output of koopmanrl_utils/koopman_regressor_comparison.py
 koopman_regressor_comparison_results/
@@ -32,4 +29,3 @@ ablation_results/
 # Output and bookkeeping of the Snakemake workflows in workflow/
 results/
 .snakemake/
-workflow/__pycache__/

.pre-commit-config.yaml

@@ -28,3 +28,11 @@ repos:
           - id: isort
             name: isort (python)
             args: ["--profile", "black"]
+
+    - repo: local
+      hooks:
+          - id: forbid-compiled-python
+            name: Forbid compiled Python files
+            entry: Compiled Python files (.pyc, .pyo, .pyd, __pycache__/) must not be committed
+            language: fail
+            files: '(\.py[cod]$|(^|/)__pycache__/)'

AGENTS.md

@@ -49,7 +49,7 @@ workflow/                Snakemake workflows: Snakefile, rules/*.smk, helpers.py
 
 ## Testing, Linting and CI
 - Run the tests of what you touch: `uv run pytest tests/test_<area>.py [-k <name>]`. There are no pytest markers; `uv run pytest` runs the whole suite (several minutes). Details and known failures are in `tests/AGENTS.md`.
-- `uv run pre-commit run --files <changed files>` (or `--all-files`): ruff (`--fix`, format; line length 120), isort (`--profile black`), vulture on `koopmanrl/`, and the basic pre-commit-hooks (whitespace, end of file, YAML, files > 1 MB, merge conflicts, debug statements).
+- `uv run pre-commit run --files <changed files>` (or `--all-files`): ruff (`--fix`, format; line length 120), isort (`--profile black`), vulture on `koopmanrl/`, the basic pre-commit-hooks (whitespace, end of file, YAML, files > 1 MB, merge conflicts, debug statements), and the local `forbid-compiled-python` hook, which fails on any `.pyc`/`.pyo`/`.pyd` or `__pycache__/` file. Compiled Python files are also gitignored in every directory, so none are tracked.
 - CI runs only pre-commit (`lint.yml`) and the docs build (`test-deploy-docs.yml` on PRs, `deploy-docs.yml` on `main`, Node 20). It does not run pytest, so run the relevant tests locally.
 - Docs site: `cd docs && npm ci && npm run build`; the build fails on broken links.
 

docs/docs/developers/contributing.md

@@ -43,6 +43,7 @@ The repository enforces formatting and linting via pre-commit:
 - **Ruff** — linting with `--fix` (`ruff`) and formatting (`ruff-format`), line length 120
 - **isort** — import sorting with `--profile black`
 - **Vulture** — dead-code detection on `koopmanrl/` with `--min-confidence 80`
+- **forbid-compiled-python** — a local hook that fails on any compiled Python file (`.pyc`, `.pyo`, `.pyd`, `__pycache__/`); these are gitignored and must not be committed
 
 In CI, `.github/workflows/lint.yml` runs `pre-commit run --all-files` on every pull request and push to `main`, and `.github/workflows/test-deploy-docs.yml` builds this documentation site on pull requests to `main`.
 

koopmanrl/environments/AGENTS.md

@@ -28,6 +28,6 @@ Each environment module calls `gym.envs.registration.register` at import, under
 
 * `gym==0.23.1` is pinned; its warning that Gym is unmaintained is expected.
 * `koopmanrl_utils/movies/` plots only FluidFlow, Lorenz and DoubleWell.
-* `__pycache__/` of this directory holds tracked `.pyc` files (including those of removed cartpole environments); they show up as modified after any run. Do not commit them.
+* `__pycache__/` of this directory is regenerated on import and gitignored, like every compiled Python file of the repository; the `forbid-compiled-python` pre-commit hook rejects one that is committed anyway (e.g. force-added).
 
 See the root `AGENTS.md` for setup, testing and the working checklist.