PyAgoraRTC 0.2.0__tar.gz

pyagorartc-0.2.0/.claude/agents/code-reviewer.md

@@ -0,0 +1,43 @@
+---
+name: code-reviewer
+description: Reviews a change in pyagorartc against CONSTITUTION.md, docs/architecture.md and docs/code_style.md. Reports findings by severity with file:line; does not rewrite. Launch over any non-trivial change before reporting it complete.
+model: opus
+tools: Read, Grep, Glob, Bash
+---
+
+You review code in the `pyagorartc` repository. Read `CONSTITUTION.md`,
+`docs/architecture.md` §1–§3 and `docs/code_style.md` before looking at the
+change. The change is the working-tree diff unless the prompt names files.
+
+Check, in this order:
+
+1. **Constitution violations** (blocking): layer direction, secrets in
+   logs/repr/exceptions, a non-success response returned instead of raised,
+   a retry timer or cooldown in auth, a second home for a concern listed in
+   architecture §3, host (Home Assistant) knowledge in the package.
+2. **Contract with the spec** (blocking): field names and types against
+   `docs/api/<group>.md` and `docs/openapi/mower.json`; required vs optional;
+   enum values verbatim; timestamps as `*_ms: int`.
+3. **Error mapping** (blocking): every status/envelope path maps to exactly
+   the exception in architecture §2.3; `TransportError` never mutates auth
+   state; `CredentialsRejectedError` is terminal and fails fast.
+4. **Style** (major/minor): comments that restate code, docstrings missing
+   on public names, `Any` in public signatures, magic numbers, imports inside
+   functions, dead code, naming.
+5. **Docs drift** (major): a change to behaviour without the matching edit in
+   `docs/`; a new choice without a `Dn`; a new unknown without a `Qn`.
+
+Report as:
+
+```
+BLOCKING
+- path:line — finding. Why it matters. What the fix is (one line).
+MAJOR
+- ...
+MINOR
+- ...
+OK — what is good and should stay.
+```
+
+Do not edit files. Do not pad with praise. If there is nothing blocking, say so
+in the first line.

pyagorartc-0.2.0/.claude/agents/test-reviewer.md

@@ -0,0 +1,48 @@
+---
+name: test-reviewer
+description: Reviews tests in pyagorartc against docs/testing.md. Reports findings by severity with file:line; does not rewrite. Launch over every test file written or modified before reporting the work complete.
+model: opus
+tools: Read, Grep, Glob, Bash
+---
+
+You review tests in the `pyagorartc` repository against `docs/testing.md`,
+which is the testing constitution. Read it first. The files under review are
+named in the prompt; otherwise review every test file in the working-tree
+diff.
+
+Check:
+
+1. **Tier and placement** (blocking): a unit test importing
+   `tests.fakeserver` or opening a socket; a test module that does not mirror
+   its source module (`tests/unit/<pkg>/test_<module>.py`); a regression test
+   without the marker, without a docstring saying what the code did wrong, or
+   that could not have been red before the fix.
+2. **Doubles** (blocking): any `MagicMock`/`Mock`/`patch` on a collaborator
+   that `tests/unit/_fakes.py` covers; mocking the unit under test; asserting
+   on call plumbing where an outcome was available.
+3. **Time and concurrency** (blocking): `asyncio.sleep(x)` with `x > 0`;
+   unbounded waits; reading the real clock; non-deterministic interleaving.
+4. **Secrets** (blocking): a real-looking credential or hostname; a test that
+   does not assert redaction where the code redacts.
+5. **Quality** (major/minor): a test that asserts nothing; several behaviours
+   in one test; names that do not read as a sentence; builders duplicated
+   instead of taken from `_helpers.py` / `_fakes.py`; fixtures with side
+   effects; missing negative cases for every documented exception.
+6. **Coverage of the contract** (major): for each public method in the
+   source module, is there a test for the success path, each documented
+   exception, and the tolerant-decoding rule (unknown field, unknown enum)?
+
+Run `uv run pytest <files> -q` and report the result. Report as:
+
+```
+RESULT: <pytest summary line>
+BLOCKING
+- path:line — finding, why, fix.
+MAJOR
+- ...
+MINOR
+- ...
+OK — what is good.
+```
+
+Do not edit files. The author fixes.

pyagorartc-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check pyagorartc/
+      - run: uv run pytest --cov --cov-report=term-missing

pyagorartc-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,73 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check pyagorartc/
+      - run: uv run pytest
+
+  publish:
+    needs: checks
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # trusted publishing to PyPI
+      contents: write  # GitHub release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --frozen
+
+      # The tag and the package version are compared after PEP 440 normalisation,
+      # so v0.2.0-beta1, v0.2.0.b1 and v0.2.0b1 all match a 0.2.0b1 package.
+      - name: Check package version matches tag
+        id: version
+        run: |
+          TAG_VERSION=${GITHUB_REF#refs/tags/v}
+          uv run python - "$TAG_VERSION" <<'PY'
+          import importlib.metadata, os, sys
+          from packaging.version import InvalidVersion, Version
+
+          package_version = Version(importlib.metadata.version("pyagorartc"))
+          try:
+              tag_version = Version(sys.argv[1])
+          except InvalidVersion:
+              sys.exit(f"Tag version ({sys.argv[1]}) is not a valid PEP 440 version")
+          if package_version != tag_version:
+              sys.exit(f"Package version ({package_version}) does not match tag version ({tag_version})")
+
+          with open(os.environ["GITHUB_OUTPUT"], "a") as fh:
+              fh.write(f"prerelease={str(package_version.is_prerelease).lower()}\n")
+              fh.write(f"version={package_version}\n")
+          PY
+
+      - run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          verbose: true
+          print-hash: true
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          prerelease: ${{ steps.version.outputs.prerelease }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

pyagorartc-0.2.0/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

pyagorartc-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.7
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty
+        entry: uv run ty check pyagorartc/
+        language: system
+        pass_filenames: false
+        types: [python]
+      - id: unit-tests
+        name: unit tests
+        entry: uv run pytest tests/unit tests/meta -q
+        language: system
+        pass_filenames: false
+        types: [python]

pyagorartc-0.2.0/.python-version

@@ -0,0 +1 @@
+3.13

pyagorartc-0.2.0/CLAUDE.md

@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+Guidance for agents working in this repository. Read `CONSTITUTION.md` first;
+it is short and it is binding.
+
+## What this is
+
+`pyagorartc`: an async Python client for Agora RTC signalling, reverse-engineered
+from Agora's Web SDK and hardened by two Home Assistant integrations
+(Mammotion mowers, PetKit cameras). It is host-agnostic: no Home Assistant, no
+vendor library, no vendor behaviour except through documented extension
+points.
+
+## Commands
+
+```bash
+uv sync
+uv run ruff check --fix . && uv run ruff format .
+uv run ty check pyagorartc/
+uv run pytest                      # all tiers except live
+uv run pytest tests/unit           # fast tier
+uv run pre-commit run --all-files
+```
+
+## Where things are
+
+| Need | Read |
+|---|---|
+| the rules | `CONSTITUTION.md` |
+| the map (layers, session lifecycle, single homes, recipes) | `docs/architecture.md` |
+| the protocol as we know it | `docs/protocol.md`, `tests/fixtures/` |
+| how to write code / tests | `docs/code_style.md`, `docs/testing.md` |
+| why something is the way it is | `docs/decisions.md` (cite as D7) |
+| what we do not know | `docs/open_questions.md` (cite as Q2) |
+| how a host adopts the library | `docs/migration.md` |
+| what is left to do | `docs/backlog.md` |
+
+## Rules of work
+
+- **Audit before adding.** Every concern has a single home
+  (`architecture.md` §3). Extend the existing site.
+- **Traceability.** A change to what goes on the wire cites its source
+  (fixture, SDK behaviour, or a regression test that was red).
+- **No host or vendor imports** anywhere under `pyagorartc/`. The meta tests
+  enforce it.
+- **Tests before merge, in the right tier.** Regression tests are seen red
+  first and marked `regression`. Launch `test-reviewer` over any test file you
+  touched and fix its blocking findings before reporting done.
+- **Reviews.** Non-trivial changes get `code-reviewer` before they are
+  reported complete. The author fixes; the reviewer does not rewrite.
+- **Decisions are written down.** New choice → `Dn`; new unknown → `Qn`.
+- **No secrets anywhere** in logs, reprs, exceptions, fixtures (redact), tests
+  or commit messages.
+- **Comments say why, in one or two lines, or do not exist.**
+- **Commits**: imperative subject, one change per commit, no attribution
+  trailers.

pyagorartc-0.2.0/CONSTITUTION.md

@@ -0,0 +1,89 @@
+# Constitution
+
+The rules that do not bend. `docs/` explains how to apply them; this file says
+what they are. Breaking one needs a new numbered entry in `docs/decisions.md`
+that supersedes the rule, not a quiet exception.
+
+## 1. Protocol fidelity is traceable
+
+`pyagorartc` speaks a signalling protocol that Agora has not published for
+Python. Every behaviour on the wire traces to one of: a recorded exchange
+(`tests/fixtures/`), the documented behaviour of Agora's Web SDK, or a fix
+that carries a regression test. A behaviour that traces to nothing is a guess,
+and a guess is written down in `docs/open_questions.md` before it ships. The
+hard-won fixes (MID extension stripping, DTLS role, no `set_client_role` after
+join, msid stream id, peer recovery) are pinned by tests, not by comments.
+
+## 2. One library, many vendors, no host
+
+Mammotion mowers and PetKit cameras both publish through Agora; other vendors
+will. The library knows channels, tokens, edges, SDP and gateway messages. It
+does not know mowers, feeders, `pymammotion`, `pypetkitapi`, or Home
+Assistant. Vendor-specific behaviour (a keep-alive the device needs, a way to
+re-request the stream) enters through callbacks and options on the session,
+never through an import. If a vendor needs something the session cannot
+express, the session grows a documented extension point.
+
+## 3. Layers point one way
+
+```
+sdp  ←  ap  ←  session  ←  (host)        rtm  ←  (host)
+```
+
+`sdp/` is pure: text and dicts in, text and dicts out, no I/O (it may read
+`const` values). `ap/` talks
+HTTP to Agora's access points. `session/` drives one WebSocket gateway
+session and composes the two. `rtm/` is independent of all three. Nothing
+imports upward. The public surface is
+`pyagorartc.__all__`.
+
+## 4. All I/O is asynchronous and owned
+
+Every network call is `async`. Background work (ping, keep-alive, peer
+recovery, restart) runs in tasks the session owns and cancels when it ends
+(`close()` or any other ending); nothing is fire-and-forget. A host may supply its own aiohttp
+session; the library never closes one it did not create.
+
+## 5. Errors are typed and scoped
+
+A failed edge discovery, a rejected join, a lost gateway connection and a
+malformed message are different exceptions with different recoveries, and
+they say which without a string match. Transient failures never change
+credential or session state. The session reports its lifecycle through one
+state enum and one event callback, not through log lines.
+
+## 6. Secrets stay secret
+
+Tokens, tickets, credentials, TURN passwords and channel encryption keys never
+appear in log lines, `repr`, or exception messages. Logs may carry a
+fingerprint (short hash) and nothing more.
+
+## 7. Wire messages are tolerant, fixtures are exact
+
+An unknown message type, an extra field or a missing optional field never
+crashes the session; it is logged once at DEBUG and ignored. Fixtures in
+`tests/fixtures/` are byte-exact recordings (redacted) and tests assert
+against them exactly; when the wire changes, the fixture changes with a
+commit that says why.
+
+## 8. Tests are part of the deliverable
+
+Nothing merges without tests in the right tier (`docs/testing.md`). Pure
+code (SDP, ORTC, payload building, ICE selection) is tested directly.
+The session is tested against an in-process fake gateway that speaks the
+recorded protocol. Doubles are real objects or hand-written fakes; a bare
+`MagicMock` is not a test double.
+
+## 9. Documentation lives outside the code
+
+Design is in `docs/`. A comment states a constraint the code cannot express,
+in one or two lines. Every non-obvious choice is a numbered decision; every
+unknown is a numbered open question; every intended change is a backlog
+entry.
+
+## 10. The public surface is deliberate
+
+`pyagorartc.__all__` lists the supported API. Anything else may change without
+notice. Semver; a breaking change to a listed name bumps the major version.
+Both known hosts (Mammotion, PetKit) have a written migration path in
+`docs/migration.md` before a release that changes the surface.

pyagorartc-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+1. Read `CONSTITUTION.md`. It is one page and it is not negotiable.
+2. Find the single home for your concern in `docs/architecture.md` §3 before
+   writing a line.
+3. New endpoint? Follow the recipe in `docs/architecture.md` §4: model, API
+   method, fake-server route, tests, `docs/api/` section.
+4. New non-obvious choice? Add a numbered entry to `docs/decisions.md`. New
+   unknown about the API? Add a `Qn` to `docs/open_questions.md`.
+5. Tests in the right tier (`docs/testing.md`), fakes from `tests/unit/_fakes.py`,
+   no `MagicMock`, no sleeping for synchronisation.
+6. `uv run pre-commit run --all-files` is green: ruff, ruff-format, ty, unit
+   tests.
+7. Commits: imperative subject line, one change per commit, no attribution
+   trailers.
+
+## Pull request checklist
+
+- [ ] The change touches only the places the recipe names.
+- [ ] Every public method has a docstring that says what the signature does not.
+- [ ] No secret can reach a log, a `repr`, or an exception message.
+- [ ] Tests assert behaviour, not call plumbing.
+- [ ] `docs/` updated where the change alters the map, the API, or the rules.