AISDK-190 Update sdks to support notification_config and source_config (#83)

Author: aaron-wilson-rev

HISTORY.rst

@@ -94,3 +94,9 @@ History
 ------------------
 * Add topic extraction client
 * Add speaker_names to async client for human transcription
+
+2.16.0
+------------------
+* Add source_config and notification_config job options to support customer provided urls with authentication headers
+* Deprecate media_url option, replace with source_config
+* Deprecate callback_url option, replace with notification_config

README.md

@@ -50,9 +50,17 @@ job = client.submit_job_url("https://example.com/file-to-transcribe.mp3")
 `job` will contain all the information normally found in a successful response from our
 [Submit Job](https://docs.rev.ai/api/asynchronous/reference/#operation/SubmitTranscriptionJob) endpoint.
 
-If you want to get fancy, both send job methods take `metadata`, `callback_url`,
-`skip_diarization`, `skip_punctuation`, `speaker_channels_count`, `custom_vocabularies`, `filter_profanity`, `remove_disfluencies`, `delete_after_seconds`, `language`, and `custom_vocabulary_id` as optional parameters, these are described in the request body of
-the [Submit Job](https://docs.rev.ai/api/asynchronous/reference/#operation/SubmitTranscriptionJob) endpoint.
+If you want to get fancy, both submit job methods take `metadata`,`notification_config`, 
+`skip_diarization`, `skip_punctuation`, `speaker_channels_count`,`custom_vocabularies`,
+`filter_profanity`, `remove_disfluencies`, `delete_after_seconds`,`language`,
+and `custom_vocabulary_id` as optional parameters.
+
+The url submission option also supports authentication headers by using the `source_config` option.
+
+All options are described in the request body of the
+[Submit Job](https://docs.rev.ai/api/asynchronous/reference/#operation/SubmitTranscriptionJob) endpoint.
+
+### Human Transcription
 
 If you want transcription to be performed by a human, both methods allow you to submit human transcription jobs
 using `transcriber=human` with `verbatim`, `rush`, `segments_to_transcribe` and `test_mode` as optional parameters.

examples/async_auth_options_example.py

@@ -0,0 +1,37 @@
+"""Copyright 2022 REV
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from rev_ai import apiclient
+from rev_ai.models.customer_url_data import CustomerUrlData
+
+# String containing your access token
+access_token = "<your_access_token>"
+
+# Create your api client
+client = apiclient.RevAiAPIClient(access_token)
+
+# Create config objects containing the url and auth headers for each option
+# These options replace media_url and callback_url and should not be used alongside them
+source_url = "https://www.rev.ai/FTC_Sample_1.mp3"
+source_auth_headers = {"Authorization": "Bearer <token>"}
+callback_url = "https://www.example.com/callback"
+callback_auth_headers = {"Authorization": "Bearer <token>"}
+
+# Submitting a job with the authentication header options
+job = client.submit_job_url(
+    source_config=CustomerUrlData(url=source_url, auth_headers=source_auth_headers),
+    notification_config=CustomerUrlData(url=callback_url, auth_headers=callback_auth_headers))
+
+print("Submitted Job")

examples/async_example.py

@@ -45,13 +45,14 @@
 #                                    remove_disfluencies=False,
 #                                    delete_after_seconds=None,
 #                                    language=None,
-#                                    custom_vocabulary_id=None)
+#                                    custom_vocabulary_id=None,
+#                                    notification_config=None)
 
 
 # Submitting a job with a link to the file you want transcribed
 # Change url to your url, custom_vocabularies is optional like above
 url = "https://www.rev.ai/FTC_Sample_1.mp3"
-job = client.submit_job_url(url,
+job = client.submit_job_url(media_url=url,
                             metadata=None,
                             callback_url=None,
                             skip_diarization=False,
@@ -60,7 +61,9 @@
                             remove_disfluencies=False,
                             delete_after_seconds=None,
                             language=None,
-                            custom_vocabulary_id=None)
+                            custom_vocabulary_id=None,
+                            source_config=None,
+                            notification_config=None)
 
 print("Submitted Job")
 
@@ -73,7 +76,7 @@
 
     # Checks if the job has been transcribed. Please note that this is not the recommended way
     # of getting job status in a real application. For recommended methods of getting job status
-    # please see our documentation on callback_urls here:
+    # please see our documentation on setting a callback url here:
     # https://docs.rev.ai/resources/tutorials/get-started-api-webhooks/
     if status == "IN_PROGRESS":
         time.sleep(5)

examples/language_identification_example.py

@@ -18,18 +18,22 @@
 
 
 # String containing your access token
+from rev_ai.models.customer_url_data import CustomerUrlData
+
 access_token = "<your_access_token>"
 
 # Create your api client
 client = language_identification_client.LanguageIdentificationClient(access_token)
 
 # Submitting a job with a link to the file you want to identify the language of
-# Change url to your url
-url = "https://www.rev.ai/FTC_Sample_1.mp3"
-job = client.submit_job_url(url,
+# Change the url specified in source_config to the url of the media to submit
+source_config = CustomerUrlData(url="https://www.rev.ai/FTC_Sample_1.mp3")
+job = client.submit_job_url(media_url=None,
                             metadata=None,
                             callback_url=None,
-                            delete_after_seconds=None)
+                            delete_after_seconds=None,
+                            source_config=source_config,
+                            notification_config=None)
 
 print("Submitted Job")
 

examples/requirements.txt

@@ -1,3 +1,3 @@
-rev-ai==2.15.0
+rev-ai==2.16.0
 pyaudio==0.2.11
 six==1.12.0

examples/topic_extraction_example.py

@@ -27,9 +27,9 @@
 text = "<input_text>"
 job = client.submit_job_from_text(text,
                                   metadata=None,
-                                  callback_url=None,
                                   delete_after_seconds=None,
-                                  language=None)
+                                  language=None,
+                                  notification_config=None)
 
 # If you'd like to submit the transcript of an existing transcription job you can do so by
 # uncommenting the lines below
@@ -40,7 +40,6 @@
 # transcript_json = transcript
 # job = client.submit_job_from_transcript(transcript_json,
 #                                         metadata=None,
-#                                         callback_url=None,
 #                                         delete_after_seconds=None,
 #                                         language=None)
 
@@ -55,7 +54,7 @@
 
     # Checks if the job has been completed. Please note that this is not the recommended way
     # of getting job status in a real application. For recommended methods of getting job status
-    # please see our documentation on callback_urls here:
+    # please see our documentation on setting a callback url here:
     # https://docs.rev.ai/resources/tutorials/get-started-api-webhooks/
     if status == "IN_PROGRESS":
         time.sleep(2)

setup.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 2.15.0
+current_version = 2.16.0
 commit = True
 tag = True
 

src/rev_ai/__init__.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """Top-level package for rev_ai"""
 
-__version__ = '2.15.1'
+__version__ = '2.16.0'
 
 from .models import Job, JobStatus, Account, Transcript, Monologue, Element, MediaConfig, \
     CaptionType, CustomVocabulary, TopicExtractionJob, TopicExtractionResult, Topic, Informant, \

src/rev_ai/apiclient.py

@@ -44,7 +44,7 @@ def __init__(self, access_token):
 
     def submit_job_url(
             self,
-            media_url,
+            media_url=None,
             metadata=None,
             callback_url=None,
             skip_diarization=False,
@@ -61,18 +61,20 @@ def submit_job_url(
             rush=None,
             test_mode=None,
             segments_to_transcribe=None,
-            speaker_names=None):
+            speaker_names=None,
+            source_config=None,
+            notification_config=None):
         """Submit media given a URL for transcription.
-        The audio data is downloaded from the URL.
-
+        The audio data is downloaded from the URL
         :param media_url: web location of the media file
+        .. deprecated:: 2.16.0
+            Use source_config instead
         :param metadata: info to associate with the transcription job
-        :param callback_url: callback url to invoke on job completion as
-                             a webhook
-        :param skip_diarization: should Rev AI skip diaization when
-                                 transcribing this file
-        :param skip_punctuation: should Rev AI skip punctuation when
-                                 transcribing this file
+        :param callback_url: callback url to invoke on job completion as a webhook
+        .. deprecated:: 2.16.0
+            Use notification_config instead
+        :param skip_diarization: should Rev AI skip diarization when transcribing this file
+        :param skip_punctuation: should Rev AI skip punctuation when transcribing this file
         :param speaker_channels_count: the number of speaker channels in the
             audio. If provided the given audio will have each channel
             transcribed separately and each channel will be treated as a single
@@ -102,19 +104,23 @@ def submit_job_url(
             Sections of transcript needed to be transcribed.
         :param speaker_names: Only available with "human" transcriber.
             Human readable names of speakers in the file.
+        :param source_config: CustomerUrlData object containing url of the source media and
+            optional authentication headers to use when accessing the source url
+        :param notification_config: CustomerUrlData object containing the callback url to
+            invoke on job completion as a webhook and optional authentication headers to use when
+            calling the callback url
         :returns: raw response data
         :raises: HTTPError
         """
-        if not media_url:
-            raise ValueError('media_url must be provided')
-        payload = self._create_job_options_payload(media_url, metadata,
-                                                   callback_url, skip_diarization,
-                                                   skip_punctuation, speaker_channels_count,
+        payload = self._create_job_options_payload(media_url, metadata, callback_url,
+                                                   skip_diarization, skip_punctuation,
+                                                   speaker_channels_count,
                                                    custom_vocabularies, filter_profanity,
                                                    remove_disfluencies, delete_after_seconds,
                                                    language, custom_vocabulary_id, transcriber,
                                                    verbatim, rush, test_mode,
-                                                   segments_to_transcribe, speaker_names)
+                                                   segments_to_transcribe, speaker_names,
+                                                   source_config, notification_config)
 
         response = self._make_http_request(
             "POST",
@@ -143,18 +149,18 @@ def submit_job_local_file(
             rush=None,
             test_mode=None,
             segments_to_transcribe=None,
-            speaker_names=None):
+            speaker_names=None,
+            notification_config=None):
         """Submit a local file for transcription.
         Note that the content type is inferred if not provided.
 
         :param filename: path to a local file on disk
         :param metadata: info to associate with the transcription job
-        :param callback_url: callback url to invoke on job completion as a
-                             webhook
-        :param skip_diarization: should Rev AI skip diaization when
-                                 transcribing this file
-        :param skip_punctuation: should Rev AI skip punctuation when
-                                 transcribing this file
+        :param callback_url: callback url to invoke on job completion as a webhook
+        .. deprecated:: 2.16.0
+                Use notification_config instead
+        :param skip_diarization: should Rev AI skip diarization when transcribing this file
+        :param skip_punctuation: should Rev AI skip punctuation when transcribing this file
         :param speaker_channels_count: the number of speaker channels in the
             audio. If provided the given audio will have each channel
             transcribed separately and each channel will be treated as a single
@@ -184,19 +190,24 @@ def submit_job_local_file(
             Sections of transcript needed to be transcribed.
         :param speaker_names: Only available with "human" transcriber.
             Human readable names of speakers in the file.
+        :param notification_config: CustomerUrlData object containing the callback url to
+            invoke on job completion as a webhook and optional authentication headers to use when
+            calling the callback url
         :returns: raw response data
-        :raises: HTTPError
+        :raises: HTTPError, ValueError
         """
         if not filename:
             raise ValueError('filename must be provided')
 
-        payload = self._create_job_options_payload(None, metadata, callback_url, skip_diarization,
-                                                   skip_punctuation, speaker_channels_count,
+        payload = self._create_job_options_payload(None, metadata, callback_url,
+                                                   skip_diarization, skip_punctuation,
+                                                   speaker_channels_count,
                                                    custom_vocabularies, filter_profanity,
                                                    remove_disfluencies, delete_after_seconds,
                                                    language, custom_vocabulary_id, transcriber,
                                                    verbatim, rush, test_mode,
-                                                   segments_to_transcribe, speaker_names)
+                                                   segments_to_transcribe, speaker_names, None,
+                                                   notification_config)
 
         with open(filename, 'rb') as f:
             files = {
@@ -426,7 +437,8 @@ def get_account(self):
         return Account.from_json(response.json())
 
     def _create_job_options_payload(
-            self, media_url,
+            self,
+            media_url=None,
             metadata=None,
             callback_url=None,
             skip_diarization=None,
@@ -443,7 +455,9 @@ def _create_job_options_payload(
             rush=None,
             test_mode=None,
             segments_to_transcribe=None,
-            speaker_names=None):
+            speaker_names=None,
+            source_config=None,
+            notification_config=None):
         payload = {}
         if media_url:
             payload['media_url'] = media_url
@@ -456,8 +470,7 @@ def _create_job_options_payload(
         if callback_url:
             payload['callback_url'] = callback_url
         if custom_vocabularies:
-            payload['custom_vocabularies'] =\
-                utils._process_vocabularies(custom_vocabularies)
+            payload['custom_vocabularies'] = utils._process_vocabularies(custom_vocabularies)
         if speaker_channels_count:
             payload['speaker_channels_count'] = speaker_channels_count
         if filter_profanity:
@@ -483,6 +496,10 @@ def _create_job_options_payload(
         if speaker_names:
             payload['speaker_names'] =\
                 utils._process_speaker_names(speaker_names)
+        if source_config:
+            payload['source_config'] = source_config.to_dict()
+        if notification_config:
+            payload['notification_config'] = notification_config.to_dict()
         return payload
 
     def _create_captions_query(self, speaker_channel):