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:

.. code-block:: bash

    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:

.. code-block:: bash

    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
###################

.. code-block:: bash

    make doc

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

Build and release
#################

The ``Makefile`` exposes the full release flow:

.. code-block:: bash

    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``:

.. code-block:: bash

    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}``.