# Copilot instructions for `django-environ`

## Build, test, and lint commands

- Install local dev dependencies:
  - `python3 -m venv .venv && . .venv/bin/activate`
  - `python -m pip install -U pip tox tox-gh-actions setuptools`
- Run the default local test workflow (matches CI entrypoint): `tox`
- Run one tox environment explicitly (recommended for iteration): `tox -e py312-django51`
- Run a single test: `tox -e py312-django51 -- tests/test_env.py::TestEnv::test_int`
- Lint: `tox -e lint`
- Build/package checks: `tox -e build`
- Docs and doctests: `tox -e docs`
- Link checks in docs: `tox -e linkcheck`
- Manifest validation: `tox -e manifest`
- Coverage combine/report after test runs: `tox -e coverage-report`
- Locally ZSH is used, keep in mind when you executing commands (like commits messages using back-ticks)
- For GitHub CLI commands that can invoke a pager (`gh pr view`, `gh issue view`, etc.), use `GH_PAGER=cat` to avoid interactive blocking.

## High-level architecture

- Core implementation is concentrated in `environ/environ.py`:
  - `Env` provides typed env access (`env()`, `env.bool()`, `env.db()`, `env.cache()`, etc.).
  - URL-to-Django-settings parsing is centralized in class methods and scheme maps (`DB_SCHEMES`, `CACHE_SCHEMES`, `EMAIL_SCHEMES`, `SEARCH_SCHEMES`, `CHANNELS_SCHEMES`).
  - `Env.read_env()` loads `.env` values into `os.environ` using `setdefault` semantics unless `overwrite=True`.
  - `Path` is a small path helper used by users in Django settings modules.
- `FileAwareEnv` (in `environ/environ.py`) swaps `ENVIRON` to `FileAwareMapping` (`environ/fileaware_mapping.py`) so `FOO_FILE` takes precedence over `FOO`.
- Compatibility/backward-driver selection lives in `environ/compat.py` (Django/redis/postgres/pymemcache driver decisions).
- Public package API is exported via `environ/__init__.py` (`from .environ import *`), and package metadata/version are also defined there and reused by `setup.py`.
- Tests are behavior-first and organized by parser domain (`tests/test_db.py`, `tests/test_cache.py`, `tests/test_email.py`, `tests/test_search.py`, etc.).

## Key repository conventions

- Keep changes small and targeted; this project expects focused PRs against `develop` (see `CONTRIBUTING.rst`).
- For public-facing text (e.g., commit messages, PR/issue comments), always write in English.
- Use `develop` as the operational integration branch; do not create extra release/aggregation branches unless explicitly requested.
- When adding/changing URL parsing behavior, update both the relevant scheme map(s) in `Env` and matching domain tests under `tests/`.
- Preserve `.env` loading behavior in `read_env()`:
  - default is non-overwriting (`setdefault`)
  - comments parsing is opt-in (`parse_comments=True`)
  - invalid lines should warn rather than crash.
- Tests often isolate environment state by replacing `os.environ` / `Env.ENVIRON` with fixtures (for example `FakeEnv.generate_data()`); follow that pattern for deterministic tests.
- CI matrix is driven by tox env naming (`py<python>-django<version>`), with mapping in `[gh-actions]` in `tox.ini`; keep new env names consistent there.
- For docs tasks, keep Python version assumptions aligned between tox docs envs and GitHub workflows (`docs.yml`, comments in `tox.ini`).
