refactor v5

- clean up endpoints
- clean up variable naming
- refactor methods adding validation
- add StreamType and BroadcastType parameters for validation
- add comments for v5 documentation

Author: anxdpanic

resources/lib/twitch/api/parameters.py

@@ -38,3 +38,19 @@ class SortBy(_Parameter):
     LOGIN = 'login'
 
     _valid = [CREATED_AT, LAST_BROADCAST, LOGIN]
+
+
+class BroadcastType(_Parameter):
+    ARCHIVE = 'archive'
+    HIGHLIGHT = 'highlight'
+    UPLOAD = 'upload'
+
+    _valid = [ARCHIVE, HIGHLIGHT, UPLOAD]
+
+
+class StreamType(_Parameter):
+    LIVE = 'live'
+    PLAYLIST = 'playlist'
+    ALL = 'all'
+
+    _valid = [LIVE, PLAYLIST, ALL]

resources/lib/twitch/api/usher.py

@@ -18,16 +18,16 @@ def channel_token(channel):
 
 
 @query
-def vod_token(id):
+def vod_token(video_id):
     q = HiddenApiQuery('vods/{vod}/access_token')
-    q.add_urlkw(keys.VOD, id)
+    q.add_urlkw(keys.VOD, video_id)
     return q
 
 
 @query
-def _legacy_video(id):
+def _legacy_video(video_id):
     q = HiddenApiQuery('videos/{id}')
-    q.add_urlkw(keys.ID, id)
+    q.add_urlkw(keys.ID, video_id)
     return q
 
 
@@ -46,23 +46,26 @@ def live(channel):
 
 @m3u8
 @query
-def _vod(id):
-    id = id[1:]
+def _vod(video_id):
+    video_id = video_id[1:]
 
-    token = vod_token(id)
+    token = vod_token(video_id)
 
     q = UsherQuery('vod/{id}')
-    q.add_urlkw(keys.ID, id)
+    q.add_urlkw(keys.ID, video_id)
     q.add_param(keys.NAUTHSIG, token[keys.SIG])
     q.add_param(keys.NAUTH, token[keys.TOKEN])
     q.add_param(keys.ALLOW_SOURCE, Boolean.TRUE)
     return q
 
 
-def video(id):
-    if id.startswith('v'):
-        return _vod(id)
-    elif id.startswith(('a', 'c')):
-        return _legacy_video(id)
+def video(video_id):
+    if video_id.startswith('videos'):
+        video_id = 'v' + video_id[6:]
+        return _vod(video_id)
+    elif video_id.startswith('v'):
+        return _vod(video_id)
+    elif video_id.startswith(('a', 'c')):
+        return _legacy_video(video_id)
     else:
         raise NotImplementedError('Unknown Video Type')

resources/lib/twitch/api/v3/blocks.py

@@ -6,19 +6,19 @@
 from twitch.queries import query
 
 
-# Needs Authentification
+# Needs Authentication
 @query
 def by_name(user):
     raise NotImplementedError
 
 
-# Needs Authentification, needs PUT
+# Needs Authentication, needs PUT
 @query
 def add_block(user, target):
     raise NotImplementedError
 
 
-# Needs Authentification, needs DELETE
+# Needs Authentication, needs DELETE
 @query
 def del_block(user, target):
     raise NotImplementedError

resources/lib/twitch/api/v3/channels.py

@@ -31,7 +31,7 @@ def editors(name):
     raise NotImplementedError
 
 
-# TODO needs authentification and put requests
+# TODO needs Authentication and put requests
 @query
 def update(name, status=None, game=None, delay=0):
     raise NotImplementedError

resources/lib/twitch/api/v3/subscriptions.py

@@ -7,19 +7,19 @@
 from twitch.queries import query
 
 
-# Needs Authentification
+# Needs Authentication
 @query
 def by_channel(channel, limit=25, offset=0, direction=Direction.ASC):
     raise NotImplementedError
 
 
-# Needs Authentification
+# Needs Authentication
 @query
 def channel_to_user(channel, user):
     raise NotImplementedError
 
 
-# Needs Authentification
+# Needs Authentication
 @query
 def user_to_channel(user, channel):
     raise NotImplementedError

resources/lib/twitch/api/v3/users.py

@@ -15,19 +15,19 @@ def by_name(name):
     return q
 
 
-# Needs Authentification
+# Needs Authentication
 @query
 def user():
     raise NotImplementedError
 
 
-# Needs Authentification
+# Needs Authentication
 @query
 def streams():
     raise NotImplementedError
 
 
-# Needs Authentification
+# Needs Authentication
 @query
 def videos():
     raise NotImplementedError

resources/lib/twitch/api/v3/videos.py

@@ -4,17 +4,17 @@
 # https://dev.twitch.tv/docs/v3/reference/videos/
 
 from twitch import keys
-from twitch.api.parameters import Boolean, Period
+from twitch.api.parameters import Boolean, BroadcastType, Period
 from twitch.queries import V3Query as Qry
 from twitch.queries import query
 
 from .users import videos
 
 
 @query
-def by_id(identification):
+def by_id(video_id):
     q = Qry('videos/{id}')
-    q.add_urlkw(keys.ID, identification)
+    q.add_urlkw(keys.ID, video_id)
     return q
 
 
@@ -30,12 +30,12 @@ def top(limit=10, offset=0, game=None, period=Period.WEEK):
 
 @query
 def by_channel(name, limit=10, offset=0,
-               broadcast_type=keys.ARCHIVE, hls=Boolean.FALSE):
+               broadcast_type=BroadcastType.ARCHIVE, hls=Boolean.FALSE):
     q = Qry('channels/{channel}/videos')
     q.add_urlkw(keys.CHANNEL, name)
     q.add_param(keys.LIMIT, limit, 10)
     q.add_param(keys.OFFSET, offset, 0)
-    q.add_param(keys.BROADCAST_TYPE, broadcast_type, keys.ARCHIVE)
+    q.add_param(keys.BROADCAST_TYPE, BroadcastType.validate(broadcast_type), BroadcastType.ARCHIVE)
     q.add_param(keys.HLS, Boolean.validate(hls), Boolean.FALSE)
     return q
 

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

@@ -1,14 +1,11 @@
 # -*- encoding: utf-8 -*-
-# https://github.com/justintv/Twitch-API/blob/master/v3_resources/
+# https://dev.twitch.tv/docs/
 
-from twitch.api.v5 import blocks  # NOQA
 from twitch.api.v5 import channels  # NOQA
-from twitch.api.v5 import follows  # NOQA
 from twitch.api.v5 import games  # NOQA
 from twitch.api.v5 import ingests  # NOQA
 from twitch.api.v5 import search  # NOQA
 from twitch.api.v5 import streams  # NOQA
-from twitch.api.v5 import subscriptions  # NOQA
 from twitch.api.v5 import teams  # NOQA
 from twitch.api.v5 import users  # NOQA
 from twitch.api.v5 import videos  # NOQA

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

@@ -1,17 +1,16 @@
 # -*- encoding: utf-8 -*-
-# https://github.com/justintv/Twitch-API/blob/master/v3_resources/channels.md
+# https://dev.twitch.tv/docs/v5/reference/channels/
 
 from twitch import keys
 from twitch.queries import V5Query as Qry
 from twitch.queries import query
-
-from .videos import by_channel
+from twitch.api.parameters import Boolean, BroadcastType, Direction
 
 
 @query
-def by_name(name):
-    q = Qry('channels/{channel}')
-    q.add_urlkw(keys.CHANNEL, name)
+def by_id(channel_id):
+    q = Qry('channels/{id}')
+    q.add_urlkw(keys.ID, channel_id)
     return q
 
 
@@ -20,16 +19,12 @@ def channel():
     raise NotImplementedError
 
 
-def get_videos(name, **kwargs):
-    return by_channel(name, **kwargs)
-
-
 @query
 def editors(name):
     raise NotImplementedError
 
 
-# TODO needs authentification and put requests
+# TODO needs Authentication and put requests
 @query
 def update(name, status=None, game=None, delay=0):
     raise NotImplementedError
@@ -48,7 +43,41 @@ def commercial(name, length=30):
 
 
 @query
-def teams(name):
-    q = Qry('channels/{channel}/teams')
-    q.add_urlkw('channel', name)
+def teams(channel_id):
+    q = Qry('channels/{id}/teams')
+    q.add_urlkw(keys.ID, channel_id)
+    return q
+
+
+@query
+def followers(channel_id, limit=25, offset=0, direction=Direction.DESC):
+    q = Qry('channels/{id}/follows')
+    q.add_urlkw(keys.ID, channel_id)
+    q.add_param(keys.LIMIT, limit, 25)
+    q.add_param(keys.OFFSET, offset, 0)
+    q.add_param(keys.DIRECTION, direction, Direction.DESC)
+    return q
+
+
+# Needs Authentication
+@query
+def subscribers(channel_id, limit=25, offset=0, direction=Direction.ASC):
+    raise NotImplementedError
+
+
+# Needs Authentication
+@query
+def subscription_status(channel_id, user_id):
+    raise NotImplementedError
+
+
+@query
+def videos(channel_id, limit=10, offset=0,
+           broadcast_type=BroadcastType.ARCHIVE, hls=Boolean.FALSE):
+    q = Qry('channels/{id}/videos')
+    q.add_urlkw(keys.ID, channel_id)
+    q.add_param(keys.LIMIT, limit, 10)
+    q.add_param(keys.OFFSET, offset, 0)
+    q.add_param(keys.BROADCAST_TYPE, BroadcastType.validate(broadcast_type), BroadcastType.ARCHIVE)
+    q.add_param(keys.HLS, Boolean.validate(hls), Boolean.FALSE)
     return q