Repository navigation
Contributing
Development setup, the checks CI runs, and the conventions this repository enforces.
Python 3.12+ is required (3.13 and 3.14 are also supported and tested).
git clone https://github.com/fulviofreitas/eero-api.git
cd eero-api
pip install -e ".[dev]"The [dev] extra installs pytest, pytest-asyncio, pytest-cov, black, isort, mypy,
ruff, rich, click, and commitizen.
Run all of these before opening a pull request — CI runs these plus a Semgrep security scan; a failure in any of them blocks the merge.
pytest # full suite
ruff check . # lint
black . # format
mypy src/ # type-check| Command | What it gates |
|---|---|
🧪 pytest
|
The full suite, unit and integration |
🔍 ruff check .
|
Lint |
🎨 black .
|
Formatting |
🏷️ mypy src/
|
Type-checking of the package source |
🛡️ Semgrep (p/python p/security-audit on src/) |
Security scan — CI-only; run semgrep --config p/python --config p/security-audit src/ locally if you have it |
pytest tests/api/ # unit tests only
pytest tests/integration/ # integration tests only
pytest --cov=eero --cov-report=term-missing # coverage
pytest -k "auth and login" # pattern match
pytest -x -v # stop on first failure, verboseTests mirror the source layout — tests/api/test_<domain>.py for src/eero/api/<domain>.py.
- Mock at the network boundary only. Do not mock internal modules.
-
pytest-asyncioruns in auto mode, soasync def test_…needs no decorator. - Use
AsyncMockfor coroutines and async context managers,MagicMockfor sync dependencies. - Never make real calls to
api-user.e2ro.com. No test may depend on a real account, a real token, or the network. - Cover the failure paths, not just the happy path: auth errors, rate limits, timeouts, malformed or partial response envelopes.
mock_client = AsyncMock()
mock_client.__aenter__ = AsyncMock(return_value=mock_client)
mock_client.__aexit__ = AsyncMock()💡 Tip: Because every method returns a raw envelope, fixtures should be realistic
{"meta": ..., "data": ...}dicts rather than tidy flat objects. See Raw Response Format.
Commits must follow Conventional Commits — commitlint
runs in CI and a non-conforming message fails the build, which skips every other job.
feat(devices): add bulk block support
fix(auth): retry once on session refresh
docs(wiki): correct the caching examples
chore(deps): bump aiohttp
Releases and version bumps are automated from these messages, so the type prefix determines the
next version number. commitizen is available if you want the interactive prompt:
cz commit-
Async everywhere. All network operations are
async/await. -
Raw returns. Every API method returns
Dict[str, Any]— the unmodified upstream response. Do not add parsing, reshaping, or model classes; that is the consumer's job. See Raw Response Format. -
Composition over inheritance. New functionality becomes a domain API class composed into
EeroAPI, not a deeper inheritance chain. -
One domain per module.
src/eero/api/<domain>.pyholds one focused class. -
network_idis a trailing optional kwarg onEeroClientand a required leading positional onEeroAPI/ domain-API methods. See Network Targeting. -
Naming:
snake_casefor functions and modules,PascalCasefor classes,SCREAMING_SNAKE_CASEfor constants. -
Never log secrets. Route logging through the helpers in
src/eero/logging.py. See Logging and Security.
- Create
src/eero/api/<domain>.pywith a class extendingAuthenticatedAPI. - Register it on
EeroAPIinsrc/eero/api/__init__.py. - Add thin
EeroClientwrappers insrc/eero/client.pyif the domain is user-facing, keepingnetwork_idas the trailing optional kwarg and wiring_ensure_network_id. - Add tests under
tests/api/. - Document it in API Reference, and in Python API if it warrants a task-oriented section.
The wiki is generated from the repository, not edited on GitHub. Source lives in
wiki/; the
sync-wiki workflow publishes it on every push to master that touches wiki/**.
- Edits made directly in the GitHub wiki UI will be overwritten on the next sync.
-
_Sidebar.mdand_Footer.mdrender on every page — update_Sidebar.mdwhen adding a page. - Links are wiki-relative and bare:
[Python API](Python-API). - Every code example must be correct against the current source. A broken example is worse than no example — this wiki had to be rebuilt once because its examples drifted several major versions behind the SDK.
- Home — Overview and quick start
- API Reference — The surface you are extending
- Raw Response Format — The architectural rule behind every return type
- Logging and Security — Safe logging requirements
- Ecosystem — Downstream consumers affected by your changes
eero-api — unofficial async Python client for the Eero cloud API. Not affiliated with or endorsed by Eero.
This wiki is generated from wiki/ in the main repository — edit there, not here. · MIT License