Development¶
The project uses uv for dependencies, ruff for formatting and linting, pyrefly for
types, pytest for tests and mkdocs-material for this site.
Setup¶
make
make runs uv sync and installs the pre-commit hooks. The manual equivalent:
uv sync --all-extras --dev
uv run pre-commit install
Python 3.11 or newer is required; CI runs 3.11 - 3.15.
Checks¶
Run the same order as CI:
uv run pyrefly check
uv run ruff check
uv run pytest
make lint runs the first two, make test runs pytest. Pytest defaults come from
pyproject.toml: -xsv tests.py, so the suite stops on the first failure. The suite runs once
per async library (asyncio, trio, curio) through pytest-aio. A focused run:
uv run pytest tests.py::test_login_state_signature
ruff covers muffin_oauth, tests.py and example.py; pyrefly checks muffin_oauth only.
The docs are excluded from both.
Example¶
make example
# or
uv run --group example uvicorn example:app --reload --port 5000
Open http://localhost:5000 and log in with GitHub or Google. The example contains a test client id and secret, so a real round trip only works for the accounts those application credentials belong to.
Documentation¶
make docs # build into ./site, fails on warnings
make docs-serve # live reload on http://127.0.0.1:8000
Pages live in docs/, navigation in mkdocs.yml. The README is the short entry point; details
belong in docs/.
Release¶
make release # minor by default
make release RELEASE=patch
The target checks out master, merges develop, bumps the version with
uvx bump-my-version (configuration lives in pyproject.toml), regenerates uv.lock, commits,
tags, and pushes both branches and the tag. Publishing is done by the release GitHub workflow
with uv build + uv publish once tests passed on master.
Layout¶
muffin_oauth/
__init__.py exports OAuthPlugin (OAuth, Plugin) and OAuthError
plugin.py the whole plugin: client registry, authorize, login, refresh, sign
tests.py pytest suite (root level, configured in pyproject.toml)
example.py runnable GitHub + Google example
docs/ this documentation