add clips discovery endpoints v4

Author: anxdpanic

resources/lib/twitch/api/__init__.py

@@ -1,6 +1,7 @@
 # -*- encoding: utf-8 -*-
 
+from twitch.api import v4
 from twitch.api import v5
 from twitch.api import v5 as default
 
-__all__ = ['v5', 'default']
+__all__ = ['v4', 'v5', 'default']

resources/lib/twitch/api/parameters.py

@@ -19,6 +19,14 @@ class Period(_Parameter):
     _valid = [WEEK, MONTH, ALL]
 
 
+class ClipPeriod(_Parameter):
+    DAY = 'day'
+    WEEK = 'week'
+    MONTH = 'month'
+    ALL = 'all'
+    _valid = [DAY, WEEK, MONTH, ALL]
+
+
 class Boolean(_Parameter):
     TRUE = 'true'
     FALSE = 'false'

resources/lib/twitch/api/usher.py

@@ -1,12 +1,13 @@
 # -*- encoding: utf-8 -*-
 
-from twitch.logging import log                                          # NOQA
-log.warning('By using this module you are violating the Twitch TOS')    # NOQA
+from twitch.logging import log  # NOQA
+
+log.warning('By using this module you are violating the Twitch TOS')  # NOQA
 
 from twitch import keys
 from twitch.api.parameters import Boolean
-from twitch.parser import m3u8
-from twitch.queries import HiddenApiQuery, UsherQuery
+from twitch.parser import m3u8, clip_embed
+from twitch.queries import ClipsQuery, HiddenApiQuery, UsherQuery
 from twitch.queries import query
 
 
@@ -72,3 +73,11 @@ def video(video_id):
         return _legacy_video(video_id)
     else:
         raise NotImplementedError('Unknown Video Type')
+
+
+@clip_embed
+@query
+def clip(slug):
+    q = ClipsQuery('embed')
+    q.add_param(keys.CLIP, slug)
+    return q

resources/lib/twitch/api/v4/__init__.py

@@ -0,0 +1,4 @@
+# -*- encoding: utf-8 -*-
+# https://dev.twitch.tv/docs/v5/guides/clips-discovery/
+
+from twitch.api.v4 import clips  # NOQA

resources/lib/twitch/api/v4/clips.py

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+# https://dev.twitch.tv/docs/v5/guides/clips-discovery/#clips-discovery-api-reference
+
+from twitch import keys
+from twitch.api.parameters import Boolean, ClipPeriod, Cursor
+from twitch.queries import V4Query as Qry
+from twitch.queries import query
+
+
+# required scope: None
+@query
+def by_slug(slug):
+    q = Qry('clips/{slug}')
+    q.add_urlkw(keys.SLUG, slug)
+    return q
+
+
+# required scope: None
+@query
+def get_top(channels=None, games=None, period=ClipPeriod.WEEK, trending=Boolean.FALSE, cursor='MA==', limit=10):
+    q = Qry('clips/top')
+    q.add_param(keys.CHANNEL, channels, None)
+    q.add_param(keys.GAME, games, None)
+    q.add_param(keys.PERIOD, ClipPeriod.validate(period), ClipPeriod.WEEK)
+    q.add_param(keys.TRENDING, Boolean.validate(trending), Boolean.FALSE)
+    q.add_param(keys.LIMIT, limit, 10)
+    q.add_param(keys.CURSOR, Cursor.validate(cursor), 'MA==')
+    return q
+
+
+# required scope: user_read
+@query
+def get_followed(trending=Boolean.FALSE, cursor='MA==', limit=10):
+    q = Qry('clips/followed')
+    q.add_param(keys.TRENDING, Boolean.validate(trending), Boolean.FALSE)
+    q.add_param(keys.LIMIT, limit, 10)
+    q.add_param(keys.CURSOR, Cursor.validate(cursor), 'MA==')
+    return q

resources/lib/twitch/api/v5/__init__.py

@@ -5,6 +5,7 @@
 from twitch.api.v5 import channel_feed  # NOQA
 from twitch.api.v5 import channels  # NOQA
 from twitch.api.v5 import chat  # NOQA
+from twitch.api.v4 import clips  # NOQA
 from twitch.api.v5 import collections  # NOQA
 from twitch.api.v5 import communities  # NOQA
 from twitch.api.v5 import games  # NOQA

resources/lib/twitch/keys.py

@@ -13,6 +13,7 @@
 CHANNEL = 'channel'
 CHANNEL_FEED_ENABLED = 'channel_feed_enabled'
 CHANNEL_ID = 'channel_id'
+CLIP = 'clip'
 COLLECTION_ID = 'collection_id'
 COMMENT_ID = 'comment_id'
 COMMENTS = 'comments'
@@ -58,6 +59,7 @@
 SCE_PLATFORM = 'sce_platform'
 SHARE = 'share'
 SIG = 'sig'
+SLUG = 'slug'
 SORT = 'sort'
 SORT_BY = 'sortby'
 STATUS = 'status'
@@ -67,6 +69,7 @@
 TEAM = 'team'
 TITLE = 'title'
 TOKEN = 'token'
+TRENDING = 'trending'
 TYPE = 'type'
 USER = 'user'
 USERNAME = 'username'

resources/lib/twitch/parser.py

@@ -1,22 +1,31 @@
 # -*- encoding: utf-8 -*-
 import re
-
 from twitch.logging import log
 
 _m3u_pattern = re.compile(
-        r'#EXT-X-MEDIA:TYPE=VIDEO.*'
-        r'GROUP-ID="(?P<group_id>[^"]*)",'
-        r'NAME="(?P<group_name>[^"]*)"[,=\w]*\n'
-        r'#EXT-X-STREAM-INF:.*\n('
-        r'?P<url>http.*)')
+    r'#EXT-X-MEDIA:TYPE=VIDEO.*'
+    r'GROUP-ID="(?P<group_id>[^"]*)",'
+    r'NAME="(?P<group_name>[^"]*)"[,=\w]*\n'
+    r'#EXT-X-STREAM-INF:.*\n('
+    r'?P<url>http.*)')
+
+_clip_embed_pattern = re.compile(r'quality_options:\s*(?P<qualities>\[[^\]]+?\])')
 
 
 def m3u8(f):
     def m3u8_wrapper(*args, **kwargs):
         return m3u8_to_list(f(*args, **kwargs))
+
     return m3u8_wrapper
 
 
+def clip_embed(f):
+    def clip_embed_wrapper(*args, **kwargs):
+        return clip_embed_to_list(f(*args, **kwargs))
+
+    return clip_embed_wrapper
+
+
 def m3u8_to_dict(string):
     log.debug('m3u8_to_dict called for:\n{}'.format(string))
     d = dict()
@@ -44,3 +53,16 @@ def m3u8_to_list(string):
 
     log.debug('m3u8_to_list result:\n{}'.format(l))
     return l
+
+
+def clip_embed_to_list(string):
+    log.debug('clip_embed_to_list called for:\n{}'.format(string))
+    match = re.search(_clip_embed_pattern, string)
+    l = list()
+    if match:
+        match = eval(match.group('qualities'))
+        l = [(item['quality'], item['source']) for item in match]
+        l.insert(0, ('Source', l[0][1]))
+
+    log.debug('clip_embed_to_list result:\n{}'.format(l))
+    return l

resources/lib/twitch/queries.py

@@ -11,7 +11,9 @@
 _kraken_baseurl = 'https://api.twitch.tv/kraken/'
 _hidden_baseurl = 'https://api.twitch.tv/api/'
 _usher_baseurl = 'https://usher.ttvnw.net/'
+_clips_baseurl = 'https://clips.twitch.tv/'
 
+_v4_headers = {'ACCEPT': 'application/vnd.twitchtv.v4+json'}
 _v5_headers = {'ACCEPT': 'application/vnd.twitchtv.v5+json'}
 
 
@@ -72,8 +74,8 @@ def add_urlkw(self, kw, replacement):
         return self
 
     def __str__(self):
-        return '{method} Query to {url}, params {params}, data {data},  headers {headers}'.format(
-                url=self.url, params=self.params, headers=self.headers, data=self.data, method=self.method)
+        return '{method} Query to {url}, params {params}, data {data},  headers {headers}'\
+            .format(url=self.url, params=self.params, headers=self.headers, data=self.data, method=self.method)
 
     def execute(self, f):
         try:
@@ -121,6 +123,17 @@ def __init__(self, path, headers={}, data={}, method=methods.GET):
         self.add_path(path)
 
 
+class ClipsQuery(DownloadQuery):
+    def __init__(self, path, headers={}, data={}, method=methods.GET):
+        super(ClipsQuery, self).__init__(_clips_baseurl, headers, data, method)
+        self.add_path(path)
+
+
+class V4Query(ApiQuery):
+    def __init__(self, path, method=methods.GET):
+        super(V4Query, self).__init__(path, _v4_headers, method=method)
+
+
 class V5Query(ApiQuery):
     def __init__(self, path, method=methods.GET):
         super(V5Query, self).__init__(path, _v5_headers, method=method)
@@ -129,19 +142,18 @@ def __init__(self, path, method=methods.GET):
 def assert_new(d, k):
     if k in d:
         v = d.get(k)
-        raise ValueError("Key '{}' already set to '{}'".format(
-                         k, v))
+        raise ValueError("Key '{}' already set to '{}'".format(k, v))
 
 
 # TODO maybe rename
 def query(f):
     def wrapper(*args, **kwargs):
         qry = f(*args, **kwargs)
         if not isinstance(qry, _Query):
-            raise ValueError('{} did not return a Query, was: {}'.format(
-                             f.__name__, repr(qry)))
+            raise ValueError('{} did not return a Query, was: {}'.format(f.__name__, repr(qry)))
         log.debug('%s QUERY: url: %s, params: %s, data: %s, '
                   'headers: %r, target_func: %r',
                   qry.method, qry.url, qry.params, qry.data, qry.headers, f.__name__)
         return qry.execute()
+
     return wrapper