fix(pypi): rename importable package wave -> wave_sdk (P0: stdlib shadow, breaking)

CHANGELOG.md

@@ -6,6 +6,31 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-09-03
+
+### Fixed
+
+- **P0: the package was permanently unimportable exactly as documented.** The published
+  `wave-sdk` / `wave-av-sdk` distribution installs a top-level module named `wave`, which
+  collides with Python's own standard-library `wave` module (WAV audio file I/O, present in
+  every CPython install since 2.x). The stdlib is always resolved before `site-packages`, so
+  `from wave import Wave` — the exact line in this README's own "Quick start" — has never
+  worked on a fresh install, on any Python version, on any platform:
+  `ImportError: cannot import name 'Wave' from 'wave' (.../lib/python3.14/wave.py)`.
+  Live-verified 2026-09-03 with a clean `uv venv` + `pip install wave-sdk` (installs `2.0.0`)
+  running the documented quick-start line.
+
+### Changed
+
+- **BREAKING: the importable package is renamed `wave` -> `wave_sdk`.** The PyPI distribution
+  name is unchanged (still `pip install wave-sdk`); every import changes from
+  `from wave import ...` / `from wave.<module> import ...` to `from wave_sdk import ...` /
+  `from wave_sdk.<module> import ...`. This is the only viable fix — the stdlib module cannot
+  be renamed or unregistered, and shadowing it silently would leave every consumer's own
+  `import wave` (e.g. anything touching WAV files) broken instead. Major version bump per
+  semver; there is no migration path that preserves the old import path, because the old
+  import path never actually reached this package.
+
 ## [2.1.0] - 2026-09-01
 
 ### Added

README.md

@@ -11,7 +11,7 @@ pip install wave-sdk
 ## Quick start
 
 ```python
-from wave import Wave
+from wave_sdk import Wave
 
 wave = Wave(api_key="your-api-key", organization_id="org_123")
 
@@ -116,7 +116,7 @@ ledger = wave.meter.ledger(channel="mail")
 ## Error handling
 
 ```python
-from wave import WaveError, RateLimitError
+from wave_sdk import WaveError, RateLimitError
 
 try:
     wave.pipeline.get("invalid-id")

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wave-sdk"
-version = "2.1.0"
+version = "3.0.0"
 description = "Official WAVE SDK for Python - 42 API modules for streaming, production, analytics, and more"
 readme = "README.md"
 license = {text = "MIT"}
@@ -78,7 +78,7 @@ Issues = "https://github.com/wave-av/sdk-python/issues"
 
 [tool.setuptools.packages.find]
 where = ["."]
-include = ["wave*"]
+include = ["wave_sdk*"]
 
 [tool.mypy]
 python_version = "3.9"
@@ -99,7 +99,7 @@ ignore = ["E501", "E701", "E702"]
 
 [tool.ruff.lint.per-file-ignores]
 # Public re-exports: the package __init__ exists to re-export the API surface.
-"wave/__init__.py" = ["F401"]
+"wave_sdk/__init__.py" = ["F401"]
 # Export-verification test imports every public symbol to assert it exists
 # (checked via __all__ / hasattr), so the names are intentionally "unused".
 "tests/test_sdk_exports.py" = ["F401"]

tests/conftest.py

@@ -9,5 +9,5 @@ def api_key():
 
 @pytest.fixture
 def wave_client():
-    from wave import Wave
+    from wave_sdk import Wave
     return Wave(api_key="test-api-key", organization_id="org_test")

tests/test_contract_coverage.py

@@ -145,7 +145,7 @@ def test_no_stale_mapping_or_allowlist_entries():
 
 
 def test_mapped_methods_exist_on_wave():
-    from wave import Wave
+    from wave_sdk import Wave
     w = Wave(api_key="test-key")
     missing = []
     for op_id, (namespace, method) in MAPPING.items():

tests/test_parity_apis.py

@@ -5,16 +5,17 @@
 from __future__ import annotations
 
 from unittest.mock import MagicMock
-from wave.inference import InferenceAPI
-from wave.mail import MailAPI
-from wave.meter import MeterAPI
-from wave.perception import PerceptionAPI
-from wave.pricing import ManifestCreateResult, PricingAPI, PricingManifest, PricingTier
-from wave.transcripts import TranscriptAPI
 
 import httpx
 import pytest
 
+from wave_sdk.inference import InferenceAPI
+from wave_sdk.mail import MailAPI
+from wave_sdk.meter import MeterAPI
+from wave_sdk.perception import PerceptionAPI
+from wave_sdk.pricing import ManifestCreateResult, PricingAPI, PricingManifest, PricingTier
+from wave_sdk.transcripts import TranscriptAPI
+
 
 @pytest.fixture
 def mock_client():
@@ -223,7 +224,7 @@ def fake_post(url, headers=None, json=None, timeout=None):
             "usage": {"cost": 0.0001, "total_tokens": 12},
         })
 
-    monkeypatch.setattr("wave.inference.httpx.post", fake_post)
+    monkeypatch.setattr("wave_sdk.inference.httpx.post", fake_post)
     api = InferenceAPI(FakeClient())
     result = api.complete("claude-haiku", [{"role": "user", "content": "hi"}])
     assert result.model == "claude-haiku"
@@ -238,9 +239,9 @@ class FakeClient:
     def fake_post(url, headers=None, json=None, timeout=None):
         return httpx.Response(500, text="funnel down")
 
-    monkeypatch.setattr("wave.inference.httpx.post", fake_post)
+    monkeypatch.setattr("wave_sdk.inference.httpx.post", fake_post)
     api = InferenceAPI(FakeClient())
-    from wave.client import WaveError
+    from wave_sdk.client import WaveError
     with pytest.raises(WaveError):
         api.complete("claude-haiku", [{"role": "user", "content": "hi"}])
 
@@ -250,7 +251,7 @@ class FakeClient:
         api_key = "test-key"
 
     api = InferenceAPI(FakeClient())
-    from wave.client import WaveError
+    from wave_sdk.client import WaveError
     with pytest.raises(WaveError, match="registry_url"):
         api.models()
 
@@ -263,7 +264,7 @@ def fake_get(url, headers=None, timeout=None):
         assert url.startswith("https://registry.example.com/rest/v1/models")
         return httpx.Response(200, json=[{"id": "m1", "rail": "openai", "cost_input_per_m": 1.0, "cost_output_per_m": 2.0}])
 
-    monkeypatch.setattr("wave.inference.httpx.get", fake_get)
+    monkeypatch.setattr("wave_sdk.inference.httpx.get", fake_get)
     api = InferenceAPI(FakeClient(), registry_url="https://registry.example.com", registry_key="k")
     models = api.models()
     assert models[0].id == "m1"

tests/test_readme_quickstart.py

@@ -11,7 +11,7 @@
 
 
 def test_readme_quickstart_calls_are_real():
-    from wave import Wave
+    from wave_sdk import Wave
     w = Wave(api_key="test-key")
     calls = sorted(set(CALL_RE.findall(README)))
     assert calls, "expected at least one wave.<namespace>.<method>(...) call in README.md"

tests/test_sdk_exports.py

@@ -10,7 +10,7 @@
 
 def test_all_modules_import():
     """All 39 API modules should be importable from wave package."""
-    from wave import (
+    from wave_sdk import (
         AudienceAPI,
         CaptionsAPI,
         ChaptersAPI,
@@ -62,22 +62,22 @@ def test_all_modules_import():
 
 def test_wave_client_import():
     """Core client classes should import."""
-    from wave import RateLimitError, WaveClient, WaveError
+    from wave_sdk import RateLimitError, WaveClient, WaveError
     assert callable(WaveClient)
     assert issubclass(WaveError, Exception)
     assert issubclass(RateLimitError, WaveError)
 
 
 def test_wave_client_requires_api_key():
     """WaveClient should raise ValueError without api_key."""
-    from wave import WaveClient
+    from wave_sdk import WaveClient
     with pytest.raises(ValueError, match="api_key"):
         WaveClient(api_key="")
 
 
 def test_wave_convenience_class():
     """Wave class should instantiate with all 33 API modules."""
-    from wave import Wave
+    from wave_sdk import Wave
     w = Wave(api_key="test-key")
 
     # Existing P3
@@ -136,45 +136,45 @@ def test_wave_convenience_class():
 def test_api_count():
     """Wave class should have exactly 42 API bindings (+ client) — parity with the
     TS SDK's 42 Wave-facade namespaces (43 including the base client)."""
-    from wave import Wave
+    from wave_sdk import Wave
     w = Wave(api_key="test-key")
     api_attrs = [a for a in dir(w) if not a.startswith('_') and a != 'client']
     assert len(api_attrs) == 42, f"Expected 42 APIs, got {len(api_attrs)}: {api_attrs}"
 
 
 def test_pipeline_has_methods():
     """PipelineAPI should have expected methods."""
-    from wave import Wave
+    from wave_sdk import Wave
     w = Wave(api_key="test-key")
     for method in ['create', 'get', 'list', 'start', 'stop', 'get_health', 'wait_for_live']:
         assert hasattr(w.pipeline, method), f"PipelineAPI missing {method}"
 
 
 def test_prism_has_methods():
     """PrismAPI should have expected methods."""
-    from wave import Wave
+    from wave_sdk import Wave
     w = Wave(api_key="test-key")
     for method in ['create_device', 'start_device', 'stop_device', 'discover_sources', 'get_presets', 'set_preset', 'recall_preset']:
         assert hasattr(w.prism, method), f"PrismAPI missing {method}"
 
 
 def test_studio_has_methods():
     """StudioAPI should have expected methods."""
-    from wave import Wave
+    from wave_sdk import Wave
     w = Wave(api_key="test-key")
     for method in ['create', 'start', 'stop', 'add_source', 'activate_scene', 'transition', 'set_program', 'get_audio_mix']:
         assert hasattr(w.studio, method), f"StudioAPI missing {method}"
 
 
 def test_version():
-    """SDK version should be 2.1.0."""
-    import wave
-    assert wave.__version__ == "2.1.0"
+    """SDK version should be 3.0.0."""
+    import wave_sdk
+    assert wave_sdk.__version__ == "3.0.0"
 
 
 def test_all_exports():
     """__all__ should contain all API classes."""
-    import wave
+    import wave_sdk
     expected = [
         "ClipsAPI", "EditorAPI", "VoiceAPI", "PhoneAPI", "CollabAPI",
         "CaptionsAPI", "ChaptersAPI", "StudioAIAPI", "TranscribeAPI",
@@ -188,4 +188,4 @@ def test_all_exports():
         "TranscriptAPI", "MailAPI", "MeterAPI", "PricingAPI", "PerceptionAPI", "InferenceAPI",
     ]
     for cls in expected:
-        assert cls in wave.__all__, f"{cls} missing from __all__"
+        assert cls in wave_sdk.__all__, f"{cls} missing from __all__"

tests/test_x402.py

@@ -1,4 +1,4 @@
-"""Conformance tests for wave.x402 (EIP-3009 "exact" scheme signing).
+"""Conformance tests for wave_sdk.x402 (EIP-3009 "exact" scheme signing).
 
 These assert the Python signer is byte-for-byte compatible with WAVE's reference TypeScript x402 signer
 (the same viem stack the WAVE facilitator verifies against). The expected values live in
@@ -14,7 +14,7 @@
 
 pytest.importorskip("eth_account", reason='x402 signing needs the extra: pip install "wave-sdk[x402]"')
 
-from wave.x402 import (  # noqa: E402  (after importorskip)
+from wave_sdk.x402 import (  # noqa: E402  (after importorskip)
     encode_exact_payment_header,
     get_network_config,
     random_nonce,