From 17c5556e43c1c93884284860bd85a08ff34e21c6 Mon Sep 17 00:00:00 2001 From: pinkrabbit412 Date: Thu, 31 Oct 2019 04:13:05 +0900 Subject: [PATCH] Set up default document. in ./docs/ --- docs/Makefile | 99 +++ docs/api.rst | 1205 +++++++++++++++++++++++++++++++++++++ docs/auth_tutorial.rst | 148 +++++ docs/code_snippet.rst | 79 +++ docs/conf.py | 4 +- docs/cursor_tutorial.rst | 94 +++ docs/extended_tweets.rst | 125 ++++ docs/getting_started.rst | 64 ++ docs/index.rst | 27 + docs/install.rst | 13 + docs/make.bat | 116 ++++ docs/parameters.rst | 27 + docs/running_tests.rst | 29 + docs/streaming_how_to.rst | 124 ++++ 14 files changed, 2152 insertions(+), 2 deletions(-) create mode 100644 docs/Makefile create mode 100644 docs/api.rst create mode 100644 docs/auth_tutorial.rst create mode 100644 docs/code_snippet.rst create mode 100644 docs/cursor_tutorial.rst create mode 100644 docs/extended_tweets.rst create mode 100644 docs/getting_started.rst create mode 100644 docs/index.rst create mode 100644 docs/install.rst create mode 100644 docs/make.bat create mode 100644 docs/parameters.rst create mode 100644 docs/running_tests.rst create mode 100644 docs/streaming_how_to.rst diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..5d97e1a --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,99 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +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 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 " 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." + +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 "To view the help file:" + @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 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/api.rst b/docs/api.rst new file mode 100644 index 0000000..6c9e9c0 --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,1205 @@ +.. _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], \ + [api_root='/1'], [search_root=''], [retry_count=0], \ + [retry_delay=0], [retry_errors=None], [timeout=60], \ + [parser=ModelParser], [compression=False], \ + [wait_on_rate_limit=False], [wait_on_rate_limit_notify=False], \ + [proxy=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 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 timeout: The maximum amount of time to wait for a response from + Twitter + :param parser: The object to use for parsing the response from Twitter + :param compression: Whether or not to use GZIP compression for requests + :param wait_on_rate_limit: Whether or not to automatically wait for rate + limits to replenish + :param wait_on_rate_limit_notify: Whether or not to print a notification + when Tweepy is waiting for rate limits to + replenish + :param proxy: The full url to an HTTPS proxy to use for connecting to + Twitter. + + +Timeline methods +---------------- + +.. 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.statuses_lookup(id_, [include_entities], [trim_user], [map_], \ + [include_ext_alt_text], [include_card_uri]) + + Returns full Tweet objects for up to 100 tweets per request, specified by + the ``id_`` parameter. + + :param id\_: A list of Tweet IDs to lookup, up to 100 + :param include_entities: |include_entities| + :param trim_user: |trim_user| + :param map\_: A boolean indicating whether or not to include tweets that + cannot be shown. Defaults to False. + :param include_ext_alt_text: |include_ext_alt_text| + :param include_card_uri: |include_card_uri| + :rtype: 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.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 + + +.. method:: API.mentions_timeline([since_id], [max_id], [count]) + + Returns the 20 most recent mentions, including retweets. + + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :rtype: list of :class:`Status` objects + + +Status methods +-------------- + +.. method:: API.get_status(id, [trim_user], [include_my_retweet], \ + [include_entities], [include_ext_alt_text], \ + [include_card_uri]) + + Returns a single status specified by the ID parameter. + + :param id: |sid| + :param trim_user: |trim_user| + :param include_my_retweet: A boolean indicating if any Tweets returned that + have been retweeted by the authenticating user should include an + additional current_user_retweet node, containing the ID of the source + status for the retweet. + :param include_entities: |include_entities| + :param include_ext_alt_text: |include_ext_alt_text| + :param include_card_uri: |include_card_uri| + :rtype: :class:`Status` object + + +.. method:: API.update_status(status, [in_reply_to_status_id], \ + [auto_populate_reply_metadata], \ + [exclude_reply_user_ids], [attachment_url], \ + [media_ids], [possibly_sensitive], [lat], \ + [long], [place_id], [display_coordinates], \ + [trim_user], [enable_dmcommands], \ + [fail_dmcommands], [card_uri]) + + Updates the authenticating user's current status, also known as Tweeting. + + For each update attempt, the update text is compared with the authenticating + user's recent Tweets. Any attempt that would result in duplication will be + blocked, resulting in a 403 error. A user cannot submit the same status + twice in a row. + + While not rate limited by the API, a user is limited in the number of Tweets + they can create at a time. If the number of updates posted by the user + reaches the current allowed limit this method will return an HTTP 403 error. + + :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. Note: This parameter will be ignored unless the author of + the Tweet this parameter references is mentioned within the status text. + Therefore, you must include @username, where username is the author of + the referenced Tweet, within the update. + :param auto_populate_reply_metadata: If set to true and used with + in_reply_to_status_id, leading @mentions will be looked up from the + original Tweet, and added to the new Tweet from there. This wil append + @mentions into the metadata of an extended Tweet as a reply chain grows, + until the limit on @mentions is reached. In cases where the original + Tweet has been deleted, the reply will fail. + :param exclude_reply_user_ids: When used with auto_populate_reply_metadata, + a comma-separated list of user ids which will be removed from the + server-generated @mentions prefix on an extended Tweet. Note that the + leading @mention cannot be removed as it would break the + in-reply-to-status-id semantics. Attempting to remove it will be + silently ignored. + :param attachment_url: In order for a URL to not be counted in the status + body of an extended Tweet, provide a URL as a Tweet attachment. This URL + must be a Tweet permalink, or Direct Message deep link. Arbitrary, + non-Twitter URLs must remain in the status text. URLs passed to the + attachment_url parameter not matching either a Tweet permalink or Direct + Message deep link will fail at Tweet creation and cause an exception. + :param media_ids: A list of media_ids to associate with the Tweet. + You may include up to 4 photos or 1 animated GIF or 1 video in a Tweet. + :param possibly_sensitive: If you upload Tweet media that might be + considered sensitive content such as nudity, or medical procedures, you + must set this value to true. + :param lat: The latitude of the location this Tweet refers to. This + parameter will be ignored unless it is inside the range -90.0 to +90.0 + (North is positive) inclusive. It will also be ignored if there is no + corresponding long parameter. + :param long: The longitude of the location this Tweet refers to. The valid + ranges for longitude are -180.0 to +180.0 (East is positive) inclusive. + This parameter will be ignored if outside that range, if it is not a + number, if geo_enabled is disabled, or if there no corresponding lat + parameter. + :param place_id: A place in the world. + :param display_coordinates: Whether or not to put a pin on the exact + coordinates a Tweet has been sent from. + :param trim_user: |trim_user| + :param enable_dmcommands: When set to true, enables shortcode commands for + sending Direct Messages as part of the status text to send a Direct + Message to a user. When set to false, disables this behavior and includes + any leading characters in the status text that is posted + :param fail_dmcommands: When set to true, causes any status text that starts + with shortcode commands to return an API error. When set to false, allows + shortcode commands to be sent in the status text and acted on by the API. + :param card_uri: Associate an ads card with the Tweet using the card_uri + value from any ads card response. + :rtype: :class:`Status` object + + +.. method:: API.update_with_media(filename, [status], \ + [in_reply_to_status_id], \ + [auto_populate_reply_metadata], [lat], \ + [long], [source], [place_id], [file]) + + *Deprecated*: Use :func:`API.media_upload` instead. Update the authenticated + user's status. Statuses that are duplicates or too long will be silently + ignored. + + :param filename: The filename of the image to upload. This will + automatically be opened unless `file` is specified + :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 auto_populate_reply_metadata: Whether to automatically include the + @mentions in the status metadata. + :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 place_id: Twitter ID of location which is listed in the Tweet if + geolocation is enabled for the user. + :param file: A file object, which will be used instead of opening + `filename`. `filename` is still required, for MIME type + detection and to use as a form field in the POST data + :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.retweeters(id, [cursor], [stringify_ids]) + + Returns up to 100 user IDs belonging to users who have retweeted the Tweet + specified by the id parameter. + + :param id: |sid| + :param cursor: |cursor| + :param stringify_ids: Have ids returned as strings instead. + :rtype: list of Integers + + +.. 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 + + +.. method:: API.unretweet(id) + + Untweets a retweeted status. Requires the id of the retweet to unretweet. + + :param id: |sid| + :rtype: :class:`Status` object + + +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], [skip_status], \ + [include_user_entities]) + + 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| + :param count: |count| + :param skip_status: |skip_status| + :param include_user_entities: |include_user_entities| + :rtype: list of :class:`User` objects + + +.. method:: API.followers([id/screen_name/user_id], [cursor]) + + Returns a user's followers ordered in which they were added. 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| + :param count: |count| + :param skip_status: |skip_status| + :param include_user_entities: |include_user_entities| + :rtype: list of :class:`User` objects + + +.. method:: API.lookup_users([user_ids], [screen_names], [include_entities], \ + [tweet_mode]) + + Returns fully-hydrated user objects for up to 100 users per request. + + There are a few things to note when using this method. + + * You must be following a protected user to be able to see their most recent + status update. If you don't follow a protected user their status will be + removed. + * The order of user IDs or screen names may not match the order of users in + the returned array. + * If a requested user is unknown, suspended, or deleted, then that user will + not be returned in the results list. + * If none of your lookup criteria can be satisfied by returning a user + object, a HTTP 404 will be thrown. + + :param user_ids: A list of user IDs, up to 100 are allowed in a single + request. + :param screen_names: A list of screen names, up to 100 are allowed in a + single request. + :param include_entities: |include_entities| + :param tweet_mode: Valid request values are compat and extended, which give + compatibility mode and extended mode, respectively for + Tweets that contain over 140 characters. + :rtype: list of :class:`User` objects + + +.. method:: API.search_users(q, [count], [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 count: 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.get_direct_message([id], [full_text]) + + Returns a specific direct message. + + :param id: |id| + :param full_text: |full_text| + :rtype: :class:`DirectMessage` object + + +.. method:: API.list_direct_messages([count], [cursor]) + + Returns all Direct Message events (both sent and received) within the last + 30 days. Sorted in reverse-chronological order. + + :param count: |count| + :param cursor: |cursor| + :rtype: list of :class:`DirectMessage` objects + + +.. method:: API.send_direct_message(recipient_id, text, [quick_reply_type], \ + [attachment_type], [attachment_media_id]) + + Sends a new direct message to the specified user from the authenticating + user. + + :param recipient_id: The ID of the user who should receive the direct + message. + :param text: The text of your Direct Message. Max length of 10,000 + characters. + :param quick_reply_type: The Quick Reply type to present to the user: + + * options - Array of Options objects (20 max). + * text_input - Text Input object. + * location - Location object. + :param attachment_type: The attachment type. Can be media or location. + :param attachment_media_id: A media id to associate with the message. + A Direct Message may only reference a single + media_id. + :rtype: :class:`DirectMessage` object + + +.. method:: API.destroy_direct_message(id) + + Deletes the direct message specified in the required ID parameter. The + authenticating user must be the recipient of the specified direct message. + Direct Messages are only removed from the interface of the user context + provided. Other members of the conversation can still access the Direct + Messages. + + :param id: The id of the Direct Message that should be deleted. + :rtype: None + + +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.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([include_entities], [skip_status], \ + [include_email]) + + Verify the supplied user credentials are valid. + + :param include_entities: |include_entities| + :param skip_status: |skip_status| + :param include_email: When set to true email will be returned in the user + objects as a string. + :rtype: :class:`User` object if credentials are valid, otherwise False + + +.. method:: API.rate_limit_status() + + Returns the current rate limits for methods belonging to the specified + resource families. When using application-only auth, this method's response + indicates the application-only auth rate limiting context. + + :param resources: A comma-separated list of resource families you want to + know the current rate limit disposition for. + :rtype: :class:`JSON` 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 + + +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.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([cursor]) + + Returns an array of numeric user ids the authenticating user is blocking. + + :param cursor: |cursor| + :rtype: list of Integers + + +Mute Methods +------------ + +.. method:: API.create_mute(id/screen_name/user_id) + + Mutes 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.destroy_mute(id/screen_name/user_id) + + Un-mutes 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.mutes([cursor], [include_entities], [skip_status]) + + Returns an array of user objects the authenticating user has muted. + + :param cursor: |cursor| + :param include_entities: |include_entities| + :param skip_status: |skip_status| + :rtype: list of :class:`User` objects + + +.. method:: API.mutes_ids([cursor]) + + Returns an array of numeric user ids the authenticating user has muted. + + :param cursor: |cursor| + :rtype: list of Integers + + +Spam Reporting Methods +---------------------- + +.. method:: API.report_spam(id/screen_name/user_id, [perform_block]) + + 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| + :param perform_block: A boolean indicating if the reported account should be + blocked. Defaults to True. + :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.search(q, [geocode], [lang], [locale], [result_type], \ + [count], [until], [since_id], [max_id], \ + [include_entities]) + + Returns a collection of relevant Tweets matching a specified query. + + Please note that Twitter's search service and, by extension, the Search API + is not meant to be an exhaustive source of Tweets. Not all Tweets will be + indexed or made available via the search interface. + + In API v1.1, the response format of the Search API has been improved to + return Tweet objects more similar to the objects you’ll find across the REST + API and platform. However, perspectival attributes (fields that pertain to + the perspective of the authenticating user) are not currently supported on + this endpoint.\ [#]_\ [#]_ + + :param q: the search query string of 500 characters maximum, including + operators. Queries may additionally be limited by complexity. + :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. A maximum of 1,000 distinct "sub-regions" will be + considered when using the radius modifier. + :param lang: Restricts tweets to the given language, given by an ISO 639-1 + code. Language detection is best-effort. + :param locale: Specify the language of the query you are sending (only ja is + currently effective). This is intended for language-specific consumers + and the default should work in the majority of cases. + :param result_type: Specifies what type of search results you would prefer + to receive. The current default is "mixed." Valid values include: + + * mixed : include both popular and real time results in the response + * recent : return only the most recent results in the response + * popular : return only the most popular results in the response + :param count: |count| + :param until: Returns tweets created before the given date. Date should be + formatted as YYYY-MM-DD. Keep in mind that the search index has a 7-day + limit. In other words, no tweets will be found for a date older than one + week. + :param since_id: |since_id| There are limits to the number of Tweets which + can be accessed through the API. If the limit of Tweets has occurred + since the since_id, the since_id will be forced to the oldest ID + available. + :param max_id: |max_id| + :param include_entities: |include_entities| + :rtype: :class:`SearchResults` object + + +List Methods +------------ + +.. method:: API.create_list(name, [mode], [description]) + + Creates a new list for the authenticated user. + Note that you can create up to 1000 lists per account. + + :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([owner_screen_name/owner_id], list_id/slug) + + Deletes the specified list. + The authenticated user must own the list to be able to destroy it. + + :param owner_screen_name: |owner_screen_name| + :param owner_id: |owner_id| + :param list_id: |list_id| + :param slug: |slug| + :rtype: :class:`List` object + + +.. method:: API.update_list(list_id/slug, [name], [mode], [description], \ + [owner_screen_name/owner_id]) + + Updates the specified list. + The authenticated user must own the list to be able to update it. + + :param list_id: |list_id| + :param slug: |slug| + :param name: The name for the list. + :param mode: |list_mode| + :param description: The description to give the list. + :param owner_screen_name: |owner_screen_name| + :param owner_id: |owner_id| + :rtype: :class:`List` object + + +.. method:: API.lists_all([screen_name], [user_id], [reverse]) + + Returns all lists the authenticating or specified user subscribes to, + including their own. The user is specified using the ``user_id`` or + ``screen_name`` parameters. If no user is given, the authenticating user is + used. + + A maximum of 100 results will be returned by this call. Subscribed lists are + returned first, followed by owned lists. This means that if a user + subscribes to 90 lists and owns 20 lists, this method returns 90 + subscriptions and 10 owned lists. The ``reverse`` method returns owned lists + first, so with ``reverse=true``, 20 owned lists and 80 subscriptions would + be returned. + + :param screen_name: |screen_name| + :param user_id: |user_id| + :param reverse: A boolean indicating if you would like owned lists to be + returned first. See description above for information on how + this parameter works. + :rtype: list of :class:`List` objects + + +.. method:: API.lists_memberships([screen_name], [user_id], \ + [filter_to_owned_lists], [cursor], [count]) + + Returns the lists the specified user has been added to. If ``user_id`` or + ``screen_name`` are not provided, the memberships for the authenticating + user are returned. + + :param screen_name: |screen_name| + :param user_id: |user_id| + :param filter_to_owned_lists: A boolean indicating whether to return just + lists the authenticating user owns, and the user represented by + ``user_id`` or ``screen_name`` is a member of. + :param cursor: |cursor| + :param count: |count| + :rtype: list of :class:`List` objects + + +.. method:: API.lists_subscriptions([screen_name], [user_id], [cursor], \ + [count]) + + Obtain a collection of the lists the specified user is subscribed to, 20 + lists per page by default. Does not include the user's own lists. + + :param screen_name: |screen_name| + :param user_id: |user_id| + :param cursor: |cursor| + :param count: |count| + :rtype: list of :class:`List` objects + + +.. method:: API.list_timeline(list_id/slug, [owner_id/owner_screen_name], \ + [since_id], [max_id], [count], \ + [include_entities], [include_rts]) + + Returns a timeline of tweets authored by members of the specified list. + Retweets are included by default. Use the ``include_rts=false`` parameter to + omit retweets. + + :param list_id: |list_id| + :param slug: |slug| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :param since_id: |since_id| + :param max_id: |max_id| + :param count: |count| + :param include_entities: |include_entities| + :param include_rts: A boolean indicating whether the list timeline will + contain native retweets (if they exist) in addition to the standard + stream of tweets. The output format of retweeted tweets is identical to + the representation you see in home_timeline. + :rtype: list of :class:`Status` objects + + +.. method:: API.get_list(list_id/slug, [owner_id/owner_screen_name]) + + Returns the specified list. Private lists will only be shown if the + authenticated user owns the specified list. + + :param list_id: |list_id| + :param slug: |slug| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :rtype: :class:`List` object + + +.. method:: API.add_list_member(list_id/slug, screen_name/user_id, \ + [owner_id/owner_screen_name]) + + 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 5,000 members. + + :param list_id: |list_id| + :param slug: |slug| + :param screen_name: |screen_name| + :param user_id: |user_id| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :rtype: :class:`List` object + + +.. method:: API.add_list_members(list_id/slug, screen_name/user_id, \ + [owner_id/owner_screen_name]) + + Add up to 100 members to a list. The authenticated user must own the list to + be able to add members to it. Lists are limited to 5,000 members. + + :param list_id: |list_id| + :param slug: |slug| + :param screen_name: A comma separated list of screen names, up to 100 are + allowed in a single request + :param user_id: A comma separated list of user IDs, up to 100 are allowed in + a single request + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :rtype: :class:`List` object + + +.. method:: API.remove_list_member(list_id/slug, screen_name/user_id, \ + [owner_id/owner_screen_name]) + + Removes the specified member from the list. The authenticated user must be + the list's owner to remove members from the list. + + :param list_id: |list_id| + :param slug: |slug| + :param screen_name: |screen_name| + :param user_id: |user_id| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :rtype: :class:`List` object + + +.. method:: API.remove_list_members(list_id/slug, screen_name/user_id, \ + [owner_id/owner_screen_name]) + + Remove up to 100 members from a list. The authenticated user must own the + list to be able to remove members from it. Lists are limited to 5,000 + members. + + :param list_id: |list_id| + :param slug: |slug| + :param screen_name: A comma separated list of screen names, up to 100 are + allowed in a single request + :param user_id: A comma separated list of user IDs, up to 100 are allowed in + a single request + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :rtype: :class:`List` object + + +.. method:: API.list_members(list_id/slug, [owner_id/owner_screen_name], \ + [cursor]) + + Returns the members of the specified list. + + :param list_id: |list_id| + :param slug: |slug| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :param cursor: |cursor| + :rtype: list of :class:`User` objects + + +.. method:: API.show_list_member(list_id/slug, screen_name/user_id, \ + [owner_id/owner_screen_name]) + + Check if the specified user is a member of the specified list. + + :param list_id: |list_id| + :param slug: |slug| + :param screen_name: |screen_name| + :param user_id: |user_id| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :rtype: :class:`User` object if user is a member of list + + +.. method:: API.subscribe_list(list_id/slug, [owner_id/owner_screen_name]) + + Subscribes the authenticated user to the specified list. + + :param list_id: |list_id| + :param slug: |slug| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :rtype: :class:`List` object + + +.. method:: API.unsubscribe_list(list_id/slug, [owner_id/owner_screen_name]) + + Unsubscribes the authenticated user from the specified list. + + :param list_id: |list_id| + :param slug: |slug| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :rtype: :class:`List` object + + +.. method:: API.list_subscribers(list_id/slug, [owner_id/owner_screen_name], \ + [cursor], [count], [include_entities], \ + [skip_status]) + + Returns the subscribers of the specified list. Private list subscribers will + only be shown if the authenticated user owns the specified list. + + :param list_id: |list_id| + :param slug: |slug| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :param cursor: |cursor| + :param count: |count| + :param include_entities: |include_entities| + :param skip_status: |skip_status| + :rtype: list of :class:`User` objects + + +.. method:: API.show_list_subscriber(list_id/slug, screen_name/user_id, \ + [owner_id/owner_screen_name]) + + Check if the specified user is a subscriber of the specified list. + + :param list_id: |list_id| + :param slug: |slug| + :param screen_name: |screen_name| + :param user_id: |user_id| + :param owner_id: |owner_id| + :param owner_screen_name: |owner_screen_name| + :rtype: :class:`User` object if user is subscribed to list + + +Trends Methods +-------------- + +.. method:: API.trends_available() + + 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. + + :rtype: :class:`JSON` object + + +.. method:: API.trends_place(id, [exclude]) + + Returns the top 50 trending topics for a specific WOEID, + if trending information is available for it. + + 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 Twitter Search, and the Twitter Search URL. + + This information is cached for 5 minutes. Requesting more frequently than + that will not return any more data, and will count against your rate limit + usage. + + The tweet_volume for the last 24 hours is also returned for many trends if + this is available. + + :param id: The Yahoo! Where On Earth ID of the location to return trending + information for. Global information is available by using 1 as + the WOEID. + :param exclude: Setting this equal to hashtags will remove all hashtags + from the trends list. + :rtype: :class:`JSON` object + + +.. method:: API.trends_closest(lat, long) + + Returns the locations that Twitter has trending topic information for, + closest to a specified location. + + The response is an array of “locations” that encode the location’s WOEID and + some other human-readable information such as a canonical name and country + the location belongs in. + + A WOEID is a Yahoo! Where On Earth ID. + + :param lat: If provided with a long parameter the available trend locations + will be sorted by distance, nearest to furthest, to the + co-ordinate pair. The valid ranges for longitude is -180.0 to + +180.0 (West is negative, East is positive) inclusive. + :param long: If provided with a lat parameter the available trend locations + will be sorted by distance, nearest to furthest, to the + co-ordinate pair. The valid ranges for longitude is -180.0 to + +180.0 (West is negative, East is positive) inclusive. + :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.geo_id(id) + + Given *id* of a place, provide more details about that place. + + :param id: Valid Twitter ID of a location. + + +Utility methods +--------------- + +.. method:: API.configuration() + + Returns the current configuration used by Twitter including twitter.com + slugs which are not usernames, maximum photo resolutions, and t.co + shortened URL length. It is recommended applications request this endpoint + when they are loaded, but no more than once a day. + + +Media methods +------------- + +.. method:: API.media_upload(filename, [file]) + + Use this endpoint to upload images to Twitter. + + :param filename: The filename of the image to upload. This will + automatically be opened unless ``file`` is specified. + :param file: A file object, which will be used instead of opening + ``filename``. ``filename`` is still required, for MIME type + detection and to use as a form field in the POST data. + :rtype: :class:`Media` object + + +.. method:: API.create_media_metadata(media_id, alt_text) + + This endpoint can be used to provide additional information about the + uploaded media_id. This feature is currently only supported for images and + GIFs. Call this endpoint to attach additional metadata such as image alt + text. + + :param media_id: The ID of the media to add alt text to. + :param alt_text: The alt text to add to the image. + + +:mod:`tweepy.error` --- Exceptions +================================== + +The exceptions are available in the ``tweepy`` module directly, which means +``tweepy.error`` itself does not need to be imported. For example, +``tweepy.error.TweepError`` is available as ``tweepy.TweepError``. + + +.. exception:: TweepError + + The main exception Tweepy uses. Is raised for a number of things. + + When a ``TweepError`` is raised due to an error Twitter responded with, + the error code (`as described in the API documentation + `_) can be + accessed at ``TweepError.response.text``. Note, however, that + ``TweepError``\ s also may be raised with other things as message + (for example plain error reason strings). + + +.. exception:: RateLimitError + + Is raised when an API method fails due to hitting Twitter's rate limit. + Makes for easy handling of the rate limit specifically. + + Inherits from :exc:`TweepError`, so ``except TweepError`` will catch a + ``RateLimitError`` too. + + +.. rubric:: Footnotes + +.. [#] https://web.archive.org/web/20170829051949/https://dev.twitter.com/rest/reference/get/search/tweets +.. [#] https://twittercommunity.com/t/favorited-reports-as-false-even-if-status-is-already-favorited-by-the-user/11145 diff --git a/docs/auth_tutorial.rst b/docs/auth_tutorial.rst new file mode 100644 index 0000000..29cac52 --- /dev/null +++ b/docs/auth_tutorial.rst @@ -0,0 +1,148 @@ +.. _auth_tutorial: + + +*********************** +Authentication Tutorial +*********************** + +Introduction +============ + +Tweepy supports both OAuth 1a (application-user) and OAuth 2 +(application-only) authentication. Authentication is handled by the +tweepy.AuthHandler class. + +OAuth 1a Authentication +======================= + +Tweepy tries to make OAuth 1a 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 key and secret. Keep these +two handy, you'll need them. + +The next step is creating an OAuthHandler instance. Into this we pass +our consumer key and secret which was given to us in the previous +paragraph:: + + auth = tweepy.OAuthHandler(consumer_key, 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_key, 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 1a "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['oauth_token']) + +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.request_token = { 'oauth_token' : token, + 'oauth_token_secret' : verifier } + + 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 + 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!') + +OAuth 2 Authentication +====================== + +Tweepy also supports OAuth 2 authentication. OAuth 2 is a method of +authentication where an application makes API requests without the +user context. Use this method if you just need read-only access to +public information. + +Like OAuth 1a, we first register our client application and acquire +a consumer key and secret. + +Then we create an AppAuthHandler instance, passing in our consumer +key and secret:: + + auth = tweepy.AppAuthHandler(consumer_key, consumer_secret) + +With the bearer token received, we are now ready for business:: + + api = tweepy.API(auth) + for tweet in tweepy.Cursor(api.search, q='tweepy').items(10): + print(tweet.text) \ No newline at end of file diff --git a/docs/code_snippet.rst b/docs/code_snippet.rst new file mode 100644 index 0000000..f838e2a --- /dev/null +++ b/docs/code_snippet.rst @@ -0,0 +1,79 @@ +.. _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! + +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 home timeline + for status in tweepy.Cursor(api.home_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() + +Handling the rate limit using cursors +===================================== + +Since cursors raise ``RateLimitError``\ s in their ``next()`` method, +handling them can be done by wrapping the cursor in an iterator. + +Running this snippet will print all users you follow that themselves follow +less than 300 people total - to exclude obvious spambots, for example - and +will wait for 15 minutes each time it hits the rate limit. + +.. code-block :: python + + # In this example, the handler is time.sleep(15 * 60), + # but you can of course handle it in any way you want. + + def limit_handled(cursor): + while True: + try: + yield cursor.next() + except tweepy.RateLimitError: + time.sleep(15 * 60) + + for follower in limit_handled(tweepy.Cursor(api.followers).items()): + if follower.friends_count < 300: + print(follower.screen_name) diff --git a/docs/conf.py b/docs/conf.py index 70cd229..a09d427 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -56,8 +56,8 @@ release = __version__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -locale_dirs = ['_locale'] -#language = None +locale_dirs = ['locale/'] +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: diff --git a/docs/cursor_tutorial.rst b/docs/cursor_tutorial.rst new file mode 100644 index 0000000..9aef25e --- /dev/null +++ b/docs/cursor_tutorial.rst @@ -0,0 +1,94 @@ +.. _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 statuses in the authenticated +user's timeline. Here is how we would do it the "old way" before the +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 the Cursor +object:: + + for status in tweepy.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 scenes, 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:: + + tweepy.Cursor(api.user_timeline, id="twitter") + +Now Cursor will pass the parameter into the method for us whenever it +makes a request. + +Items or Pages +============== + +So far we have just demonstrated pagination iterating per +item. What if instead you want to process per page of results? You +would use the pages() method:: + + for page in tweepy.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 tweepy.Cursor(api.user_timeline).items(200): + process_status(status) + + # Only iterate through the first 3 pages + for page in tweepy.Cursor(api.user_timeline).pages(3): + process_page(page) diff --git a/docs/extended_tweets.rst b/docs/extended_tweets.rst new file mode 100644 index 0000000..d47ef66 --- /dev/null +++ b/docs/extended_tweets.rst @@ -0,0 +1,125 @@ +.. _extended_tweets: +.. _Twitter's Tweet updates documentation: https://developer.twitter.com/en/docs/tweets/tweet-updates + +*************** +Extended Tweets +*************** + +This supplements `Twitter's Tweet updates documentation`_. + +Introduction +============ + +On May 24, 2016, Twitter +`announced `_ +changes to the way that replies and URLs are handled and +`published plans `_ +around support for these changes in the Twitter API and initial technical +documentation describing the updates to Tweet objects and API options.\ [#]_ +On September 26, 2017, Twitter +`started testing `_ +280 characters for certain languages,\ [#]_ and on November 7, 2017, +`announced `_ +that the character limit was being expanded for Tweets in languages where +cramming was an issue.\ [#]_ + +Standard API methods +==================== + +Any ``tweepy.API`` method that returns a Status object accepts a new +``tweet_mode`` parameter. Valid values for this parameter are ``compat`` and +``extended``, which give compatibility mode and extended mode, respectively. +The default mode (if no parameter is provided) is compatibility mode. + +Compatibility mode +------------------ + +By default, using compatibility mode, the ``text`` attribute of Status objects +returned by ``tweepy.API`` methods is truncated to 140 characters, as needed. +When this truncation occurs, the ``truncated`` attribute of the Status object +will be ``True``, and only entities that are fully contained within the +available 140 characters range will be included in the ``entities`` attribute. +It will also be discernible that the ``text`` attribute of the Status object +is truncated as it will be suffixed with an ellipsis character, a space, and a +shortened self-permalink URL to the Tweet. + +Extended mode +------------- + +When using extended mode, the ``text`` attribute of Status objects returned by +``tweepy.API`` methods is replaced by a ``full_text`` attribute, which +contains the entire untruncated text of the Tweet. The ``truncated`` attribute +of the Status object will be ``False``, and the ``entities`` attribute will +contain all entities. Additionally, the Status object will have a +``display_text_range`` attribute, an array of two Unicode code point indices, +identifying the inclusive start and exclusive end of the displayable content +of the Tweet. + +Streaming +========= + +By default, the Status objects from streams may contain an ``extended_tweet`` +attribute representing the equivalent field in the raw data/payload for the +Tweet. This attribute/field will only exist for extended Tweets, containing a +dictionary of sub-fields. The ``full_text`` sub-field/key of this dictionary +will contain the full, untruncated text of the Tweet, and the ``entities`` +sub-field/key will contain the full set of entities. If there are extended +entities, the ``extended_entities`` sub-field/key will contain the full set of +those. Additionally, the ``display_text_range`` sub-field/key will contain an +array of two Unicode code point indices, identifying the inclusive start and +exclusive end of the displayable content of the Tweet. + +Handling Retweets +================= + +When using extended mode with a Retweet, the ``full_text`` attribute of the +Status object may be truncated with an ellipsis character instead of +containing the full text of the Retweet. However, since the +``retweeted_status`` attribute (of a Status object that is a Retweet) is +itself a Status object, the ``full_text`` attribute of the Retweeted Status +object can be used instead. + +This also applies similarly to Status objects/payloads that are Retweets from +streams. The dictionary from the ``extended_tweet`` attribute/field contains a +``full_text`` sub-field/key that may be truncated with an ellipsis character. +Instead, the ``extended_tweet`` attribute/field of the Retweeted Status (from +the ``retweeted_status`` attribute/field) can be used. + +Examples +======== + +Given an existing ``tweepy.API`` object and ``id`` for a Tweet, the following +can be used to print the full text of the Tweet, or if it's a Retweet, the +full text of the Retweeted Tweet:: + + status = api.get_status(id, tweet_mode="extended") + try: + print(status.retweeted_status.full_text) + except AttributeError: # Not a Retweet + print(status.full_text) + +If ``status`` is a Retweet, ``status.full_text`` could be truncated. + +This Status event handler for a ``StreamListener`` prints the full text of the +Tweet, or if it's a Retweet, the full text of the Retweeted Tweet:: + + def on_status(self, status): + if hasattr(status, "retweeted_status"): # Check if Retweet + try: + print(status.retweeted_status.extended_tweet["full_text"]) + except AttributeError: + print(status.retweeted_status.text) + else: + try: + print(status.extended_tweet["full_text"]) + except AttributeError: + print(status.text) + +If ``status`` is a Retweet, it will not have an ``extended_tweet`` attribute, +and ``status.text`` could be truncated. + +.. rubric:: Footnotes + +.. [#] https://twittercommunity.com/t/upcoming-changes-to-simplify-replies-and-links-in-tweets/67497 +.. [#] https://twittercommunity.com/t/testing-280-characters-for-certain-languages/94126 +.. [#] https://twittercommunity.com/t/updating-the-character-limit-and-the-twitter-text-library/96425 diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..c084fde --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,64 @@ +.. _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 + + auth = tweepy.OAuthHandler(consumer_key, consumer_secret) + auth.set_access_token(access_token, access_token_secret) + + api = tweepy.API(auth) + + public_tweets = api.home_timeline() + for tweet in public_tweets: + print(tweet.text) + +This example will download your home timeline tweets and print each +one of their texts to the console. Twitter requires all requests to +use OAuth for authentication. +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 = api.get_user('twitter') + +Models contain 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 new file mode 100644 index 0000000..1daa4f9 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,27 @@ +.. 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 + + getting_started.rst + auth_tutorial.rst + code_snippet.rst + cursor_tutorial.rst + extended_tweets.rst + streaming_how_to.rst + api.rst + running_tests.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 0000000..0d4857a --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,13 @@ +Installation +============ + +Install from PyPI:: + + easy_install tweepy + +Install from source:: + + git clone git://github.com/tweepy/tweepy.git + cd tweepy + python setup.py install + diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..1a93dda --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,116 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +set SPHINXBUILD=sphinx-build +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% +) + +pause + +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. 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 +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "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. + goto end +) + +if "%1" == "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.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\tweepy.ghc + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "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. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end +pause diff --git a/docs/parameters.rst b/docs/parameters.rst new file mode 100644 index 0000000..28c04f2 --- /dev/null +++ b/docs/parameters.rst @@ -0,0 +1,27 @@ +.. API parameters: + +.. |count| replace:: The number of results to try and retrieve per page. +.. |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. +.. |date| replace:: Permits specifying a start date for the report. The date should be formatted YYYY-MM-DD. +.. |exclude| replace:: Setting this equal to hashtags will remove all hashtags from the trends list. +.. |full_text| replace:: A boolean indicating whether or not the full text of a message should be returned. If False the message text returned will be truncated to 140 chars. Defaults to False. +.. |include_card_uri| replace:: A boolean indicating if the retrieved Tweet should include a card_uri attribute when there is an ads card attached to the Tweet and when that card was attached using the card_uri value. +.. |include_entities| replace:: The entities node will not be included when set to false. Defaults to true. +.. |include_ext_alt_text| replace:: If alt text has been added to any attached media entities, this parameter will return an ext_alt_text value in the top-level key for the media entity. +.. |include_user_entities| replace:: The user object entities node will not be included when set to false. Defaults to true. +.. |list_id| replace:: The 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 +.. |max_id| replace:: Returns only statuses with an ID less than (that is, older than) or equal to the specified ID. +.. |owner_id| replace:: The user ID of the user who owns the list being requested by a slug. +.. |owner_screen_name| replace:: The screen name of the user who owns the list being requested by a slug. +.. |page| replace:: Specifies the page of results to retrieve. Note: there are pagination limits. +.. |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. +.. |since_id| replace:: Returns only statuses with an ID greater than (that is, more recent than) the specified ID. +.. |skip_status| replace:: A boolean indicating whether statuses will not be included in the returned user objects. Defaults to false. +.. |slug| replace:: You can identify a list by its slug instead of its numerical id. If you decide to do so, note that you'll also have to specify the list owner using the owner_id or owner_screen_name parameters. +.. |trim_user| replace:: A boolean indicating if user IDs should be provided, instead of complete user objects. Defaults to False. +.. |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. + diff --git a/docs/running_tests.rst b/docs/running_tests.rst new file mode 100644 index 0000000..3131751 --- /dev/null +++ b/docs/running_tests.rst @@ -0,0 +1,29 @@ +.. _running_tests: + +************* +Running Tests +************* + +These steps outline how to run tests for Tweepy: + +1. Download Tweepy's source code to a directory. + +2. Install from the downloaded source with the ``test`` extra, e.g. + ``pip install .[test]``. Optionally install the ``dev`` extra as well, for + ``tox`` and ``coverage``, e.g. ``pip install .[dev,test]``. + +3. Run ``python setup.py nosetests`` or simply ``nosetests`` in the source + directory. With the ``dev`` extra, coverage will be shown, and ``tox`` can + also be run to test different Python versions. + +To record new cassettes, the following environment variables can be used: + +``TWITTER_USERNAME`` +``CONSUMER_KEY`` +``CONSUMER_SECRET`` +``ACCESS_KEY`` +``ACCESS_SECRET`` +``USE_REPLAY`` + +Simply set ``USE_REPLAY`` to ``False`` and provide the app and account +credentials and username. diff --git a/docs/streaming_how_to.rst b/docs/streaming_how_to.rst new file mode 100644 index 0000000..81d1539 --- /dev/null +++ b/docs/streaming_how_to.rst @@ -0,0 +1,124 @@ +.. _streaming_how_to: +.. _Twitter Streaming API Documentation: https://developer.twitter.com/en/docs/tweets/filter-realtime/overview +.. _Twitter Streaming API Connecting Documentation: https://developer.twitter.com/en/docs/tutorials/consuming-streaming-data +.. _Twitter Response Codes Documentation: https://dev.twitter.com/overview/api/response-codes + +********************* +Streaming With Tweepy +********************* +Tweepy makes it easier to use the twitter streaming api by handling authentication, +connection, creating and destroying the session, reading incoming messages, +and partially routing messages. + +This page aims to help you get started using Twitter streams with Tweepy +by offering a first walk through. Some features of Tweepy streaming are +not covered here. See streaming.py in the Tweepy source code. + +API authorization is required to access Twitter streams. +Follow the :ref:`auth_tutorial` if you need help with authentication. + +Summary +======= +The Twitter streaming API is used to download twitter messages in real +time. It is useful for obtaining a high volume of tweets, or for +creating a live feed using a site stream or user stream. +See the `Twitter Streaming API Documentation`_. + +The streaming api is quite different from the REST api because the +REST api is used to *pull* data from twitter but the streaming api +*pushes* messages to a persistent session. This allows the streaming +api to download more data in real time than could be done using the +REST API. + +In Tweepy, an instance of **tweepy.Stream** establishes a streaming +session and routes messages to **StreamListener** instance. The +**on_data** method of a stream listener receives all messages and +calls functions according to the message type. The default +**StreamListener** can classify most common twitter messages and +routes them to appropriately named methods, but these methods are +only stubs. + +Therefore using the streaming api has three steps. + +1. Create a class inheriting from **StreamListener** + +2. Using that class create a **Stream** object + +3. Connect to the Twitter API using the **Stream**. + + +Step 1: Creating a **StreamListener** +===================================== +This simple stream listener prints status text. +The **on_data** method of Tweepy's **StreamListener** conveniently passes +data from statuses to the **on_status** method. +Create class **MyStreamListener** inheriting from **StreamListener** +and overriding **on_status**.:: + import tweepy + #override tweepy.StreamListener to add logic to on_status + class MyStreamListener(tweepy.StreamListener): + + def on_status(self, status): + print(status.text) + +Step 2: Creating a **Stream** +============================= +We need an api to stream. See :ref:`auth_tutorial` to learn how to get an api object. +Once we have an api and a status listener we can create our stream object.:: + + myStreamListener = MyStreamListener() + myStream = tweepy.Stream(auth = api.auth, listener=myStreamListener) + +Step 3: Starting a Stream +========================= +A number of twitter streams are available through Tweepy. Most cases +will use filter, the user_stream, or the sitestream. +For more information on the capabilities and limitations of the different +streams see `Twitter Streaming API Documentation`_. + +In this example we will use **filter** to stream all tweets containing +the word *python*. The **track** parameter is an array of search terms to stream. :: + + myStream.filter(track=['python']) + +This example shows how to use **filter** to stream tweets by a specific user. The **follow** parameter is an array of IDs. :: + + myStream.filter(follow=["2211149702"]) + +An easy way to find a single ID is to use one of the many conversion websites: search for 'what is my twitter ID'. + +A Few More Pointers +=================== + +Async Streaming +--------------- +Streams do not terminate unless the connection is closed, blocking the thread. +Tweepy offers a convenient **is_async** parameter on **filter** so the stream will run on a new +thread. For example :: + + myStream.filter(track=['python'], is_async=True) + +Handling Errors +--------------- +When using Twitter's streaming API one must be careful of the dangers of +rate limiting. If clients exceed a limited number of attempts to connect to the streaming API +in a window of time, they will receive error 420. The amount of time a client has to wait after receiving error 420 +will increase exponentially each time they make a failed attempt. + +Tweepy's **Stream Listener** passes error codes to an **on_error** stub. The +default implementation returns **False** for all codes, but we can override it +to allow Tweepy to reconnect for some or all codes, using the backoff +strategies recommended in the `Twitter Streaming API Connecting +Documentation`_. :: + + class MyStreamListener(tweepy.StreamListener): + + def on_error(self, status_code): + if status_code == 420: + #returning False in on_error disconnects the stream + return False + + # returning non-False reconnects the stream, with backoff. + +For more information on error codes from the Twitter API see `Twitter Response Codes Documentation`_. + -- 2.25.1