From: Joshua Roesslein Date: Tue, 8 Dec 2009 23:17:57 +0000 (-0600) Subject: Some more work on documentation of API and timeline methods. X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=6f25df17c7a5310ff06c5d4b1bfc6792d860f1fa;p=tweepy.git Some more work on documentation of API and timeline methods. --- diff --git a/doc/_parameters.rst b/doc/_parameters.rst new file mode 100644 index 0000000..1b47c1b --- /dev/null +++ b/doc/_parameters.rst @@ -0,0 +1,11 @@ +.. API parameters: + +.. |since_id| replace:: Returns only statuses with an ID greater than (that is, more recent than) the specified ID. +.. |max_id| replace:: Returns only statuses with an ID less than (that is, older than) or equal to the specified ID. +.. |count| replace:: Specifies the number of statuses to retrieve. +.. |page| replace:: Specifies the page of results to retrieve. Note: there are pagination limits. +.. |uid| replace:: Specifies the ID or screen name of the user. +.. |user_id| replace:: Specfies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name. +.. |screen_name| replace:: Specfies the screen name of the user. Helpful for disambiguating when a valid screen name is also a user ID. +.. |sid| replace:: The numerical ID of the status. + diff --git a/doc/api.rst b/doc/api.rst index 0e0a0e3..c576c27 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -1,5 +1,7 @@ .. _api_reference: +.. include:: _parameters.rst + API Reference ============= @@ -9,11 +11,21 @@ This page contains some basic documentation for the Tweepy module. :mod:`tweepy.api` --- Twitter API wrapper ========================================= -.. class:: API([auth_handler], [host], [search_host], [cache], [secure], [api_root], [search_root], [retry_count], [retry_delay], [retry_errors]) +.. class:: API([auth_handler=None], [host='api.twitter.com'], [search_host='search.twitter.com'], [cache=None], [secure=False], [api_root='/1'], [search_root=''], [retry_count=0], [retry_delay=0], [retry_errors=None]) This class provides a wrapper for the API as provided by Twitter. The functions provided in this class are listed below. + :param auth_handler: authentication handler to be used + :param host: general API host + :param search_host: search API host + :param cache: cache backend to use + :param secure: if True use https + :param api_root: general API path root + :param search_root: search API path root + :param retry_count: default number of retries to attempt when error occurs + :param retry_delay: number of seconds to wait between retries + :param retry_errors: which HTTP status codes to retry Timeline methods ---------------- @@ -24,9 +36,7 @@ Timeline methods set a custom user icon. The public timeline is cached for 60 seconds so requesting it more often than that is a waste of resources. - Parameters: None - - Returns: list of :class:`Status` objects + :rtype: list of :class:`Status` objects .. method:: API.home_timeline([since_id], [max_id], [count], [page]) @@ -35,9 +45,11 @@ Timeline methods authenticating user and that user's friends. This is the equivalent of /timeline/home on the Web. - Parameters: *since_id*, *max_id*, *count*, *page* - - Returns: list of :class:`Status` objects + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`Status` objects .. method:: API.friends_timeline([since_id], [max_id], [count], [page]) @@ -45,7 +57,12 @@ Timeline methods Returns the 20 most recent statuses posted by the authenticating user and that user's friends. - Parameters: *since_id*, *max_id*, *count*, *page* + + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`Status` objects Returns: list of :class:`Status` objects @@ -53,12 +70,17 @@ Timeline methods .. method:: API.user_timeline([id/user_id/screen_name], [since_id], [max_id], [count], [page]) Returns the 20 most recent statuses posted from the authenticating - user. It's also possible to request another user's timeline via the id + user or the user specified. It's also possible to request another user's timeline via the id parameter. - Parameters: *id* or *user_id* or *screen_name*, *since_id*, *max_id*, *count*, *page* - - Returns: list of :class:`Status` objects + :param id: |uid| + :param user_id: |user_id| + :param screen_name: |screen_name| + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`Status` objects .. method:: API.mentions([since_id], [max_id], [count], [page]) @@ -66,18 +88,22 @@ Timeline methods Returns the 20 most recent mentions (status containing @username) for the authenticating user. - Parameters: *since_id*, *max_id*, *count*, *page* - - Returns: list of :class:`Status` objects + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`Status` objects .. method:: API.retweeted_by_me([since_id], [max_id], [count], [page]) Returns the 20 most recent retweets posted by the authenticating user. - Parameters: *since_id*, *max_id*, *count*, *page* - - Returns: list of :class:`Status` objects + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`Status` objects .. method:: API.retweeted_to_me([since_id], [max_id], [count], [page]) @@ -85,19 +111,23 @@ Timeline methods Returns the 20 most recent retweets posted by the authenticating user's friends. - Parameters: *since_id*, *max_id*, *count*, *page* + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`Status` objects - Returns: list of :class:`Status` objects - -.. method:: API.retweets_of_me +.. method:: API.retweets_of_me([since_id], [max_id], [count], [page]) Returns the 20 most recent tweets of the authenticated user that have been retweeted by others. - Parameters: *since_id*, *max_id*, *count*, *page* - - Returns: list of :class:`Status` objects + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`Status` objects Status methods @@ -105,11 +135,10 @@ Status methods .. method:: API.get_status(id) -Returns a single status specified by the ID parameter. - -Parameters: *id* (Required) + Returns a single status specified by the ID parameter. -Returns: :class:`Status` object + :param id: |sid| + :rtype: :class:`Status` object .. method:: API.update_status(status, [in_reply_to_status_id], [lat], [long])