diff --git a/assemblyai/__version__.py b/assemblyai/__version__.py index d6a282f..f5d43bc 100644 --- a/assemblyai/__version__.py +++ b/assemblyai/__version__.py @@ -1 +1 @@ -__version__ = "1.10.12" +__version__ = "1.10.14" diff --git a/assemblyai/prerecorded/v2/client.py b/assemblyai/prerecorded/v2/client.py index 7a86cfb..36fd4ff 100644 --- a/assemblyai/prerecorded/v2/client.py +++ b/assemblyai/prerecorded/v2/client.py @@ -4,7 +4,7 @@ import concurrent.futures import os -from typing import BinaryIO, List, Optional, Set, Tuple, Union +from typing import BinaryIO, List, Optional, Tuple, Union from ... import api as _root_api from ... import client as _client @@ -132,7 +132,9 @@ def transcribe_group( ) -> Union[TranscriptGroup, Tuple[TranscriptGroup, List[types.AssemblyAIError]]]: config = self._resolve_config(config) - future_transcripts: Set[concurrent.futures.Future[Transcript]] = set() + # A list, read back in the same order below, so the group follows the + # order of `data`. A set of futures iterates in an arbitrary order. + future_transcripts: List[concurrent.futures.Future[Transcript]] = [] with concurrent.futures.ThreadPoolExecutor(max_workers=8) as executor: for d in data: @@ -143,16 +145,16 @@ def transcribe_group( poll=False, ) - future_transcripts.add(transcript_future) + future_transcripts.append(transcript_future) - finished_futures, _ = concurrent.futures.wait(future_transcripts) + concurrent.futures.wait(future_transcripts) transcript_group = TranscriptGroup( client=self._client, ) failures: List[types.AssemblyAIError] = [] - for future in finished_futures: + for future in future_transcripts: try: transcript_group.add_transcript(future.result()) except types.TranscriptError as e: @@ -331,6 +333,10 @@ def submit_group( config: Transcription options and features. If `None` is given, the Transcriber's default configuration will be used. return_failures: Whether to include a list of errors for transcriptions that failed due to HTTP errors + + Returns: The `TranscriptGroup`, with its transcripts in the order of `data`. + An input whose request failed with an HTTP error is left out (see + `return_failures`); the others keep their order. """ return self._impl.transcribe_group( data=data, @@ -428,6 +434,10 @@ def transcribe_group( config: Transcription options and features. If `None` is given, the Transcriber's default configuration will be used. return_failures: Whether to include a list of errors for transcriptions that failed due to HTTP errors + + Returns: The `TranscriptGroup`, with its transcripts in the order of `data`. + An input whose request failed with an HTTP error is left out (see + `return_failures`); the others keep their order. """ return self._impl.transcribe_group( diff --git a/assemblyai/prerecorded/v2/transcript_group.py b/assemblyai/prerecorded/v2/transcript_group.py index ef64629..ffeb8ed 100644 --- a/assemblyai/prerecorded/v2/transcript_group.py +++ b/assemblyai/prerecorded/v2/transcript_group.py @@ -3,7 +3,7 @@ from __future__ import annotations import concurrent.futures -from typing import Iterator, List, Optional, Set, Tuple, Union +from typing import Iterator, List, Optional, Tuple, Union from typing_extensions import Self @@ -52,15 +52,18 @@ def wait_for_completion( transcripts: List[Transcript] = [] failures: List[types.AssemblyAIError] = [] - future_transcripts: Set[concurrent.futures.Future[Transcript]] = set() + # A list, read back in the same order below, so the transcripts keep + # their order in the group. A set of futures iterates in an arbitrary + # order. + future_transcripts: List[concurrent.futures.Future[Transcript]] = [] for transcript in self.transcripts: future = transcript.wait_for_completion_async() - future_transcripts.add(future) + future_transcripts.append(future) - finished_futures, _ = concurrent.futures.wait(future_transcripts) + concurrent.futures.wait(future_transcripts) - for future in finished_futures: + for future in future_transcripts: try: transcripts.append(future.result()) except types.TranscriptError as e: @@ -167,6 +170,8 @@ def wait_for_completion( Note - if an HTTP error is encountered when waiting for a Transcript in the TranscriptGroup, it will be popped from the group and added to the list of failures. You can return this list of failures with `return_failures=True`. + The transcripts that remain keep their order in the group. + Args: return_failures: Whether to return a list of errors for transcripts that failed due to HTTP errors. """ diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py index cd0e2c0..a13d9ab 100644 --- a/tests/unit/conftest.py +++ b/tests/unit/conftest.py @@ -1,3 +1,6 @@ +import concurrent.futures +import itertools + import pytest @@ -9,3 +12,25 @@ def faker_seed(): See: https://faker.readthedocs.io/en/master/pytest-fixtures.html """ return 12345 + + +@pytest.fixture +def futures_hash_in_descending_order(monkeypatch): + """ + Gives each `concurrent.futures.Future` a small hash, descending in the + order the futures are first hashed. + + A set of futures iterates by hash. A future's default hash comes from its + memory address, so a set of them can iterate in creation order by chance. + With these hashes it never does: a test of result order then fails for + any code that takes its order from a set of futures. + """ + next_hash = itertools.count(1000, -1) + + def descending_hash(future): + if not hasattr(future, "_order_test_hash"): + future._order_test_hash = next(next_hash) + + return future._order_test_hash + + monkeypatch.setattr(concurrent.futures.Future, "__hash__", descending_hash) diff --git a/tests/unit/test_transcriber.py b/tests/unit/test_transcriber.py index 6f444a1..7d21308 100644 --- a/tests/unit/test_transcriber.py +++ b/tests/unit/test_transcriber.py @@ -482,6 +482,102 @@ def test_transcribe_group_urls_succeeds(httpx_mock: HTTPXMock): assert len(httpx_mock.get_requests()) == 4 +_GROUP_AUDIO_URLS = [f"https://example.org/{index}.wav" for index in range(8)] + + +def _mock_group_requests(httpx_mock: HTTPXMock, *, poll: bool, failing_url=None): + """ + Mocks the job API for `_GROUP_AUDIO_URLS`: each creation request gets a + transcript whose id carries the URL's index, and `failing_url` gets a 500. + """ + + def response_for(index: int) -> dict: + response = factories.generate_dict_factory( + factories.TranscriptCompletedResponseFactory + )() + response["id"] = f"transcript-{index}" + response["audio_url"] = _GROUP_AUDIO_URLS[index] + + return response + + def create_transcript(request: httpx.Request) -> httpx.Response: + audio_url = json.loads(request.content)["audio_url"] + if audio_url == failing_url: + return httpx.Response( + httpx.codes.INTERNAL_SERVER_ERROR, + json={"error": "something went wrong"}, + ) + + return httpx.Response( + httpx.codes.OK, json=response_for(_GROUP_AUDIO_URLS.index(audio_url)) + ) + + for index, audio_url in enumerate(_GROUP_AUDIO_URLS): + # One registration per request; older pytest-httpx has no is_reusable. + httpx_mock.add_callback( + create_transcript, + url=f"{aai.settings.base_url}{ENDPOINT_TRANSCRIPT}", + method="POST", + ) + if poll and audio_url != failing_url: + httpx_mock.add_response( + url=f"{aai.settings.base_url}{ENDPOINT_TRANSCRIPT}/transcript-{index}", + status_code=httpx.codes.OK, + method="GET", + json=response_for(index), + ) + + +def test_transcribe_group_keeps_input_order( + httpx_mock: HTTPXMock, futures_hash_in_descending_order +): + """ + Tests that the transcripts of a group are in the order of the inputs, + so the caller can match each transcript to the file it came from. + """ + _mock_group_requests(httpx_mock, poll=True) + + transcript_group = aai.Transcriber().transcribe_group(_GROUP_AUDIO_URLS) + + assert [t.audio_url for t in transcript_group] == _GROUP_AUDIO_URLS + + +def test_submit_group_keeps_input_order( + httpx_mock: HTTPXMock, futures_hash_in_descending_order +): + """ + Tests that a submitted group, which does not wait for completion, is in + the order of the inputs as well. + """ + _mock_group_requests(httpx_mock, poll=False) + + transcript_group = aai.Transcriber().submit_group(_GROUP_AUDIO_URLS) + + assert [t.audio_url for t in transcript_group] == _GROUP_AUDIO_URLS + + +def test_transcribe_group_keeps_input_order_when_one_fails( + httpx_mock: HTTPXMock, futures_hash_in_descending_order +): + """ + Tests that when one input fails, the others stay in the order of the + inputs and the failure is returned. + """ + failing_url = _GROUP_AUDIO_URLS[3] + _mock_group_requests(httpx_mock, poll=True, failing_url=failing_url) + + transcript_group, failures = aai.Transcriber().transcribe_group( + _GROUP_AUDIO_URLS, + return_failures=True, + ) + + assert [t.audio_url for t in transcript_group] == [ + audio_url for audio_url in _GROUP_AUDIO_URLS if audio_url != failing_url + ] + assert len(failures) == 1 + assert failures[0].status_code == httpx.codes.INTERNAL_SERVER_ERROR + + def test_transcribe_group_urls_fails_during_upload(httpx_mock: HTTPXMock): """ Tests the scenario of when a list of paths or URLs are being transcribed diff --git a/tests/unit/test_transcript_group.py b/tests/unit/test_transcript_group.py index b62c20a..0133bf3 100644 --- a/tests/unit/test_transcript_group.py +++ b/tests/unit/test_transcript_group.py @@ -101,6 +101,74 @@ def test_get_by_ids(httpx_mock: HTTPXMock): assert len(transcript_ids) == 0 +_ORDERED_TRANSCRIPT_IDS = [f"transcript-{index}" for index in range(8)] + + +def _mock_completed_transcripts(httpx_mock: HTTPXMock, failing_id=None): + """ + Mocks a completed transcript for each of `_ORDERED_TRANSCRIPT_IDS`, and a + 500 for `failing_id`. + """ + for transcript_id in _ORDERED_TRANSCRIPT_IDS: + url = f"{aai.settings.base_url}{ENDPOINT_TRANSCRIPT}/{transcript_id}" + if transcript_id == failing_id: + httpx_mock.add_response( + url=url, + status_code=httpx.codes.INTERNAL_SERVER_ERROR, + method="GET", + json={"error": "something went wrong"}, + ) + continue + + response = factories.generate_dict_factory( + factories.TranscriptCompletedResponseFactory + )() + response["id"] = transcript_id + httpx_mock.add_response( + url=url, + status_code=httpx.codes.OK, + method="GET", + json=response, + ) + + +def test_get_by_ids_keeps_given_order( + httpx_mock: HTTPXMock, futures_hash_in_descending_order +): + """ + Tests that the transcripts of a fetched group are in the order of the + given IDs. + """ + _mock_completed_transcripts(httpx_mock) + + transcript_group = aai.TranscriptGroup.get_by_ids(_ORDERED_TRANSCRIPT_IDS) + + assert [t.id for t in transcript_group] == _ORDERED_TRANSCRIPT_IDS + + +def test_wait_for_completion_keeps_order_when_one_fails( + httpx_mock: HTTPXMock, futures_hash_in_descending_order +): + """ + Tests that when polling one transcript fails, it leaves the group and the + others stay in their order. + """ + failing_id = _ORDERED_TRANSCRIPT_IDS[3] + _mock_completed_transcripts(httpx_mock, failing_id=failing_id) + + transcript_group, failures = aai.TranscriptGroup( + transcript_ids=_ORDERED_TRANSCRIPT_IDS + ).wait_for_completion(return_failures=True) + + assert [t.id for t in transcript_group] == [ + transcript_id + for transcript_id in _ORDERED_TRANSCRIPT_IDS + if transcript_id != failing_id + ] + assert len(failures) == 1 + assert failures[0].status_code == httpx.codes.INTERNAL_SERVER_ERROR + + def test_get_by_id_async(httpx_mock: HTTPXMock): transcript_ids = ["123", "456"] mock_transcript_response = factories.generate_dict_factory(