Merge pull request #44 from sns-sdks/feat_subscription

MerleLiuKun · web-flow · commit 8cffdbf332fc · 2020-01-01T22:11:50.000+08:00
Feat subscription
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,9 +1,26 @@
 Changelog
 ---------
 
+Version 0.5.2
+=============
+
+What's New
+++++++++++
+Now you can use authorized access token to get your subscriptions.
+You can to the demo `A demo for get my subscription <examples/subscription.py>`_ to see simple usage.
+Or you can see the `subscriptions usage <README.rst#subscriptions>`_ docs.
+
+    #43 add api for get my subscriptions
+    #41 add api for channel subscriptions
+
+
+
 Version 0.5.1
 =============
 
+What's New
+++++++++++
+
 Now some apis can get all target items just by one method call.
 
 For example, you can get playlist's all items by follow call::
@@ -14,7 +31,7 @@ For example, you can get playlist's all items by follow call::
     In [3]: len(r.items)
     Out[4]: 73
 
-You can see the `README <https://github.com/sns-sdks/python-youtube/blob/master/README.rst>`_ to find which methods support this.
+You can see the `README`_ to find which methods support this.
 
 Version 0.5.0
 =============
@@ -25,7 +42,7 @@ Broken Change
 Now introduce new model ApiResponse representing the response from youtube, so previous usage has been invalidated.
 
 You need to read the docs to get more change `Modules Documentation <https://python-youtube.readthedocs.io/en/latest/pyyoutube.html#module-pyyoutube.api>`_,
-or see the `README <https://github.com/sns-sdks/python-youtube/blob/v0.5.0/README.rst>`_ to get the simple new usage.
+or see the `README`_ to get the simple new usage.
 
 What's New
 ++++++++++
@@ -35,3 +52,5 @@ Split some method into multiple usage, for example get video has been split thre
 * api.get_video_by_id()
 * api.get_videos_by_chart()
 * api.get_videos_by_myrating()
+
+.. _README: README.rst
diff --git a/README.rst b/README.rst
@@ -353,6 +353,58 @@ Get video categories with region code::
      VideoCategory(kind='youtube#videoCategory', id='15'),
      ...]
 
+-------------
+SUBSCRIPTIONS
+-------------
+
+You can get subscriptions info by id, by point channel or by yourself.
+
+.. note::
+    If you want to get the subscriptions not set to public. You need do authorization first and get the access token.
+    You can see the demo `A demo for get my subscription <examples/subscription.py>`_.
+
+Get subscriptions info by id(s), this need your token have the permission for the subscriptions belongs channel or user::
+
+    In [6]: r = api.get_subscription_by_id(
+       ...:     subscription_id=[
+       ...:         "zqShTXi-2-Tx7TtwQqhCBwViE_j9IEgnmRmPnqJljxo",
+       ...:         "zqShTXi-2-Rya5uUxEp3ZsPI3fZrFQnSXNQCwvHBGGo"])
+    In [7]: r
+    Out[7]: SubscriptionListResponse(kind='youtube#subscriptionListResponse')
+    In [8]: r.items
+    Out[8]:
+    [Subscription(kind='youtube#subscription', id='zqShTXi-2-Tx7TtwQqhCBwViE_j9IEgnmRmPnqJljxo', snippet=SubscriptionSnippet(title='PyCon 2015', description='')),
+     Subscription(kind='youtube#subscription', id='zqShTXi-2-Rya5uUxEp3ZsPI3fZrFQnSXNQCwvHBGGo', snippet=SubscriptionSnippet(title='ikaros-life', description='This is a test channel.'))]
+
+Get yourself subscriptions, this need you do authorization first or give the authorized access token::
+
+    In [9]: r = api.get_subscription_by_me(
+       ...:     mine=True,
+       ...:     parts=["id", "snippet"],
+       ...:     count=2
+       ...:)
+    In [10]: r
+    Out[10]: SubscriptionListResponse(kind='youtube#subscriptionListResponse')
+    In [11]: r.items
+    Out[11]:
+    [Subscription(kind='youtube#subscription', id='zqShTXi-2-Tx7TtwQqhCBwtJ-Aho6DZeutqZiP4Q79Q', snippet=SubscriptionSnippet(title='Next Day Video', description='')),
+     Subscription(kind='youtube#subscription', id='zqShTXi-2-Tx7TtwQqhCBwViE_j9IEgnmRmPnqJljxo', snippet=SubscriptionSnippet(title='PyCon 2015', description=''))]
+
+Get public channel's subscriptions::
+
+    In [12]: r = api.get_subscription_by_channel(
+    ...:     channel_id="UCAuUUnT6oDeKwE6v1NGQxug",
+    ...:     parts="id,snippet",
+    ...:     count=2
+    ...:     )
+    In [13]: r
+    Out[13]: SubscriptionListResponse(kind='youtube#subscriptionListResponse')
+    In [14]: r.items
+    Out[14]:
+    [Subscription(kind='youtube#subscription', id='FMP3Mleijt-52zZDGkHtR5KhwkvCcdQKWWWIA1j5eGc', snippet=SubscriptionSnippet(title='TEDx Talks', description="TEDx is an international community that organizes TED-style events anywhere and everywhere -- celebrating locally-driven ideas and elevating them to a global stage. TEDx events are produced independently of TED conferences, each event curates speakers on their own, but based on TED's format and rules.\n\nFor more information on using TED for commercial purposes (e.g. employee learning, in a film, or in an online course), please submit a media request using the link below.")),
+     Subscription(kind='youtube#subscription', id='FMP3Mleijt_ZKvy5M-HhRlsqI4wXY7VmP5g8lvmRhVU', snippet=SubscriptionSnippet(title='TED Residency', description='The TED Residency program is an incubator for breakthrough ideas. It is free and open to all via a semi-annual competitive application. Those chosen as TED Residents spend four months at TED headquarters in New York City, working on their idea. Selection criteria include the strength of their idea, their character, and their ability to bring a fresh perspective and positive contribution to the diverse TED community.'))]
+
+
 ====
 TODO
 ====
@@ -368,6 +420,7 @@ Now this has follows api.
 - Comment Info
 - Video Categories Info
 - Guide Categories Info
+- Subscriptions Info
 
 Doing
 
diff --git a/docs/models.rst b/docs/models.rst
@@ -5,13 +5,14 @@ Python-YouTube provides following models of the the objects returned by the API:
 
 * :py:class:`pyyoutube.models.AccessToken`
 * :py:class:`pyyoutube.models.UserProfile`
-* :py:class:`pyyoutube.models.Channel`
-* :py:class:`pyyoutube.models.Video`
-* :py:class:`pyyoutube.models.PlayList`
-* :py:class:`pyyoutube.models.PlaylistItem`
-* :py:class:`pyyoutube.models.Comment`
-* :py:class:`pyyoutube.models.CommentThread`
-* :py:class:`pyyoutube.models.VideoCategory`
-* :py:class:`pyyoutube.models.GuideCategory`
+* :py:class:`pyyoutube.models.ChannelListResponse`
+* :py:class:`pyyoutube.models.VideoListResponse`
+* :py:class:`pyyoutube.models.PlaylistListResponse`
+* :py:class:`pyyoutube.models.PlaylistItemListResponse`
+* :py:class:`pyyoutube.models.CommentListResponse`
+* :py:class:`pyyoutube.models.CommentThreadListResponse`
+* :py:class:`pyyoutube.models.VideoCategoryListResponse`
+* :py:class:`pyyoutube.models.GuideCategoryListResponse`
+* :py:class:`pyyoutube.models.SubscriptionListResponse`
 
 And so on.
diff --git a/examples/subscription.py b/examples/subscription.py
@@ -0,0 +1,41 @@
+"""
+    This demo show how to use this library to do authorization and get your subscription.
+"""
+
+import pyyoutube
+import webbrowser
+
+CLIENT_ID = "your app id"
+CLIENT_SECRET = "your app secret"
+
+
+def get_subscriptions():
+    api = pyyoutube.Api(client_id=CLIENT_ID, client_secret=CLIENT_SECRET)
+
+    # need follows scope
+    scope = ["https://www.googleapis.com/auth/youtube.readonly"]
+
+    url, _ = api.get_authorization_url(scope=scope)
+
+    print(
+        "Try to start a browser to visit the authorization page. If not opened. you can copy and visit by hand:\n"
+        f"{url}"
+    )
+    webbrowser.open(url)
+
+    auth_response = input(
+        "\nCopy the whole url if you finished the step to authorize:\n"
+    )
+
+    api.exchange_code_to_access_token(authorization_response=auth_response)
+
+    sub_res = api.get_subscription_by_me(mine=True, parts="id,snippet", count=None)
+
+    with open("subscriptions.json", "w+") as f:
+        f.write(sub_res.to_json())
+
+    print("Finished.")
+
+
+if __name__ == "__main__":
+    get_subscriptions()
diff --git a/pyyoutube/__version__.py b/pyyoutube/__version__.py
@@ -6,6 +6,6 @@
 # 88         YP       YP    YP   YP  `Y88P'  VP   V8P    YP     `Y88P'  ~Y8888P'    YP    ~Y8888P' Y8888P' Y88888P
 
 
-VERSION = (0, 5, 1)
+VERSION = (0, 5, 2)
 
 __version__ = ".".join(map(str, VERSION))
diff --git a/pyyoutube/api.py b/pyyoutube/api.py
@@ -56,6 +56,9 @@ class Api(object):
             >>> api.get_comments()
             >>> api.get_guide_categories()
             >>> api.get_video_categories()
+            >>> api.get_subscription_by_id()
+            >>> api.get_subscription_by_channel()
+            >>> api.get_subscription_by_me()
     """
 
     BASE_URL = "https://www.googleapis.com/youtube/v3/"
diff --git a/setup.py b/setup.py
@@ -14,7 +14,7 @@
 # Package meta-data.
 NAME = "python-youtube"
 DESCRIPTION = "A Python wrapper around for YouTube Data API."
-URL = "https://github.com/MerleLiuKun/python-youtube"
+URL = "https://github.com/sns-sdks/python-youtube"
 EMAIL = "merle.liukun@gmail.com"
 AUTHOR = "Ikaros Kun"
 REQUIRES_PYTHON = ">=3.6.0"
@@ -119,6 +119,7 @@ def run(self):
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.6",
         "Programming Language :: Python :: 3.7",
+        "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: Implementation :: CPython",
         "Programming Language :: Python :: Implementation :: PyPy",
     ],
