fix(packaging): Apache-2.0 metadata, a migration note, and CI that actually runs the tests

.github/workflows/python-tests.yml

@@ -0,0 +1,56 @@
+name: python tests
+
+# Runs the pytest suite on every pull request and every push to main.
+#
+# WHY THIS EXISTS: before this workflow, NOTHING in CI ran pytest. The repo had
+# six test files (SDK exports, parity APIs, contract coverage, README quickstart,
+# x402, packaging) and 52 tests, and a pull request could delete or break every
+# one of them and still show all-green — `python-lint` runs ruff only,
+# `foundation-gate` runs a secret scan and a file-size gate, `smoke-install`
+# builds and imports the wheel, and `release` builds a distribution. None of them
+# execute a test. That gap is what let the stdlib-shadow defect reach PyPI as
+# wave-sdk 2.0.0.
+#
+# The matrix mirrors smoke-install.yml (the floor and the two current versions in
+# `requires-python = ">=3.9"`), so a version that can install the wheel is also a
+# version whose behaviour is asserted.
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: python-tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pytest:
+    name: pytest (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install the SDK with every extra it tests
+        # `realtime` and `x402` are optional extras with their own test modules,
+        # so the suite needs them present or those tests silently do less work.
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,realtime,x402]"
+
+      - name: pytest
+        run: python -m pytest -q

MIGRATING.md

@@ -0,0 +1,109 @@
+# Migrating to `wave-sdk` 2.1.0
+
+Two things changed between the published `2.0.0` releases and `2.1.0`: the
+**distribution you install** and the **package you import**. Both changes are
+mechanical, and the second one is not optional — the old import never worked
+outside the SDK's own repo.
+
+| | Old (`2.0.0`, published) | New (`2.1.0`) |
+| --- | --- | --- |
+| Install name(s) | `wave-av-sdk`, `wave-sdk` | `wave-sdk` |
+| Import name | `wave` (broken — see below) | `wave_sdk` |
+| Client class | `Wave` | `Wave` (unchanged) |
+| Method surface | 35 `*API` classes | 42 `*API` classes |
+
+## 1. Install `wave-sdk`
+
+```bash
+pip uninstall -y wave-av-sdk wave-sdk
+pip install "wave-sdk>=2.1.0"
+```
+
+`wave-av-sdk` and `wave-sdk` were both published at `2.0.0` and contain the same
+code. `wave-sdk` is the one name that continues; `wave-av-sdk` is not being
+republished. Uninstall **both** before installing: they each drop a top-level
+`wave/` directory into `site-packages`, and leaving one behind leaves that
+directory (and its stale `2.0.0` modules) on disk next to the new `wave_sdk`.
+
+## 2. Change `import wave` to `import wave_sdk`
+
+```diff
+-from wave import Wave
++from wave_sdk import Wave
+
+-from wave import WaveError, RateLimitError
++from wave_sdk import WaveError, RateLimitError
+
+-import wave
+-client = wave.Wave(api_key=..., organization_id=...)
++import wave_sdk
++client = wave_sdk.Wave(api_key=..., organization_id=...)
+```
+
+Nothing below the top-level name changed. Every class, method, argument and
+return type keeps its name, so a find-and-replace of the import line is the
+whole migration:
+
+```bash
+# from the root of your project
+grep -rl --include='*.py' -E '^\s*(from|import)\s+wave(\W|$)' . \
+  | xargs sed -i.bak -E 's/^(\s*)(from|import)(\s+)wave(\W|$)/\1\2\3wave_sdk\4/'
+```
+
+## Why the rename was required
+
+CPython ships a standard-library module called `wave` (`Lib/wave.py`, the WAV
+audio reader/writer) in every install, on every supported version. The
+standard-library directory sits **ahead of `site-packages`** on `sys.path`.
+
+So for anyone who ran `pip install wave-sdk==2.0.0`, `import wave` resolved to
+the standard library, not to the SDK. The SDK's own files were on disk, in
+`site-packages/wave/`, and were unreachable:
+
+```console
+$ python -m venv v && ./v/bin/pip install wave-sdk==2.0.0
+$ ./v/bin/python -c "import wave; print(wave.__file__)"
+/…/lib/python3.12/wave.py            # the standard library, not the SDK
+$ ./v/bin/python -c "from wave import Wave"
+ImportError: cannot import name 'Wave' from 'wave'
+```
+
+The defect was invisible during development because the repo checkout is the
+first entry on `sys.path`; inside the checkout, the local `wave/` directory won
+`import wave` and the test suite passed. `wave_sdk` collides with nothing, and
+`import wave` now correctly keeps meaning the standard library:
+
+```console
+$ ./v/bin/python -c "import wave_sdk; print(wave_sdk.__version__)"
+2.1.0
+$ ./v/bin/python -c "import wave; print(wave.__file__)"
+/…/lib/python3.12/wave.py            # still the standard library — no shadowing
+```
+
+Two gates keep this from recurring: `tests/test_packaging.py` fails any pull
+request that reintroduces a top-level package named after a standard-library
+module, and `.github/workflows/smoke-install.yml` builds the wheel and imports
+it from a fresh virtualenv with no repo on `sys.path`.
+
+## A note on the `wave.<api>` names in the README
+
+The README's API tables are written as `wave.clips`, `wave.pipeline`, and so on.
+Those are **attributes of a client instance**, not module paths — they describe
+the shape of the `Wave` facade whatever you name your variable:
+
+```python
+from wave_sdk import Wave
+
+wave = Wave(api_key="…", organization_id="org_123")
+wave.clips.list()        # the `wave.clips` in the README table
+```
+
+There is no importable `wave` module in this SDK, and there will not be one.
+
+## License
+
+`2.1.0` also corrects the distribution's license metadata. The repo has been
+Apache-2.0 since commit `99d81d3`, but `pyproject.toml` still declared `MIT`, so
+`2.0.0` shipped `License: MIT` in its `METADATA` alongside an Apache-2.0
+`LICENSE` file in the same archive. The license itself did not change — the
+metadata now matches the `LICENSE` and `NOTICE` files it ships with.

README.md

@@ -120,6 +120,30 @@ except WaveError as e:
 - httpx
 - pydantic
 
+## Migrating from 2.0.0
+
+If you installed `wave-av-sdk` or `wave-sdk` at `2.0.0`, two names changed:
+
+- **Install** `wave-sdk` (not `wave-av-sdk`).
+- **Import** `wave_sdk` (not `wave`).
+
+```diff
+-from wave import Wave
++from wave_sdk import Wave
+```
+
+Nothing below the top-level name changed, so replacing the import line is the
+whole migration. The old `wave` package collided with the Python standard
+library's own `wave` module and was never importable from an installed
+`2.0.0` — full detail, the uninstall step, and a bulk find-and-replace are in
+[MIGRATING.md](MIGRATING.md).
+
+Note that the `wave.<api>` names in the tables above are attributes of a client
+instance, not module paths: name your client whatever you like
+(`client = Wave(...)` in the quick start above), and `client.clips` is the row
+the table writes as `wave.clips`.
+
 ## License
 
-MIT - WAVE Online, LLC
+Apache-2.0 - WAVE Online, LLC. See [LICENSE](LICENSE) and [NOTICE](NOTICE); the
+WAVE marks are not licensed under the Apache grant.

pyproject.toml

@@ -7,7 +7,14 @@ name = "wave-sdk"
 version = "2.1.0"
 description = "Official WAVE SDK for Python - 42 API modules for streaming, production, analytics, and more"
 readme = "README.md"
-license = {text = "MIT"}
+# Apache-2.0 is the repo's actual license: the LICENSE file is the Apache 2.0
+# text and NOTICE carves the WAVE marks out of that grant. This field said "MIT"
+# from the initial commit (1b7be39) and was missed when the repo adopted
+# Apache-2.0 (99d81d3), so every built wheel shipped `License: MIT` metadata
+# next to an Apache-2.0 LICENSE file inside the SAME dist-info. Kept as
+# `{text = ...}` rather than a bare PEP 639 SPDX string because the build
+# requirement here is setuptools>=61, and the SPDX form needs setuptools>=77.
+license = {text = "Apache-2.0"}
 requires-python = ">=3.9"
 authors = [
     {name = "WAVE Online, LLC", email = "sdk@wave.online"}
@@ -37,7 +44,7 @@ keywords = [
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
-    "License :: OSI Approved :: MIT License",
+    "License :: OSI Approved :: Apache Software License",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.9",
@@ -74,6 +81,9 @@ dev = [
     "mypy>=1.0.0",
     "ruff>=0.1.0",
     "black>=23.0.0",
+    # tests/test_packaging.py reads this file back to assert the shipped metadata
+    # matches the repo (name/version/license). tomllib is stdlib from 3.11 only.
+    "tomli>=2.0.0; python_version < '3.11'",
 ]
 
 [project.urls]