feat(python/sdk): Add info about HTTP response status code (#7653)

GitOrigin-RevId: c6fc606f037f04da42872e72797fe66ca441b19e

Author: ploeber

README.md

@@ -937,6 +937,32 @@ The asynchronous approach allows the application to continue running while the t
 
 You can identify those two approaches by the `_async` suffix in the `Transcriber`'s method name (e.g. `transcribe` vs `transcribe_async`).
 
+## Getting the HTTP status code
+
+There are two ways of accessing the HTTP status code:
+
+- All custom AssemblyAI Error classes have a `status_code` attribute.
+- The latest HTTP response is stored in `aai.Client.get_default().latest_response` after every API call. This approach works also if no Exception is thrown.
+
+```python
+transcriber = aai.Transcriber()
+
+# Option 1: Catch the error
+try:
+    transcript = transcriber.submit("./example.mp3")
+except aai.AssemblyAIError as e:
+    print(e.status_code)
+
+# Option 2: Access the latest response through the client
+client = aai.Client.get_default()
+
+try:
+    transcript = transcriber.submit("./example.mp3")
+except:
+    print(client.last_response)
+    print(client.last_response.status_code)
+```
+
 ## Polling Intervals
 
 By default we poll the `Transcript`'s status each `3s`. In case you would like to adjust that interval:

assemblyai/__version__.py

@@ -1 +1 @@
-__version__ = "0.35.1"
+__version__ = "0.36.0"

assemblyai/api.py

@@ -43,7 +43,8 @@ def create_transcript(
     )
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
-            f"failed to transcribe url {request.audio_url}: {_get_error_message(response)}"
+            f"failed to transcribe url {request.audio_url}: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.TranscriptResponse.parse_obj(response.json())
@@ -60,6 +61,7 @@ def get_transcript(
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
             f"failed to retrieve transcript {transcript_id}: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.TranscriptResponse.parse_obj(response.json())
@@ -76,6 +78,7 @@ def delete_transcript(
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
             f"failed to delete transcript {transcript_id}: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.TranscriptResponse.parse_obj(response.json())
@@ -102,7 +105,8 @@ def upload_file(
 
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
-            f"Failed to upload audio file: {_get_error_message(response)}"
+            f"Failed to upload audio file: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return response.json()["upload_url"]
@@ -127,7 +131,8 @@ def export_subtitles_srt(
 
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
-            f"failed to export SRT for transcript {transcript_id}: {_get_error_message(response)}"
+            f"failed to export SRT for transcript {transcript_id}: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return response.text
@@ -152,7 +157,8 @@ def export_subtitles_vtt(
 
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
-            f"failed to export VTT for transcript {transcript_id}: {_get_error_message(response)}"
+            f"failed to export VTT for transcript {transcript_id}: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return response.text
@@ -174,7 +180,8 @@ def word_search(
 
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
-            f"failed to search words in transcript {transcript_id}: {_get_error_message(response)}"
+            f"failed to search words in transcript {transcript_id}: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.WordSearchMatchResponse.parse_obj(response.json())
@@ -199,17 +206,20 @@ def get_redacted_audio(
 
     if response.status_code == httpx.codes.ACCEPTED:
         raise types.RedactedAudioIncompleteError(
-            f"redacted audio for transcript {transcript_id} is not ready yet"
+            f"redacted audio for transcript {transcript_id} is not ready yet",
+            response.status_code,
         )
 
     if response.status_code == httpx.codes.BAD_REQUEST:
         raise types.RedactedAudioExpiredError(
-            f"redacted audio for transcript {transcript_id} is no longer available"
+            f"redacted audio for transcript {transcript_id} is no longer available",
+            response.status_code,
         )
 
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
-            f"failed to retrieve redacted audio for transcript {transcript_id}: {_get_error_message(response)}"
+            f"failed to retrieve redacted audio for transcript {transcript_id}: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.RedactedAudioResponse.parse_obj(response.json())
@@ -225,7 +235,8 @@ def get_sentences(
 
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
-            f"failed to retrieve sentences for transcript {transcript_id}: {_get_error_message(response)}"
+            f"failed to retrieve sentences for transcript {transcript_id}: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.SentencesResponse.parse_obj(response.json())
@@ -241,7 +252,8 @@ def get_paragraphs(
 
     if response.status_code != httpx.codes.OK:
         raise types.TranscriptError(
-            f"failed to retrieve paragraphs for transcript {transcript_id}: {_get_error_message(response)}"
+            f"failed to retrieve paragraphs for transcript {transcript_id}: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.ParagraphsResponse.parse_obj(response.json())
@@ -264,7 +276,8 @@ def list_transcripts(
 
     if response.status_code != httpx.codes.OK:
         raise types.AssemblyAIError(
-            f"failed to retrieve transcripts: {_get_error_message(response)}"
+            f"failed to retrieve transcripts: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.ListTranscriptResponse.parse_obj(response.json())
@@ -285,7 +298,8 @@ def lemur_question(
 
     if response.status_code != httpx.codes.OK:
         raise types.LemurError(
-            f"failed to call Lemur questions: {_get_error_message(response)}"
+            f"failed to call Lemur questions: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.LemurQuestionResponse.parse_obj(response.json())
@@ -306,7 +320,8 @@ def lemur_summarize(
 
     if response.status_code != httpx.codes.OK:
         raise types.LemurError(
-            f"failed to call Lemur summary: {_get_error_message(response)}"
+            f"failed to call Lemur summary: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.LemurSummaryResponse.parse_obj(response.json())
@@ -327,7 +342,8 @@ def lemur_action_items(
 
     if response.status_code != httpx.codes.OK:
         raise types.LemurError(
-            f"failed to call Lemur action items: {_get_error_message(response)}"
+            f"failed to call Lemur action items: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.LemurActionItemsResponse.parse_obj(response.json())
@@ -348,7 +364,8 @@ def lemur_task(
 
     if response.status_code != httpx.codes.OK:
         raise types.LemurError(
-            f"failed to call Lemur task: {_get_error_message(response)}"
+            f"failed to call Lemur task: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.LemurTaskResponse.parse_obj(response.json())
@@ -366,7 +383,8 @@ def lemur_purge_request_data(
 
     if response.status_code != httpx.codes.OK:
         raise types.LemurError(
-            f"Failed to purge LeMUR request data for provided request ID: {request.request_id}. Error: {_get_error_message(response)}"
+            f"Failed to purge LeMUR request data for provided request ID: {request.request_id}. Error: {_get_error_message(response)}",
+            response.status_code,
         )
 
     return types.LemurPurgeResponse.parse_obj(response.json())
@@ -387,7 +405,8 @@ def lemur_get_response_data(
 
     if response.status_code != httpx.codes.OK:
         raise types.LemurError(
-            f"Failed to get LeMUR response data for provided request ID: {request_id}. Error: {_get_error_message(response)}"
+            f"Failed to get LeMUR response data for provided request ID: {request_id}. Error: {_get_error_message(response)}",
+            response.status_code,
         )
 
     json_data = response.json()
@@ -411,7 +430,8 @@ def create_temporary_token(
 
     if response.status_code != httpx.codes.OK:
         raise types.AssemblyAIError(
-            f"Failed to create temporary token: {_get_error_message(response)}"
+            f"Failed to create temporary token: {_get_error_message(response)}",
+            response.status_code,
         )
 
     data = types.RealtimeCreateTemporaryTokenResponse.parse_obj(response.json())

assemblyai/client.py

@@ -3,7 +3,6 @@
 from typing import ClassVar, Optional
 
 import httpx
-from typing_extensions import Self
 
 from . import types
 from .__version__ import __version__
@@ -41,14 +40,30 @@ def __init__(
 
         headers = {"user-agent": user_agent}
         if self._settings.api_key:
-            headers["authorization"] = self.settings.api_key
+            headers["authorization"] = self._settings.api_key
+
+        self._last_response: Optional[httpx.Response] = None
+
+        def _store_response(response):
+            self._last_response = response
 
         self._http_client = httpx.Client(
             base_url=self.settings.base_url,
             headers=headers,
             timeout=self.settings.http_timeout,
+            event_hooks={"response": [_store_response]},
         )
 
+    @property
+    def last_response(self) -> Optional[httpx.Response]:
+        """
+        Get the last HTTP response, corresponding to the last request sent from this client.
+
+        Returns:
+            The last HTTP response.
+        """
+        return self._last_response
+
     @property
     def settings(self) -> types.Settings:
         """
@@ -72,7 +87,7 @@ def http_client(self) -> httpx.Client:
         return self._http_client
 
     @classmethod
-    def get_default(cls, api_key_required: bool = True) -> Self:
+    def get_default(cls, api_key_required: bool = True):
         """
         Return the default client.