Development

Contributions are welcome but require:

  • methods with title, arguments and returns docstring (Google style for public, one-line for _-prefixed)

  • unit tests (and integration tests where the changed code touches the AWS surface)

  • the code quality stack passing locally before push

Code quality

The repo uses the modern Python toolchain (uv + ruff + pyright + pytest). All commands are wrapped in Makefile targets:

make sync  # uv sync (install / refresh dev deps)
make lint  # uv run ruff check --no-fix .
make format  # uv run ruff format .
make typecheck  # uv run pyright
make test  # uv run pytest

The toolchain is configured in pyproject.toml:

  • ruff under [tool.ruff] and [tool.ruff.lint]: select = ["ALL"] strict, with the ignore list and per-file overrides next to it.

  • pyright under [tool.pyright]: typeCheckingMode = "strict"; botocore-stubs provides the typed surface for botocore.auth.SigV4Auth and the credential chain.

  • pytest under [tool.pytest.ini_options]: asyncio_mode = "auto"; integration tests are gated by the integration marker and deselected by default.

Run integration test

The integration test (tests/test_integration.py) hits real AWS Polly and is deselected by default. To run it:

AWS_PROFILE=your-profile uv run pytest -m integration -v -s

Requires AWS credentials with polly:StartSpeechSynthesisStream permission and a region/voice combination supporting bidirectional streaming (default in the test: eu-central-1 + Matthew).

Build documentation

make doc

Sphinx output goes to docs/build/html/index.html.

Build and release

The Makefile exposes the full release flow:

make buildtest  # build wheel + sdist, upload to TestPyPI
make installtest  # install from TestPyPI in a sandbox venv and verify import
make build  # build wheel + sdist, upload to PyPI
make install  # install from PyPI in a sandbox venv and verify import

Versioning is automated by bump-my-version and CHANGELOG.md is regenerated by git-cliff:

make patch  # bump x.y.Z, regenerate CHANGELOG, tag
make minor  # bump x.Y.0
make major  # bump X.0.0

The default commit message produced by bump-my-version is build: release {new_version}; the tag message is amazon-polly-streaming {new_version}.