Tweepy Version 4.0.0

Major New Features / Improvements

• Support Twitter API v2 (#1472, #1535)

  • Replace API v1.1 models in package namespace

• Rework media uploading (#640, #1486, #1501)

• Support asynchronous streaming (#732, #1491)

• Rework API

  • Replace bind_api and APIMethod with API.request
    • Stop using property decorators for API methods
    • Use pagination decorator
  • Add requests.Session instance as API.session attribute (2f28757)
    • Initialize a single requests.Session instance per API instance, rather than for each request
  • Log warning when API.request is passed an unexpected keyword argument that isn't an endpoint parameter (c82d7ac)
  • Rename allowed parameters (allowed_param) to endpoint parameters (endpoint_parameters) (b4fc6a0)
  • Rename methods and method parameters (see Breaking Changes section)
  • Require parameters for methods (see Breaking Changes section)
  • Stop allowing arbitrary positional arguments for methods (see Breaking Changes section)
  • Remove unnecessary attributes and parameters (see Breaking Changes section)
  • Improve, optimize, and simplify API.request and other API methods

• Rework streaming

  • StreamListener has been merged into Stream (see Breaking Changes section)
  • Stream data/event handling methods (i.e. those starting with on_) now log by default and disregard return values
  • Allow the stream to disconnect when any line of data is received, including keep-alive signals (#773, #897)
  • Remove, rename, and replace attributes, methods, and parameters (see Breaking Changes section)
  • Improve, optimize, and simplify Stream

• Rework documentation

  • Automatically use docstrings for documentation
  • Use NumPy style docstrings
  • Use Intersphinx linking
  • Add tooltips for cross references using sphinx-hoverxref
  • Document Stream (18a6059)
  • Document models (0724060, 78a0c22)
  • Document pagination (695d531, 652fece)
  • Add table for API documentation (6db8e4c)
  • Separate documentation for exceptions (8a831b1)
  • Move changelog to documentation (fc98629)
  • Update, improve, and organize documentation

• Rework exceptions

  • Replace TweepError with TweepyException (5c39cd1) and HTTPException (#599)
  • Replace RateLimitError with TooManyRequests (cd5f696)
  • Remove Parser.parse_error (cd5f696)
  • Add NotFound (2d84b27)
  • Add Unauthorized (3ffec76)
  • Add Forbidden (4a9bc58)
  • Add BadRequest (3da5ede)
  • Add TwitterServerError (b443557)

Breaking Changes

• Drop support for Python 2 (#1253, #1482)
• Drop support for Python 3.5 (#1487)

API

• Rename API and models methods
  • API.blocks -> API.get_blocks (9541794)
  • API.blocks_ids -> API.get_blocked_ids (e241ca4)
  • API.destroy_direct_message -> API.delete_direct_message (2731fc9)
    • DirectMessage.destroy -> DirectMessage.delete (2731fc9)
  • API.favorites -> API.get_favorites (3c467da)
  • API.followers -> API.get_followers (ce768d9)
  • API.followers_ids -> API.get_follower_ids (fa5e7c4)
    • models.User.followers_ids -> models.User.follower_ids (fa5e7c4)
  • API.friends -> API.get_friends (6f3fccb)
  • API.friends_ids -> API.get_friend_ids (bab3e5e)
  • API.friendships_incoming -> API.incoming_friendships (007bd07)
  • API.friendships_outgoing -> API.outgoing_friendships (1400065)
  • API.geo_search -> API.search_geo (6f4fb39)
  • API.list_direct_messages -> API.get_direct_messages (ff1186f)
  • API.list_members -> API.get_list_members (5845f02)
  • API.list_subscribers -> API.get_list_subscribers (a05b630)
  • API.lists_all -> API.get_lists (458e0e8)
  • API.lists_memberships -> API.get_list_memberships (9dddc12)
    • models.User.lists_memberships -> models.User.list_memberships (9dddc12)
  • API.lists_subscriptions -> API.get_list_subscriptions (51945a7)
    • models.User.lists_subscriptions -> models.User.list_subscriptions (51945a7)
  • API.mutes -> API.get_mutes (744edc2)
  • API.mutes_ids -> API.get_muted_ids (ea26a29)
  • API.retweeters -> API.get_retweeter_ids (588c342)
  • API.retweets -> API.get_retweets (3b3ba24)
  • API.retweets_of_me -> API.get_retweets_of_me (737bd0b)
  • API.saved_searches -> API.get_saved_searches (8b39f74)
  • API.search -> API.search_tweets (7fac253)
  • API.show_friendship -> API.get_friendship (ee9ea2e)
  • API.show_list_member -> API.get_list_member (431ab15)
  • API.show_list_subscriber -> API.get_list_subscriber (bf26301)
  • API.statuses_lookup -> API.lookup_statuses (#477)
  • API.trends_available -> API.available_trends (68b33d7)
  • API.trends_closest -> API.closest_trends (2e18162)
  • API.trends_place -> API.get_place_trends (4912a7c)
  • API.update_with_media -> API.update_status_with_media (0a5e533)
• Rename API method parameters
  • API.geo_id: id -> place_id (78051e8)
  • API.lookup_friendships: screen_names -> screen_name (4573b35), user_ids -> user_id (3bcccf8)
  • API.lookup_statuses: id_ -> id (f13a34b)
  • API.lookup_users: screen_names -> screen_name (17a2e7c), user_ids -> user_id (e7d9e55)
  • API.search_30_day: environment_name -> label (6c66c60)
  • API.search_full_archive: environment_name -> label (295bfe4)
  • API.update_profile_image: file_ -> file (69f6c1d)
• Require API method parameters
  • API.closest_trends: lat, long (75b9616)
  • API.create_favorite: id (d3d2abe)
  • API.create_list: name (5e7385a)
  • API.create_saved_search: query (c57a4be)
  • API.delete_direct_message: id (bcb56ab)
  • API.destroy_favorite: id (a9d41b6)
  • API.get_direct_message: id (f5775ee)
  • API.get_oembed: url (af0cc51)
  • API.get_place_trends: id (c50f540)
  • API.get_retweeter_ids: id (66f6704)
  • API.get_status: id (bac73c3)
  • API.reverse_geocode: lat, long (87d8646)
  • API.search_30_day: query (52874b7)
  • API.search_full_archive: query (801f15d)
  • API.search_tweets: q (9377e7e)
  • API.search_users: q (21802f9)
  • API.update_status: status (f64c076)
  • API.update_status_with_media: status (0726263)
• Stop allowing positional arguments for API methods (change to be keyword-only arguments):
  • API.add_list_member (ae18ee5)
  • API.add_list_members (8eb900f)
  • API.available_trends (7a74863)
  • API.closest_trends, besides lat and long (7946490)
  • API.create_block (caa34c6)
  • API.create_favorite, besides id (0b83984)
  • API.create_friendship (82cd798)
  • API.create_list, besides name (25cb01e)
  • API.create_mute (4aae710)
  • API.create_saved_search, besides query (76be2d9)
  • API.delete_direct_message, besides id (53ca00f)
  • API.destroy_block (c49cfb2)
  • API.destroy_favorite, besides id (8afee87)
  • API.destroy_friendship (b2d44fe)
  • API.destroy_list (4b2cfc4)
  • API.destroy_mute (009b54e)
  • API.destroy_saved_search, besides id (b7afca2)
  • API.destroy_status, besides id (876c8ca)
  • API.geo_id, besides place_id (a0cff22)
  • API.get_blocked_ids (ff38b70)
  • API.get_blocks (dc81854)
  • API.get_direct_message, besides id (4ae0ec8)
  • API.get_direct_messages (8e0507d)
  • API.get_favorites (e80b49a)
  • API.get_follower_ids (7d42597)
  • API.get_followers (c6ab5a0)
  • API.get_friend_ids (c65641b)
  • API.get_friends (e6965fa)
  • API.get_friendship (6dea7de)
  • API.get_list (92dc37f)
  • API.get_list_member (0af06db)
  • API.get_list_members (7c8be8d)
  • API.get_list_memberships (ec7601f)
  • API.get_list_subscriber (a175cdd)
  • API.get_list_subscribers (3ee84ef)
  • API.get_list_subscriptions (178d719)
  • API.get_lists (3cd0058)
  • API.get_muted_ids (2967104)
  • API.get_mutes (9e9d370)
  • API.get_oembed, besides url (d13d853)
  • API.get_place_trends, besides id (548810c)
  • API.get_retweeter_ids, besides id (9907c25)
  • API.get_retweets, besides id (0bd0292)
  • API.get_retweets_of_me (2b2ed0a)
  • API.get_saved_search, besides id (1d3d3ae)
  • API.get_saved_searches (c5f5b4b)
  • API.get_settings (2c2f0ec)
  • API.get_status, besides id (30af3ac)
  • API.get_user (6b761ce)
  • API.home_timeline (b91be22)
  • API.incoming_friendships (6d3b7f2)
  • API.list_timeline (e3ec5c1)
  • API.lookup_friendships (0eff951)
  • API.lookup_statuses, besides id (cf9845d)
  • API.lookup_users (7317109)
  • API.media_upload, besides filename (ec2498f)
  • API.mentions_timeline (3614ce4)
  • API.outgoing_friendships (09f8504)
  • API.rate_limit_status (b4b91c1)
  • API.remove_list_member (e7fa800)
  • API.remove_list_members (593ef1c)
  • API.report_spam (f55efcf)
  • API.retweet, besides id (4f7be88)
  • API.reverse_geocode: besides lat and long (b209c48)
  • API.search_30_day, besides label and query (434fd35)
  • API.search_full_archive, besides label and query (44391bc)
  • API.search_geo (0a6bec9)
  • API.search_tweets, besides q (445da4e)
  • API.search_users, besides q (76ca416)
  • API.send_direct_message, besides recipient_id and text (7d1a549)
  • API.set_settings (bf1d928)
  • API.supported_languages (2034efc)
  • API.subscribe_list (ee3b718)
  • API.unretweet, besides id (4626c42)
  • API.unsubscribe_list (2df2311)
  • API.update_list (8b3b4fb)
  • API.update_profile (99cd815)
  • API.update_profile_banner, besides filename (1ca22be)
  • API.update_profile_image, besides filename (3539fa2)
  • API.update_status, besides status (761cbfe)
  • API.update_status_with_media, besides filename and status (0ac4e83)
  • API.user_timeline (0ef964f)
• Reorder API.update_status_with_media parameters (87abdcd)
• Rename API initialization parameter: auth_handler -> auth (ee313bd)
• Stop allowing positional arguments besides auth for API initialization (da2f276)
• Remove API.api_root and API.upload_root (e757919)
• Remove API.compression (4590c7a)
• Remove API.me, AuthHandler.get_username, and OAuthHandler.get_username (807f937)
• Remove API.search_host and API.search_root (92db0cf)
• Remove API.wait_on_rate_limit_notify (f325738)
  • Always log warning when rate limit reached
• Remove map_ keyword argument aliasing for API.lookup_statuses (0a404c3)

Stream

• Remove and replace StreamListener by merging it into Stream (39abff4)
  • StreamListener.keep_alive -> Stream.on_keep_alive (abf4d5d)
  • StreamListener.on_connect -> Stream.on_connect
  • StreamListener.on_data -> Stream.on_data
  • StreamListener.on_delete -> Stream.on_delete
  • StreamListener.on_disconnect -> Stream.on_disconnect_message (6c3b997)
  • StreamListener.on_error -> Stream.on_request_error (fe3bb8b)
  • StreamListener.on_exception -> Stream.on_exception
  • StreamListener.on_limit -> Stream.on_limit
  • StreamListener.on_scrub_geo -> Stream.on_scrub_geo
  • StreamListener.on_status -> Stream.on_status
  • StreamListener.on_status_withheld -> Stream.on_status_withheld
  • StreamListener.on_timeout -> Stream.on_connection_error (8f62297)
  • StreamListener.on_user_withheld -> Stream.on_user_withheld
  • StreamListener.on_warning -> Stream.on_warning
• Remove Stream.api (21a9db2)
• Remove Stream.body (3e40193)
• Remove Stream.headers (d07af4e)
• Remove Stream.host (9cf8518)
• Remove Stream.new_session (26518ab)
• Remove Stream.timeout (a2f79f1)
• Remove Stream.url (48cbf97)
• Remove Stream parameters and attributes for reconnect wait times (24059d4)
  • Remove Stream.retry_time_start, Stream.retry_420_start, Stream.retry_time_cap, Stream.snooze_time_step, Stream.snooze_time_cap, Stream.retry_time, and Stream.snooze_time
• Rename Stream.retry_count to Stream.max_retries (3585f13)
• Replace Stream.auth with parameters and attributes for each credential (c9f59e6)
  • Replace Stream.auth with Stream.consumer_key, Stream.consumer_secret, Stream.access_token, and Stream.access_token_secret
• Replace Stream parameter, proxies, with proxy (#1272)
• Remove Stream.filter parameter: encoding (b3f2db2)
• Rename Stream.filter and Stream.sample parameters: is_async -> threaded (6c96c15)
• Stop allowing positional arguments for Stream.filter (0629d5f)
• Stop allowing positional arguments for Stream.sample (b170720)

Twitter API Breaking Changes

• Remove API.configuration (#1614)
• Remove API.geo_similar_places (c6cfd97)
• Remove API.related_results (068273b)
  • Remove Relation model (cc4479a)
• Remove id endpoint parameter for API.create_block (e4eaa4b)
• Remove id endpoint parameter for API.create_friendship (6a3c1ab)
• Remove id endpoint parameter for API.create_mute (bb25d69)
• Remove id endpoint parameter for API.destroy_block (1a9b52d)
• Remove id endpoint parameter for API.destroy_friendship (66f1612)
• Remove id endpoint parameter for API.destroy_mute (8c444c5)
• Remove id endpoint parameter for API.get_follower_ids (5cddd12)
• Remove id endpoint parameter for API.get_followers (a3fb959)
• Remove id endpoint parameter for API.get_friend_ids(7cbf818)
• Remove id endpoint parameter for API.get_friends (6875e15)
• Remove id endpoint parameter for API.get_user (a2681ed)
• Remove accuracy and contained_within endpoint parameters for API.search_geo (d37a409)
• Remove allow_contributor_request endpoint parameter for API.set_settings (1cc33b2)
• Update API.update_profile_banner endpoint parameters: offset_right -> offset_top (83f9b79)
• Remove enable_dmcommands and fail_dmcommands parameters for API.update_status (fe5b3ef)
• Remove in_reply_to_status_id_str and auto_populate_reply_metadata endpoint parameters for API.update_status_with_media (c3c9d29)
• Remove id endpoint parameter for API.user_timeline (#1484)
• Remove Stream.firehose (ad50cdc)
• Remove Stream.retweet(6b1944b)
• Remove Stream.sitestream and Stream.userstream (96f7e63)
  • Remove StreamListener.on_direct_message and StreamListener.on_friends (ab2479b)
  • Remove StreamListener.on_event (20b5afb)

Other

• Datetime objects for models.List.created_at, models.SavedSearch.created_at, models.Status.created_at, and models.User.created_at are now aware (59d4d92)
• Change return_cursors parameter for JSONParser.parse and ModelParser.parse to be keyword-only argument (56b8e31)
• Remove method parameter from parse method for Parser and its subclasses (dda2ec6)
• Remove handling of 401 HTTP status code in API.verify_credentials (7e4d2a4)
• Remove models.List.is_member and models.List.is_subscribed (b765aee)

New Features / Improvements

New Methods And Parameters / Attributes

• Add API.get_list_ownerships (#1282, #1498)
  • Add models.User.list_ownerships (#1282)
• Add API.get_profile_banner (58ac8bb)
• Add API.no_retweets_friendships (496a399)
• Add API.remove_profile_banner (f0e53c6)
• Add API.update_friendship (ddd24a4)
• Add API.user_agent (bbec64b)
• Add endpoint parameters for API methods:
  • API.create_block: include_entities, skip_status (5e694b2)
  • API.create_favorite: include_entities (65c7ce7)
  • API.destroy_block: include_entities, skip_status (7299362)
  • API.destroy_favorite: include_entities (ecd19f0)
  • API.destroy_status: trim_user (ed363e6)
  • API.get_blocked_ids: stringify_ids (316b4cc)
  • API.get_blocks: include_entities, skip_status (7ef1e85)
  • API.get_favorites: include_entities (2b91edc)
  • API.get_follower_ids: stringify_ids (c490027)
  • API.get_friend_ids: stringify_ids, count (aba327e)
  • API.get_list_member: include_entities, skip_status (e959787)
  • API.get_list_members: count, include_entities, skip_status (232fa29)
  • API.get_list_subscriber: include_entities, skip_status (783941a)
  • API.get_muted_ids: stringify_ids (8b04108)
  • API.get_retweeter_ids: count (71ca488)
  • API.get_retweets: trim_user (e377188)
  • API.get_retweets_of_me: trim_user, include_entities, include_user_entities (589d97d)
  • API.get_user: include_entities (485691d)
  • API.incoming_friendships: stringify_ids (ffb7c0e)
  • API.media_upload: media_category, additional_owners (#1486)
  • API.mentions_timeline: trim_user, include_entities (eb7c8f6)
  • API.outgoing_friendships: stringify_ids (7ed0762)
  • API.retweet: trim_user (70d9665)
  • API.search_users: include_entities (8d64b61)
  • API.unretweet: trim_user (6d93f3b)
  • API.update_profile: include_entities, skip_status (9715c4a)
• Add Stream.on_disconnect method (#277)
• Expose Stream.thread (9c2419d)

New Functionality

• Allow sending Quick Reply Options with Direct Messages (#1280)
  • Replace API.send_direct_message parameter, quick_reply_type, with quick_reply_options
• Allow sending Call-To-Action buttons with Direct Messages in API.send_direct_message (#1311)

Documentation For Existing Methods

• Document API.get_settings (cbac800)
• Document API.incoming_friendships (09dbe0e)
• Document API.outgoing_friendships (8ff5f22)
• Document API.search_geo (a51a097)
• Document API.set_settings (4703da3)
• Document API.supported_languages (9bb8446)
• Document API.update_profile_banner (a5df615)

Dependencies

• Update requests_oauthlib dependency requirement to >= 1.0.0 (bf629e5)
• Remove requests socks extra from setup.py install_requires (38b6de6)
  • Add socks extra requiring requests socks extra

Other

• Check consumer key and secret type when initializing OAuthHandler (#1489)
• Make models.User hashable (#1306)
• Reduce extra sleep time for rate limit handling for API (#1049)
• Handle keyword arguments for API.update_profile_image (ab96f2f)
• Handle keyword arguments for API.update_profile_banner (88c3fa1)
• Treat all 2xx HTTP status codes as successful responses (a0f6984)
• Support gevent for streaming (#651)
• Return thread when using threaded Stream.filter and Stream.sample (2e957b6)
• Use specific user agent for Stream (5994c4b)

Misc

• Update and improve various documentation and tests
• Various other optimizations and improvements

Bug Fixes

• Handle connection errors when streaming (#237, #448, #750, #1024, #1113, #1416)
• Remove dependence on string length delimitation in Stream (#892)
• Stop reraising exceptions in Stream._connect (#1072)
• Change Stream.sample method to use GET HTTP method (1b0e869)
• Default to models.User model in models.Status.parse more broadly for user attribute to handle parsers without model_factory attribute or model factories without user attribute (41e7afa)
• Default to models.Status model in models.SearchResults.parse more broadly for results to handle parsers without model_factory attribute or model factories without status attribute (71c031b)
• Start on page 1 for PageIterator (#958)
• Handle Twitter API issue with duplicate pages for API.search_users (#958, #1465)
• Allow integer IDs for Stream.filter (#829, #830)
• Handle ChunkedEncodingError during streaming (e8fcc4d)
• Handle Twitter API errors with successful HTTP status codes (#1427)
• Handle initial negative or zero limits in Cursor iterators (c1457b7)