scribe-client 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. {scribe_client-0.2.0 → scribe_client-0.3.0}/Cargo.lock +3 -3
  2. {scribe_client-0.2.0 → scribe_client-0.3.0}/Cargo.toml +1 -1
  3. {scribe_client-0.2.0 → scribe_client-0.3.0}/PKG-INFO +13 -1
  4. {scribe_client-0.2.0/crates/scribe-client-py → scribe_client-0.3.0}/README.md +12 -0
  5. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/README.md +1 -1
  6. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/src/client.rs +52 -0
  7. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/src/model.rs +28 -2
  8. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/tests/settings_test.rs +64 -0
  9. {scribe_client-0.2.0 → scribe_client-0.3.0/crates/scribe-client-py}/README.md +12 -0
  10. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/src/client.rs +19 -0
  11. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/tests/test_settings.py +37 -0
  12. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/uv.lock +1 -1
  13. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/Cargo.toml +0 -0
  14. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/examples/pkce_flow.rs +0 -0
  15. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/src/auth.rs +0 -0
  16. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/src/channel.rs +0 -0
  17. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/src/error.rs +0 -0
  18. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/src/lib.rs +0 -0
  19. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/tests/auth_test.rs +0 -0
  20. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/tests/channel_test.rs +0 -0
  21. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client/tests/client_test.rs +0 -0
  22. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/Cargo.toml +0 -0
  23. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/build.rs +0 -0
  24. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/examples/pkce_flow.py +0 -0
  25. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/src/auth.rs +0 -0
  26. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/src/channel.rs +0 -0
  27. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/src/error.rs +0 -0
  28. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/src/lib.rs +0 -0
  29. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/src/model.rs +0 -0
  30. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/tests/conftest.py +0 -0
  31. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/tests/test_auth.py +0 -0
  32. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/tests/test_channel.py +0 -0
  33. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/tests/test_client.py +0 -0
  34. {scribe_client-0.2.0 → scribe_client-0.3.0}/crates/scribe-client-py/tests/test_pkce_and_tokens.py +0 -0
  35. {scribe_client-0.2.0 → scribe_client-0.3.0}/pyproject.toml +0 -0
@@ -1678,7 +1678,7 @@ dependencies = [
1678
1678
 
1679
1679
  [[package]]
1680
1680
  name = "scribe-client"
1681
- version = "0.2.0"
1681
+ version = "0.3.0"
1682
1682
  dependencies = [
1683
1683
  "base64 0.22.1",
1684
1684
  "futures-util",
@@ -1698,7 +1698,7 @@ dependencies = [
1698
1698
 
1699
1699
  [[package]]
1700
1700
  name = "scribe-client-ffi"
1701
- version = "0.2.0"
1701
+ version = "0.3.0"
1702
1702
  dependencies = [
1703
1703
  "futures-util",
1704
1704
  "reqwest",
@@ -1714,7 +1714,7 @@ dependencies = [
1714
1714
 
1715
1715
  [[package]]
1716
1716
  name = "scribe-client-py"
1717
- version = "0.2.0"
1717
+ version = "0.3.0"
1718
1718
  dependencies = [
1719
1719
  "pyo3",
1720
1720
  "pyo3-build-config",
@@ -3,7 +3,7 @@ resolver = "2"
3
3
  members = ["crates/scribe-client", "crates/scribe-client-py"]
4
4
 
5
5
  [workspace.package]
6
- version = "0.2.0"
6
+ version = "0.3.0"
7
7
  edition = "2021"
8
8
  license = "MIT OR Apache-2.0"
9
9
  repository = "https://github.com/PneumaSolutions/scribe-api-client"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: scribe-client
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Classifier: Development Status :: 4 - Beta
5
5
  Classifier: Intended Audience :: Developers
6
6
  Classifier: License :: OSI Approved :: MIT License
@@ -116,6 +116,18 @@ client.update_settings(document_id, {"large_print": True})
116
116
 
117
117
  `update_settings` takes a plain dict; only the keys you pass are changed server-side.
118
118
 
119
+ ## Voices and their samples
120
+
121
+ `voices()` lists the text-to-speech voices by dialect, each as a `(name, short_name, has_sample)` triple. A voice whose `has_sample` is true has a short MP3 the user can listen to before choosing it, as the Scribe app lets them. `voice_sample_url(short_name)` gives its URL, which needs no token, so you can hand it straight to a media player to stream. `voice_sample(short_name)` downloads the MP3 bytes instead. Both raise `NotFoundError` when there's no sample.
122
+
123
+ ```python
124
+ voices = client.voices()
125
+ name, short_name, has_sample = voices["en-US"][0]
126
+ if has_sample:
127
+ play(client.voice_sample_url(short_name)) # or: data = client.voice_sample(short_name)
128
+ client.update_settings(document_id, {"voices": {"en-US": short_name}})
129
+ ```
130
+
119
131
  ## Converting to another format
120
132
 
121
133
  Creating a document starts only the `html_stream` conversion. Converting to any other format — `pdf`, `epub`, `daisy`, `docx`, `brf`, `mp3`, `offline_html`, `mobi` — happens over a **real-time channel**, not a REST call, so the server can guarantee it's subscribed to progress on whatever it just started converting.
@@ -95,6 +95,18 @@ client.update_settings(document_id, {"large_print": True})
95
95
 
96
96
  `update_settings` takes a plain dict; only the keys you pass are changed server-side.
97
97
 
98
+ ## Voices and their samples
99
+
100
+ `voices()` lists the text-to-speech voices by dialect, each as a `(name, short_name, has_sample)` triple. A voice whose `has_sample` is true has a short MP3 the user can listen to before choosing it, as the Scribe app lets them. `voice_sample_url(short_name)` gives its URL, which needs no token, so you can hand it straight to a media player to stream. `voice_sample(short_name)` downloads the MP3 bytes instead. Both raise `NotFoundError` when there's no sample.
101
+
102
+ ```python
103
+ voices = client.voices()
104
+ name, short_name, has_sample = voices["en-US"][0]
105
+ if has_sample:
106
+ play(client.voice_sample_url(short_name)) # or: data = client.voice_sample(short_name)
107
+ client.update_settings(document_id, {"voices": {"en-US": short_name}})
108
+ ```
109
+
98
110
  ## Converting to another format
99
111
 
100
112
  Creating a document starts only the `html_stream` conversion. Converting to any other format — `pdf`, `epub`, `daisy`, `docx`, `brf`, `mp3`, `offline_html`, `mobi` — happens over a **real-time channel**, not a REST call, so the server can guarantee it's subscribed to progress on whatever it just started converting.
@@ -42,7 +42,7 @@ async fn main() -> Result<(), scribe_client::ScribeError> {
42
42
  By default TLS is done by [rustls](https://crates.io/crates/rustls), with no system library to link against. To use the platform's own TLS library instead (Security.framework on Apple platforms, SChannel on Windows, OpenSSL elsewhere), turn off the default features and turn on `native-tls`:
43
43
 
44
44
  ```toml
45
- scribe-client = { version = "0.2", default-features = false, features = ["native-tls"] }
45
+ scribe-client = { version = "0.3", default-features = false, features = ["native-tls"] }
46
46
  ```
47
47
 
48
48
  ## License
@@ -719,6 +719,52 @@ impl ScribeClient {
719
719
  Ok(response.voices)
720
720
  }
721
721
 
722
+ /// Where the sample of a voice can be played from: an MP3 that needs no
723
+ /// token, so it can go straight to a media player, which can start it
724
+ /// before the whole file has arrived. `short_name` is a voice's short
725
+ /// name from [`voices`](Self::voices); only voices whose `has_sample`
726
+ /// is true have one.
727
+ ///
728
+ /// # Errors
729
+ ///
730
+ /// Returns [`ScribeError::NotFound`] if `short_name` can't be a voice's
731
+ /// name (it may only have letters, digits and `-`).
732
+ pub fn voice_sample_url(&self, short_name: &str) -> Result<String, ScribeError> {
733
+ Ok(self.voice_sample_location(short_name)?.into())
734
+ }
735
+
736
+ /// The sample of a voice, as MP3 bytes. See
737
+ /// [`voice_sample_url`](Self::voice_sample_url), which a player can
738
+ /// stream instead.
739
+ ///
740
+ /// # Errors
741
+ ///
742
+ /// Returns [`ScribeError::NotFound`] if the voice has no sample, or
743
+ /// [`ScribeError::Http`]/[`ScribeError::Api`] on other request failures.
744
+ pub async fn voice_sample(&self, short_name: &str) -> Result<Vec<u8>, ScribeError> {
745
+ let url = self.voice_sample_location(short_name)?;
746
+ let response = self.http.get(url).send().await?;
747
+ if response.status() == reqwest::StatusCode::NOT_FOUND {
748
+ return Err(no_sample(short_name));
749
+ }
750
+ let response = response.error_for_status_or_json_error().await?;
751
+ Ok(response.bytes().await?.to_vec())
752
+ }
753
+
754
+ fn voice_sample_location(&self, short_name: &str) -> Result<Url, ScribeError> {
755
+ let is_name = !short_name.is_empty()
756
+ && short_name
757
+ .chars()
758
+ .all(|c| c.is_ascii_alphanumeric() || c == '-');
759
+ if !is_name {
760
+ return Err(no_sample(short_name));
761
+ }
762
+ let mut url = self.base_url.clone();
763
+ url.set_path(&format!("/sounds/tts-samples/{short_name}.mp3"));
764
+ url.set_query(None);
765
+ Ok(url)
766
+ }
767
+
722
768
  /// Sends a request built by `build`, retrying once with a
723
769
  /// force-refreshed token if the server returns `401`. Returns the
724
770
  /// validated response for callers that need to read the body themselves.
@@ -751,6 +797,12 @@ impl ScribeClient {
751
797
  }
752
798
  }
753
799
 
800
+ fn no_sample(short_name: &str) -> ScribeError {
801
+ ScribeError::NotFound {
802
+ message: format!("There's no sample of the voice {short_name:?}."),
803
+ }
804
+ }
805
+
754
806
  /// Small helper trait so response-status handling reads the same way at every call site.
755
807
  /// How many bytes the body will be, if the server says.
756
808
  ///
@@ -210,14 +210,40 @@ pub struct Settings {
210
210
  pub notify_when_complete: bool,
211
211
  }
212
212
 
213
+ /// The server takes `dialects` and `voices` as strings holding JSON, though
214
+ /// it gives them back decoded, so an object written back as it was read is
215
+ /// sent as its JSON. A string is sent as it is.
216
+ #[allow(clippy::ref_option, reason = "serde's serialize_with signature")]
217
+ fn as_json_string<S: serde::Serializer>(
218
+ value: &Option<serde_json::Value>,
219
+ serializer: S,
220
+ ) -> Result<S::Ok, S::Error> {
221
+ match value {
222
+ Some(serde_json::Value::String(text)) => serializer.serialize_str(text),
223
+ Some(other) => serializer.serialize_str(&other.to_string()),
224
+ None => serializer.serialize_none(),
225
+ }
226
+ }
227
+
213
228
  /// A partial update to a document's conversion settings
214
229
  #[derive(Debug, Clone, Default, Serialize, Deserialize)]
215
230
  pub struct SettingsUpdate {
216
231
  #[serde(default, skip_serializing_if = "Option::is_none")]
217
232
  pub language: Option<String>,
218
- #[serde(default, skip_serializing_if = "Option::is_none")]
233
+ /// Language code to dialect locale. An object is sent as the string of
234
+ /// JSON the server takes.
235
+ #[serde(
236
+ default,
237
+ skip_serializing_if = "Option::is_none",
238
+ serialize_with = "as_json_string"
239
+ )]
219
240
  pub dialects: Option<serde_json::Value>,
220
- #[serde(default, skip_serializing_if = "Option::is_none")]
241
+ /// Dialect locale to voice short name, sent as `dialects` is.
242
+ #[serde(
243
+ default,
244
+ skip_serializing_if = "Option::is_none",
245
+ serialize_with = "as_json_string"
246
+ )]
221
247
  pub voices: Option<serde_json::Value>,
222
248
  #[serde(default, skip_serializing_if = "Option::is_none")]
223
249
  pub tts_gender: Option<String>,
@@ -277,3 +277,67 @@ async fn update_default_settings_sends_voices_as_a_json_string() {
277
277
  };
278
278
  client.update_default_settings(&update).await.unwrap();
279
279
  }
280
+
281
+ #[tokio::test]
282
+ async fn voice_sample_downloads_the_mp3_without_a_token() {
283
+ let server = MockServer::start().await;
284
+ Mock::given(method("GET"))
285
+ .and(path("/sounds/tts-samples/en-US-JennyNeural.mp3"))
286
+ .respond_with(ResponseTemplate::new(200).set_body_bytes(b"ID3mp3".to_vec()))
287
+ .mount(&server)
288
+ .await;
289
+ let client = client_for(&server, valid_tokens());
290
+ let data = client.voice_sample("en-US-JennyNeural").await.unwrap();
291
+ assert_eq!(data, b"ID3mp3");
292
+ let requests = server.received_requests().await.unwrap();
293
+ assert!(requests[0].headers.get("authorization").is_none());
294
+ }
295
+
296
+ #[tokio::test]
297
+ async fn voice_sample_maps_a_missing_sample_to_not_found() {
298
+ let server = MockServer::start().await;
299
+ Mock::given(method("GET"))
300
+ .respond_with(ResponseTemplate::new(404).set_body_string("<html>Not Found</html>"))
301
+ .mount(&server)
302
+ .await;
303
+ let client = client_for(&server, valid_tokens());
304
+ let err = client.voice_sample("xx-XX-NobodyNeural").await.unwrap_err();
305
+ assert!(matches!(err, ScribeError::NotFound { .. }), "{err:?}");
306
+ }
307
+
308
+ #[tokio::test]
309
+ async fn voice_sample_url_names_the_file_and_refuses_other_paths() {
310
+ let server = MockServer::start().await;
311
+ let client = client_for(&server, valid_tokens());
312
+ assert_eq!(
313
+ client.voice_sample_url("en-US-JennyNeural").unwrap(),
314
+ format!("{}/sounds/tts-samples/en-US-JennyNeural.mp3", server.uri())
315
+ );
316
+ for bad in ["", "../secret", "a/b", "a.mp3", "a?b"] {
317
+ assert!(
318
+ matches!(
319
+ client.voice_sample_url(bad),
320
+ Err(ScribeError::NotFound { .. })
321
+ ),
322
+ "{bad}"
323
+ );
324
+ assert!(client.voice_sample(bad).await.is_err(), "{bad}");
325
+ }
326
+ assert!(server.received_requests().await.unwrap().is_empty());
327
+ }
328
+
329
+ #[test]
330
+ fn voices_and_dialects_objects_go_out_as_json_strings() {
331
+ let update = SettingsUpdate {
332
+ voices: Some(serde_json::json!({"en-US": "en-US-JennyNeural"})),
333
+ dialects: Some(serde_json::Value::String(r#"{"en":"en-US"}"#.into())),
334
+ ..Default::default()
335
+ };
336
+ let body = serde_json::to_value(&update).unwrap();
337
+ assert_eq!(body["voices"], r#"{"en-US":"en-US-JennyNeural"}"#);
338
+ assert_eq!(body["dialects"], r#"{"en":"en-US"}"#);
339
+ assert!(serde_json::to_value(SettingsUpdate::default())
340
+ .unwrap()
341
+ .get("voices")
342
+ .is_none());
343
+ }
@@ -95,6 +95,18 @@ client.update_settings(document_id, {"large_print": True})
95
95
 
96
96
  `update_settings` takes a plain dict; only the keys you pass are changed server-side.
97
97
 
98
+ ## Voices and their samples
99
+
100
+ `voices()` lists the text-to-speech voices by dialect, each as a `(name, short_name, has_sample)` triple. A voice whose `has_sample` is true has a short MP3 the user can listen to before choosing it, as the Scribe app lets them. `voice_sample_url(short_name)` gives its URL, which needs no token, so you can hand it straight to a media player to stream. `voice_sample(short_name)` downloads the MP3 bytes instead. Both raise `NotFoundError` when there's no sample.
101
+
102
+ ```python
103
+ voices = client.voices()
104
+ name, short_name, has_sample = voices["en-US"][0]
105
+ if has_sample:
106
+ play(client.voice_sample_url(short_name)) # or: data = client.voice_sample(short_name)
107
+ client.update_settings(document_id, {"voices": {"en-US": short_name}})
108
+ ```
109
+
98
110
  ## Converting to another format
99
111
 
100
112
  Creating a document starts only the `html_stream` conversion. Converting to any other format — `pdf`, `epub`, `daisy`, `docx`, `brf`, `mp3`, `offline_html`, `mobi` — happens over a **real-time channel**, not a REST call, so the server can guarantee it's subscribed to progress on whatever it just started converting.
@@ -208,4 +208,23 @@ impl PyScribeClient {
208
208
  })
209
209
  .map_err(to_py_err)
210
210
  }
211
+
212
+ /// Where a voice's sample MP3 can be played from, without a token, so a
213
+ /// media player can stream it. Only voices whose `has_sample` is true
214
+ /// have one. Raises `NotFoundError` for a name that can't be a voice's.
215
+ fn voice_sample_url(&self, short_name: &str) -> PyResult<String> {
216
+ self.inner.voice_sample_url(short_name).map_err(to_py_err)
217
+ }
218
+
219
+ /// A voice's sample, as MP3 bytes. Raises `NotFoundError` if it has none.
220
+ fn voice_sample<'py>(
221
+ &self,
222
+ py: Python<'py>,
223
+ short_name: &str,
224
+ ) -> PyResult<Bound<'py, PyBytes>> {
225
+ let data = py
226
+ .detach(|| runtime().block_on(self.inner.voice_sample(short_name)))
227
+ .map_err(to_py_err)?;
228
+ Ok(PyBytes::new(py, &data))
229
+ }
211
230
  }
@@ -133,3 +133,40 @@ def test_voices_returns_map_of_lists(mock_server):
133
133
  client = ScribeClient(mock_server.base_url, "test-client-id", valid_tokens())
134
134
  voices = client.voices()
135
135
  assert voices == {"en-US": [("Jenny (Female)", "en-US-JennyNeural", True)]}
136
+
137
+
138
+ def test_voice_sample_downloads_the_mp3_without_a_token(mock_server):
139
+ mock_server.add_bytes_route(
140
+ "GET", "/sounds/tts-samples/en-US-JennyNeural.mp3", 200, b"ID3mp3", "audio/mpeg"
141
+ )
142
+ client = ScribeClient(mock_server.base_url, "test-client-id", valid_tokens())
143
+ assert client.voice_sample("en-US-JennyNeural") == b"ID3mp3"
144
+ headers = {k.lower() for k in mock_server.recorded_requests[0]["headers"]}
145
+ assert "authorization" not in headers
146
+
147
+
148
+ def test_voice_sample_raises_not_found_without_a_sample(mock_server):
149
+ client = ScribeClient(mock_server.base_url, "test-client-id", valid_tokens())
150
+ with pytest.raises(NotFoundError):
151
+ client.voice_sample("xx-XX-NobodyNeural")
152
+
153
+
154
+ def test_voice_sample_url_names_the_file_and_refuses_other_paths(mock_server):
155
+ client = ScribeClient(mock_server.base_url, "test-client-id", valid_tokens())
156
+ assert (
157
+ client.voice_sample_url("en-US-JennyNeural")
158
+ == f"{mock_server.base_url}/sounds/tts-samples/en-US-JennyNeural.mp3"
159
+ )
160
+ for bad in ["", "../secret", "a/b"]:
161
+ with pytest.raises(NotFoundError):
162
+ client.voice_sample_url(bad)
163
+
164
+
165
+ def test_update_settings_sends_a_voices_dict_as_the_json_string_the_server_takes(mock_server):
166
+ import json
167
+
168
+ mock_server.add_json_route("PATCH", "/api/documents/doc-1/settings", 200, settings_body())
169
+ client = ScribeClient(mock_server.base_url, "test-client-id", valid_tokens())
170
+ client.update_settings("doc-1", {"voices": {"en-US": "en-US-JennyNeural"}})
171
+ body = json.loads(mock_server.recorded_requests[0]["body"])
172
+ assert json.loads(body["settings"]["voices"]) == {"en-US": "en-US-JennyNeural"}
@@ -146,7 +146,7 @@ wheels = [
146
146
 
147
147
  [[package]]
148
148
  name = "scribe-client"
149
- version = "0.2.0"
149
+ version = "0.3.0"
150
150
  source = { editable = "." }
151
151
 
152
152
  [package.dev-dependencies]