From: Aaron Hill Date: Tue, 18 Feb 2014 19:25:37 +0000 (-0500) Subject: Revert "Create new blank sphinx docs." X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=b57b6dfe55ae023f19a9e314804dc86dd2f2537a;p=tweepy.git Revert "Create new blank sphinx docs." This reverts commit 2162d65483de7a419ccfd65b0d0b14dfeb70ccfa. Conflicts: docs/conf.py docs/index.rst --- diff --git a/docs/.gitignore b/docs/.gitignore index 69fa449..e35d885 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1 +1 @@ -_build/ +_build diff --git a/docs/Makefile b/docs/Makefile index 11e0963..5d97e1a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -12,119 +12,88 @@ PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest help: @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: -rm -rf $(BUILDDIR)/* html: + mkdir -p $(BUILDDIR)/html $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: + mkdir -p $(BUILDDIR)/dirhtml $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - pickle: + mkdir -p $(BUILDDIR)/pickle $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: + mkdir -p $(BUILDDIR)/json $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: + mkdir -p $(BUILDDIR)/htmlhelp $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: + mkdir -p $(BUILDDIR)/qthelp $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Tweepy.qhcp" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/tweepy.qhcp" @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Tweepy.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/Tweepy" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Tweepy" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/tweepy.qhc" latex: + mkdir -p $(BUILDDIR)/latex $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - make -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." changes: + mkdir -p $(BUILDDIR)/changes $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: + mkdir -p $(BUILDDIR)/linkcheck $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." doctest: + mkdir -p $(BUILDDIR)/doctest $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/_static/.keep b/docs/_static/.keep deleted file mode 100644 index e69de29..0000000 diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..8f05a2c --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,867 @@ +.. _api_reference: + +.. include:: parameters.rst + +API Reference +============= + +This page contains some basic documentation for the Tweepy module. + + +:mod:`tweepy.api` --- Twitter API wrapper +========================================= + +.. 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], [model_factory]) + + 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 + :param model_factory: used for creating new model instances + +Timeline methods +---------------- + +.. method:: API.public_timeline() + + Returns the 20 most recent statuses from non-protected users who have + 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. + + :rtype: list of :class:`Status` objects + + +.. method:: API.home_timeline([since_id], [max_id], [count], [page]) + + Returns the 20 most recent statuses, including retweets, posted by the + authenticating user and that user's friends. This is the equivalent of + /timeline/home on the Web. + + :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]) + + Returns the 20 most recent statuses posted by the authenticating user + and that user's friends. + + + :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.user_timeline([id/user_id/screen_name], [since_id], [max_id], [count], [page]) + + Returns the 20 most recent statuses posted from the authenticating + user or the user specified. It's also possible to request another user's timeline via the id + parameter. + + :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]) + + Returns the 20 most recent mentions (status containing @username) for + the authenticating user. + + :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. + + :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]) + + Returns the 20 most recent retweets posted by the authenticating + user's friends. + + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`Status` objects + + +.. 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. + + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`Status` objects + + +Status methods +-------------- + +.. method:: API.get_status(id) + + Returns a single status specified by the ID parameter. + + :param id: |sid| + :rtype: :class:`Status` object + + +.. method:: API.update_status(status, [in_reply_to_status_id], [lat], [long], [source], [place_id]) + + Update the authenticated user's status. Statuses that are duplicates + or too long will be silently ignored. + + :param status: The text of your status update. + :param in_reply_to_status_id: The ID of an existing status that the update is in reply to. + :param lat: The location's latitude that this tweet refers to. + :param long: The location's longitude that this tweet refers to. + :param source: Source of the update. Only supported by Identi.ca. Twitter ignores this parameter. + :param id: Twitter ID of location which is listed in the Tweet if geolocation is enabled for the user. + :rtype: :class:`Status` object + + +.. method:: API.destroy_status(id) + + Destroy the status specified by the id parameter. The authenticated + user must be the author of the status to destroy. + + :param id: |sid| + :rtype: :class:`Status` object + + +.. method:: API.retweet(id) + + Retweets a tweet. Requires the id of the tweet you are retweeting. + + :param id: |sid| + :rtype: :class:`Status` object + + +.. method:: API.retweets(id[,count]) + + Returns up to 100 of the first retweets of the given tweet. + + :param id: |sid| + :param count: Specifies the number of retweets to retrieve. + :rtype: list of :class:`Status` objects + + +User methods +------------ + +.. method:: API.get_user(id/user_id/screen_name) + + Returns information about the specified user. + + :param id: |uid| + :param user_id: |user_id| + :param screen_name: |screen_name| + :rtype: :class:`User` object + + +.. method:: API.me() + + Returns the authenticated user's information. + + :rtype: :class:`User` object + + +.. method::API.friends([id/user_id/screen_name], [cursor]) + + Returns an user's friends ordered in which they were added 100 at a time. If no user is specified it defaults to the authenticated user. + + :param id: |uid| + :param user_id: |user_id| + :param screen_name: |screen_name| + :param cursor: |cursor| + :rtype: list of :class:`User` objects + + +.. method:: API.followers([id/screen_name/user_id], [cursor]) + + Returns an user's followers ordered in which they were added 100 at a + time. If no user is specified by id/screen name, it defaults to the + authenticated user. + + :param id: |uid| + :param user_id: |user_id| + :param screen_name: |screen_name| + :param cursor: |cursor| + :rtype: list of :class:`User` objects + +.. method:: API.search_users(q, [per_page], [page]) + + Run a search for users similar to Find People button on Twitter.com; + the same results returned by people search on Twitter.com will be + returned by using this API (about being listed in the People + Search). It is only possible to retrieve the first 1000 matches from + this API. + + :param q: The query to run against people search. + :param per_page: Specifies the number of statuses to retrieve. May not be greater than 20. + :param page: |page| + :rtype: list of :class:`User` objects + + +Direct Message Methods +---------------------- + +.. method:: API.direct_messages([since_id], [max_id], [count], [page]) + + Returns direct messages sent to the authenticating user. + + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`DirectMessage` objects + + +.. method:: API.sent_direct_messages([since_id], [max_id], [count], [page]) + + Returns direct messages sent by the authenticating user. + + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param page: |page| + :rtype: list of :class:`DirectMessage` objects + + +.. method:: API.send_direct_message(user/screen_name/user_id, text) + + Sends a new direct message to the specified user from the + authenticating user. + + :param user: The ID or screen name of the recipient user. + :param screen_name: screen name of the recipient user + :param user_id: user id of the recipient user + :rtype: :class:`DirectMessage` object + + +.. method:: API.destroy_direct_message(id) + + Destroy a direct message. Authenticating user must be the recipient of + the direct message. + + :param id: The ID of the direct message to destroy. + :rtype: :class:`DirectMessage` object + + +Friendship Methods +------------------ + +.. method:: API.create_friendship(id/screen_name/user_id[,follow]) + + Create a new friendship with the specified user (aka follow). + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :param follow: Enable notifications for the target user in addition to becoming friends. + :rtype: :class:`User` object + + +.. method:: API.destroy_friendship(id/screen_name/user_id) + + Destroy a friendship with the specified user (aka unfollow). + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :rtype: :class:`User` object + + +.. method:: API.exists_friendship(user_a, user_b) + + Checks if a friendship exists between two users. Will return True if + user_a follows user_b, otherwise False. + + :param user_a: The ID or screen_name of the subject user. + :param user_b: The ID or screen_name of the user to test for following. + :rtype: True/False + + +.. method:: API.show_friendship(source_id/source_screen_name, target_id/target_screen_name) + + Returns detailed information about the relationship between two users. + + :param source_id: The user_id of the subject user. + :param source_screen_name: The screen_name of the subject user. + :param target_id: The user_id of the target user. + :param target_screen_name: The screen_name of the target user. + :rtype: :class:`Friendship` object + + +.. method:: API.friends_ids(id/screen_name/user_id[,cursor]) + + Returns an array containing the IDs of users being followed by the + specified user. + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :param cursor: |cursor| + :rtype: list of Integers + + +.. method:: API.followers_ids(id/screen_name/user_id) + + Returns an array containing the IDs of users following the specified + user. + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :param cursor: |cursor| + :rtype: list of Integers + + +Account Methods +--------------- + +.. method:: API.verify_credentials() + + Verify the supplied user credentials are valid. + + :rtype: :class:`User` object if credentials are valid, otherwise False + + +.. method:: API.rate_limit_status() + + Returns the remaining number of API requests available to the + requesting user before the API limit is reached for the current + hour. Calls to rate_limit_status do not count against the rate + limit. If authentication credentials are provided, the rate limit + status for the authenticating user is returned. Otherwise, the rate + limit status for the requester's IP address is returned. + + :rtype: :class:`JSON` object + + +.. method:: API.set_delivery_device(device) + + Sets which device Twitter delivers updates to for the authenticating + user. Sending "none" as the device parameter will disable SMS updates. + + :param device: Must be one of: sms, none + :rtype: :class:`User` object + + +.. method:: API.update_profile_colors([profile_background_color], [profile_text_color], [profile_link_color], [profile_sidebar_fill_color], [profile_sidebar_border_color]) + + Sets one or more hex values that control the color scheme of the + authenticating user's profile page on twitter.com. + + :param profile_background_color: + :param profile_text_color: + :param profile_link_color: + :param profile_sidebar_fill_color: + :param profile_sidebar_border_color: + :rtype: :class:`User` object + + +.. method:: API.update_profile_image(filename) + + Update the authenticating user's profile image. Valid formats: GIF, + JPG, or PNG + + :param filename: local path to image file to upload. Not a remote URL! + :rtype: :class:`User` object + + +.. method:: API.update_profile_background_image(filename) + + Update authenticating user's background image. Valid formats: GIF, + JPG, or PNG + + :param filename: local path to image file to upload. Not a remote URL! + :rtype: :class:`User` object + + +.. method:: API.update_profile([name], [url], [location], [description]) + + Sets values that users are able to set under the "Account" tab of + their settings page. + + :param name: Maximum of 20 characters + :param url: Maximum of 100 characters. Will be prepended with "http://" if not present + :param location: Maximum of 30 characters + :param description: Maximum of 160 characters + :rtype: :class:`User` object + + +Favorite Methods +---------------- + +.. method:: API.favorites([id], [page]) + + Returns the favorite statuses for the authenticating user or user + specified by the ID parameter. + + :param id: The ID or screen name of the user to request favorites + :param page: |page| + :rtype: list of :class:`Status` objects + + +.. method:: API.create_favorite(id) + + Favorites the status specified in the ID parameter as the + authenticating user. + + :param id: |sid| + :rtype: :class:`Status` object + + +.. method:: API.destroy_favorite(id) + + Un-favorites the status specified in the ID parameter as the + authenticating user. + + :param id: |sid| + :rtype: :class:`Status` object + + +Notification Methods +-------------------- + +.. method:: API.enable_notifications(id/screen_name/user_id) + + Enables device notifications for updates from the specified user. + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :rtype: :class:`User` object + + +.. method:: API.disable_notifications(id/screen_name/user_id) + + Disables notifications for updates from the specified user to the + authenticating user. + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :rtype: :class:`User` object + + +Block Methods +------------- + +.. method:: API.create_block(id/screen_name/user_id) + + Blocks the user specified in the ID parameter as the authenticating + user. Destroys a friendship to the blocked user if it exists. + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :rtype: :class:`User` object + + +.. method:: API.destroy_block(id/screen_name/user_id) + + Un-blocks the user specified in the ID parameter for the + authenticating user. + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :rtype: :class:`User` object + + +.. method:: API.exists_block(id/screen_name/user_id) + + Checks if the authenticated user is blocking the specified user. + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :rtype: True/False + + +.. method:: API.blocks([page]) + + Returns an array of user objects that the authenticating user is + blocking. + + :param page: |page| + :rtype: list of :class:`User` objects + + +.. method:: API.blocks_ids() + + Returns an array of numeric user ids the authenticating user is + blocking. + + :rtype: list of Integers + + +Spam Reporting Methods +---------------------- + +.. method:: API.report_spam([id/user_id/screen_name]) + + The user specified in the id is blocked by the authenticated user and + reported as a spammer. + + :param id: |uid| + :param screen_name: |screen_name| + :param user_id: |user_id| + :rtype: :class:`User` object + + +Saved Searches Methods +---------------------- + +.. method:: API.saved_searches() + + Returns the authenticated user's saved search queries. + + :rtype: list of :class:`SavedSearch` objects + + +.. method:: API.get_saved_search(id) + + Retrieve the data for a saved search owned by the authenticating user + specified by the given id. + + :param id: The id of the saved search to be retrieved. + :rtype: :class:`SavedSearch` object + + +.. method:: API.create_saved_search(query) + + Creates a saved search for the authenticated user. + + :param query: The query of the search the user would like to save. + :rtype: :class:`SavedSearch` object + + +.. method:: API.destroy_saved_search(id) + + Destroys a saved search for the authenticated user. The search + specified by id must be owned by the authenticating user. + + :param id: The id of the saved search to be deleted. + :rtype: :class:`SavedSearch` object + + +Help Methods +------------ + +.. method:: API.test() + + Invokes the test method in the Twitter API. Return True if successful, + otherwise False. + + :rtype: True/False + + +.. method:: API.search(q[,lang],[locale],[rpp],[page],[since_id],[geocode],[show_user]) + + Returns tweets that match a specified query. + + :param q: the search query string + :param lang: Restricts tweets to the given language, given by an ISO 639-1 code. + :param locale: Specify the language of the query you are sending. This is intended for language-specific clients and the default should work in the majority of cases. + :param rpp: The number of tweets to return per page, up to a max of 100. + :param page: The page number (starting at 1) to return, up to a max of roughly 1500 results (based on rpp * page. + :param geocode: Returns tweets by users located within a given radius of the given latitude/longitude. The location is preferentially taking from the Geotagging API, but will fall back to their Twitter profile. The parameter value is specified by "latitide,longitude,radius", where radius units must be specified as either "mi" (miles) or "km" (kilometers). Note that you cannot use the near operator via the API to geocode arbitrary locations; however you can use this geocode parameter to search near geocodes directly. + :param show_user: When true, prepends ":" to the beginning of the tweet. This is useful for readers that do not display Atom's author field. The default is false. + :rtype: list of :class:`SearchResult` objects + + +.. method:: API.trends() + + Returns the top ten topics that are currently trending on Twitter. The + response includes the time of the request, the name of each trend, and + the url to the Twitter Search results page for that topic. + + :rtype: :class:`JSON` object + + +.. method:: API.trends_current([exclude]) + + Returns the current top 10 trending topics on Twitter. The response + includes the time of the request, the name of each trending topic, and + query used on Twitter Search results page for that topic. + + :param exclude: |exclude| + :rtype: :class:`JSON` object + + +.. method:: API.trends_daily([date], [exclude]) + + Returns the top 20 trending topics for each hour in a given day. + + :param date: |date| + :param exclude: |exclude| + :rtype: :class:`JSON` object + + +.. method:: API.trends_weekly([date], [exclude]) + + Returns the top 30 trending topics for each day in a given week. + + :param date: |date| + :param exclude: |exclude| + :rtype: :class:`JSON` object + + +List Methods +------------ + +.. method:: API.create_list(name, [mode], [description]) + + Creates a new list for the authenticated user. Accounts are limited to + 20 lists. + + :param name: The name of the new list. + :param mode: |list_mode| + :param description: The description of the list you are creating. + :rtype: :class:`List` object + + +.. method:: API.destroy_list(slug) + + Deletes the specified list. Must be owned by the authenticated user. + + :param slug: |slug| + :rtype: :class:`List` object + + +.. method:: API.update_list(slug, [name], [mode], [description]) + + Updates the specified list. Note: this current throws a 500. Twitter + is looking into the issue. + + :param slug: |slug| + :param name: What you'd like to change the lists name to. + :param mode: |list_mode| + :param description: What you'd like to change the list description to. + :rtype: :class:`List` object + + +.. method:: API.lists([cursor]) + + List the lists of the specified user. Private lists will be included + if the authenticated users is the same as the user who's lists are + being returned. + + :param cursor: |cursor| + :rtype: list of :class:`List` objects + + +.. method:: API.lists_memberships([cursor]) + + List the lists the specified user has been added to. + + :param cursor: |cursor| + :rtype: list of :class:`List` objects + + +.. method:: API.lists_subscriptions([cursor]) + + List the lists the specified user follows. + + :param cursor: |cursor| + :rtype: list of :class:`List` objects + + +.. method:: API.list_timeline(owner, slug, [since_id], [max_id], [per_page], [page]) + + Show tweet timeline for members of the specified list. + + :param owner: |list_owner| + :param slug: |slug| + :param since_id: |since_id| + :param max_id: |max_id| + :param per_page: Number of results per a page + :param page: |page| + :rtype: list of :class:`Status` objects + + +.. method:: API.get_list(owner, slug) + + Show the specified list. Private lists will only be shown if the + authenticated user owns the specified list. + + :param owner: |list_owner| + :param slug: |slug| + :rtype: :class:`List` object + + +.. method:: API.add_list_member(slug, id) + + Add a member to a list. The authenticated user must own the list to be + able to add members to it. Lists are limited to having 500 members. + + :param slug: |slug| + :param id: the ID of the user to add as a member + :rtype: :class:`List` object + + +.. method:: API.remove_list_member(slug, id) + + Removes the specified member from the list. The authenticated user + must be the list's owner to remove members from the list. + + :param slug: |slug| + :param id: the ID of the user to remove as a member + :rtype: :class:`List` object + + +.. method:: API.list_members(owner, slug, cursor) + + Returns the members of the specified list. + + :param owner: |list_owner| + :param slug: |slug| + :param cursor: |cursor| + :rtype: list of :class:`User` objects + + +.. method:: API.is_list_member(owner, slug, id) + + Check if a user is a member of the specified list. + + :param owner: |list_owner| + :param slug: |slug| + :param id: the ID of the user to check + :rtype: :class:`User` object if user is a member of list, otherwise False. + + +.. method:: API.subscribe_list(owner, slug) + + Make the authenticated user follow the specified list. + + :param owner: |list_owner| + :param slug: |slug| + :rtype: :class:`List` object + + +.. method:: API.unsubscribe_list(owner, slug) + + Unsubscribes the authenticated user form the specified list. + + :param owner: |list_owner| + :param slug: |slug| + :rtype: :class:`List` object + + +.. method:: API.list_subscribers(owner, slug, [cursor]) + + Returns the subscribers of the specified list. + + :param owner: |list_owner| + :param slug: |slug| + :param cursor: |cursor| + :rtype: list of :class:`User` objects + + +.. method:: API.is_subscribed_list(owner, slug, id) + + Check if the specified user is a subscriber of the specified list. + + :param owner: |list_owner| + :param slug: |slug| + :param id: the ID of the user to check + :rtype: :class:`User` object if user is subscribed to the list, otherwise False. + + +Local Trends Methods +-------------------- + +.. method:: API.trends_available([lat], [long]) + + Returns the locations that Twitter has trending topic information for. The response is an array of "locations" that encode the location's WOEID (a Yahoo! Where On Earth ID) and some other human-readable information such as a canonical name and country the location belongs in. [Coming soon] + + :param lat: If passed in conjunction with long, then the available trend locations will be sorted by distance to the lat and long passed in. The sort is nearest to furthest. + :param long: See lat. + :rtype: :class:`JSON` object + + +.. method:: API.trends_location(woeid) + + Returns the top 10 trending topics for a specific location Twitter has trending topic information for. The response is an array of "trend" objects that encode the name of the trending topic, the query parameter that can be used to search for the topic on Search, and the direct URL that can be issued against Search. This information is cached for five minutes, and therefore users are discouraged from querying these endpoints faster than once every five minutes. Global trends information is also available from this API by using a WOEID of 1. + + :param woeid: * The WOEID of the location to be querying for. + :rtype: :class:`JSON` object + +Geo Methods +----------- + +.. method:: API.reverse_geocode([lat], [long], [accuracy], [granularity], [max_results]) + + Given a latitude and longitude, looks for places (cities and + neighbourhoods) whose IDs can be specified in a call to + :func:`update_status` to appear as the name of the location. This + call provides a detailed response about the location in question; + the :func:`nearby_places` function should be preferred for getting + a list of places nearby without great detail. + + :param lat: The location's latitude. + :param long: The location's longitude. + :param accuracy: Specify the "region" in which to search, such as a number (then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet). If this is not passed in, then it is assumed to be 0m + :param granularity: Assumed to be `neighborhood' by default; can also be `city'. + :param max_results: A hint as to the maximum number of results to return. This is only a guideline, which may not be adhered to. + +.. method:: API.reverse_geocode([lat], [long], [ip], [accuracy], [granularity], [max_results]) + + Given a latitude and longitude, looks for nearby places (cities and + neighbourhoods) whose IDs can be specified in a call to + :func:`update_status` to appear as the name of the location. This + call provides a detailed response about the location in question; + the :func:`nearby_places` function should be preferred for getting + a list of places nearby without great detail. + + :param lat: The location's latitude. + :param long: The location's longitude. + :param ip: The location's IP address. Twitter will attempt to geolocate using the IP address. + :param accuracy: Specify the "region" in which to search, such as a number (then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet). If this is not passed in, then it is assumed to be 0m + :param granularity: Assumed to be `neighborhood' by default; can also be `city'. + :param max_results: A hint as to the maximum number of results to return. This is only a guideline, which may not be adhered to. + +.. method:: API.geo_id(id) + + Given *id* of a place, provide more details about that place. + + :param id: Valid Twitter ID of a location. diff --git a/docs/auth_tutorial.rst b/docs/auth_tutorial.rst new file mode 100644 index 0000000..68075cb --- /dev/null +++ b/docs/auth_tutorial.rst @@ -0,0 +1,166 @@ +.. _auth_tutorial: + + +*********************** +Authentication Tutorial +*********************** + +Introduction +============ + +Tweepy supports both basic and oauth authentication. Authentication is +handled by tweepy.AuthHandler classes with two implementations +provided: + +* OAuthHandler + +* BasicAuthHandler + +Basic Authentication +==================== + +Twitter has disabled basic authentication on August 16th 2010 - use OAuth +authentication instead. + +Basic authentication uses the user's Twitter username and password for +authenticating with the API. You must query the user for these two +pieces of information before we can authenticate. + +Now first we must create an instance of the BasicAuthHandler and pass +into it the username and password:: + + auth = tweepy.BasicAuthHandler(username, password) + +Next we need to create our API instance which will be used for +executing requests to the Twitter API:: + + api = tweepy.API(auth) + +We are now ready to make API calls that are authenticated! Here is a +quick example posting a new tweet to the authenticated user's account:: + + api.update_status('hello from tweepy!') + +OAuth Authentication +==================== + +OAuth is a bit trickier than basic auth, but there are some advantages +to using it: + +* You can set a 'from myappname' which will appear in tweets + posted + +* More secure since you don't need the user's password + +* Your app does not break if the user changes their password in + the future + +Tweepy tries to make OAuth as painless as possible for you. To begin +the process we need to register our client application with +Twitter. Create a new application and once you +are done you should have your consumer token and secret. Keep these +two handy, you'll need them. + +The next step is creating an OAuthHandler instance. Into this we pass +our consumer token and secret which was given to us in the previous +paragraph:: + + auth = tweepy.OAuthHandler(consumer_token, consumer_secret) + +If you have a web application and are using a callback URL that needs +to be supplied dynamically you would pass it in like so:: + + auth = tweepy.OAuthHandler(consumer_token, consumer_secret, + callback_url) + +If the callback URL will not be changing, it is best to just configure +it statically on twitter.com when setting up your application's +profile. + +Unlike basic auth, we must do the OAuth "dance" before we can start +using the API. We must complete the following steps: + +#. Get a request token from twitter + +#. Redirect user to twitter.com to authorize our application + +#. If using a callback, twitter will redirect the user to + us. Otherwise the user must manually supply us with the verifier + code. + +#. Exchange the authorized request token for an access token. + +So let's fetch our request token to begin the dance:: + + try: + redirect_url = auth.get_authorization_url() + except tweepy.TweepError: + print 'Error! Failed to get request token.' + +This call requests the token from twitter and returns to us the +authorization URL where the user must be redirect to authorize us. Now +if this is a desktop application we can just hang onto our +OAuthHandler instance until the user returns back. In a web +application we will be using a callback request. So we must store the +request token in the session since we will need it inside the callback +URL request. Here is a pseudo example of storing the request token in +a session:: + + session.set('request_token', (auth.request_token.key, + auth.request_token.secret)) + +So now we can redirect the user to the URL returned to us earlier from +the get_authorization_url() method. + +If this is a desktop application (or any application not using +callbacks) we must query the user for the "verifier code" that twitter +will supply them after they authorize us. Inside a web application +this verifier value will be supplied in the callback request from +twitter as a GET query parameter in the URL. + +.. code-block :: python + + # Example using callback (web app) + verifier = request.GET.get('oauth_verifier') + + # Example w/o callback (desktop) + verifier = raw_input('Verifier:') + +The final step is exchanging the request token for an access +token. The access token is the "key" for opening the Twitter API +treasure box. To fetch this token we do the following:: + + # Let's say this is a web app, so we need to re-build the auth handler + # first... + auth = tweepy.OAuthHandler(consumer_key, consumer_secret) + token = session.get('request_token') + session.delete('request_token') + auth.set_request_token(token[0], token[1]) + + try: + auth.get_access_token(verifier) + except tweepy.TweepError: + print 'Error! Failed to get access token.' + +It is a good idea to save the access token for later use. You do not +need to re-fetch it each time. Twitter currently does not expire the +tokens, so the only time it would ever go invalid is if the user +revokes our application access. To store the access token depends on +your application. Basically you need to store 2 string values: key and +secret:: + + auth.access_token.key + auth.access_token.secret + +You can throw these into a database, file, or where ever you store +your data. To re-build an OAuthHandler from this stored access token +you would do this:: + + auth = tweepy.OAuthHandler(consumer_key, consumer_secret) + auth.set_access_token(key, secret) + +So now that we have our OAuthHandler equipped with an access token, we +are ready for business:: + + api = tweepy.API(auth) + api.update_status('tweepy + oauth!') diff --git a/docs/code_snippet.rst b/docs/code_snippet.rst new file mode 100644 index 0000000..13ea0ac --- /dev/null +++ b/docs/code_snippet.rst @@ -0,0 +1,61 @@ +.. _code_snippet: + + +************* +Code Snippets +************* + +Introduction +============ + +Here are some code snippets to help you out with using Tweepy. Feel +free to contribute your own snippets or improve the ones here! + +BasicAuth +========= + +.. code-block :: python + + auth = tweepy.BasicAuthHandler("username", "password") + api = tweepy.API(auth) + +OAuth +===== + +.. code-block :: python + + auth = tweepy.OAuthHandler("consumer_key", "consumer_secret") + + # Redirect user to Twitter to authorize + redirect_user(auth.get_authorization_url()) + + # Get access token + auth.get_access_token("verifier_value") + + # Construct the API instance + api = tweepy.API(auth) + +Pagination +========== + +.. code-block :: python + + # Iterate through all of the authenticated user's friends + for friend in tweepy.Cursor(api.friends).items(): + # Process the friend here + process_friend(friend) + + # Iterate through the first 200 statuses in the friends timeline + for status in tweepy.Cursor(api.friends_timeline).items(200): + # Process the status here + process_status(status) + +FollowAll +========= + +This snippet will follow every follower of the authenticated user. + +.. code-block :: python + + for follower in tweepy.Cursor(api.followers).items(): + follower.follow() diff --git a/docs/conf.py b/docs/conf.py index ee9ff78..7e0c75e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # -# Tweepy documentation build configuration file, created by -# sphinx-quickstart on Fri Apr 15 18:57:17 2011. +# tweepy documentation build configuration file, created by +# sphinx-quickstart on Sun Dec 6 11:13:52 2009. # # This file is execfile()d with the current directory set to its containing dir. # @@ -16,32 +16,30 @@ import sys, os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -#sys.path.insert(0, os.path.abspath('.')) +sys.path.append(os.path.abspath('.')) +sys.path.append(os.path.abspath('..')) # -- General configuration ----------------------------------------------------- -# If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' - # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = [] +extensions = ['sphinx.ext.autodoc'] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +#templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. -#source_encoding = 'utf-8-sig' +#source_encoding = 'utf-8' # The master toctree document. master_doc = 'index' # General information about the project. -project = u'Tweepy' -copyright = u'2011, Joshua Roesslein' +project = u'tweepy' +copyright = u'2009, Joshua Roesslein' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -65,9 +63,12 @@ release = __version__ # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -exclude_patterns = ['_build'] +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None @@ -92,8 +93,8 @@ pygments_style = 'sphinx' # -- Options for HTML output --------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme @@ -123,7 +124,7 @@ html_theme = 'default' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +#html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -141,7 +142,7 @@ html_static_path = ['_static'] #html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +html_use_modindex = True # If false, no index is generated. #html_use_index = True @@ -152,22 +153,16 @@ html_static_path = ['_static'] # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. #html_use_opensearch = '' -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' # Output file base name for HTML help builder. -htmlhelp_basename = 'Tweepydoc' +htmlhelp_basename = 'tweepydoc' # -- Options for LaTeX output -------------------------------------------------- @@ -181,7 +176,7 @@ htmlhelp_basename = 'Tweepydoc' # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ - ('index', 'Tweepy.tex', u'Tweepy Documentation', + ('index', 'tweepy.tex', u'tweepy Documentation', u'Joshua Roesslein', 'manual'), ] @@ -193,12 +188,6 @@ latex_documents = [ # not chapters. #latex_use_parts = False -# If true, show page references after internal links. -#latex_show_pagerefs = False - -# If true, show URL addresses after external links. -#latex_show_urls = False - # Additional stuff for the LaTeX preamble. #latex_preamble = '' @@ -206,14 +195,4 @@ latex_documents = [ #latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True - - -# -- Options for manual page output -------------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - ('index', 'tweepy', u'Tweepy Documentation', - [u'Joshua Roesslein'], 1) -] +#latex_use_modindex = True diff --git a/docs/cursor_tutorial.rst b/docs/cursor_tutorial.rst new file mode 100644 index 0000000..be0b83a --- /dev/null +++ b/docs/cursor_tutorial.rst @@ -0,0 +1,93 @@ +.. _cursor_tutorial: + +*************** +Cursor Tutorial +*************** + +This tutorial describes details on pagination with Cursor objects. + +Introduction +============ + +We use pagination a lot in Twitter API development. Iterating through +timelines, user lists, direct messages, etc. In order to perform +pagination we must supply a page/cursor parameter with each of our +requests. The problem here is this requires a lot of boiler plate code +just to manage the pagination loop. To help make pagination easier and +require less code Tweepy has the Cursor object. + +Old way vs Cursor way +--------------------- + +First let's demonstrate iterating the statues in the authenticated +user's timeline. Here is how we would do it the "old way" before +Cursor object was introduced:: + + page = 1 + while True: + statuses = api.user_timeline(page=page) + if statuses: + for status in statuses: + # process status here + process_status(status) + else: + # All done + break + page += 1 # next page + +As you can see we must manage the "page" parameter manually in our +pagination loop. Now here is the version of the code using Cursor +object:: + + for status in Cursor(api.user_timeline).items(): + # process status here + process_status(status) + +Now that looks much better! Cursor handles all the pagination work for +us behind the scene so our code can now focus entirely on processing +the results. + +Passing parameters into the API method +-------------------------------------- + +What if you need to pass in parameters to the API method? + +.. code-block :: python + + api.user_timeline(id="twitter") + +Since we pass Cursor the callable, we can not pass the parameters +directly into the method. Instead we pass the parameters into the +Cursor constructor method:: + + Cursor(api.user_timeline, id="twitter") + +Now Cursor will pass the parameter into the method for us when ever it +makes a request. + +Items or Pages +-------------- + +So far we have just demonstrated pagination iterating per an +item. What if instead you want to process per a page of results? You +would use the pages() method:: + + for page in Cursor(api.user_timeline).pages(): + # page is a list of statuses + process_page(page) + + +Limits +------ + +What if you only want n items or pages returned? You pass into the items() or pages() methods the limit you want to impose. + +.. code-block :: python + + # Only iterate through the first 200 statuses + for status in Cursor(api.user_timeline).items(200): + process_status(status) + + # Only iterate through the first 3 pages + for page in Cursor(api.user_timeline).pages(3): + process_page(page) diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..295ee9c --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,66 @@ +.. _getting_started: + + +*************** +Getting started +*************** + +Introduction +============ + +If you are new to Tweepy, this is the place to begin. The goal of this +tutorial is to get you set-up and rolling with Tweepy. We won't go +into too much detail here, just some important basics. + +Hello Tweepy +============ + +.. code-block :: python + + import tweepy + + public_tweets = tweepy.api.public_timeline() + for tweet in public_tweets: + print tweet.text + +This example will download the public timeline tweets and print each +one of their texts to the console. tweepy.api in the above code +snippet is an unauthenticated instance of the tweepy API class. The +API class contains all the methods for access the Twitter API. By +unauthenticated means there is no user associated with this +instance. So you may only do unauthenticated API calls with this +instance. For example the following would fail:: + + tweepy.api.update_status('will not work!') + +The :ref:`auth_tutorial` goes into more details about authentication. + +API +=== + +The API class provides access to the entire twitter RESTful API +methods. Each method can accept various parameters and return +responses. For more information about these methods please refer to +:ref:`API Reference `. + +Models +====== + +When we invoke an API method most of the time returned back to us will +be a Tweepy model class instance. This will contain the data returned +from Twitter which we can then use inside our application. For example +the following code returns to us an User model:: + + # Get the User object for twitter... + user = tweepy.api.get_user('twitter') + +Models container the data and some helper methods which we can then +use:: + + print user.screen_name + print user.followers_count + for friend in user.friends(): + print friend.screen_name + +For more information about models please see ModelsReference. + diff --git a/docs/index.rst b/docs/index.rst index 39d4242..005c6ae 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,13 +1,24 @@ -.. Tweepy documentation master file, created by - sphinx-quickstart on Fri Apr 15 18:57:17 2011. +.. tweepy documentation master file, created by + sphinx-quickstart on Sun Dec 6 11:13:52 2009. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. Tweepy Documentation ==================== +Contents: + .. toctree:: :maxdepth: 2 - install + getting_started.rst + auth_tutorial.rst + code_snippet.rst + cursor_tutorial.rst + api.rst + +Indices and tables +================== +* :ref:`genindex` +* :ref:`search` diff --git a/docs/make.bat b/docs/make.bat index 2e1a13c..10adbcd 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -2,9 +2,7 @@ REM Command file for Sphinx documentation -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) +set SPHINXBUILD=sphinx-build set BUILDDIR=_build set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . if NOT "%PAPER%" == "" ( @@ -16,21 +14,16 @@ if "%1" == "" goto help if "%1" == "help" ( :help echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. changes to make an overview over all changed/added/deprecated items - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled goto end ) @@ -42,7 +35,6 @@ if "%1" == "clean" ( if "%1" == "html" ( %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/html. goto end @@ -50,23 +42,13 @@ if "%1" == "html" ( if "%1" == "dirhtml" ( %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. goto end ) -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - if "%1" == "pickle" ( %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the pickle files. goto end @@ -74,7 +56,6 @@ if "%1" == "pickle" ( if "%1" == "json" ( %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can process the JSON files. goto end @@ -82,7 +63,6 @@ if "%1" == "json" ( if "%1" == "htmlhelp" ( %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run HTML Help Workshop with the ^ .hhp project file in %BUILDDIR%/htmlhelp. @@ -91,59 +71,24 @@ if "%1" == "htmlhelp" ( if "%1" == "qthelp" ( %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Tweepy.qhcp + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\tweepy.qhcp echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Tweepy.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\tweepy.ghc goto end ) if "%1" == "latex" ( %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 echo. echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. goto end ) -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - if "%1" == "changes" ( %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 echo. echo.The overview file is in %BUILDDIR%/changes. goto end @@ -151,7 +96,6 @@ if "%1" == "changes" ( if "%1" == "linkcheck" ( %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 echo. echo.Link check complete; look for any errors in the above output ^ or in %BUILDDIR%/linkcheck/output.txt. @@ -160,7 +104,6 @@ or in %BUILDDIR%/linkcheck/output.txt. if "%1" == "doctest" ( %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 echo. echo.Testing of doctests in the sources finished, look at the ^ results in %BUILDDIR%/doctest/output.txt. diff --git a/docs/parameters.rst b/docs/parameters.rst new file mode 100644 index 0000000..5fa1338 --- /dev/null +++ b/docs/parameters.rst @@ -0,0 +1,17 @@ +.. 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:: Specifies the ID of the user. Helpful for disambiguating when a valid user ID is also a valid screen name. +.. |screen_name| replace:: Specifies 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. +.. |cursor| replace:: Breaks the results into pages. Provide a value of -1 to begin paging. Provide values as returned to in the response body's next_cursor and previous_cursor attributes to page back and forth in the list. +.. |exclude| replace:: Setting this equal to hashtags will remove all hashtags from the trends list. +.. |date| replace:: Permits specifying a start date for the report. The date should be formatted YYYY-MM-DD. +.. |slug| replace:: the slug name or numerical ID of the list +.. |list_mode| replace:: Whether your list is public or private. Values can be public or private. Lists are public by default if no mode is specified. +.. |list_owner| replace:: the screen name of the owner of the list +