soniox 2.4.0__tar.gz → 2.5.0__tar.gz

soniox-2.5.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,81 @@
+name: Bug report
+description: Report something the SDK does wrong, or fails to do
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug. A **minimal** reproducer speeds things up significantly.
+
+  - type: checkboxes
+    id: non_api
+    attributes:
+      label: SDK or API?
+      description: For API-level problems such as transcription accuracy or server-side errors, please contact [support@soniox.com](mailto:support@soniox.com) instead.
+      options:
+        - label: I confirm this is an issue with the Python SDK, not the Soniox API.
+          required: true
+
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened?
+      description: What did you observe? What did you expect instead?
+      placeholder: |
+        Observed: ...
+        Expected: ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproducer
+      description: The smallest script that triggers the issue. Strip out anything unrelated.
+      render: python
+      placeholder: |
+        from soniox import SonioxClient
+        ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Logs or traceback
+      description: Full traceback or relevant log lines, if any.
+      render: shell
+    validations:
+      required: false
+
+  - type: input
+    id: sdk_version
+    attributes:
+      label: SDK version
+      placeholder: "soniox==2.4.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      placeholder: "Python 3.12.3"
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating system
+      placeholder: "Ubuntu 24.04 / macOS 15 / Windows 11"
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Anything else relevant: timing patterns, frequency, workarounds you have tried.
+    validations:
+      required: false

soniox-2.5.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,44 @@
+name: Feature request
+description: Propose a new capability or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Use this template to propose new SDK functionality or improvements to existing APIs.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What are you trying to do? What does the SDK currently make hard or awkward?
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: The shape of the API or behavior you would like. Python sketches welcome.
+      render: python
+      placeholder: |
+        # What the call site could look like:
+        client.foo.bar(...)
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches you thought about, and why you do not prefer them.
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Links to similar features in other SDKs, related issues, or use-case background.
+    validations:
+      required: false

soniox-2.5.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,27 @@
+## Summary
+
+<!-- One or two sentences. What does this PR do, and why? -->
+
+## Type of change
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Internal refactor
+- [ ] Documentation
+
+## How to test
+
+<!-- Steps a reviewer can run to verify the change. -->
+
+## Checklist
+
+- [ ] Tests added or updated under `tests/unit/` or `tests/realtime/`.
+- [ ] `just lint`, `just typecheck`, and `just test` all pass locally.
+- [ ] `CHANGELOG.md` `[Unreleased]` section updated, if the change is user-visible.
+- [ ] Reference docs regenerated with `just docs`, if public APIs changed.
+- [ ] No leftover `print()` debug statements or commented-out code.
+
+## Related issues
+
+<!-- Closes #123, refs #456 -->

{soniox-2.4.0 → soniox-2.5.0}/CHANGELOG.md

@@ -63,20 +63,44 @@ Examples:
 
 ### Added
 
--
-
 ### Changed
 
--
+### Deprecated
 
 ### Fixed
 
--
-
 ### Removed
 
 ---
 
+## [2.5.0] - 12 jun 2026
+
+### Added
+
+- `LanguageCode` type alias (`Annotated[str, Field(min_length=2, max_length=2)]`) representing an ISO 639-1 two-letter code. Now used by `TranslationConfig.target_language`, `language_a`, `language_b`, and by the `language_hints` lists on `CreateTranscriptionPayload`, `CreateTranscriptionConfig`, and `RealtimeSTTConfig`.
+- `SupportedLanguage` model (renamed from `Language`) describing a `{code, name}` language entry returned by `client.models.list()`.
+- `translate*` methods on the async and sync STT clients (`translate`, `translate_from_url`, `translate_from_file_id`, `translate_from_file`, `translate_and_wait`, `translate_and_wait_with_tokens`). Pass `to=` for one-way translation (optionally with `source=` as a strict language hint) or `between=("en", "fr")` for two-way; exactly one of `to` or `between` is required.
+- `connect_timeout_sec` parameter on the realtime `connect()` and `connect_multi_stream()` methods (STT and TTS, sync and async): maximum seconds to wait for the WebSocket handshake. Defaults to 10 seconds; must be greater than zero. ([#4](https://github.com/soniox/soniox-python/pull/4) by [@imcooder](https://github.com/imcooder))
+
+### Changed
+
+- Reorganized reference docs: `async_client.md` now documents only the async surface (the sync `SonioxClient` is a line-by-line mirror, called out in a preamble); `realtime_client.md` continues to cover both sync and async realtime clients.
+- Expanded the `output_file_for_audio_format` docstring with a proper `Args` block.
+- `language_hints` fields now validate each entry as a two-letter code; previously any string was accepted client-side.
+- Realtime WebSocket connection failures now raise `SonioxRealtimeError` (with message `"Connection timed out"` when the handshake times out) instead of propagating raw `websockets` exceptions. ([#4](https://github.com/soniox/soniox-python/pull/4) by [@imcooder](https://github.com/imcooder))
+- Default model for asynchronous transcriptions is now `stt-async-v5` (was `stt-async-v4`).
+
+### Deprecated
+
+- `Language` is a deprecated alias for `SupportedLanguage`. Update imports to `from soniox.types import SupportedLanguage`.
+
+### Fixed
+
+- Removed Sphinx `:meth:` directive leaks from realtime STT client docstrings; they were rendering as raw text in the generated markdown reference.
+- `AsyncRealtimeTTSClient.connect_multi_stream()` now validates that an API key is available, matching the sync `RealtimeTTSClient.connect_multi_stream()`; previously it silently constructed a connection with an empty key.
+
+---
+
 ## [2.4.0] - 13 may 2026
 
 ### Added

soniox-2.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our standards
+
+Behavior that contributes to a positive environment includes:
+
+- Using welcoming and inclusive language.
+- Respecting differing viewpoints and experiences.
+- Accepting constructive criticism gracefully.
+- Focusing on what is best for the community.
+- Showing empathy toward other community members.
+
+Unacceptable behavior includes:
+
+- Sexualized language or imagery, and unwelcome sexual attention or advances.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information, such as a physical or email address, without their explicit permission.
+- Other conduct that could reasonably be considered inappropriate in a professional setting.
+
+## Scope
+
+This Code of Conduct applies on GitHub, Discord, and any other channel where someone is representing the project.
+
+## Reporting and enforcement
+
+Report incidents to [support@soniox.com](mailto:support@soniox.com). All reports are reviewed and investigated promptly and fairly. We respect the privacy of reporters.
+
+Maintainers are responsible for clarifying and enforcing these standards, and may take corrective action in response to behavior they consider inappropriate.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, available at <https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.

soniox-2.5.0/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# Contributing
+
+Contributions are welcome. PRs that are small, typed, and tested move through review fastest.
+
+By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Development setup
+
+Install [uv](https://docs.astral.sh/uv/) and [just](https://github.com/casey/just), then:
+
+```bash
+git clone https://github.com/soniox/soniox-python
+cd soniox-python
+uv sync --extra dev
+```
+
+> Python 3.13.6 has a regression in the `ssl` module that hangs realtime WebSocket sessions ([CPython #137583](https://github.com/python/cpython/issues/137583)). For local development, use Python 3.10 through 3.12, or 3.13.5 / 3.13.7 and later.
+
+Day-to-day commands:
+
+```bash
+just test          # full test suite
+just lint          # ruff
+just typecheck     # pyright
+just docs          # regenerate docs/*.md from source
+```
+
+## Opening a pull request
+
+Open PRs against the `dev` branch. `main` tracks releases.
+
+Before you push:
+
+1. Keep the PR focused. One bug fix, one feature, or one refactor. Mixed PRs are slower to review.
+2. Add tests. New endpoints belong in `tests/unit/`; realtime helpers belong in `tests/realtime/`.
+3. Run `just lint`, `just typecheck`, and `just test`. All three must pass before review.
+4. Maintain coverage above the threshold set in `pyproject.toml`.
+5. Update the `[Unreleased]` section of `CHANGELOG.md` for any user-visible change. Categorize as Added, Changed, Fixed, or Removed.
+6. If you changed public APIs, regenerate the reference docs with `just docs`.
+
+To pick up a newer OpenAPI schema, run `just download-schema`. This pulls the latest `openapi.json` into `tests/data/`. The `test_schema_drift.py` suite then reports missing fields and changed signatures automatically.
+
+## Conventions
+
+- `ruff` handles formatting and lint rules; the configuration lives in `pyproject.toml`.
+- `pyright` runs in strict mode against `src/`. Tests have a narrower config in the same file.
+- Write docstrings in plain markdown with backticks for code references. Do not use Sphinx directives such as `:meth:` or `:param:`. They leak as raw text into the generated reference.
+- Write comments to explain why, not what. Well-named identifiers already say what the code does.
+
+## Reporting bugs
+
+File issues at [github.com/soniox/soniox-python/issues](https://github.com/soniox/soniox-python/issues) using the bug report template. Include the SDK version, the Python version, and a minimal reproducer.
+
+## Reporting security issues
+
+Do not file a public issue for security vulnerabilities. See [SECURITY.md](SECURITY.md) for the channels we monitor.

{soniox-2.4.0 → soniox-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: soniox
-Version: 2.4.0
+Version: 2.5.0
 Summary: The official Python SDK for the Soniox API (STT, REST)
 Project-URL: Homepage, https://soniox.com
 Project-URL: Documentation, https://soniox.com/docs

soniox-2.5.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+If you have discovered a security vulnerability in this SDK, please report it through one of the channels below. Use whichever is most convenient; we monitor all of them.
+
+- **Email** [support@soniox.com](mailto:support@soniox.com) with a description of the issue and steps to reproduce.
+- **Open a GitHub issue** describing the broad nature of the problem, but omit sensitive details (payloads, tokens, exact exploit steps). We will follow up privately to collect the rest.
+- **Direct-message a maintainer** on GitHub or anywhere else you have already corresponded with us.
+- **Reach us on [Discord](https://discord.gg/soniox)** and ask for a maintainer in DMs.
+
+## Responsible disclosure
+
+We ask that you allow us a reasonable window to investigate and ship a fix before publishing any details. We will acknowledge your report, work through the diagnosis with you, and credit your disclosure in the release notes if you would like.