==============
Best Practices
==============

Project conventions for all new and modified code live in
``.cursor/rules/python_best_practices.mdc`` (with peer files for
``dependency_management``, ``documentation``, ``environment_best_practices``,
``git_workflow``, ``pull_request``, and ``security``). That file is the
authoritative standard; this page lists the rules that come up most often.

Code style
----------

* Maximum line length: 100 characters (enforced by Ruff).
* Naming: ``lowercase_with_underscores`` for functions and local variables,
  ``TitleCase`` for classes, ``ALL_CAPS_WITH_UNDERSCORES`` for module-level
  constants. Prefix non-public names with a single underscore.
* Type-annotate every function parameter and return value, including
  ``-> None``. Use modern ``list[str]``, ``dict[str, int]``, ``X | None``
  syntax.
* Keep modules under 1000 lines. Split larger modules into a package.
* Do not introduce backwards-compatibility shims unless explicitly requested;
  change the code instead.

Linting and typing
------------------

* Run ``ruff check src tests`` and ``ruff format --check src tests`` on the
  full codebase after changes.
* Run ``mypy src tests`` and fix every error. Do not add module-level
  ``# mypy: ignore-errors`` or global ``exclude`` entries. A line-level
  ``# type: ignore[error-code]`` is acceptable only with a brief
  justification.

Testing
-------

* Use ``pytest`` with ``pytest-xdist``; the canonical command is
  ``pytest -n auto --dist=loadfile`` (the ``--dist=loadfile`` flag is
  required because PyQt6 workers crash under default xdist scheduling).
* Annotate test function parameters and return types; return ``-> None``.
* One assertion per condition (no ``and`` in assertions). When testing
  exceptions, use ``pytest.raises`` as a context manager and assert on the
  exception message content via ``match=``.
* Target at least 90 % line coverage over the full suite.

Documentation
-------------

* Every module, class, function, and method has a docstring written in
  Google style with ``Parameters:``, ``Returns:``, and ``Raises:`` as
  needed. Wrap docstring text to 90 characters.
* Do not use smart quotes, em-dashes, or arrows in ``.py`` files (they are
  fine in ``.rst`` and ``.md``).
* Update docstrings when the associated code changes, and remove them when
  the code is removed.
* After a code change, run ``sphinx-build -W -b html docs docs/_build`` and
  fix every warning.