.cursorrules

Activating environments
-----------------------

When trying to run any invoke or Django command use the following to enable environments:

```
source venv/bin/activate
```


Checking code quality
---------------------

All code quality commands are expected to run from the root of the repository.

You can check the unit tests by running the following from the source of the project:

```
invoke test.run
```

You should also check basic syntax with:

```
flake8 .
```


Style guidelines
----------------

Apart from using flake8 the following guidelines also apply.

Step by step we're moving all legacy code over to use type hints compatible with Python 3.10.
New code should use type hints.

In this repo we use double quotes wherever possible, because that's easier with the English language in strings.

Our max line length is 120 characters, because our screens are somewhat wider than terminals from the 70's.
Having multiple windows fit on a single screen is still beneficial, so having a limit is good.
But adding a comment with "noqa: E501" can make code more readable especially with long error messages.

Prefer function and method definitions on a single line when they fit reasonably.
If a signature needs wrapping, prefer a compact two-line rewrite over one argument per line where possible.
Do not introduce a vertical signature with a single argument on each line unless there is no cleaner option.
Favor left-to-right readability of the signature over strict adherence to the line limit when the result is still clear.

As an example never ever do this:

```python
    def __init__(
            self, defaults: dict[str, Any] | None = None, namespace: str = "global",
            private: Sequence[str] = ("_private", "_defaults", "_namespace",)
    ) -> None:
        ...
```

Always write these cases like this:

```python
    def __init__(self, defaults: dict[str, Any] | None = None, namespace: str = "global",
                 private: Sequence[str] = ("_private", "_defaults", "_namespace",)) -> None:
        ...
```


Working on Resources
--------------------

When developing `Resource` integrations, follow this workflow:

1) Live-first development
- Use real-world input and a live dependency first (for example: local Tika, vendor API).
- Keep tests on the normal `Resource.extract(...).close()` path while iterating.
- Do not bypass the public extraction flow unless a test is explicitly about a lower-level helper.

2) Assert contract behavior
- Assert the behavior we care about for the resource contract (status, content shape, key metadata).
- Prefer assertions that describe the boundary contract over implementation details.

3) Snapshot lock-in (boundary isolation)
- After behavior is correct, record snapshots with `invoke test.run --snapshots`.
- In non-snapshot runs, tests should load from snapshots and avoid live calls.
- Snapshot mode is for updating fixtures, not for changing normal assertion intent.

4) Contract change workflow
- If upstream contract changes, re-run with `--snapshots` to refresh captured responses.
- Then update the `Resource` implementation/tests to match the new contract.

Guardrails:
- Do not rewrite tests to bypass `Resource.extract()` just to force an error path, unless explicitly requested.
- Do not add `@pytest.mark.snapshots` to tests that are not part of snapshot recording/update workflow.
- Keep snapshot and non-snapshot behavior explicit and aligned with the same public resource flow.