diff --git a/README.rst b/README.rst index 855396f8..9b5d120a 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,6 @@ Python YouTube -A Python wrapper around for YouTube Data API V3. +A Python wrapper for the YouTube Data API V3. .. image:: https://github.com/sns-sdks/python-youtube/workflows/Test/badge.svg :target: https://github.com/sns-sdks/python-youtube/actions @@ -21,17 +21,17 @@ THANKS Inspired by `Python-Twitter `_. -Thanks a lot for Python-Twitter Developers. +Thanks a lot to Python-Twitter Developers. ============ Introduction ============ -Library provides an easy way to use YouTube Data API V3. +This library provides an easy way to use the YouTube Data API V3. .. - Recently, we are working on the new structure for the library. `Read docs `_ to get more detail. + We have recently been working on the new structure for the library. `Read docs `_ to get more detail. ============= Documentation @@ -56,21 +56,21 @@ You can install this lib from PyPI: Using ===== -Now, the library covers all resource methods, including ``insert``,``update`` and so on. +The library covers all resource methods, including ``insert``,``update``, and so on. -Currently, we recommend using ``pyyoutube.Client`` to operate DATA API. It has more features. +We recommend using the ``pyyoutube.Client`` to operate DATA API. It is more modern and feature rich than ``pyyoutube.Api``. Work with Client ---------------- -You can just initialize with an api key: +You can initialize with an api key: .. code-block:: python >>> from pyyoutube import Client >>> client = Client(api_key="your api key") -If you want to get some authorization data. you need to initialize with an access token: +To access additional data that requires authorization, you need to initialize with an access token: .. code-block:: python @@ -79,7 +79,7 @@ If you want to get some authorization data. you need to initialize with an acces You can read the docs to see how to get an access token. -Or you can ask for user to do oauth flow: +Or you can ask for user to do OAuth: .. code-block:: python @@ -104,14 +104,14 @@ Get channel detail: ... } -To get more usage to see our `client docs `_, or `client examples `_ +See the `client docs `_, or `client examples `_, for additional usage Work with API ---------------- .. - We still support the old way for the sake of compatibility with older users. + For compatibility with older code, we continue to support the old way. You can just initialize with an api key: @@ -120,7 +120,7 @@ You can just initialize with an api key: >>> from pyyoutube import Api >>> api = Api(api_key="your api key") -If you want to get some authorization data. you need to initialize with an access token: +To access additional data that requires authorization, you need to initialize with an access token: .. code-block:: python @@ -129,7 +129,7 @@ If you want to get some authorization data. you need to initialize with an acces You can read the docs to see how to get an access token. -Or you can ask for user to do oauth flow: +Or you can ask for user to do OAuth flow: .. code-block:: python @@ -184,4 +184,4 @@ Get channel detail: ... } -To get more usage to see our `api docs `_, or `api examples `_ +See the `api docs `_, or `api examples `_, for additional usage. diff --git a/docs/docs/authorization.md b/docs/docs/authorization.md index 8d38f6ec..147071be 100644 --- a/docs/docs/authorization.md +++ b/docs/docs/authorization.md @@ -1,20 +1,20 @@ -If you want to get some more data for your channel. You need provide the authorization first. +If you want to get more data for your channel, You need provide the authorization. -So, this doc show how to do authorize. +This doc shows how to authorize a client. ## Prerequisite -At the beginning. You must know what is authorization. +To begin with, you must know what authorization is. You can see some information at the [Official Documentation](https://developers.google.com/youtube/v3/guides/authentication). -Then you need have an app with the [Access scopes](https://developers.google.com/youtube/v3/guides/auth/server-side-web-apps#identify-access-scopes) approval by YouTube. +You will need to create an app with [Access scope](https://developers.google.com/youtube/v3/guides/auth/server-side-web-apps#identify-access-scopes) approval by YouTube. -If everything goes well. Now let do a simple authorize with `Python-Youtube` library. +Once complete, you will be able to do a simple authorize with `Python-Youtube` library. ## Get authorization url -Suppose now we want to get user's permission to manage his youtube account. +Suppose now we want to get user's permission to manage their YouTube account. For the `Python-YouTube` library, the default scopes are: @@ -23,11 +23,11 @@ For the `Python-YouTube` library, the default scopes are: You can get more scope information at [Access scopes](https://developers.google.com/youtube/v3/guides/auth/server-side-web-apps#identify-access-scopes). -And We set the default redirect url is `https://localhost/`. +(The defailt redirect URI used in PyYoutube is `https://localhost/`) -Now we can begin do the follows step. +We can now perform the following steps: -Initialize the api instance with you app credentials +Initialize the api instance with your app credentials ``` In [1]: from pyyoutube import Client @@ -40,46 +40,47 @@ Out[3]: 'PyYouTube') ``` -Now you get the authorization url, you just need copy the link, and open browser to paste the link, click the enter bar. +Open your broswer of choice and copy the link returned by `get_authorize_url()` into the searchbar. ## Do authorization -If you enter the url. you will see this. +On entering the URL, you will see the following: ![auth-1-chose-account](images/auth-1-chose-account.png) -Now you need to chose or enter you google account with youtube. +Select the account to authorize your app to read data from. -If your app have not got the approval from youtube. You will get an warning from youtube. If you have been approved, you will -see the next image show directly. +If your app is not approved for use, you will recieve a warning. You can prevent this by adding your chosen Google account as a test member on your created OAuth application. +Otherwise, you will see the following: ![auth-2-not-approval](images/auth-2-not-approval.png) -For now, you need to click the button ``Advanced``, then click the ``Go to Python-YouTube (unsafe)``. +You will need to click ``Advanced``, then click the ``Go to Python-YouTube (unsafe)``. ![auth-3-advanced](images/auth-3-advanced.png) -Now you can get a window to give permissions. +You should now see a window to select permissions granted to the application. ![auth-4-allow-permission](images/auth-4-allow-permission.png) -click the blue button `allow` to give the permission. +Click `allow` to give the permission. -Then you will get a Connection Error, don't worry. This just because we set the redirect link to `localhost`. +You will see a Connection Error, as the link is redirecting to `localhost`. This is standard behaviour, so don't close the window or return to a previous page! ## Retrieve access token -Now you need to copy the full url in the browser address bar. Then back to you console. +Copy the full redicted URL from the browser address bar, and return to your original console. ``` -In [4]: token = cli.generate_access_token(authorization_response="the whole url") +In [4]: token = cli.generate_access_token(authorization_response="$redirect_url") In [5]: token Out[5]: AccessToken(access_token='access token', expires_in=3600, token_type='Bearer') ``` +(Replace `$redirect_url` with the URL you copied) -now you have got your access token to visit your self data. +You now have an access token to view your account data. ## Get your data @@ -97,4 +98,4 @@ Out[7]: !!! note "Tips" - If you have some confuse. you need to read the [Authorize Requests](https://developers.google.com/youtube/v3/guides/authentication) first. + If you are confused, it is beneficial to read the [Authorize Requests](https://developers.google.com/youtube/v3/guides/authentication) guide first. diff --git a/docs/docs/getting_started.md b/docs/docs/getting_started.md index 906c77eb..8c4fa7b9 100644 --- a/docs/docs/getting_started.md +++ b/docs/docs/getting_started.md @@ -1,44 +1,44 @@ -This doc is a simple tutorial to show how to use this library to get data from YouTube DATA API. +This document is a simple tutorial to show how to use this library to get data from YouTube data API. -You can get the whole description for YouTube API at [YouTube API Reference](https://developers.google.com/youtube/v3/docs/). +You can get the whole description for the YouTube API at [YouTube API Reference](https://developers.google.com/youtube/v3/docs/). ## Prerequisite -At the beginning. You need to create a [Google Project](https://console.cloud.google.com) by your google account. +To begin, you need to create a [Google Project](https://console.cloud.google.com) with your google account. -Every new account has 12 project to cost. +Every new account has a free quota of 12 projects. ## Create your project -Click the `Select a project-> NEW PROJECT` to create a new project to use our library. +Click `Select a project-> NEW PROJECT` to create a new project to use our library. -Fill the basic info to finish created. +Fill in the basic info and create the project. ![gt-create-app-1](images/gt-create-app-1.png) ## Enable YouTube DATA API service -Once the project created, the browser will redirect project home page. +Once the project created, the browser will redirect you to the project home page. -Then click the `≡≡` symbol on the left top. Chose the `APIs & Services` tab. +Click the `≡≡` symbol on the top left and select the `APIs & Services` tab. -You will see follow info. +You will see following info: ![gt-create-app-2](images/gt-create-app-2.png) -Click the `+ ENABLE APIS AND SERVICES` symbol. And input `YouTube DATA API` to search. +Click the `+ ENABLE APIS AND SERVICES` symbol, and input `YouTube DATA API` to search. ![gt-create-app-3](images/gt-create-app-3.png) -Then chose the ``YouTube DATA API`` item. +Chose the ``YouTube DATA API`` item. ![gt-create-app-4](images/gt-create-app-4.png) -Then click the `ENABLE` blue button. Now the service has been activated. +Then click the `ENABLE` blue button. After a short period where the API is added to your project, the service will be activated. ## Create credentials -To use this API, you may need credentials. Click 'Create credentials' to get started. +To use this API, you need credentials. Click `Create credentials` to get started. ![gt-create-app-5](images/gt-create-app-5.png) @@ -50,9 +50,9 @@ Then click the blue button `What credentials do I need?` to create. ![gt-create-app-6](images/gt-create-app-6.png) -Now you have generated one api key. +You have now generated an api key. -Use this key. You can retrieve public data for YouTube data by our library +Using this key, you can retrieve public YouTube data with our library ```python from pyyoutube import Client @@ -60,10 +60,10 @@ from pyyoutube import Client cli = Client(api_key="your api key") ``` -If you want to get some examples to see, check out the [examples](https://github.com/sns-sdks/python-youtube/tree/master/examples). +Check out the [examples](https://github.com/sns-sdks/python-youtube/tree/master/examples) directory for some examples of using the library. -If you have an opens source application using python-youtube, send me a link, and I am very happy to add a link to it here. +If you have an open source application using python-youtube, send me a link. I am very happy to add a link to it here. -But if you want to get user data by OAuth. You need create the credential for ``OAuth client ID``. +If you want to get user data by OAuth. You need create the credential for ``OAuth client ID``. -And get more info at next page for [Authorization](authorization.md). +You will find more information on OAth at the [Authorization](authorization.md) page. diff --git a/docs/docs/index.md b/docs/docs/index.md index 0e541a58..e8663acc 100644 --- a/docs/docs/index.md +++ b/docs/docs/index.md @@ -13,7 +13,7 @@ Use the API to upload videos, manage playlists and subscriptions, update channel This library provides a Python interface for the [YouTube DATA API](https://developers.google.com/youtube/v3). -Library could work on Python 3.6+. +This library has works on all Python versions 3.6 and newer. !!! tip "Tips" diff --git a/docs/docs/installation.md b/docs/docs/installation.md index 19b25016..16f5c8e1 100644 --- a/docs/docs/installation.md +++ b/docs/docs/installation.md @@ -17,7 +17,7 @@ $ pip install --upgrade python-youtube ``` -Also, you can build this library from source code +You can also build this library from source ```shell $ git clone https://github.com/sns-sdks/python-youtube.git @@ -28,8 +28,8 @@ $ make build ## Testing -If you have been installing the requirements use ``make env``. -You can use following command to test the code +Run `make env` after you have installed the project requirements. +Once completed, you can run code tests with ```shell $ make tests-html diff --git a/docs/docs/introduce-new-structure.md b/docs/docs/introduce-new-structure.md index 594641ca..701ab800 100644 --- a/docs/docs/introduce-new-structure.md +++ b/docs/docs/introduce-new-structure.md @@ -2,12 +2,12 @@ This doc will show you the new api structure for this library. ## Brief -To make the package easier to maintain and easy to use. We are shifted to using classes for different YouTube resources in an easier, higher-level programming experience. +To make the package easier to maintain and easy to use. We have shifted to using classes for different YouTube resources in an easier, higher-level, programming experience. ![structure-uml](images/structure-uml.png) -In this structure, every resource will have self class. And to operate with YouTube API. +In this structure, every resource has a self class. ## Simple usage diff --git a/docs/docs/usage/work-with-api.md b/docs/docs/usage/work-with-api.md index e1d3e6c2..1d2070dc 100644 --- a/docs/docs/usage/work-with-api.md +++ b/docs/docs/usage/work-with-api.md @@ -2,7 +2,7 @@ !!! note "Tips" - This is previous version to operate YouTube DATA API. + This is the previous version to operate YouTube DATA API. We recommend using the latest version of methods to operate YouTube DATA API. @@ -10,7 +10,7 @@ The API is exposed via the ``pyyoutube.Api`` class. ## INSTANTIATE -There provide two method to create instance the ``pyyoutube.Api``. +We provide two method to create instances of the ``pyyoutube.Api``. You can just initialize with an api key. @@ -20,7 +20,7 @@ You can just initialize with an api key. >>> api = Api(api_key="your api key") ``` -If you want to get some authorization data. you need to initialize with access token. +If you want to get authorization data, you will need to initialize with an access token. ``` >>> from pyyoutube import Api @@ -30,7 +30,7 @@ If you want to get some authorization data. you need to initialize with access t You can read the docs to see how to get an access token. -Or you can ask for user to do oauth flow: +Or you can ask for the user to do oauth flow: ``` >>> from pyyoutube import Api @@ -51,9 +51,9 @@ Now you can use the instance to get data from YouTube. ### CHANNEL DATA -The library provides several ways to get channel's data. +The library provides several ways to get a channels data. -If a channel is not found, the property ``items`` will return with blank list. +If a channel is not found, the property ``items`` will return an empty list. You can use channel id: @@ -88,8 +88,9 @@ You can use channel id: } ``` -You can pass a channel id with comma-separated id string or a list, tuple or set of ids to get multiple channels. -Many methods also provide this functionality. +To get multiple channels, you can pass any of: a string containing comma-seperated ids; or an enumarable (list, tuple, or set) of ids + +Many other methods also provide this functionality. with ids: @@ -100,7 +101,7 @@ with ids: Channel(kind='youtube#channel', id='UCa-vrCLQHviTOVnEKDOdetQ')] ``` -You can also use channel name: +You can also use a channel name: ``` >>> channel_by_username = api.get_channel_info(for_username="GoogleDevelopers") @@ -108,7 +109,7 @@ You can also use channel name: Channel(kind='youtube#channel', id='UC_x5XG1OV2P6uZZ5FSM9Ttw') ``` -If you have authorized, you can get your channels: +If you have authorized your client, you can get your channels directly: ``` >>> channel_by_mine = api_with_authorization.get_channel_info(mine=True) @@ -122,7 +123,7 @@ Channel(kind='youtube#channel', id='UCa-vrCLQHviTOVnEKDOdetQ') ### PLAYLIST -There are methods to get playlists by playlist id, channel id or get your own playlists. +There are methods to get playlists by playlist id, channel id, or get your own playlists. Get playlists by id: @@ -132,7 +133,7 @@ Get playlists by id: [Playlist(kind='youtube#playlist', id='PLOU2XLYxmsIKpaV8h0AGE05so0fAwwfTw')] ``` -Get playlists by channel (If you want to get all playlists for the target channel's , just provide the +Get playlists by channel (If you want to get all playlists for the target channels, provide the parameter `count=None`): ``` @@ -145,7 +146,7 @@ parameter `count=None`): Playlist(kind='youtube#playlist', id='PLOU2XLYxmsIJ8ItHmK4bRlY4GCzMgXLAJ')] ``` -Get your playlists(this requires authorization): +Get your playlists (this requires authorization): ``` >>> playlists_by_mine = api.get_playlists(mine=True) @@ -165,7 +166,7 @@ Get playlist items by id: [PlaylistItem(kind='youtube#playlistItem', id='UExPVTJYTFl4bXNJS3BhVjhoMEFHRTA1c28wZkF3d2ZUdy41NkI0NEY2RDEwNTU3Q0M2')] ``` -Get playlist items by playlist id (If you want to get target playlist all items, just provide the +Get playlist items by playlist id (If you want to get return all items in a playlist, provide the parameter `count=None`): ``` @@ -204,7 +205,7 @@ Get videos by chart (If you want to get all videos, just provide the parameter ` Video(kind='youtube#video', id='hDeuSfo_Ys0')] ``` -Get videos by your rating (this requires authorization, also if you want to get all videos, just provide the +Get videos by your rating (this requires authorization. If you also want to get all videos, provide the parameter `count=None`): ``` @@ -213,7 +214,7 @@ parameter `count=None`): ### COMMENT THREAD -You can get comment thread information by id or some filter. +You can get comment thread information by id or by a filter. Get comment thread by id(s): @@ -226,8 +227,8 @@ Get comment thread by id(s): CommentThread(kind='youtube#commentThread', id='UgzhytyP79_PwaDd4UB4AaABAg')] ``` -Get all comment threads related to a channel (including comment threads for the channel's video, also if you want to get -all comment threads, just provide the parameter `count=None`): +Get all comment threads related to a channel (including comment threads for the channel's video. If you want to get +all comment threads, provide the parameter `count=None`): ``` >>> ct_by_all = api.get_comment_threads(all_to_channel_id="UC_x5XG1OV2P6uZZ5FSM9Ttw", count=2) @@ -237,7 +238,7 @@ all comment threads, just provide the parameter `count=None`): CommentThread(kind='youtube#commentThread', id='UgyvoQJ2LsxCBwGEpMB4AaABAg')] ``` -Get comment threads only for the channel (If you want to get all comment threads, just provide the +Get comment threads only for the channel (If you want to get all comment threads, provide the parameter `count=None`): ``` @@ -248,7 +249,7 @@ parameter `count=None`): CommentThread(kind='youtube#commentThread', id='Ugzi3lkqDPfIOirGFLh4AaABAg')] ``` -Get comment threads only for the video (If you want to get all comment threads, just provide the +Get comment threads only for the video (If you want to get all comment threads, provide the parameter `count=None`): ``` @@ -318,10 +319,10 @@ You can get subscription information by id, by point channel, or your own. !!! note "Tips" - 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). + If you want to get the non-public subscriptions, you need to authorize and obtain the access token first. + See the demo [A demo for get my subscription](examples/subscription.py). -To get subscription info by id(s), this needs your token to have the permission for the subscriptions belonging to a +To get subscription info by id(s), your token needs to have the permission for the subscriptions belonging to a channel or user: ``` @@ -336,7 +337,7 @@ SubscriptionListResponse(kind='youtube#subscriptionListResponse') Subscription(kind='youtube#subscription', id='zqShTXi-2-Rya5uUxEp3ZsPI3fZrFQnSXNQCwvHBGGo', snippet=SubscriptionSnippet(title='ikaros-life', description='This is a test channel.'))] ``` -Get your own subscriptions, this need you do authorization first or give the authorized access token: +Get your own subscriptions, you need to authorize first, and supply the token: ``` >>> r = api.get_subscription_by_me( @@ -351,7 +352,7 @@ SubscriptionListResponse(kind='youtube#subscriptionListResponse') Subscription(kind='youtube#subscription', id='zqShTXi-2-Tx7TtwQqhCBwViE_j9IEgnmRmPnqJljxo', snippet=SubscriptionSnippet(title='PyCon 2015', description=''))] ``` -Get public channel's subscriptions: +Get public channel subscriptions: ``` >>> r = api.get_subscription_by_channel( @@ -413,7 +414,7 @@ CaptionListResponse(kind='youtube#captionListResponse') ### CHANNEL SECTIONS -You can get channel sections by self id or belonged channel id or your own channel. +You can get channel sections by channel id, section id, or your own channel. Get channel sections by channel id: @@ -517,7 +518,7 @@ You can retrieve a list of reasons that can be used to report abusive videos: ### SEARCH -You can use those methods to search the video,playlist,channel data. For more info, you can see +You can use those methods to search the video, playlist, or channel data. For more info, you can see the [Search Request Docs](https://developers.google.com/youtube/v3/docs/search/list). You can search different type of resource with keywords: diff --git a/docs/docs/usage/work-with-client.md b/docs/docs/usage/work-with-client.md index 3e2adffc..a2d95826 100644 --- a/docs/docs/usage/work-with-client.md +++ b/docs/docs/usage/work-with-client.md @@ -20,7 +20,7 @@ from pyyoutube import Client cli = Client(api_key="your api key") ``` -If you want to update your channel data. or upload video. You need initialize with `access token`, Or do auth flow. +If you want to update your channel data. or upload video. You need to initialize with `access token`, or do the auth flow. ```python from pyyoutube import Client @@ -47,7 +47,7 @@ Only `web` and some `installed` type client_secrets are supported. The fields `client_id` and `client_secret` must be set. -If the field `redirect_uris` has 1 or more values set, the `Client.DEFAULT_REDIRECT_URI` will be set to the first entrie. +`Client.DEFAULT_REDIRECT_URI` will be set the first entry of the field `redirect_uris`. ```python from pyyoutube import Client @@ -58,13 +58,13 @@ cli = Client(client_secret_path=file_path) # Then go through auth flow descriped above ``` -Once initialize client. Then you can operate API to get data. +Once initialize to the client, you can operate the API to get data. ## Usage ### Channel Resource -The API supports the following methods for `channels` resources: +The API supports the following methods for the `channels` resources: - list: Returns a collection of zero or more channel resources that match the request criteria. - update: Updates a channel's metadata. Note that this method currently only supports updates to the channel resource's diff --git a/examples/README.md b/examples/README.md index 6d6f8401..e5a753a7 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,9 +1,9 @@ # Examples -Now we provide two entry for operate YouTube DATA API. +We provide two entry points to operate the YouTube DATA API. -- Use Api `from pyyoutube import Api`: This is an old implementation used to be compatible with older versions of code. -- Use Client `from pyyoutube import Client`: This is a new implementation for operating the API and provides additional +- Api `from pyyoutube import Api`: This is an old implementation used to be compatible with older versions of code. +- Client `from pyyoutube import Client`: This is a new implementation for operating the API and provides additional capabilities. # Basic Usage @@ -18,7 +18,7 @@ api.get_channel_info(channel_id="id for channel") # ChannelListResponse(kind='youtube#channelListResponse') ``` -You can get more examples at [this](/examples/apis/). +You can get more examples at [api examples](/examples/apis/). ## Client @@ -30,4 +30,4 @@ cli.channels.list(channel_id="UC_x5XG1OV2P6uZZ5FSM9Ttw") # ChannelListResponse(kind='youtube#channelListResponse') ``` -You can get more examples at [this](/examples/clients/). +You can get more examples at [client examples](/examples/clients/).