Retire EnvLock and the env-mutation guards from test_support (#494)

.rules/python-00.md

@@ -0,0 +1,133 @@
+# Python 3.14 code style guidelines (with Ruff, Pyright, and pytest)
+
+## Naming Conventions
+
+- **Directories:** Use *snake_case* for top-level features or modules (e.g.,
+  `data_pipeline`, `user_auth`).
+- **Files:** Use *snake_case.py*; name for contents (e.g., `http_client.py`,
+  `task_queue.py`).
+- **Classes:** Use *PascalCase*.
+- **Variables & Functions:** Use *snake_case*.
+- **Constants:** Use *UPPER_SNAKE_CASE* for module-level constants.
+- **Private/Internal:** Prefix with a single underscore (`_`) for non-exported
+  helpers or internal APIs.
+
+## Python Typing Practices
+
+- **Use typing everywhere.** Enable and maintain full static type coverage. Use
+  Pyright for type-checking.
+- **Use `TypedDict` or `Dataclass` for structured data where appropriate.** For
+  internal-only usage, prefer `@dataclass(slots=True)`.
+- **Avoid `Any`.** Prefer concrete types, `object`, generics, or type variables.
+  Use a documented `cast()` or `Any` only when the boundary requires it.
+- **Be explicit with returns.** Use `-> None`, `-> str`, etc., for all public
+  functions and class methods.
+  - **Favour immutability.** Prefer tuples to lists, and `frozendict` or
+    `types.MappingProxyType` where appropriate.
+
+## Tooling and Runtime Practices
+
+- **Enable Ruff.** Use Ruff to lint for performance, security, consistency, and
+  style issues. Enable fixers and formatters.
+- Use `pyproject.toml` to configure tools like Ruff, Pyright, and Pytest.
+- **Enforce `strict` in Pyright.** Treat all Pyright warnings as CI errors. Use
+  `# pyright: ignore` sparingly and with explanation.
+- **Avoid side effects at import time.** Modules should not modify global state
+  or perform actions on import.
+- **Use `.env` or settings modules** for environment-specific configuration.
+  Never hardcode secrets.
+
+## Linting and Formatting
+
+- **Use Ruff for linting** (replacing flake8, isort, pyflakes, etc.).
+- **Use Ruff for formatting**. Let Ruff handle whitespace and formatting
+  entirely—don't fight it.
+
+## Documentation
+
+- **Use docstrings.** Document public functions, classes, and modules using
+  NumPy format. For example:
+
+```python
+def scale(values: list[float], factor: float) -> list[float]:
+    """
+    Scale a list of numbers by a given factor.
+
+    Parameters
+    ----------
+    values : list of float
+        The list of numeric values to scale.
+    factor : float
+        The multiplier to apply to each value.
+
+    Returns
+    -------
+    list of float
+        The scaled numeric values.
+    """
+    return [v * factor for v in values]
+```
+
+- **Explain tricky code.** Use inline comments for non-obvious logic or
+  decisions.
+- **Colocate documentation.** Keep README.md or `docs/` near reusable packages;
+  include usage examples.
+
+## Testing with pytest
+
+- **Colocate unit tests with code** using an `unittests` subdirectory and a
+  `test_` prefix. This keeps logic and its tests together:
+
+```text
+user_auth/
+  models.py
+  login_flow.py
+  unittests/
+    test_models.py
+    test_login_flow.py
+```
+
+- **Structure integration tests separately.** When tests span multiple
+  components, use `tests/integration/`:
+
+  ```text
+  tests/
+    integration/
+      test_login_flow.py
+      test_user_onboarding.py
+  ```
+
+- **Use `pytest` idioms.** Prefer fixtures over setup/teardown methods.
+  Parametrize broadly. Avoid unnecessary mocks.
+
+- **Group related tests** using `class` with method names prefixed by `test_`.
+
+- **Write tests from a user's perspective.** Test public behaviour, not
+  internals.
+
+- **Avoid mocking too much.** Prefer test doubles only for external services or
+  non-deterministic behaviours.
+
+## Example
+
+```python
+# login_flow.py
+def login_user(username: str, password: str) -> bool:
+    """Return True if the user is authenticated."""
+    ...
+
+
+# login_flow_test.py
+def test_login_success():
+    assert login_user("alice", "correct-password") is True
+
+
+def test_login_failure():
+    assert not login_user("alice", "wrong-password")
+```
+
+______________________________________________________________________
+
+This style guide aims to foster clean, consistent, and maintainable Python 3.14
+code with modern tooling. The priority is correctness, clarity, and developer
+empathy.

.rules/python-context-managers.md

@@ -0,0 +1,111 @@
+# Using Context Managers for Cleanup and Resource Management
+
+Use context managers to encapsulate setup and teardown logic cleanly and
+safely. This reduces the risk of forgetting to release resources (files, locks,
+connections, etc.) and simplifies error handling.
+
+Context managers can be written either with `contextlib.contextmanager` (for
+simple procedural control flow) or by implementing `__enter__` and `__exit__`
+in a class (for more complex or stateful use cases).
+
+## Why Use Context Managers?
+
+- **Safety:** Ensures cleanup occurs even if an exception is raised.
+- **Clarity:** Reduces boilerplate and visually scopes side effects.
+- **Reuse:** Common setup/teardown logic becomes reusable and composable.
+
+______________________________________________________________________
+
+## Example: Using `contextlib.contextmanager`
+
+Use this for straightforward procedural setup/teardown:
+
+```python
+from contextlib import contextmanager
+
+
+@contextmanager
+def managed_file(path: str, mode: str):
+    f = open(path, mode)
+    try:
+        yield f
+    finally:
+        f.close()
+
+
+# Usage:
+with managed_file("/tmp/data.txt", "w") as f:
+    f.write("hello")
+```
+
+This avoids repeating `try/finally` in every file access.
+
+______________________________________________________________________
+
+## Example: Using a Class-Based Context Manager
+
+Use this when state or lifecycle logic spans methods:
+
+```python
+class Resource:
+    def __enter__(self):
+        self.conn = connect()
+        return self.conn
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.conn.close()
+
+
+# Usage:
+with Resource() as conn:
+    conn.send("ping")
+```
+
+This keeps state encapsulated and makes testing easier.
+
+______________________________________________________________________
+
+## When to Use Which
+
+- Use `@contextmanager` when control flow is linear and no persistent state is
+  required.
+
+- Use a class when:
+
+  - There is internal state or methods tied to the resource lifecycle.
+  - You need to support re-entry or more advanced context features.
+
+______________________________________________________________________
+
+## Common Use Cases
+
+- File or network resource handling
+- Lock acquisition and release
+- Temporary resources and isolated environment changes (e.g., `patch`,
+  `tempfile`)
+- Logging scope control or tracing
+- Transaction control in databases or services
+
+______________________________________________________________________
+
+## Don't Do This
+
+```python
+f = open("file.txt")
+try:
+    process(f)
+finally:
+    f.close()
+```
+
+## Do This Instead
+
+```python
+with open("file.txt") as f:
+    process(f)
+```
+
+Context managers make intent and error handling explicit. Prefer them over
+manual `try/finally` for clearer, safer code. For directory-dependent work,
+inject the directory explicitly or run a child process with its working
+directory set; do not change the process working directory with `os.chdir`.