Permalink
Browse files

updated docs

  • Loading branch information...
1 parent 4cb3051 commit c2538de98c9a4aa921cf5c14f275d58ddab0e390 @noahsilas noahsilas committed Jul 13, 2011
Showing with 245 additions and 17 deletions.
  1. +60 −0 docs/client.rst
  2. +4 −17 docs/index.rst
  3. +118 −0 docs/overview.rst
  4. +43 −0 docs/streams.rst
  5. +20 −0 docs/subscriptions.rst
View
@@ -0,0 +1,60 @@
+=================
+The Pytube Client
+=================
+
+Instantiating
+=============
+When creating a Client, you must supply an application identifier. This is
+an arbitrary string you can choose to identify the application submitting
+API requests.
+
+You may also specify a `developer key`_. This is recommended for high volume
+applications.
+
+.. _developer key: http://code.google.com/apis/youtube/dashboard/
+
+Authenticating
+==============
+Authenticating the client enables a number of actions to be taken on behalf
+of a user and may cause some API results for content that the authenticated
+user to include additional or private data.
+
+You can authenticate a client against a youtube account through google's
+ClientLogin or AuthSub::
+
+ c = pytube.Client('appid')
+ # Client Login
+ c.authenticate(channelname, password)
+
+ # Authsub Login
+ c.authenticate(authsub=token)
+
+
+Captcha Requests When Authenticating
+------------------------------------
+Sometimes google will request that you complete a captcha when authenticating
+via ClientLogin. Here is an example of how to handle this in a console-based app::
+
+ while True:
+ captcha = None
+ try:
+ c.authenticate(channelname, password, captcha)
+ break
+ except pytube.CaptchaRequired, captcha:
+ print "please solve the captcha at %s" % captcha.captcha
+ captcha.solved = raw_input('>>> ')
+
+
+pytube.CaptchaRequired has the following attributes:
+ * `token` - a unique token that must be submitted with the solved captcha
+ * `captcha` - the url of a captcha image to be solved
+
+If you don't want to store the exception, you may create an object to pass
+into authenticate from a token and a solved captcha. Anything supplying the
+attributes `token` and `solved` will work::
+
+ class SolvedCaptcha(object):
+ def __init__(self, token, solved):
+ self.token = token
+ self.solved = solved
+
View
@@ -11,20 +11,7 @@ Contents:
.. toctree::
:maxdepth: 2
-.. automodule:: pytube
-
-.. autoclass:: pytube.Client
- :members:
-
-.. autofunction:: pytube.video_id_from_youtube_url
-
-.. autoexception:: pytube.AuthenticationError
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-
+ overview
+ client
+ streams
+ subscriptions
View
@@ -0,0 +1,118 @@
+===============
+PyTube Overview
+===============
+
+PyTube is a pure python library for accessing the YouTube Data API.
+
+
+Example
+=======
+Display the 50 most recent videos from the 'mahalobaking' user::
+
+ import pytube
+ client = pytube.Client('my-app-identifier')
+ videos = client.user_videos('mahalobaking')
+ for video in videos[:50]:
+ sys.stdout.write('%s %s\n' % (video.id, video.title))
+
+
+Fetching Videos
+===============
+
+Getting a Specific Video
+------------------------
+client.video(`video_id`)
+ Gets the video with youtube id `video_id`. If the video id doesn't exist,
+ or has been deleted, this will raise `pytube.NoSuchVideoException`. If the
+ video is private and the client is not authenticated to a user with
+ permission to see it, this will raise `pytube.PrivateVideoException`.
+
+
+Getting Videos from a Channel
+-----------------------------
+client.user_videos(`username='default`)
+ Returns a video stream of videos in `username`'s channel. If the client is
+ authenticated, you may omit the username to get the authenticated user's
+ stream.
+
+
+Searching for Videos
+--------------------
+
+client.video_search(`q=None, **query`)
+ Returns a VideoStream of videos matching the query parameters.
+ You can perform a basic search very simply::
+
+ vids = c.video_search('search terms')
+
+ You can also pass any of the `parameters accepted by the gdata API`_::
+
+ vids = c.video_search(
+ category='cars|music', # category is cars or music
+ author='schmoyoho', # in schmoyoho's channel
+ orderby='published', # ordered by published date
+ safeSearch='strict', # 'moderate' and 'none' are the other safe search options
+ )
+
+.. _parameters accepted by the gdata API: http://code.google.com/apis/youtube/2.0/reference.html#Query_parameter_definitions
+
+
+Video objects
+=============
+
+Attributes
+----------
+Videos fetched from the API should have the following attributes available.
+
+* id
+* title
+* author
+* category
+* category.label
+* keywords
+* published
+* updated
+* description
+* duration
+* aspect_ratio
+* private - True if this is a private video, False otherwise
+* access_control - a dictionary mapping 'actions' to 'permissions'
+
+Possible Attributes
+-------------------
+The following attributes may not be set on video objects, depending on the
+privacy settings on the video you have fetched.
+
+* like_count
+* dislike_count
+* favorite_count
+* view_count
+* comment_count
+* uploaded - the datetime that the video was uploaded
+
+Available Streams
+-----------------
+Depending on the youtube API result, any or all of the following streams may
+be available on Video instances:
+
+Video.`related_videos`
+ A stream of videos that youtube believes are related to this video.
+
+Video.`video_responses`
+ A stream of videos that are video responses to this video.
+
+Video.`comments`
+ A stream of comments made on this video
+
+Updating A Video
+----------------
+Videos owned by a user who has authenticated this client can be updated. To
+update a video, you simply update it's attributes and then call
+Video.`update`(). The following attributes may be updated this way:
+
+* title
+* description
+* category
+* keywords
+* access_control
+* private
View
@@ -0,0 +1,43 @@
+==============
+PyTube Streams
+==============
+
+Most PyTube methods that return a collection of objects actually return a
+`Stream`. Streams have some nice properties:
+
+* Streams will perform the minimum number of API queries necessary to
+ return all of the results you have requested.
+* For some common behaviors (iterating, fetching the first N objects) the
+ stream can maintain an internal cache, allowing you to iterate the stream
+ multiple times or fetch an instance from the stream without sending
+ additional youtube API queries.
+
+Use Streams like lists
+======================
+::
+
+ videos = client.user_videos('BeyonceVEVO')
+
+ # iterate across a stream
+ for video in videos:
+ print video.title
+
+ # slice a stream
+ new_videos = videos[:10]
+ older_videos = videos[10:20]
+
+ # get one item from a stream
+ video = videos[7]
+
+
+Streams can only retrieve 1000 results
+======================================
+Due to limitations in the youtube API, streams may only return the first 1000
+results. This can lead to confusing behavior: when you ask a stream for its
+length it returns the total number of items in the collection, not the number
+of items that it will return.::
+
+ >>> len(videos)
+ 5223
+ >>> len(list(videos))
+ 1000
View
@@ -0,0 +1,20 @@
+=============
+Subscriptions
+=============
+
+Get the channels a user is subscribed to
+----------------------------------------
+Client.user_subscriptions(`username`)
+ Authenticated clients may omit the `username` parameter to fetch a stream
+ of usernames that the authenticated user is subscribed to.::
+
+ c = pytube.Client('app_id')
+ c.user_subscriptions('TheOfficialSkrillex)
+
+
+Subscribe the Authenticated User to a channel
+---------------------------------------------
+Client.subscribe(`username`)
+ Authenticated clients may call this method to subscribe to a channel.
+
+PyTube doesn't have an unsubscribe method yet. =(

0 comments on commit c2538de

Please sign in to comment.