Merge pull request #645 from danielthepope/feature/subtitles

Add ability to upload subtitles and link to media

Author: jeremylow

testdata/subs.srt

@@ -0,0 +1,8 @@
+1
+00:00:00,000 --> 00:00:03,251
+Lorem ipsum dolor sit amet,
+consectetur adipiscing elit.
+
+2
+00:00:03,251 --> 00:00:06,502
+Maecenas rutrum suscipit accumsan.

tests/test_api_30.py

@@ -1548,6 +1548,87 @@ def testPostUploadMediaChunkedFinalize(self):
         self.assertEqual(len(responses.calls), 1)
         self.assertTrue(resp)
 
+    @responses.activate
+    def testPostMediaSubtitlesCreateSuccess(self):
+        responses.add(
+            POST,
+            'https://upload.twitter.com/1.1/media/subtitles/create.json',
+            body=b'',
+            status=200)
+        expected_body = {
+            'media_id': '1234',
+            'media_category': 'TweetVideo',
+            'subtitle_info': {
+                'subtitles': [{
+                    'media_id': '5678',
+                    'language_code': 'en',
+                    'display_name': 'English'
+                }]
+            }
+        }
+        resp = self.api.PostMediaSubtitlesCreate(video_media_id=1234,
+                                                 subtitle_media_id=5678,
+                                                 language_code='en',
+                                                 display_name='English')
+
+        self.assertEqual(len(responses.calls), 1)
+        self.assertEqual(responses.calls[0].request.url,
+                         'https://upload.twitter.com/1.1/media/subtitles/create.json')
+        request_body = json.loads(responses.calls[0].request.body.decode('utf-8'))
+        self.assertTrue(resp)
+        self.assertDictEqual(expected_body, request_body)
+
+    @responses.activate
+    def testPostMediaSubtitlesCreateFailure(self):
+        responses.add(
+            POST,
+            'https://upload.twitter.com/1.1/media/subtitles/create.json',
+            body=b'{"error":"Some error happened"}',
+            status=400)
+        self.assertRaises(
+            twitter.TwitterError,
+            lambda: self.api.PostMediaSubtitlesCreate(video_media_id=1234,
+                                                      subtitle_media_id=5678,
+                                                      language_code='en',
+                                                      display_name='English'))
+
+    @responses.activate
+    def testPostMediaSubtitlesDeleteSuccess(self):
+        responses.add(
+            POST,
+            'https://upload.twitter.com/1.1/media/subtitles/delete.json',
+            body=b'',
+            status=200)
+        expected_body = {
+            'media_id': '1234',
+            'media_category': 'TweetVideo',
+            'subtitle_info': {
+                'subtitles': [{
+                    'language_code': 'en'
+                }]
+            }
+        }
+        resp = self.api.PostMediaSubtitlesDelete(video_media_id=1234, language_code='en')
+
+        self.assertEqual(len(responses.calls), 1)
+        self.assertEqual(responses.calls[0].request.url,
+                         'https://upload.twitter.com/1.1/media/subtitles/delete.json')
+        request_body = json.loads(responses.calls[0].request.body.decode('utf-8'))
+        self.assertTrue(resp)
+        self.assertDictEqual(expected_body, request_body)
+
+    @responses.activate
+    def testPostMediaSubtitlesDeleteFailure(self):
+        responses.add(
+            POST,
+            'https://upload.twitter.com/1.1/media/subtitles/delete.json',
+            body=b'{"error":"Some error happened"}',
+            status=400)
+        self.assertRaises(
+            twitter.TwitterError,
+            lambda: self.api.PostMediaSubtitlesDelete(video_media_id=1234,
+                                                      language_code='en'))
+
     @responses.activate
     def testGetUserSuggestionCategories(self):
         with open('testdata/get_user_suggestion_categories.json') as f:

tests/test_twitter_utils.py

@@ -75,6 +75,13 @@ def test_parse_media_file_fileobj(self):
             self.assertEqual(file_size, 44772)
             self.assertEqual(media_type, 'image/jpeg')
 
+    def test_parse_media_file_subtitle(self):
+        data_file, filename, file_size, media_type = parse_media_file('testdata/subs.srt')
+        self.assertTrue(hasattr(data_file, 'read'))
+        self.assertEqual(filename, 'subs.srt')
+        self.assertEqual(file_size, 157)
+        self.assertEqual(media_type, 'text/srt')
+
     def test_utils_error_checking(self):
         with open('testdata/168NQ.jpg', 'r') as f:
             self.assertRaises(

twitter/api.py

@@ -1028,15 +1028,15 @@ def PostUpdate(self,
                    attachment_url=None):
         """Post a twitter status message from the authenticated user.
 
-        https://dev.twitter.com/docs/api/1.1/post/statuses/update
+        https://developer.twitter.com/en/docs/tweets/post-and-engage/api-reference/post-statuses-update
 
         Args:
             status (str):
                 The message text to be posted. Must be less than or equal to
                 CHARACTER_LIMIT characters.
             media (int, str, fp, optional):
-                A URL, a local file, or a file-like object (something with a
-                read() method), or a list of any combination of the above.
+                A media ID, URL, local file, or file-like object (something with
+                a read() method), or a list of any combination of the above.
             media_additional_owners (list, optional):
                 A list of user ids representing Twitter users that should be able
                 to use the uploaded media in their tweets. If you pass a list of
@@ -1398,7 +1398,7 @@ def UploadMediaChunked(self,
                 number of additional owners is capped at 100 by Twitter.
             media_category:
                 Category with which to identify media upload. Only use with Ads
-                API & video files.
+                API, video files and subtitles.
 
         Returns:
             media_id:
@@ -1424,6 +1424,81 @@ def UploadMediaChunked(self,
         except KeyError:
             raise TwitterError('Media could not be uploaded.')
 
+    def PostMediaSubtitlesCreate(self,
+                                 video_media_id,
+                                 subtitle_media_id,
+                                 language_code,
+                                 display_name):
+        """Associate uploaded subtitles to an uploaded video. You can associate
+        subtitles to a video before or after Tweeting.
+
+        Args:
+            video_media_id (int):
+                Media ID of the uploaded video to add the subtitles to. The
+                video must have been uploaded using the category 'TweetVideo'.
+            subtitle_media_id (int):
+                Media ID of the uploaded subtitle file. The subtitles myst have
+                been uploaded using the category 'Subtitles'.
+            language_code (str):
+                The language code that the subtitles are written in. The
+                language code should be a BCP47 code (e.g. 'en', 'sp')
+            display_name (str):
+                Language name (e.g. 'English', 'Spanish')
+
+        Returns:
+            True if successful. Raises otherwise.
+        """
+        url = '%s/media/subtitles/create.json' % self.upload_url
+
+        subtitle = {}
+        subtitle['media_id'] = str(subtitle_media_id)
+        subtitle['language_code'] = language_code
+        subtitle['display_name'] = display_name
+        parameters = {}
+        parameters['media_id'] = str(video_media_id)
+        parameters['media_category'] = 'TweetVideo'
+        parameters['subtitle_info'] = {}
+        parameters['subtitle_info']['subtitles'] = [subtitle]
+
+        resp = self._RequestUrl(url, 'POST', json=parameters)
+        # Response body should be blank, so only do error checking if the response is not blank.
+        if resp.content.decode('utf-8'):
+            self._ParseAndCheckTwitter(resp.content.decode('utf-8'))
+
+        return True
+
+    def PostMediaSubtitlesDelete(self,
+                                 video_media_id,
+                                 language_code):
+        """Remove subtitles from an uploaded video.
+
+        Args:
+            video_media_id (int):
+                Media ID of the video for which the subtitles will be removed.
+            language_code (str):
+                The language code of the subtitle file that should be deleted.
+                The language code should be a BCP47 code (e.g. 'en', 'sp')
+
+        Returns:
+            True if successful. Raises otherwise.
+        """
+        url = '%s/media/subtitles/delete.json' % self.upload_url
+
+        subtitle = {}
+        subtitle['language_code'] = language_code
+        parameters = {}
+        parameters['media_id'] = str(video_media_id)
+        parameters['media_category'] = 'TweetVideo'
+        parameters['subtitle_info'] = {}
+        parameters['subtitle_info']['subtitles'] = [subtitle]
+
+        resp = self._RequestUrl(url, 'POST', json=parameters)
+        # Response body should be blank, so only do error checking if the response is not blank.
+        if resp.content.decode('utf-8'):
+            self._ParseAndCheckTwitter(resp.content.decode('utf-8'))
+
+        return True
+
     def _TweetTextWrap(self,
                        status,
                        char_lim=CHARACTER_LIMIT):

twitter/twitter_utils.py

@@ -243,6 +243,7 @@ def parse_media_file(passed_media, async_upload=False):
     long_img_formats = [
         'image/gif'
     ]
+    subtitle_formats = ['text/srt']
     video_formats = ['video/mp4',
                      'video/quicktime']
 
@@ -274,6 +275,9 @@ def parse_media_file(passed_media, async_upload=False):
         pass
 
     media_type = mimetypes.guess_type(os.path.basename(filename))[0]
+    # The .srt extension is not recognised by the mimetypes module.
+    if os.path.basename(filename).endswith('.srt'):
+        media_type = 'text/srt'
     if media_type is not None:
         if media_type in img_formats and file_size > 5 * 1048576:
             raise TwitterError({'message': 'Images must be less than 5MB.'})
@@ -283,7 +287,7 @@ def parse_media_file(passed_media, async_upload=False):
             raise TwitterError({'message': 'Videos must be less than 15MB.'})
         elif media_type in video_formats and async_upload and file_size > 512 * 1048576:
             raise TwitterError({'message': 'Videos must be less than 512MB.'})
-        elif media_type not in img_formats and media_type not in video_formats and media_type not in long_img_formats:
+        elif media_type not in img_formats + long_img_formats + subtitle_formats + video_formats:
             raise TwitterError({'message': 'Media type could not be determined.'})
 
     return data_file, filename, file_size, media_type