twython-3.4.0/0000755000076500000240000000000012711075147014644 5ustar mikehelmickstaff00000000000000twython-3.4.0/HISTORY.rst0000644000076500000240000003006512711074360016537 0ustar mikehelmickstaff00000000000000.. :changelog: History ------- 3.4.0 (2016-30-04) ++++++++++++++++++ - Added `upload_video` endpoint - Fix quoted status checks in `html_for_tweet` - Fix `html_for_tweet` method response when hashtag/mention is a substring of another 3.3.0 (2015-18-07) ++++++++++++++++++ - Added support for muting users - Fix typos in documentation - Updated documentation examples - Added dynamic filtering to streamer 3.2.0 (2014-10-30) ++++++++++++++++++ - PEP8'd some code - Added `lookup_status` function to `endpoints.py` - Added keyword argument to `cursor` to return full pages rather than individual results - `cursor` now uses while loop rather than recursion - Fixed issue where Twython was unnecessarily disabling compression - Using `responses` to mock API calls in tests - Fixed some typos in documentation - Added `retry_after` attribute to `TwythonRateLimitError` - Added `upload_media` method to `Twython` in favor of `update_with_media` - Deprecating `update_with_media` per Twitter API 1.1 (https://dev.twitter.com/rest/reference/post/statuses/update_with_media) - Unpin `requests` and `requests-oauthlib` in `requirements.txt` 3.1.2 (2013-12-05) ++++++++++++++++++ - Fixed Changelog (HISTORY.rst) 3.1.1 (2013-12-05) ++++++++++++++++++ - Update `requests` version to 2.1.0. - Fixed: Streaming issue where `Exceptions` in handlers or `on_success` which subclass `ValueError` would previously be caught and reported as a JSON decoding problem, and `on_error()` would be called (with status_code=200) - Fixed issue where XML was returned when bad tokens were passed to `get_authorized_tokens` - Fixed import for `setup` causing installation to fail on some devices (eg. Nokia N9/MeeGo) 3.1.0 (2013-09-25) ++++++++++++++++++ - Added ``html_for_tweet`` static method. This method accepts a tweet object returned from a Twitter API call and will return a string with urls, mentions and hashtags in the tweet replaced with HTML. - Pass ``client_args`` to the streaming ``__init__``, much like in core Twython (you can pass headers, timeout, hooks, proxies, etc.). - Streamer has new parameter ``handlers`` which accepts a list of strings related to functions that are apart of the Streaming class and start with "on\_". i.e. ['delete'] is passed, when 'delete' is received from a stream response; ``on_delete`` will be called. - When an actual request error happens and a ``RequestException`` is raised, it is caught and a ``TwythonError`` is raised instead for convenience. - Added "cursor"-like functionality. Endpoints with the attribute ``iter_mode`` will be able to be passed to ``Twython.cursor`` and returned as a generator. - ``Twython.search_gen`` has been deprecated. Please use ``twitter.cursor(twitter.search, q='your_query')`` instead, where ``twitter`` is your ``Twython`` instance. - Added methods ``get_list_memberships``, ``get_twitter_configuration``, ``get_supported_languages``, ``get_privacy_policy``, ``get_tos`` - Added ``auth_endpoint`` parameter to ``Twython.__init__`` for cases when the right parameters weren't being shown during the authentication step. - Fixed streaming issue where results wouldn't be returned for streams that weren't so active (See https://github.com/ryanmcgrath/twython/issues/202#issuecomment-19915708) - Streaming API now uses ``_transparent_params`` so when passed ``True`` or ``False`` or an array, etc. Twython formats it to meet Twitter parameter standards (i.e. ['ryanmcgrath', 'mikehelmick', 'twitterapi'] would convert to string 'ryanmcgrath,mikehelmick,twitterapi') 3.0.0 (2013-06-18) ++++++++++++++++++ - Changed ``twython/twython.py`` to ``twython/api.py`` in attempt to make structure look a little neater - Removed all camelCase function access (anything like ``getHomeTimeline`` is now ``get_home_timeline``) - Removed ``shorten_url``. With the ``requests`` library, shortening a URL on your own is simple enough - ``twitter_token``, ``twitter_secret`` and ``callback_url`` are no longer passed to ``Twython.__init__`` - ``twitter_token`` and ``twitter_secret`` have been replaced with ``app_key`` and ``app_secret`` respectively - ``callback_url`` is now passed through ``Twython.get_authentication_tokens`` - Update ``test_twython.py`` docstrings per http://www.python.org/dev/peps/pep-0257/ - Removed ``get_list_memberships``, method is Twitter API 1.0 deprecated - Developers can now pass an array as a parameter to Twitter API methods and they will be automatically joined by a comma and converted to a string - ``endpoints.py`` now contains ``EndpointsMixin`` (rather than the previous ``api_table`` dict) for Twython, which enables Twython to use functions declared in the Mixin. - Added OAuth 2 authentication (Application Only) for when you want to make read-only calls to Twitter without having to go through the whole user authentication ritual (see docs for usage) - Added ``obtain_access_token`` to obtain an OAuth 2 Application Only read-only access token - ``construct_api_url`` now accepts keyword arguments like other Twython methods (e.g. instead of passing ``{'q': 'twitter', 'result_type': 'recent'}``, pass ``q='twitter', result_type='recent'``) - Pass ``client_args`` to the Twython ``__init__`` to manipulate request variables. ``client_args`` accepts a dictionary of keywords and values that accepted by ``requests`` (`Session API `_) [ex. headers, proxies, verify(SSL verification)] and the "request" section directly below it. - Added ``get_application_rate_limit_status`` API method for returning the current rate limits for the specified source - Added ``invalidate_token`` API method which allows registed apps to revoke an access token presenting its client credentials - ``get_lastfunction_header`` now accepts a ``default_return_value`` parameter. This means that if you pass a second value (ex. ``Twython.get_lastfunction_header('x-rate-limit-remaining', 0)``) and the value is not found, it returns your default value 2.10.1 (2013-05-29) ++++++++++++++++++ - More test coverage! - Fix ``search_gen`` - Fixed ``get_lastfunction_header`` to actually do what its docstring says, returns ``None`` if header is not found - Updated some internal API code, ``__init__`` didn't need to have ``self.auth`` and ``self.headers`` because they were never used anywhere else but the ``__init__`` - Added ``disconnect`` method to ``TwythonStreamer``, allowing users to disconnect as they desire - Updated ``TwythonStreamError`` docstring, also allow importing it from ``twython`` - No longer raise ``TwythonStreamError`` when stream line can't be decoded. Instead, sends signal to ``TwythonStreamer.on_error`` - Allow for (int, long, float) params to be passed to Twython Twitter API functions in Python 2, and (int, float) in Python 3 2.10.0 (2013-05-21) ++++++++++++++++++ - Added ``get_retweeters_ids`` method - Fixed ``TwythonDeprecationWarning`` on camelCase functions if the camelCase was the same as the PEP8 function (i.e. ``Twython.retweet`` did not change) - Fixed error message bubbling when error message returned from Twitter was not an array (i.e. if you try to retweet something twice, the error is not found at index 0) - Added "transparent" parameters for making requests, meaning users can pass bool values (True, False) to Twython methods and we convert your params in the background to satisfy the Twitter API. Also, file objects can now be passed seamlessly (see examples in README and in /examples dir for details) - Callback URL is optional in ``get_authentication_tokens`` to accomedate those using OOB authorization (non web clients) - Not part of the python package, but tests are now available along with Travis CI hooks - Added ``__repr__`` definition for Twython, when calling only returning - Cleaned up ``Twython.construct_api_url``, uses "transparent" parameters (see 4th bullet in this version for explaination) - Update ``requests`` and ``requests-oauthlib`` requirements, fixing posting files AND post data together, making authenticated requests in general in Python 3.3 2.9.1 (2013-05-04) ++++++++++++++++++ - "PEP8" all the functions. Switch functions from camelCase() to underscore_funcs(). (i.e. ``updateStatus()`` is now ``update_status()``) 2.9.0 (2013-05-04) ++++++++++++++++++ - Fixed streaming issue #144, added ``TwythonStreamer`` to aid users in a friendly streaming experience (streaming examples in ``examples`` and README's have been updated as well) - ``Twython`` now requires ``requests-oauthlib`` 0.3.1, fixes #154 (unable to upload media when sending POST data with the file) 2.8.0 (2013-04-29) ++++++++++++++++++ - Added a ``HISTORY.rst`` to start tracking history of changes - Updated ``twitter_endpoints.py`` to ``endpoints.py`` for cleanliness - Removed twython3k directory, no longer needed - Added ``compat.py`` for compatability with Python 2.6 and greater - Added some ascii art, moved description of Twython and ``__author__`` to ``__init__.py`` - Added ``version.py`` to store the current Twython version, instead of repeating it twice -- it also had to go into it's own file because of dependencies of ``requests`` and ``requests-oauthlib``, install would fail because those libraries weren't installed yet (on fresh install of Twython) - Removed ``find_packages()`` from ``setup.py``, only one package (we can just define it) - added quick publish method for Ryan and I: ``python setup.py publish`` is faster to type and easier to remember than ``python setup.py sdist upload`` - Removed ``base_url`` from ``endpoints.py`` because we're just repeating it in ``Twython.__init__`` - ``Twython.get_authentication_tokens()`` now takes ``callback_url`` argument rather than passing the ``callback_url`` through ``Twython.__init__``, ``callback_url`` is only used in the ``get_authentication_tokens`` method and nowhere else (kept in init though for backwards compatability) - Updated README to better reflect current Twython codebase - Added ``warnings.simplefilter('default')`` line in ``twython.py`` for Python 2.7 and greater to display Deprecation Warnings in console - Added Deprecation Warnings for usage of ``twitter_token``, ``twitter_secret`` and ``callback_url`` in ``Twython.__init__`` - Headers now always include the User-Agent as Twython vXX unless User-Agent is overwritten - Removed senseless TwythonError thrown if method is not GET or POST, who cares -- if the user passes something other than GET or POST just let Twitter return the error that they messed up - Removed conversion to unicode of (int, bool) params passed to a requests. ``requests`` isn't greedy about variables that can't be converted to unicode anymore - Removed `bulkUserLookup` (please use `lookupUser` instead), removed `getProfileImageUrl` (will be completely removed from Twitter API on May 7th, 2013) - Updated shortenUrl to actually work for those using it, but it is being deprecated since `requests` makes it easy for developers to implement their own url shortening in their app (see https://github.com/ryanmcgrath/twython/issues/184) - Twython Deprecation Warnings will now be seen in shell when using Python 2.7 and greater - Twython now takes ``ssl_verify`` parameter, defaults True. Set False if you're having development server issues - Removed internal ``_media_update`` function, we could have always just used ``self.post`` 2.7.3 (2013-04-12) ++++++++++++++++++ - Fixed issue where Twython Exceptions were not being logged correctly 2.7.2 (2013-04-08) ++++++++++++++++++ - Fixed ``AttributeError`` when trying to decode the JSON response via ``Response.json()`` 2.7.1 (2013-04-08) ++++++++++++++++++ - Removed ``simplejson`` dependency - Fixed ``destroyDirectMessage``, ``createBlock``, ``destroyBlock`` endpoints in ``twitter_endpoints.py`` - Added ``getProfileBannerSizes`` method to ``twitter_endpoints.py`` - Made oauth_verifier argument required in ``get_authorized_tokens`` - Update ``updateProfileBannerImage`` to use v1.1 endpoint 2.7.0 (2013-04-04) ++++++++++++++++++ - New ``showOwnedLists`` method 2.7.0 (2013-03-31) ++++++++++++++++++ - Added missing slash to ``getMentionsTimeline`` in ``twitter_endpoints.py`` 2.6.0 (2013-03-29) ++++++++++++++++++ - Updated ``twitter_endpoints.py`` to better reflect order of API endpoints on the Twitter API v1.1 docs site twython-3.4.0/LICENSE0000644000076500000240000000206112711074104015640 0ustar mikehelmickstaff00000000000000The MIT License Copyright (c) 2013 Ryan McGrath Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. twython-3.4.0/MANIFEST.in0000644000076500000240000000007012711074104016367 0ustar mikehelmickstaff00000000000000include README.rst HISTORY.rst LICENSE requirements.txt twython-3.4.0/PKG-INFO0000644000076500000240000006031112711075147015742 0ustar mikehelmickstaff00000000000000Metadata-Version: 1.1 Name: twython Version: 3.4.0 Summary: Actively maintained, pure Python wrapper for the Twitter API. Supports both normal and streaming Twitter APIs Home-page: https://github.com/ryanmcgrath/twython/tree/master Author: Ryan McGrath Author-email: ryan@venodesigns.net License: The MIT License Copyright (c) 2013 Ryan McGrath Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Description: Twython ======= .. image:: https://img.shields.io/pypi/v/twython.svg?style=flat-square :target: https://pypi.python.org/pypi/twython .. image:: https://img.shields.io/pypi/dw/twython.svg?style=flat-square :target: https://pypi.python.org/pypi/twython .. image:: https://img.shields.io/travis/ryanmcgrath/twython.svg?style=flat-square :target: https://travis-ci.org/ryanmcgrath/twython .. image:: https://img.shields.io/coveralls/ryanmcgrath/twython/master.svg?style=flat-square :target: https://coveralls.io/r/ryanmcgrath/twython?branch=master ``Twython`` is the premier Python library providing an easy (and up-to-date) way to access Twitter data. Actively maintained and featuring support for Python 2.6+ and Python 3. It's been battle tested by companies, educational institutions and individuals alike. Try it today! Features -------- - Query data for: - User information - Twitter lists - Timelines - Direct Messages - and anything found in `the docs `_ - Image Uploading: - Update user status with an image - Change user avatar - Change user background image - Change user banner image - OAuth 2 Application Only (read-only) Support - Support for Twitter's Streaming API - Seamless Python 3 support! Installation ------------ Install Twython via `pip `_ .. code-block:: bash $ pip install twython or, with `easy_install `_ .. code-block:: bash $ easy_install twython But, hey... `that's up to you `_. Or, if you want the code that is currently on GitHub .. code-block:: bash git clone git://github.com/ryanmcgrath/twython.git cd twython python setup.py install Documentation ------------- Documentation is available at https://twython.readthedocs.org/en/latest/ Starting Out ------------ First, you'll want to head over to https://dev.twitter.com/apps and register an application! After you register, grab your applications ``Consumer Key`` and ``Consumer Secret`` from the application details tab. The most common type of authentication is Twitter user authentication using OAuth 1. If you're a web app planning to have users sign up with their Twitter account and interact with their timelines, updating their status, and stuff like that this **is** the authentication for you! First, you'll want to import Twython .. code-block:: python from twython import Twython Authentication ~~~~~~~~~~~~~~ Obtain Authorization URL ^^^^^^^^^^^^^^^^^^^^^^^^ Now, you'll want to create a Twython instance with your ``Consumer Key`` and ``Consumer Secret`` Only pass *callback_url* to *get_authentication_tokens* if your application is a Web Application Desktop and Mobile Applications **do not** require a callback_url .. code-block:: python APP_KEY = 'YOUR_APP_KEY' APP_SECRET = 'YOUR_APP_SECRET' twitter = Twython(APP_KEY, APP_SECRET) auth = twitter.get_authentication_tokens(callback_url='http://mysite.com/callback') From the ``auth`` variable, save the ``oauth_token`` and ``oauth_token_secret`` for later use (these are not the final auth tokens). In Django or other web frameworks, you might want to store it to a session variable .. code-block:: python OAUTH_TOKEN = auth['oauth_token'] OAUTH_TOKEN_SECRET = auth['oauth_token_secret'] Send the user to the authentication url, you can obtain it by accessing .. code-block:: python auth['auth_url'] Handling the Callback ^^^^^^^^^^^^^^^^^^^^^ If your application is a Desktop or Mobile Application *oauth_verifier* will be the PIN code After they authorize your application to access some of their account details, they'll be redirected to the callback url you specified in ``get_authentication_tokens`` You'll want to extract the ``oauth_verifier`` from the url. Django example: .. code-block:: python oauth_verifier = request.GET['oauth_verifier'] Now that you have the ``oauth_verifier`` stored to a variable, you'll want to create a new instance of Twython and grab the final user tokens .. code-block:: python twitter = Twython(APP_KEY, APP_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET) final_step = twitter.get_authorized_tokens(oauth_verifier) Once you have the final user tokens, store them in a database for later use:: OAUTH_TOKEN = final_step['oauth_token'] OAUTH_TOKEN_SECRET = final_step['oauth_token_secret'] For OAuth 2 (Application Only, read-only) authentication, see `our documentation `_ Dynamic Function Arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~ Keyword arguments to functions are mapped to the functions available for each endpoint in the Twitter API docs. Doing this allows us to be incredibly flexible in querying the Twitter API, so changes to the API aren't held up from you using them by this library. Basic Usage ----------- **Function definitions (i.e. get_home_timeline()) can be found by reading over twython/endpoints.py** Create a Twython instance with your application keys and the users OAuth tokens .. code-block:: python from twython import Twython twitter = Twython(APP_KEY, APP_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET) Authenticated Users Home Timeline ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Documentation: https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline .. code-block:: python twitter.get_home_timeline() Updating Status ~~~~~~~~~~~~~~~ This method makes use of dynamic arguments, `read more about them `_ Documentation: https://dev.twitter.com/docs/api/1/post/statuses/update .. code-block:: python twitter.update_status(status='See how easy using Twython is!') Searching ~~~~~~~~~ https://dev.twitter.com/docs/api/1.1/get/search/tweets says it takes "q" and "result_type" amongst other arguments .. code-block:: python twitter.search(q='twitter') twitter.search(q='twitter', result_type='popular') Advanced Usage -------------- - `Advanced Twython Usage `_ - `Streaming with Twython `_ Notes ----- - Twython 3.0.0 has been injected with 1000mgs of pure awesomeness! OAuth 2 application authentication is now supported. And a *whole lot* more! See the `CHANGELOG `_ for more details! Questions, Comments, etc? ------------------------- My hope is that Twython is so simple that you'd never *have* to ask any questions, but if you feel the need to contact me for this (or other) reasons, you can hit me up at ryan@venodesigns.net. Or if I'm to busy to answer, feel free to ping mikeh@ydekproductions.com as well. Follow us on Twitter: - `@ryanmcgrath `_ - `@mikehelmick `_ Want to help? ------------- Twython is useful, but ultimately only as useful as the people using it (say that ten times fast!). If you'd like to help, write example code, contribute patches, document things on the wiki, tweet about it. Your help is always appreciated! .. :changelog: History ------- 3.4.0 (2016-30-04) ++++++++++++++++++ - Added `upload_video` endpoint - Fix quoted status checks in `html_for_tweet` - Fix `html_for_tweet` method response when hashtag/mention is a substring of another 3.3.0 (2015-18-07) ++++++++++++++++++ - Added support for muting users - Fix typos in documentation - Updated documentation examples - Added dynamic filtering to streamer 3.2.0 (2014-10-30) ++++++++++++++++++ - PEP8'd some code - Added `lookup_status` function to `endpoints.py` - Added keyword argument to `cursor` to return full pages rather than individual results - `cursor` now uses while loop rather than recursion - Fixed issue where Twython was unnecessarily disabling compression - Using `responses` to mock API calls in tests - Fixed some typos in documentation - Added `retry_after` attribute to `TwythonRateLimitError` - Added `upload_media` method to `Twython` in favor of `update_with_media` - Deprecating `update_with_media` per Twitter API 1.1 (https://dev.twitter.com/rest/reference/post/statuses/update_with_media) - Unpin `requests` and `requests-oauthlib` in `requirements.txt` 3.1.2 (2013-12-05) ++++++++++++++++++ - Fixed Changelog (HISTORY.rst) 3.1.1 (2013-12-05) ++++++++++++++++++ - Update `requests` version to 2.1.0. - Fixed: Streaming issue where `Exceptions` in handlers or `on_success` which subclass `ValueError` would previously be caught and reported as a JSON decoding problem, and `on_error()` would be called (with status_code=200) - Fixed issue where XML was returned when bad tokens were passed to `get_authorized_tokens` - Fixed import for `setup` causing installation to fail on some devices (eg. Nokia N9/MeeGo) 3.1.0 (2013-09-25) ++++++++++++++++++ - Added ``html_for_tweet`` static method. This method accepts a tweet object returned from a Twitter API call and will return a string with urls, mentions and hashtags in the tweet replaced with HTML. - Pass ``client_args`` to the streaming ``__init__``, much like in core Twython (you can pass headers, timeout, hooks, proxies, etc.). - Streamer has new parameter ``handlers`` which accepts a list of strings related to functions that are apart of the Streaming class and start with "on\_". i.e. ['delete'] is passed, when 'delete' is received from a stream response; ``on_delete`` will be called. - When an actual request error happens and a ``RequestException`` is raised, it is caught and a ``TwythonError`` is raised instead for convenience. - Added "cursor"-like functionality. Endpoints with the attribute ``iter_mode`` will be able to be passed to ``Twython.cursor`` and returned as a generator. - ``Twython.search_gen`` has been deprecated. Please use ``twitter.cursor(twitter.search, q='your_query')`` instead, where ``twitter`` is your ``Twython`` instance. - Added methods ``get_list_memberships``, ``get_twitter_configuration``, ``get_supported_languages``, ``get_privacy_policy``, ``get_tos`` - Added ``auth_endpoint`` parameter to ``Twython.__init__`` for cases when the right parameters weren't being shown during the authentication step. - Fixed streaming issue where results wouldn't be returned for streams that weren't so active (See https://github.com/ryanmcgrath/twython/issues/202#issuecomment-19915708) - Streaming API now uses ``_transparent_params`` so when passed ``True`` or ``False`` or an array, etc. Twython formats it to meet Twitter parameter standards (i.e. ['ryanmcgrath', 'mikehelmick', 'twitterapi'] would convert to string 'ryanmcgrath,mikehelmick,twitterapi') 3.0.0 (2013-06-18) ++++++++++++++++++ - Changed ``twython/twython.py`` to ``twython/api.py`` in attempt to make structure look a little neater - Removed all camelCase function access (anything like ``getHomeTimeline`` is now ``get_home_timeline``) - Removed ``shorten_url``. With the ``requests`` library, shortening a URL on your own is simple enough - ``twitter_token``, ``twitter_secret`` and ``callback_url`` are no longer passed to ``Twython.__init__`` - ``twitter_token`` and ``twitter_secret`` have been replaced with ``app_key`` and ``app_secret`` respectively - ``callback_url`` is now passed through ``Twython.get_authentication_tokens`` - Update ``test_twython.py`` docstrings per http://www.python.org/dev/peps/pep-0257/ - Removed ``get_list_memberships``, method is Twitter API 1.0 deprecated - Developers can now pass an array as a parameter to Twitter API methods and they will be automatically joined by a comma and converted to a string - ``endpoints.py`` now contains ``EndpointsMixin`` (rather than the previous ``api_table`` dict) for Twython, which enables Twython to use functions declared in the Mixin. - Added OAuth 2 authentication (Application Only) for when you want to make read-only calls to Twitter without having to go through the whole user authentication ritual (see docs for usage) - Added ``obtain_access_token`` to obtain an OAuth 2 Application Only read-only access token - ``construct_api_url`` now accepts keyword arguments like other Twython methods (e.g. instead of passing ``{'q': 'twitter', 'result_type': 'recent'}``, pass ``q='twitter', result_type='recent'``) - Pass ``client_args`` to the Twython ``__init__`` to manipulate request variables. ``client_args`` accepts a dictionary of keywords and values that accepted by ``requests`` (`Session API `_) [ex. headers, proxies, verify(SSL verification)] and the "request" section directly below it. - Added ``get_application_rate_limit_status`` API method for returning the current rate limits for the specified source - Added ``invalidate_token`` API method which allows registed apps to revoke an access token presenting its client credentials - ``get_lastfunction_header`` now accepts a ``default_return_value`` parameter. This means that if you pass a second value (ex. ``Twython.get_lastfunction_header('x-rate-limit-remaining', 0)``) and the value is not found, it returns your default value 2.10.1 (2013-05-29) ++++++++++++++++++ - More test coverage! - Fix ``search_gen`` - Fixed ``get_lastfunction_header`` to actually do what its docstring says, returns ``None`` if header is not found - Updated some internal API code, ``__init__`` didn't need to have ``self.auth`` and ``self.headers`` because they were never used anywhere else but the ``__init__`` - Added ``disconnect`` method to ``TwythonStreamer``, allowing users to disconnect as they desire - Updated ``TwythonStreamError`` docstring, also allow importing it from ``twython`` - No longer raise ``TwythonStreamError`` when stream line can't be decoded. Instead, sends signal to ``TwythonStreamer.on_error`` - Allow for (int, long, float) params to be passed to Twython Twitter API functions in Python 2, and (int, float) in Python 3 2.10.0 (2013-05-21) ++++++++++++++++++ - Added ``get_retweeters_ids`` method - Fixed ``TwythonDeprecationWarning`` on camelCase functions if the camelCase was the same as the PEP8 function (i.e. ``Twython.retweet`` did not change) - Fixed error message bubbling when error message returned from Twitter was not an array (i.e. if you try to retweet something twice, the error is not found at index 0) - Added "transparent" parameters for making requests, meaning users can pass bool values (True, False) to Twython methods and we convert your params in the background to satisfy the Twitter API. Also, file objects can now be passed seamlessly (see examples in README and in /examples dir for details) - Callback URL is optional in ``get_authentication_tokens`` to accomedate those using OOB authorization (non web clients) - Not part of the python package, but tests are now available along with Travis CI hooks - Added ``__repr__`` definition for Twython, when calling only returning - Cleaned up ``Twython.construct_api_url``, uses "transparent" parameters (see 4th bullet in this version for explaination) - Update ``requests`` and ``requests-oauthlib`` requirements, fixing posting files AND post data together, making authenticated requests in general in Python 3.3 2.9.1 (2013-05-04) ++++++++++++++++++ - "PEP8" all the functions. Switch functions from camelCase() to underscore_funcs(). (i.e. ``updateStatus()`` is now ``update_status()``) 2.9.0 (2013-05-04) ++++++++++++++++++ - Fixed streaming issue #144, added ``TwythonStreamer`` to aid users in a friendly streaming experience (streaming examples in ``examples`` and README's have been updated as well) - ``Twython`` now requires ``requests-oauthlib`` 0.3.1, fixes #154 (unable to upload media when sending POST data with the file) 2.8.0 (2013-04-29) ++++++++++++++++++ - Added a ``HISTORY.rst`` to start tracking history of changes - Updated ``twitter_endpoints.py`` to ``endpoints.py`` for cleanliness - Removed twython3k directory, no longer needed - Added ``compat.py`` for compatability with Python 2.6 and greater - Added some ascii art, moved description of Twython and ``__author__`` to ``__init__.py`` - Added ``version.py`` to store the current Twython version, instead of repeating it twice -- it also had to go into it's own file because of dependencies of ``requests`` and ``requests-oauthlib``, install would fail because those libraries weren't installed yet (on fresh install of Twython) - Removed ``find_packages()`` from ``setup.py``, only one package (we can just define it) - added quick publish method for Ryan and I: ``python setup.py publish`` is faster to type and easier to remember than ``python setup.py sdist upload`` - Removed ``base_url`` from ``endpoints.py`` because we're just repeating it in ``Twython.__init__`` - ``Twython.get_authentication_tokens()`` now takes ``callback_url`` argument rather than passing the ``callback_url`` through ``Twython.__init__``, ``callback_url`` is only used in the ``get_authentication_tokens`` method and nowhere else (kept in init though for backwards compatability) - Updated README to better reflect current Twython codebase - Added ``warnings.simplefilter('default')`` line in ``twython.py`` for Python 2.7 and greater to display Deprecation Warnings in console - Added Deprecation Warnings for usage of ``twitter_token``, ``twitter_secret`` and ``callback_url`` in ``Twython.__init__`` - Headers now always include the User-Agent as Twython vXX unless User-Agent is overwritten - Removed senseless TwythonError thrown if method is not GET or POST, who cares -- if the user passes something other than GET or POST just let Twitter return the error that they messed up - Removed conversion to unicode of (int, bool) params passed to a requests. ``requests`` isn't greedy about variables that can't be converted to unicode anymore - Removed `bulkUserLookup` (please use `lookupUser` instead), removed `getProfileImageUrl` (will be completely removed from Twitter API on May 7th, 2013) - Updated shortenUrl to actually work for those using it, but it is being deprecated since `requests` makes it easy for developers to implement their own url shortening in their app (see https://github.com/ryanmcgrath/twython/issues/184) - Twython Deprecation Warnings will now be seen in shell when using Python 2.7 and greater - Twython now takes ``ssl_verify`` parameter, defaults True. Set False if you're having development server issues - Removed internal ``_media_update`` function, we could have always just used ``self.post`` 2.7.3 (2013-04-12) ++++++++++++++++++ - Fixed issue where Twython Exceptions were not being logged correctly 2.7.2 (2013-04-08) ++++++++++++++++++ - Fixed ``AttributeError`` when trying to decode the JSON response via ``Response.json()`` 2.7.1 (2013-04-08) ++++++++++++++++++ - Removed ``simplejson`` dependency - Fixed ``destroyDirectMessage``, ``createBlock``, ``destroyBlock`` endpoints in ``twitter_endpoints.py`` - Added ``getProfileBannerSizes`` method to ``twitter_endpoints.py`` - Made oauth_verifier argument required in ``get_authorized_tokens`` - Update ``updateProfileBannerImage`` to use v1.1 endpoint 2.7.0 (2013-04-04) ++++++++++++++++++ - New ``showOwnedLists`` method 2.7.0 (2013-03-31) ++++++++++++++++++ - Added missing slash to ``getMentionsTimeline`` in ``twitter_endpoints.py`` 2.6.0 (2013-03-29) ++++++++++++++++++ - Updated ``twitter_endpoints.py`` to better reflect order of API endpoints on the Twitter API v1.1 docs site Keywords: twitter search api tweet twython stream Platform: UNKNOWN Classifier: Development Status :: 4 - Beta Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: MIT License Classifier: Topic :: Software Development :: Libraries :: Python Modules Classifier: Topic :: Communications :: Chat Classifier: Topic :: Internet twython-3.4.0/README.rst0000644000076500000240000001651412711074104016332 0ustar mikehelmickstaff00000000000000Twython ======= .. image:: https://img.shields.io/pypi/v/twython.svg?style=flat-square :target: https://pypi.python.org/pypi/twython .. image:: https://img.shields.io/pypi/dw/twython.svg?style=flat-square :target: https://pypi.python.org/pypi/twython .. image:: https://img.shields.io/travis/ryanmcgrath/twython.svg?style=flat-square :target: https://travis-ci.org/ryanmcgrath/twython .. image:: https://img.shields.io/coveralls/ryanmcgrath/twython/master.svg?style=flat-square :target: https://coveralls.io/r/ryanmcgrath/twython?branch=master ``Twython`` is the premier Python library providing an easy (and up-to-date) way to access Twitter data. Actively maintained and featuring support for Python 2.6+ and Python 3. It's been battle tested by companies, educational institutions and individuals alike. Try it today! Features -------- - Query data for: - User information - Twitter lists - Timelines - Direct Messages - and anything found in `the docs `_ - Image Uploading: - Update user status with an image - Change user avatar - Change user background image - Change user banner image - OAuth 2 Application Only (read-only) Support - Support for Twitter's Streaming API - Seamless Python 3 support! Installation ------------ Install Twython via `pip `_ .. code-block:: bash $ pip install twython or, with `easy_install `_ .. code-block:: bash $ easy_install twython But, hey... `that's up to you `_. Or, if you want the code that is currently on GitHub .. code-block:: bash git clone git://github.com/ryanmcgrath/twython.git cd twython python setup.py install Documentation ------------- Documentation is available at https://twython.readthedocs.org/en/latest/ Starting Out ------------ First, you'll want to head over to https://dev.twitter.com/apps and register an application! After you register, grab your applications ``Consumer Key`` and ``Consumer Secret`` from the application details tab. The most common type of authentication is Twitter user authentication using OAuth 1. If you're a web app planning to have users sign up with their Twitter account and interact with their timelines, updating their status, and stuff like that this **is** the authentication for you! First, you'll want to import Twython .. code-block:: python from twython import Twython Authentication ~~~~~~~~~~~~~~ Obtain Authorization URL ^^^^^^^^^^^^^^^^^^^^^^^^ Now, you'll want to create a Twython instance with your ``Consumer Key`` and ``Consumer Secret`` Only pass *callback_url* to *get_authentication_tokens* if your application is a Web Application Desktop and Mobile Applications **do not** require a callback_url .. code-block:: python APP_KEY = 'YOUR_APP_KEY' APP_SECRET = 'YOUR_APP_SECRET' twitter = Twython(APP_KEY, APP_SECRET) auth = twitter.get_authentication_tokens(callback_url='http://mysite.com/callback') From the ``auth`` variable, save the ``oauth_token`` and ``oauth_token_secret`` for later use (these are not the final auth tokens). In Django or other web frameworks, you might want to store it to a session variable .. code-block:: python OAUTH_TOKEN = auth['oauth_token'] OAUTH_TOKEN_SECRET = auth['oauth_token_secret'] Send the user to the authentication url, you can obtain it by accessing .. code-block:: python auth['auth_url'] Handling the Callback ^^^^^^^^^^^^^^^^^^^^^ If your application is a Desktop or Mobile Application *oauth_verifier* will be the PIN code After they authorize your application to access some of their account details, they'll be redirected to the callback url you specified in ``get_authentication_tokens`` You'll want to extract the ``oauth_verifier`` from the url. Django example: .. code-block:: python oauth_verifier = request.GET['oauth_verifier'] Now that you have the ``oauth_verifier`` stored to a variable, you'll want to create a new instance of Twython and grab the final user tokens .. code-block:: python twitter = Twython(APP_KEY, APP_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET) final_step = twitter.get_authorized_tokens(oauth_verifier) Once you have the final user tokens, store them in a database for later use:: OAUTH_TOKEN = final_step['oauth_token'] OAUTH_TOKEN_SECRET = final_step['oauth_token_secret'] For OAuth 2 (Application Only, read-only) authentication, see `our documentation `_ Dynamic Function Arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~ Keyword arguments to functions are mapped to the functions available for each endpoint in the Twitter API docs. Doing this allows us to be incredibly flexible in querying the Twitter API, so changes to the API aren't held up from you using them by this library. Basic Usage ----------- **Function definitions (i.e. get_home_timeline()) can be found by reading over twython/endpoints.py** Create a Twython instance with your application keys and the users OAuth tokens .. code-block:: python from twython import Twython twitter = Twython(APP_KEY, APP_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET) Authenticated Users Home Timeline ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Documentation: https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline .. code-block:: python twitter.get_home_timeline() Updating Status ~~~~~~~~~~~~~~~ This method makes use of dynamic arguments, `read more about them `_ Documentation: https://dev.twitter.com/docs/api/1/post/statuses/update .. code-block:: python twitter.update_status(status='See how easy using Twython is!') Searching ~~~~~~~~~ https://dev.twitter.com/docs/api/1.1/get/search/tweets says it takes "q" and "result_type" amongst other arguments .. code-block:: python twitter.search(q='twitter') twitter.search(q='twitter', result_type='popular') Advanced Usage -------------- - `Advanced Twython Usage `_ - `Streaming with Twython `_ Notes ----- - Twython 3.0.0 has been injected with 1000mgs of pure awesomeness! OAuth 2 application authentication is now supported. And a *whole lot* more! See the `CHANGELOG `_ for more details! Questions, Comments, etc? ------------------------- My hope is that Twython is so simple that you'd never *have* to ask any questions, but if you feel the need to contact me for this (or other) reasons, you can hit me up at ryan@venodesigns.net. Or if I'm to busy to answer, feel free to ping mikeh@ydekproductions.com as well. Follow us on Twitter: - `@ryanmcgrath `_ - `@mikehelmick `_ Want to help? ------------- Twython is useful, but ultimately only as useful as the people using it (say that ten times fast!). If you'd like to help, write example code, contribute patches, document things on the wiki, tweet about it. Your help is always appreciated! twython-3.4.0/requirements.txt0000644000076500000240000000016012711074104020115 0ustar mikehelmickstaff00000000000000coverage==3.6.0 requests>=2.1.0 requests_oauthlib>=0.4.0 python-coveralls==2.1.0 nose-cov==1.6 responses==0.3.0 twython-3.4.0/setup.cfg0000644000076500000240000000007312711075147016465 0ustar mikehelmickstaff00000000000000[egg_info] tag_build = tag_date = 0 tag_svn_revision = 0 twython-3.4.0/setup.py0000755000076500000240000000241512711074405016357 0ustar mikehelmickstaff00000000000000#!/usr/bin/env python import os import sys try: from setuptools import setup except ImportError: from distutils.core import setup __author__ = 'Ryan McGrath ' __version__ = '3.4.0' packages = [ 'twython', 'twython.streaming' ] if sys.argv[-1] == 'publish': os.system('python setup.py sdist upload') sys.exit() setup( name='twython', version=__version__, install_requires=['requests>=2.1.0', 'requests_oauthlib>=0.4.0'], author='Ryan McGrath', author_email='ryan@venodesigns.net', license=open('LICENSE').read(), url='https://github.com/ryanmcgrath/twython/tree/master', keywords='twitter search api tweet twython stream', description='Actively maintained, pure Python wrapper for the \ Twitter API. Supports both normal and streaming Twitter APIs', long_description=open('README.rst').read() + '\n\n' + open('HISTORY.rst').read(), include_package_data=True, packages=packages, classifiers=[ 'Development Status :: 4 - Beta', 'Intended Audience :: Developers', 'License :: OSI Approved :: MIT License', 'Topic :: Software Development :: Libraries :: Python Modules', 'Topic :: Communications :: Chat', 'Topic :: Internet' ] ) twython-3.4.0/twython/0000755000076500000240000000000012711075147016360 5ustar mikehelmickstaff00000000000000twython-3.4.0/twython/__init__.py0000644000076500000240000000143312711074412020464 0ustar mikehelmickstaff00000000000000# ______ __ __ # /_ __/_ __ __ __ / /_ / /_ ____ ____ # / / | | /| / // / / // __// __ \ / __ \ / __ \ # / / | |/ |/ // /_/ // /_ / / / // /_/ // / / / # /_/ |__/|__/ \__, / \__//_/ /_/ \____//_/ /_/ # /____/ """ Twython ------- Twython is a library for Python that wraps the Twitter API. It aims to abstract away all the API endpoints, so that additions to the library and/or the Twitter API won't cause any overall problems. Questions, comments? ryan@venodesigns.net """ __author__ = 'Ryan McGrath ' __version__ = '3.4.0' from .api import Twython from .streaming import TwythonStreamer from .exceptions import ( TwythonError, TwythonRateLimitError, TwythonAuthError, TwythonStreamError ) twython-3.4.0/twython/advisory.py0000644000076500000240000000125112711074104020561 0ustar mikehelmickstaff00000000000000# -*- coding: utf-8 -*- """ twython.advisory ~~~~~~~~~~~~~~~~ This module contains Warning classes for Twython to specifically alert the user about. This mainly is because Python 2.7 > mutes DeprecationWarning and when we deprecate a method or variable in Twython, we want to use to see the Warning but don't want ALL DeprecationWarnings to appear, only TwythonDeprecationWarnings. """ class TwythonDeprecationWarning(DeprecationWarning): """Custom DeprecationWarning to be raised when methods/variables are being deprecated in Twython. Python 2.7 > ignores DeprecationWarning so we want to specifcally bubble up ONLY Twython Deprecation Warnings """ pass twython-3.4.0/twython/api.py0000644000076500000240000006061312711074104017501 0ustar mikehelmickstaff00000000000000# -*- coding: utf-8 -*- """ twython.api ~~~~~~~~~~~ This module contains functionality for access to core Twitter API calls, Twitter Authentication, and miscellaneous methods that are useful when dealing with the Twitter API """ import warnings import re import requests from requests.auth import HTTPBasicAuth from requests_oauthlib import OAuth1, OAuth2 from . import __version__ from .advisory import TwythonDeprecationWarning from .compat import json, urlencode, parse_qsl, quote_plus, str, is_py2 from .endpoints import EndpointsMixin from .exceptions import TwythonError, TwythonAuthError, TwythonRateLimitError from .helpers import _transparent_params warnings.simplefilter('always', TwythonDeprecationWarning) # For Python 2.7 > class Twython(EndpointsMixin, object): def __init__(self, app_key=None, app_secret=None, oauth_token=None, oauth_token_secret=None, access_token=None, token_type='bearer', oauth_version=1, api_version='1.1', client_args=None, auth_endpoint='authenticate'): """Instantiates an instance of Twython. Takes optional parameters for authentication and such (see below). :param app_key: (optional) Your applications key :param app_secret: (optional) Your applications secret key :param oauth_token: (optional) When using **OAuth 1**, combined with oauth_token_secret to make authenticated calls :param oauth_token_secret: (optional) When using **OAuth 1** combined with oauth_token to make authenticated calls :param access_token: (optional) When using **OAuth 2**, provide a valid access token if you have one :param token_type: (optional) When using **OAuth 2**, provide your token type. Default: bearer :param oauth_version: (optional) Choose which OAuth version to use. Default: 1 :param api_version: (optional) Choose which Twitter API version to use. Default: 1.1 :param client_args: (optional) Accepts some requests Session parameters and some requests Request parameters. See http://docs.python-requests.org/en/latest/api/#sessionapi and requests section below it for details. [ex. headers, proxies, verify(SSL verification)] :param auth_endpoint: (optional) Lets you select which authentication endpoint will use your application. This will allow the application to have DM access if the endpoint is 'authorize'. Default: authenticate. """ # API urls, OAuth urls and API version; needed for hitting that there # API. self.api_version = api_version self.api_url = 'https://api.twitter.com/%s' self.app_key = app_key self.app_secret = app_secret self.oauth_token = oauth_token self.oauth_token_secret = oauth_token_secret self.access_token = access_token # OAuth 1 self.request_token_url = self.api_url % 'oauth/request_token' self.access_token_url = self.api_url % 'oauth/access_token' self.authenticate_url = self.api_url % ('oauth/%s' % auth_endpoint) if self.access_token: # If they pass an access token, force OAuth 2 oauth_version = 2 self.oauth_version = oauth_version # OAuth 2 if oauth_version == 2: self.request_token_url = self.api_url % 'oauth2/token' self.client_args = client_args or {} default_headers = {'User-Agent': 'Twython v' + __version__} if 'headers' not in self.client_args: # If they didn't set any headers, set our defaults for them self.client_args['headers'] = default_headers elif 'User-Agent' not in self.client_args['headers']: # If they set headers, but didn't include User-Agent.. set # it for them self.client_args['headers'].update(default_headers) # Generate OAuth authentication object for the request # If no keys/tokens are passed to __init__, auth=None allows for # unauthenticated requests, although I think all v1.1 requests # need auth auth = None if oauth_version == 1: # User Authentication is through OAuth 1 if self.app_key is not None and self.app_secret is not None: auth = OAuth1(self.app_key, self.app_secret, self.oauth_token, self.oauth_token_secret) elif oauth_version == 2 and self.access_token: # Application Authentication is through OAuth 2 token = {'token_type': token_type, 'access_token': self.access_token} auth = OAuth2(self.app_key, token=token) self.client = requests.Session() self.client.auth = auth # Make a copy of the client args and iterate over them # Pop out all the acceptable args at this point because they will # Never be used again. client_args_copy = self.client_args.copy() for k, v in client_args_copy.items(): if k in ('cert', 'hooks', 'max_redirects', 'proxies'): setattr(self.client, k, v) self.client_args.pop(k) # Pop, pop! # Headers are always present, so we unconditionally pop them and merge # them into the session headers. self.client.headers.update(self.client_args.pop('headers')) self._last_call = None def __repr__(self): return '' % (self.app_key) def _request(self, url, method='GET', params=None, api_call=None): """Internal request method""" method = method.lower() params = params or {} func = getattr(self.client, method) params, files = _transparent_params(params) requests_args = {} for k, v in self.client_args.items(): # Maybe this should be set as a class variable and only done once? if k in ('timeout', 'allow_redirects', 'stream', 'verify'): requests_args[k] = v if method == 'get': requests_args['params'] = params else: requests_args.update({ 'data': params, 'files': files, }) try: response = func(url, **requests_args) except requests.RequestException as e: raise TwythonError(str(e)) # create stash for last function intel self._last_call = { 'api_call': api_call, 'api_error': None, 'cookies': response.cookies, 'headers': response.headers, 'status_code': response.status_code, 'url': response.url, 'content': response.text, } # greater than 304 (not modified) is an error if response.status_code > 304: error_message = self._get_error_message(response) self._last_call['api_error'] = error_message ExceptionType = TwythonError if response.status_code == 429: # Twitter API 1.1, always return 429 when # rate limit is exceeded ExceptionType = TwythonRateLimitError elif response.status_code == 401 or 'Bad Authentication data' \ in error_message: # Twitter API 1.1, returns a 401 Unauthorized or # a 400 "Bad Authentication data" for invalid/expired # app keys/user tokens ExceptionType = TwythonAuthError raise ExceptionType( error_message, error_code=response.status_code, retry_after=response.headers.get('X-Rate-Limit-Reset')) try: if response.status_code == 204: content = response.content else: content = response.json() except ValueError: raise TwythonError('Response was not valid JSON. \ Unable to decode.') return content def _get_error_message(self, response): """Parse and return the first error message""" error_message = 'An error occurred processing your request.' try: content = response.json() # {"errors":[{"code":34,"message":"Sorry, # that page does not exist"}]} error_message = content['errors'][0]['message'] except TypeError: error_message = content['errors'] except ValueError: # bad json data from Twitter for an error pass except (KeyError, IndexError): # missing data so fallback to default message pass return error_message def request(self, endpoint, method='GET', params=None, version='1.1'): """Return dict of response received from Twitter's API :param endpoint: (required) Full url or Twitter API endpoint (e.g. search/tweets) :type endpoint: string :param method: (optional) Method of accessing data, either GET or POST. (default GET) :type method: string :param params: (optional) Dict of parameters (if any) accepted the by Twitter API endpoint you are trying to access (default None) :type params: dict or None :param version: (optional) Twitter API version to access (default 1.1) :type version: string :rtype: dict """ if endpoint.startswith('http://'): raise TwythonError('api.twitter.com is restricted to SSL/TLS traffic.') # In case they want to pass a full Twitter URL # i.e. https://api.twitter.com/1.1/search/tweets.json if endpoint.startswith('https://'): url = endpoint else: url = '%s/%s.json' % (self.api_url % version, endpoint) content = self._request(url, method=method, params=params, api_call=url) return content def get(self, endpoint, params=None, version='1.1'): """Shortcut for GET requests via :class:`request`""" return self.request(endpoint, params=params, version=version) def post(self, endpoint, params=None, version='1.1'): """Shortcut for POST requests via :class:`request`""" return self.request(endpoint, 'POST', params=params, version=version) def get_lastfunction_header(self, header, default_return_value=None): """Returns a specific header from the last API call This will return None if the header is not present :param header: (required) The name of the header you want to get the value of Most useful for the following header information: x-rate-limit-limit, x-rate-limit-remaining, x-rate-limit-class, x-rate-limit-reset """ if self._last_call is None: raise TwythonError('This function must be called after an API call. \ It delivers header information.') return self._last_call['headers'].get(header, default_return_value) def get_authentication_tokens(self, callback_url=None, force_login=False, screen_name=''): """Returns a dict including an authorization URL, ``auth_url``, to direct a user to :param callback_url: (optional) Url the user is returned to after they authorize your app (web clients only) :param force_login: (optional) Forces the user to enter their credentials to ensure the correct users account is authorized. :param screen_name: (optional) If forced_login is set OR user is not currently logged in, Prefills the username input box of the OAuth login screen with the given value :rtype: dict """ if self.oauth_version != 1: raise TwythonError('This method can only be called when your \ OAuth version is 1.0.') request_args = {} if callback_url: request_args['oauth_callback'] = callback_url response = self.client.get(self.request_token_url, params=request_args) if response.status_code == 401: raise TwythonAuthError(response.content, error_code=response.status_code) elif response.status_code != 200: raise TwythonError(response.content, error_code=response.status_code) request_tokens = dict(parse_qsl(response.content.decode('utf-8'))) if not request_tokens: raise TwythonError('Unable to decode request tokens.') oauth_callback_confirmed = request_tokens.get('oauth_callback_confirmed') \ == 'true' auth_url_params = { 'oauth_token': request_tokens['oauth_token'], } if force_login: auth_url_params.update({ 'force_login': force_login, 'screen_name': screen_name }) # Use old-style callback argument if server didn't accept new-style if callback_url and not oauth_callback_confirmed: auth_url_params['oauth_callback'] = self.callback_url request_tokens['auth_url'] = self.authenticate_url + \ '?' + urlencode(auth_url_params) return request_tokens def get_authorized_tokens(self, oauth_verifier): """Returns a dict of authorized tokens after they go through the :class:`get_authentication_tokens` phase. :param oauth_verifier: (required) The oauth_verifier (or a.k.a PIN for non web apps) retrieved from the callback url querystring :rtype: dict """ if self.oauth_version != 1: raise TwythonError('This method can only be called when your \ OAuth version is 1.0.') response = self.client.get(self.access_token_url, params={'oauth_verifier': oauth_verifier}, headers={'Content-Type': 'application/\ json'}) if response.status_code == 401: try: try: # try to get json content = response.json() except AttributeError: # pragma: no cover # if unicode detected content = json.loads(response.content) except ValueError: content = {} raise TwythonError(content.get('error', 'Invalid / expired To \ ken'), error_code=response.status_code) authorized_tokens = dict(parse_qsl(response.content.decode('utf-8'))) if not authorized_tokens: raise TwythonError('Unable to decode authorized tokens.') return authorized_tokens # pragma: no cover def obtain_access_token(self): """Returns an OAuth 2 access token to make OAuth 2 authenticated read-only calls. :rtype: string """ if self.oauth_version != 2: raise TwythonError('This method can only be called when your \ OAuth version is 2.0.') data = {'grant_type': 'client_credentials'} basic_auth = HTTPBasicAuth(self.app_key, self.app_secret) try: response = self.client.post(self.request_token_url, data=data, auth=basic_auth) content = response.content.decode('utf-8') try: content = content.json() except AttributeError: content = json.loads(content) access_token = content['access_token'] except (KeyError, ValueError, requests.exceptions.RequestException): raise TwythonAuthError('Unable to obtain OAuth 2 access token.') else: return access_token @staticmethod def construct_api_url(api_url, **params): """Construct a Twitter API url, encoded, with parameters :param api_url: URL of the Twitter API endpoint you are attempting to construct :param \*\*params: Parameters that are accepted by Twitter for the endpoint you're requesting :rtype: string Usage:: >>> from twython import Twython >>> twitter = Twython() >>> api_url = 'https://api.twitter.com/1.1/search/tweets.json' >>> constructed_url = twitter.construct_api_url(api_url, q='python', result_type='popular') >>> print constructed_url https://api.twitter.com/1.1/search/tweets.json?q=python&result_type=popular """ querystring = [] params, _ = _transparent_params(params or {}) params = requests.utils.to_key_val_list(params) for (k, v) in params: querystring.append( '%s=%s' % (Twython.encode(k), quote_plus(Twython.encode(v))) ) return '%s?%s' % (api_url, '&'.join(querystring)) def search_gen(self, search_query, **params): # pragma: no cover warnings.warn( 'This method is deprecated. You should use Twython.cursor instead. \ [eg. Twython.cursor(Twython.search, q=\'your_query\')]', TwythonDeprecationWarning, stacklevel=2 ) return self.cursor(self.search, q=search_query, **params) def cursor(self, function, return_pages=False, **params): """Returns a generator for results that match a specified query. :param function: Instance of a Twython function (Twython.get_home_timeline, Twython.search) :param \*\*params: Extra parameters to send with your request (usually parameters accepted by the Twitter API endpoint) :rtype: generator Usage:: >>> from twython import Twython >>> twitter = Twython(APP_KEY, APP_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET) >>> results = twitter.cursor(twitter.search, q='python') >>> for result in results: >>> print result """ if not hasattr(function, 'iter_mode'): raise TwythonError('Unable to create generator for Twython \ method "%s"' % function.__name__) while True: content = function(**params) if not content: raise StopIteration if hasattr(function, 'iter_key'): results = content.get(function.iter_key) else: results = content if return_pages: yield results else: for result in results: yield result if function.iter_mode == 'cursor' and \ content['next_cursor_str'] == '0': raise StopIteration try: if function.iter_mode == 'id': if 'max_id' not in params: # Add 1 to the id because since_id and # max_id are inclusive if hasattr(function, 'iter_metadata'): since_id = content[function.iter_metadata].get('since_id_str') else: since_id = content[0]['id_str'] params['since_id'] = (int(since_id) - 1) elif function.iter_mode == 'cursor': params['cursor'] = content['next_cursor_str'] except (TypeError, ValueError): # pragma: no cover raise TwythonError('Unable to generate next page of search \ results, `page` is not a number.') @staticmethod def unicode2utf8(text): try: if is_py2 and isinstance(text, str): text = text.encode('utf-8') except: pass return text @staticmethod def encode(text): if is_py2 and isinstance(text, (str)): return Twython.unicode2utf8(text) return str(text) @staticmethod def html_for_tweet(tweet, use_display_url=True, use_expanded_url=False, expand_quoted_status=False): """Return HTML for a tweet (urls, mentions, hashtags replaced with links) :param tweet: Tweet object from received from Twitter API :param use_display_url: Use display URL to represent link (ex. google.com, github.com). Default: True :param use_expanded_url: Use expanded URL to represent link (e.g. http://google.com). Default False If use_expanded_url is True, it overrides use_display_url. If use_display_url and use_expanded_url is False, short url will be used (t.co/xxxxx) """ if 'retweeted_status' in tweet: tweet = tweet['retweeted_status'] if 'entities' in tweet: text = tweet['text'] entities = tweet['entities'] # Mentions for entity in sorted(entities['user_mentions'], key=lambda mention: len(mention['screen_name']), reverse=True): start, end = entity['indices'][0], entity['indices'][1] mention_html = '@%(screen_name)s' text = re.sub(r'(?)' + tweet['text'][start:end] + '(?!)', mention_html % {'screen_name': entity['screen_name']}, text) # Hashtags for entity in sorted(entities['hashtags'], key=lambda hashtag: len(hashtag['text']), reverse=True): start, end = entity['indices'][0], entity['indices'][1] hashtag_html = '#%(hashtag)s' text = re.sub(r'(?)' + tweet['text'][start:end] + '(?!)', hashtag_html % {'hashtag': entity['text']}, text) # Urls for entity in entities['urls']: start, end = entity['indices'][0], entity['indices'][1] if use_display_url and entity.get('display_url') \ and not use_expanded_url: shown_url = entity['display_url'] elif use_expanded_url and entity.get('expanded_url'): shown_url = entity['expanded_url'] else: shown_url = entity['url'] url_html = '%s' text = text.replace(tweet['text'][start:end], url_html % (entity['url'], shown_url)) # Media if 'media' in entities: for entity in entities['media']: start, end = entity['indices'][0], entity['indices'][1] if use_display_url and entity.get('display_url') \ and not use_expanded_url: shown_url = entity['display_url'] elif use_expanded_url and entity.get('expanded_url'): shown_url = entity['expanded_url'] else: shown_url = entity['url'] url_html = '%s' text = text.replace(tweet['text'][start:end], url_html % (entity['url'], shown_url)) if expand_quoted_status and tweet.get('is_quote_status') and tweet.get('quoted_status'): quoted_status = tweet['quoted_status'] text += '
%(quote)s' \ '%(quote_user_name)s' \ '@%(quote_user_screen_name)s' \ '
' % \ {'quote': Twython.html_for_tweet(quoted_status, use_display_url, use_expanded_url, False), 'quote_tweet_link': 'https://twitter.com/%s/status/%s' % (quoted_status['user']['screen_name'], quoted_status['id_str']), 'quote_user_name': quoted_status['user']['name'], 'quote_user_screen_name': quoted_status['user']['screen_name']} return text twython-3.4.0/twython/compat.py0000644000076500000240000000125212711074104020205 0ustar mikehelmickstaff00000000000000# -*- coding: utf-8 -*- """ twython.compat ~~~~~~~~~~~~~~ This module contains imports and declarations for seamless Python 2 and Python 3 compatibility. """ import sys _ver = sys.version_info #: Python 2.x? is_py2 = (_ver[0] == 2) #: Python 3.x? is_py3 = (_ver[0] == 3) try: import simplejson as json except ImportError: import json if is_py2: from urllib import urlencode, quote_plus from urlparse import parse_qsl str = unicode basestring = basestring numeric_types = (int, long, float) elif is_py3: from urllib.parse import urlencode, quote_plus, parse_qsl str = str basestring = (str, bytes) numeric_types = (int, float) twython-3.4.0/twython/endpoints.py0000644000076500000240000010732512711074104020735 0ustar mikehelmickstaff00000000000000# -*- coding: utf-8 -*- """ twython.endpoints ~~~~~~~~~~~~~~~~~ This module provides a mixin for a :class:`Twython ` instance. Parameters that need to be embedded in the API url just need to be passed as a keyword argument. e.g. Twython.retweet(id=12345) This map is organized the order functions are documented at: https://dev.twitter.com/docs/api/1.1 """ import os import warnings try: from StringIO import StringIO except ImportError: from io import StringIO from .advisory import TwythonDeprecationWarning class EndpointsMixin(object): # Timelines def get_mentions_timeline(self, **params): """Returns the 20 most recent mentions (tweets containing a users's @screen_name) for the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/mentions_timeline """ return self.get('statuses/mentions_timeline', params=params) get_mentions_timeline.iter_mode = 'id' def get_user_timeline(self, **params): """Returns a collection of the most recent Tweets posted by the user indicated by the screen_name or user_id parameters. Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/user_timeline """ return self.get('statuses/user_timeline', params=params) get_user_timeline.iter_mode = 'id' def get_home_timeline(self, **params): """Returns a collection of the most recent Tweets and retweets posted by the authenticating user and the users they follow. Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline """ return self.get('statuses/home_timeline', params=params) get_home_timeline.iter_mode = 'id' def retweeted_of_me(self, **params): """Returns the most recent tweets authored by the authenticating user that have been retweeted by others. Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/retweets_of_me """ return self.get('statuses/retweets_of_me', params=params) retweeted_of_me.iter_mode = 'id' # Tweets def get_retweets(self, **params): """Returns up to 100 of the first retweets of a given tweet. Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/retweets/%3Aid """ return self.get('statuses/retweets/%s' % params.get('id'), params=params) def show_status(self, **params): """Returns a single Tweet, specified by the id parameter Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/show/%3Aid """ return self.get('statuses/show/%s' % params.get('id'), params=params) def lookup_status(self, **params): """Returns fully-hydrated tweet objects for up to 100 tweets per request, as specified by comma-separated values passed to the id parameter. Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/lookup """ return self.post('statuses/lookup', params=params) def destroy_status(self, **params): """Destroys the status specified by the required ID parameter Docs: https://dev.twitter.com/docs/api/1.1/post/statuses/destroy/%3Aid """ return self.post('statuses/destroy/%s' % params.get('id')) def update_status(self, **params): """Updates the authenticating user's current status, also known as tweeting Docs: https://dev.twitter.com/docs/api/1.1/post/statuses/update """ return self.post('statuses/update', params=params) def retweet(self, **params): """Retweets a tweet specified by the id parameter Docs: https://dev.twitter.com/docs/api/1.1/post/statuses/retweet/%3Aid """ return self.post('statuses/retweet/%s' % params.get('id')) def update_status_with_media(self, **params): # pragma: no cover """Updates the authenticating user's current status and attaches media for upload. In other words, it creates a Tweet with a picture attached. Docs: https://dev.twitter.com/docs/api/1.1/post/statuses/update_with_media """ warnings.warn( 'This method is deprecated. You should use Twython.upload_media instead.', TwythonDeprecationWarning, stacklevel=2 ) return self.post('statuses/update_with_media', params=params) def upload_media(self, **params): """Uploads media file to Twitter servers. The file will be available to be attached to a status for 60 minutes. To attach to a update, pass a list of returned media ids to the 'update_status' method using the 'media_ids' param. Docs: https://dev.twitter.com/rest/reference/post/media/upload """ return self.post('https://upload.twitter.com/1.1/media/upload.json', params=params) def upload_video(self, media, media_type, size=None): """Uploads video file to Twitter servers in chunks. The file will be available to be attached to a status for 60 minutes. To attach to a update, pass a list of returned media ids to the 'update_status' method using the 'media_ids' param. Upload happens in 3 stages: - INIT call with size of media to be uploaded(in bytes). If this is more than 15mb, twitter will return error. - APPEND calls each with media chunk. This returns a 204(No Content) if chunk is received. - FINALIZE call to complete media upload. This returns media_id to be used with status update. Twitter media upload api expects each chunk to be not more than 5mb. We are sending chunk of 1mb each. Docs: https://dev.twitter.com/rest/public/uploading-media#chunkedupload """ upload_url = 'https://upload.twitter.com/1.1/media/upload.json' if not size: media.seek(0, os.SEEK_END) size = media.tell() media.seek(0) # Stage 1: INIT call params = { 'command': 'INIT', 'media_type': media_type, 'total_bytes': size } response_init = self.post(upload_url, params=params) media_id = response_init['media_id'] # Stage 2: APPEND calls with 1mb chunks segment_index = 0 while True: data = media.read(1*1024*1024) if not data: break media_chunk = StringIO() media_chunk.write(data) media_chunk.seek(0) params = { 'command': 'APPEND', 'media_id': media_id, 'segment_index': segment_index, 'media': media_chunk, } self.post(upload_url, params=params) segment_index += 1 # Stage 3: FINALIZE call to complete upload params = { 'command': 'FINALIZE', 'media_id': media_id } return self.post(upload_url, params=params) def get_oembed_tweet(self, **params): """Returns information allowing the creation of an embedded representation of a Tweet on third party sites. Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/oembed """ return self.get('statuses/oembed', params=params) def get_retweeters_ids(self, **params): """Returns a collection of up to 100 user IDs belonging to users who have retweeted the tweet specified by the id parameter. Docs: https://dev.twitter.com/docs/api/1.1/get/statuses/retweeters/ids """ return self.get('statuses/retweeters/ids', params=params) get_retweeters_ids.iter_mode = 'cursor' get_retweeters_ids.iter_key = 'ids' # Search def search(self, **params): """Returns a collection of relevant Tweets matching a specified query. Docs: https://dev.twitter.com/docs/api/1.1/get/search/tweets """ return self.get('search/tweets', params=params) search.iter_mode = 'id' search.iter_key = 'statuses' search.iter_metadata = 'search_metadata' # Direct Messages def get_direct_messages(self, **params): """Returns the 20 most recent direct messages sent to the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/get/direct_messages """ return self.get('direct_messages', params=params) get_direct_messages.iter_mode = 'id' def get_sent_messages(self, **params): """Returns the 20 most recent direct messages sent by the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/get/direct_messages/sent """ return self.get('direct_messages/sent', params=params) get_sent_messages.iter_mode = 'id' def get_direct_message(self, **params): """Returns a single direct message, specified by an id parameter. Docs: https://dev.twitter.com/docs/api/1.1/get/direct_messages/show """ return self.get('direct_messages/show', params=params) def destroy_direct_message(self, **params): """Destroys the direct message specified in the required id parameter Docs: https://dev.twitter.com/docs/api/1.1/post/direct_messages/destroy """ return self.post('direct_messages/destroy', params=params) def send_direct_message(self, **params): """Sends a new direct message to the specified user from the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/post/direct_messages/new """ return self.post('direct_messages/new', params=params) # Friends & Followers def get_user_ids_of_blocked_retweets(self, **params): """Returns a collection of user_ids that the currently authenticated user does not want to receive retweets from. Docs: https://dev.twitter.com/docs/api/1.1/get/friendships/no_retweets/ids """ return self.get('friendships/no_retweets/ids', params=params) def get_friends_ids(self, **params): """Returns a cursored collection of user IDs for every user the specified user is following (otherwise known as their "friends"). Docs: https://dev.twitter.com/docs/api/1.1/get/friends/ids """ return self.get('friends/ids', params=params) get_friends_ids.iter_mode = 'cursor' get_friends_ids.iter_key = 'ids' def get_followers_ids(self, **params): """Returns a cursored collection of user IDs for every user following the specified user. Docs: https://dev.twitter.com/docs/api/1.1/get/followers/ids """ return self.get('followers/ids', params=params) get_followers_ids.iter_mode = 'cursor' get_followers_ids.iter_key = 'ids' def lookup_friendships(self, **params): """Returns the relationships of the authenticating user to the comma-separated list of up to 100 screen_names or user_ids provided. Docs: https://dev.twitter.com/docs/api/1.1/get/friendships/lookup """ return self.get('friendships/lookup', params=params) def get_incoming_friendship_ids(self, **params): """Returns a collection of numeric IDs for every user who has a pending request to follow the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/get/friendships/incoming """ return self.get('friendships/incoming', params=params) get_incoming_friendship_ids.iter_mode = 'cursor' get_incoming_friendship_ids.iter_key = 'ids' def get_outgoing_friendship_ids(self, **params): """Returns a collection of numeric IDs for every protected user for whom the authenticating user has a pending follow request. Docs: https://dev.twitter.com/docs/api/1.1/get/friendships/outgoing """ return self.get('friendships/outgoing', params=params) get_outgoing_friendship_ids.iter_mode = 'cursor' get_outgoing_friendship_ids.iter_key = 'ids' def create_friendship(self, **params): """Allows the authenticating users to follow the user specified in the ID parameter. Docs: https://dev.twitter.com/docs/api/1.1/post/friendships/create """ return self.post('friendships/create', params=params) def destroy_friendship(self, **params): """Allows the authenticating user to unfollow the user specified in the ID parameter. Docs: https://dev.twitter.com/docs/api/1.1/post/friendships/destroy """ return self.post('friendships/destroy', params=params) def update_friendship(self, **params): """Allows one to enable or disable retweets and device notifications from the specified user. Docs: https://dev.twitter.com/docs/api/1.1/post/friendships/update """ return self.post('friendships/update', params=params) def show_friendship(self, **params): """Returns detailed information about the relationship between two arbitrary users. Docs: https://dev.twitter.com/docs/api/1.1/get/friendships/show """ return self.get('friendships/show', params=params) def get_friends_list(self, **params): """Returns a cursored collection of user objects for every user the specified user is following (otherwise known as their "friends"). Docs: https://dev.twitter.com/docs/api/1.1/get/friends/list """ return self.get('friends/list', params=params) get_friends_list.iter_mode = 'cursor' get_friends_list.iter_key = 'users' def get_followers_list(self, **params): """Returns a cursored collection of user objects for users following the specified user. Docs: https://dev.twitter.com/docs/api/1.1/get/followers/list """ return self.get('followers/list', params=params) get_followers_list.iter_mode = 'cursor' get_followers_list.iter_key = 'users' # Users def get_account_settings(self, **params): """Returns settings (including current trend, geo and sleep time information) for the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/get/account/settings """ return self.get('account/settings', params=params) def verify_credentials(self, **params): """Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; returns a 401 status code and an error message if not. Docs: https://dev.twitter.com/docs/api/1.1/get/account/verify_credentials """ return self.get('account/verify_credentials', params=params) def update_account_settings(self, **params): """Updates the authenticating user's settings. Docs: https://dev.twitter.com/docs/api/1.1/post/account/settings """ return self.post('account/settings', params=params) def update_delivery_service(self, **params): """Sets which device Twitter delivers updates to for the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_delivery_device """ return self.post('account/update_delivery_device', params=params) def update_profile(self, **params): """Sets values that users are able to set under the "Account" tab of their settings page. Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile """ return self.post('account/update_profile', params=params) def update_profile_banner_image(self, **params): # pragma: no cover """Updates the authenticating user's profile background image. Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile_background_image """ return self.post('account/update_profile_banner', params=params) def update_profile_colors(self, **params): """Sets one or more hex values that control the color scheme of the authenticating user's profile page on twitter.com. Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile_colors """ return self.post('account/update_profile_colors', params=params) def update_profile_image(self, **params): # pragma: no cover """Updates the authenticating user's profile image. Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile_image """ return self.post('account/update_profile_image', params=params) def list_blocks(self, **params): """Returns a collection of user objects that the authenticating user is blocking. Docs: https://dev.twitter.com/docs/api/1.1/get/blocks/list """ return self.get('blocks/list', params=params) list_blocks.iter_mode = 'cursor' list_blocks.iter_key = 'users' def list_block_ids(self, **params): """Returns an array of numeric user ids the authenticating user is blocking. Docs: https://dev.twitter.com/docs/api/1.1/get/blocks/ids """ return self.get('blocks/ids', params=params) list_block_ids.iter_mode = 'cursor' list_block_ids.iter_key = 'ids' def create_block(self, **params): """Blocks the specified user from following the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/post/blocks/create """ return self.post('blocks/create', params=params) def destroy_block(self, **params): """Un-blocks the user specified in the ID parameter for the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/post/blocks/destroy """ return self.post('blocks/destroy', params=params) def lookup_user(self, **params): """Returns fully-hydrated user objects for up to 100 users per request, as specified by comma-separated values passed to the user_id and/or screen_name parameters. Docs: https://dev.twitter.com/docs/api/1.1/get/users/lookup """ return self.get('users/lookup', params=params) def show_user(self, **params): """Returns a variety of information about the user specified by the required user_id or screen_name parameter. Docs: https://dev.twitter.com/docs/api/1.1/get/users/show """ return self.get('users/show', params=params) def search_users(self, **params): """Provides a simple, relevance-based search interface to public user accounts on Twitter. Docs: https://dev.twitter.com/docs/api/1.1/get/users/search """ return self.get('users/search', params=params) def get_contributees(self, **params): """Returns a collection of users that the specified user can "contribute" to. Docs: https://dev.twitter.com/docs/api/1.1/get/users/contributees """ return self.get('users/contributees', params=params) def get_contributors(self, **params): """Returns a collection of users who can contribute to the specified account. Docs: https://dev.twitter.com/docs/api/1.1/get/users/contributors """ return self.get('users/contributors', params=params) def remove_profile_banner(self, **params): """Removes the uploaded profile banner for the authenticating user. Returns HTTP 200 upon success. Docs: https://dev.twitter.com/docs/api/1.1/post/account/remove_profile_banner """ return self.post('account/remove_profile_banner', params=params) def update_profile_background_image(self, **params): """Uploads a profile banner on behalf of the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/post/account/update_profile_banner """ return self.post('account/update_profile_background_image', params=params) def get_profile_banner_sizes(self, **params): """Returns a map of the available size variations of the specified user's profile banner. Docs: https://dev.twitter.com/docs/api/1.1/get/users/profile_banner """ return self.get('users/profile_banner', params=params) def list_mutes(self, **params): """Returns a collection of user objects that the authenticating user is muting. Docs: https://dev.twitter.com/docs/api/1.1/get/mutes/users/list """ return self.get('mutes/users/list', params=params) list_mutes.iter_mode = 'cursor' list_mutes.iter_key = 'users' def list_mute_ids(self, **params): """Returns an array of numeric user ids the authenticating user is muting. Docs: https://dev.twitter.com/docs/api/1.1/get/mutes/users/ids """ return self.get('mutes/users/ids', params=params) list_mute_ids.iter_mode = 'cursor' list_mute_ids.iter_key = 'ids' def create_mute(self, **params): """Mutes the specified user, preventing their tweets appearing in the authenticating user's timeline. Docs: https://dev.twitter.com/docs/api/1.1/post/mutes/users/create """ return self.post('mutes/users/create', params=params) def destroy_mute(self, **params): """Un-mutes the user specified in the user or ID parameter for the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/post/mutes/users/destroy """ return self.post('mutes/users/destroy', params=params) # Suggested Users def get_user_suggestions_by_slug(self, **params): """Access the users in a given category of the Twitter suggested user list. Docs: https://dev.twitter.com/docs/api/1.1/get/users/suggestions/%3Aslug """ return self.get('users/suggestions/%s' % params.get('slug'), params=params) def get_user_suggestions(self, **params): """Access to Twitter's suggested user list. Docs: https://dev.twitter.com/docs/api/1.1/get/users/suggestions """ return self.get('users/suggestions', params=params) def get_user_suggestions_statuses_by_slug(self, **params): """Access the users in a given category of the Twitter suggested user list and return their most recent status if they are not a protected user. Docs: https://dev.twitter.com/docs/api/1.1/get/users/suggestions/%3Aslug/members """ return self.get('users/suggestions/%s/members' % params.get('slug'), params=params) # Favorites def get_favorites(self, **params): """Returns the 20 most recent Tweets favorited by the authenticating or specified user. Docs: https://dev.twitter.com/docs/api/1.1/get/favorites/list """ return self.get('favorites/list', params=params) get_favorites.iter_mode = 'id' def destroy_favorite(self, **params): """Un-favorites the status specified in the ID parameter as the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/post/favorites/destroy """ return self.post('favorites/destroy', params=params) def create_favorite(self, **params): """Favorites the status specified in the ID parameter as the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/post/favorites/create """ return self.post('favorites/create', params=params) # Lists def show_lists(self, **params): """Returns all lists the authenticating or specified user subscribes to, including their own. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/list """ return self.get('lists/list', params=params) def get_list_statuses(self, **params): """Returns a timeline of tweets authored by members of the specified list. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/statuses """ return self.get('lists/statuses', params=params) get_list_statuses.iter_mode = 'id' def delete_list_member(self, **params): """Removes the specified member from the list. Docs: https://dev.twitter.com/docs/api/1.1/post/lists/members/destroy """ return self.post('lists/members/destroy', params=params) def get_list_memberships(self, **params): """Returns the lists the specified user has been added to. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/memberships """ return self.get('lists/memberships', params=params) get_list_memberships.iter_mode = 'cursor' get_list_memberships.iter_key = 'lists' def get_list_subscribers(self, **params): """Returns the subscribers of the specified list. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/subscribers """ return self.get('lists/subscribers', params=params) get_list_subscribers.iter_mode = 'cursor' get_list_subscribers.iter_key = 'users' def subscribe_to_list(self, **params): """Subscribes the authenticated user to the specified list. Docs: https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/create """ return self.post('lists/subscribers/create', params=params) def is_list_subscriber(self, **params): """Check if the specified user is a subscriber of the specified list. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/subscribers/show """ return self.get('lists/subscribers/show', params=params) def unsubscribe_from_list(self, **params): """Unsubscribes the authenticated user from the specified list. Docs: https://dev.twitter.com/docs/api/1.1/post/lists/subscribers/destroy """ return self.post('lists/subscribers/destroy', params=params) def create_list_members(self, **params): """Adds multiple members to a list, by specifying a comma-separated list of member ids or screen names. Docs: https://dev.twitter.com/docs/api/1.1/post/lists/members/create_all """ return self.post('lists/members/create_all', params=params) def is_list_member(self, **params): """Check if the specified user is a member of the specified list. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/members/show """ return self.get('lists/members/show', params=params) def get_list_members(self, **params): """Returns the members of the specified list. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/members """ return self.get('lists/members', params=params) get_list_members.iter_mode = 'cursor' get_list_members.iter_key = 'users' def add_list_member(self, **params): """Add a member to a list. Docs: https://dev.twitter.com/docs/api/1.1/post/lists/members/create """ return self.post('lists/members/create', params=params) def delete_list(self, **params): """Deletes the specified list. Docs: https://dev.twitter.com/docs/api/1.1/post/lists/destroy """ return self.post('lists/destroy', params=params) def update_list(self, **params): """Updates the specified list. Docs: https://dev.twitter.com/docs/api/1.1/post/lists/update """ return self.post('lists/update', params=params) def create_list(self, **params): """Creates a new list for the authenticated user. Docs: https://dev.twitter.com/docs/api/1.1/post/lists/create """ return self.post('lists/create', params=params) def get_specific_list(self, **params): """Returns the specified list. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/show """ return self.get('lists/show', params=params) def get_list_subscriptions(self, **params): """Obtain a collection of the lists the specified user is subscribed to. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/subscriptions """ return self.get('lists/subscriptions', params=params) get_list_subscriptions.iter_mode = 'cursor' get_list_subscriptions.iter_key = 'lists' def delete_list_members(self, **params): """Removes multiple members from a list, by specifying a comma-separated list of member ids or screen names. Docs: https://dev.twitter.com/docs/api/1.1/post/lists/members/destroy_all """ return self.post('lists/members/destroy_all', params=params) def show_owned_lists(self, **params): """Returns the lists owned by the specified Twitter user. Docs: https://dev.twitter.com/docs/api/1.1/get/lists/ownerships """ return self.get('lists/ownerships', params=params) show_owned_lists.iter_mode = 'cursor' show_owned_lists.iter_key = 'lists' # Saved Searches def get_saved_searches(self, **params): """Returns the authenticated user's saved search queries. Docs: https://dev.twitter.com/docs/api/1.1/get/saved_searches/list """ return self.get('saved_searches/list', params=params) def show_saved_search(self, **params): """Retrieve the information for the saved search represented by the given id. Docs: https://dev.twitter.com/docs/api/1.1/get/saved_searches/show/%3Aid """ return self.get('saved_searches/show/%s' % params.get('id'), params=params) def create_saved_search(self, **params): """Create a new saved search for the authenticated user. Docs: https://dev.twitter.com/docs/api/1.1/post/saved_searches/create """ return self.post('saved_searches/create', params=params) def destroy_saved_search(self, **params): """Destroys a saved search for the authenticating user. Docs: https://dev.twitter.com/docs/api/1.1/post/saved_searches/destroy/%3Aid """ return self.post('saved_searches/destroy/%s' % params.get('id'), params=params) # Places & Geo def get_geo_info(self, **params): """Returns all the information about a known place. Docs: https://dev.twitter.com/docs/api/1.1/get/geo/id/%3Aplace_id """ return self.get('geo/id/%s' % params.get('place_id'), params=params) def reverse_geocode(self, **params): """Given a latitude and a longitude, searches for up to 20 places that can be used as a place_id when updating a status. Docs: https://dev.twitter.com/docs/api/1.1/get/geo/reverse_geocode """ return self.get('geo/reverse_geocode', params=params) def search_geo(self, **params): """Search for places that can be attached to a statuses/update. Docs: https://dev.twitter.com/docs/api/1.1/get/geo/search """ return self.get('geo/search', params=params) def get_similar_places(self, **params): """Locates places near the given coordinates which are similar in name. Docs: https://dev.twitter.com/docs/api/1.1/get/geo/similar_places """ return self.get('geo/similar_places', params=params) def create_place(self, **params): # pragma: no cover """Creates a new place object at the given latitude and longitude. Docs: https://dev.twitter.com/docs/api/1.1/post/geo/place """ return self.post('geo/place', params=params) # Trends def get_place_trends(self, **params): """Returns the top 10 trending topics for a specific WOEID, if trending information is available for it. Docs: https://dev.twitter.com/docs/api/1.1/get/trends/place """ return self.get('trends/place', params=params) def get_available_trends(self, **params): """Returns the locations that Twitter has trending topic information for. Docs: https://dev.twitter.com/docs/api/1.1/get/trends/available """ return self.get('trends/available', params=params) def get_closest_trends(self, **params): """Returns the locations that Twitter has trending topic information for, closest to a specified location. Docs: https://dev.twitter.com/docs/api/1.1/get/trends/closest """ return self.get('trends/closest', params=params) # Spam Reporting def report_spam(self, **params): # pragma: no cover """Report the specified user as a spam account to Twitter. Docs: https://dev.twitter.com/docs/api/1.1/post/users/report_spam """ return self.post('users/report_spam', params=params) # OAuth def invalidate_token(self, **params): # pragma: no cover """Allows a registered application to revoke an issued OAuth 2 Bearer Token by presenting its client credentials. Docs: https://dev.twitter.com/docs/api/1.1/post/oauth2/invalidate_token """ return self.post('oauth2/invalidate_token', params=params) # Help def get_twitter_configuration(self, **params): """Returns the current configuration used by Twitter Docs: https://dev.twitter.com/docs/api/1.1/get/help/configuration """ return self.get('help/configuration', params=params) def get_supported_languages(self, **params): """Returns the list of languages supported by Twitter along with their ISO 639-1 code. Docs: https://dev.twitter.com/docs/api/1.1/get/help/languages """ return self.get('help/languages', params=params) def get_privacy_policy(self, **params): """Returns Twitter's Privacy Policy Docs: https://dev.twitter.com/docs/api/1.1/get/help/privacy """ return self.get('help/privacy', params=params) def get_tos(self, **params): """Return the Twitter Terms of Service Docs: https://dev.twitter.com/docs/api/1.1/get/help/tos """ return self.get('help/tos', params=params) def get_application_rate_limit_status(self, **params): """Returns the current rate limits for methods belonging to the specified resource families. Docs: https://dev.twitter.com/docs/api/1.1/get/application/rate_limit_status """ return self.get('application/rate_limit_status', params=params) # from https://dev.twitter.com/docs/error-codes-responses TWITTER_HTTP_STATUS_CODE = { 200: ('OK', 'Success!'), 304: ('Not Modified', 'There was no new data to return.'), 400: ('Bad Request', 'The request was invalid. An accompanying \ error message will explain why. This is the status code \ will be returned during rate limiting.'), 401: ('Unauthorized', 'Authentication credentials were missing \ or incorrect.'), 403: ('Forbidden', 'The request is understood, but it has been \ refused. An accompanying error message will explain why. \ This code is used when requests are being denied due to \ update limits.'), 404: ('Not Found', 'The URI requested is invalid or the resource \ requested, such as a user, does not exists.'), 406: ('Not Acceptable', 'Returned by the Search API when an \ invalid format is specified in the request.'), 410: ('Gone', 'This resource is gone. Used to indicate that an \ API endpoint has been turned off.'), 422: ('Unprocessable Entity', 'Returned when an image uploaded to \ POST account/update_profile_banner is unable to be processed.'), 429: ('Too Many Requests', 'Returned in API v1.1 when a request cannot \ be served due to the application\'s rate limit having been \ exhausted for the resource.'), 500: ('Internal Server Error', 'Something is broken. Please post to the \ group so the Twitter team can investigate.'), 502: ('Bad Gateway', 'Twitter is down or being upgraded.'), 503: ('Service Unavailable', 'The Twitter servers are up, but overloaded \ with requests. Try again later.'), 504: ('Gateway Timeout', 'The Twitter servers are up, but the request \ couldn\'t be serviced due to some failure within our stack. Try \ again later.'), } twython-3.4.0/twython/exceptions.py0000644000076500000240000000325012711074104021103 0ustar mikehelmickstaff00000000000000# -*- coding: utf-8 -*- """ twython.exceptions ~~~~~~~~~~~~~~~~~~ This module contains Twython specific Exception classes. """ from .endpoints import TWITTER_HTTP_STATUS_CODE class TwythonError(Exception): """Generic error class, catch-all for most Twython issues. Special cases are handled by TwythonAuthError & TwythonRateLimitError. from twython import TwythonError, TwythonRateLimitError, TwythonAuthError """ def __init__(self, msg, error_code=None, retry_after=None): self.error_code = error_code if error_code is not None and error_code in TWITTER_HTTP_STATUS_CODE: msg = 'Twitter API returned a %s (%s), %s' % \ (error_code, TWITTER_HTTP_STATUS_CODE[error_code][0], msg) super(TwythonError, self).__init__(msg) @property def msg(self): # pragma: no cover return self.args[0] class TwythonAuthError(TwythonError): """Raised when you try to access a protected resource and it fails due to some issue with your authentication. """ pass class TwythonRateLimitError(TwythonError): # pragma: no cover """Raised when you've hit a rate limit. The amount of seconds to retry your request in will be appended to the message. """ def __init__(self, msg, error_code, retry_after=None): if isinstance(retry_after, int): msg = '%s (Retry after %d seconds)' % (msg, retry_after) TwythonError.__init__(self, msg, error_code=error_code) self.retry_after = retry_after class TwythonStreamError(TwythonError): """Raised when an invalid response from the Stream API is received""" pass twython-3.4.0/twython/helpers.py0000644000076500000240000000157012711074104020367 0ustar mikehelmickstaff00000000000000# -*- coding: utf-8 -*- """ twython.helpers ~~~~~~~~~~~~~~~ This module contains functions that are repeatedly used throughout the Twython library. """ from .compat import basestring, numeric_types def _transparent_params(_params): params = {} files = {} for k, v in _params.items(): if hasattr(v, 'read') and callable(v.read): files[k] = v # pragma: no cover elif isinstance(v, bool): if v: params[k] = 'true' else: params[k] = 'false' elif isinstance(v, basestring) or isinstance(v, numeric_types): params[k] = v elif isinstance(v, list): try: params[k] = ','.join(v) except TypeError: params[k] = ','.join(map(str, v)) else: continue # pragma: no cover return params, files twython-3.4.0/twython/streaming/0000755000076500000240000000000012711075147020351 5ustar mikehelmickstaff00000000000000twython-3.4.0/twython/streaming/__init__.py0000644000076500000240000000004112711074104022445 0ustar mikehelmickstaff00000000000000from .api import TwythonStreamer twython-3.4.0/twython/streaming/api.py0000644000076500000240000001727012711074104021473 0ustar mikehelmickstaff00000000000000# -*- coding: utf-8 -*- """ twython.streaming.api ~~~~~~~~~~~~~~~~~~~~~ This module contains functionality for interfacing with streaming Twitter API calls. """ from .. import __version__ from ..compat import json, is_py3 from ..helpers import _transparent_params from .types import TwythonStreamerTypes import requests from requests_oauthlib import OAuth1 import time class TwythonStreamer(object): def __init__(self, app_key, app_secret, oauth_token, oauth_token_secret, timeout=300, retry_count=None, retry_in=10, client_args=None, handlers=None, chunk_size=1): """Streaming class for a friendly streaming user experience Authentication IS required to use the Twitter Streaming API :param app_key: (required) Your applications key :param app_secret: (required) Your applications secret key :param oauth_token: (required) Used with oauth_token_secret to make authenticated calls :param oauth_token_secret: (required) Used with oauth_token to make authenticated calls :param timeout: (optional) How long (in secs) the streamer should wait for a response from Twitter Streaming API :param retry_count: (optional) Number of times the API call should be retired :param retry_in: (optional) Amount of time (in secs) the previous API call should be tried again :param client_args: (optional) Accepts some requests Session parameters and some requests Request parameters. See http://docs.python-requests.org/en/latest/api/#sessionapi and requests section below it for details. [ex. headers, proxies, verify(SSL verification)] :param handlers: (optional) Array of message types for which corresponding handlers will be called :param chunk_size: (optional) Define the buffer size before data is actually returned from the Streaming API. Default: 1 """ self.auth = OAuth1(app_key, app_secret, oauth_token, oauth_token_secret) self.client_args = client_args or {} default_headers = {'User-Agent': 'Twython Streaming v' + __version__} if 'headers' not in self.client_args: # If they didn't set any headers, set our defaults for them self.client_args['headers'] = default_headers elif 'User-Agent' not in self.client_args['headers']: # If they set headers, but didn't include User-Agent.. # set it for them self.client_args['headers'].update(default_headers) self.client_args['timeout'] = timeout self.client = requests.Session() self.client.auth = self.auth self.client.stream = True # Make a copy of the client args and iterate over them # Pop out all the acceptable args at this point because they will # Never be used again. client_args_copy = self.client_args.copy() for k, v in client_args_copy.items(): if k in ('cert', 'headers', 'hooks', 'max_redirects', 'proxies'): setattr(self.client, k, v) self.client_args.pop(k) # Pop, pop! self.api_version = '1.1' self.retry_in = retry_in self.retry_count = retry_count # Set up type methods StreamTypes = TwythonStreamerTypes(self) self.statuses = StreamTypes.statuses self.user = StreamTypes.user self.site = StreamTypes.site self.connected = False self.handlers = handlers if handlers else \ ['delete', 'limit', 'disconnect'] self.chunk_size = chunk_size def _request(self, url, method='GET', params=None): """Internal stream request handling""" self.connected = True retry_counter = 0 method = method.lower() func = getattr(self.client, method) params, _ = _transparent_params(params) def _send(retry_counter): requests_args = {} for k, v in self.client_args.items(): # Maybe this should be set as a class # variable and only done once? if k in ('timeout', 'allow_redirects', 'verify'): requests_args[k] = v while self.connected: try: if method == 'get': requests_args['params'] = params else: requests_args['data'] = params response = func(url, **requests_args) except requests.exceptions.Timeout: self.on_timeout() else: if response.status_code != 200: self.on_error(response.status_code, response.content) if self.retry_count and \ (self.retry_count - retry_counter) > 0: time.sleep(self.retry_in) retry_counter += 1 _send(retry_counter) return response while self.connected: response = _send(retry_counter) for line in response.iter_lines(self.chunk_size): if not self.connected: break if line: try: if is_py3: line = line.decode('utf-8') data = json.loads(line) except ValueError: # pragma: no cover self.on_error(response.status_code, 'Unable to decode response, \ not valid JSON.') else: if self.on_success(data): # pragma: no cover for message_type in self.handlers: if message_type in data: handler = getattr(self, 'on_' + message_type, None) if handler \ and callable(handler) \ and not handler(data.get(message_type)): break response.close() def on_success(self, data): # pragma: no cover """Called when data has been successfully received from the stream. Returns True if other handlers for this message should be invoked. Feel free to override this to handle your streaming data how you want it handled. See https://dev.twitter.com/docs/streaming-apis/messages for messages sent along in stream responses. :param data: data recieved from the stream :type data: dict """ return True def on_error(self, status_code, data): # pragma: no cover """Called when stream returns non-200 status code Feel free to override this to handle your streaming data how you want it handled. :param status_code: Non-200 status code sent from stream :type status_code: int :param data: Error message sent from stream :type data: dict """ return def on_timeout(self): # pragma: no cover """ Called when the request has timed out """ return def disconnect(self): """Used to disconnect the streaming client manually""" self.connected = False twython-3.4.0/twython/streaming/types.py0000644000076500000240000000653212711074104022065 0ustar mikehelmickstaff00000000000000# -*- coding: utf-8 -*- """ twython.streaming.types ~~~~~~~~~~~~~~~~~~~~~~~ This module contains classes and methods for :class:`TwythonStreamer` to use. """ class TwythonStreamerTypes(object): """Class for different stream endpoints Not all streaming endpoints have nested endpoints. User Streams and Site Streams are single streams with no nested endpoints Status Streams include filter, sample and firehose endpoints """ def __init__(self, streamer): self.streamer = streamer self.statuses = TwythonStreamerTypesStatuses(streamer) def user(self, **params): """Stream user Accepted params found at: https://dev.twitter.com/docs/api/1.1/get/user """ url = 'https://userstream.twitter.com/%s/user.json' \ % self.streamer.api_version self.streamer._request(url, params=params) def site(self, **params): """Stream site Accepted params found at: https://dev.twitter.com/docs/api/1.1/get/site """ url = 'https://sitestream.twitter.com/%s/site.json' \ % self.streamer.api_version self.streamer._request(url, params=params) class TwythonStreamerTypesStatuses(object): """Class for different statuses endpoints Available so TwythonStreamer.statuses.filter() is available. Just a bit cleaner than TwythonStreamer.statuses_filter(), statuses_sample(), etc. all being single methods in TwythonStreamer """ def __init__(self, streamer): self.streamer = streamer self.params = None def filter(self, **params): """Stream statuses/filter :param \*\*params: Parameters to send with your stream request Accepted params found at: https://dev.twitter.com/docs/api/1.1/post/statuses/filter """ url = 'https://stream.twitter.com/%s/statuses/filter.json' \ % self.streamer.api_version self.streamer._request(url, 'POST', params=params) def sample(self, **params): """Stream statuses/sample :param \*\*params: Parameters to send with your stream request Accepted params found at: https://dev.twitter.com/docs/api/1.1/get/statuses/sample """ url = 'https://stream.twitter.com/%s/statuses/sample.json' \ % self.streamer.api_version self.streamer._request(url, params=params) def firehose(self, **params): """Stream statuses/firehose :param \*\*params: Parameters to send with your stream request Accepted params found at: https://dev.twitter.com/docs/api/1.1/get/statuses/firehose """ url = 'https://stream.twitter.com/%s/statuses/firehose.json' \ % self.streamer.api_version self.streamer._request(url, params=params) def set_dynamic_filter(self, **params): """Set/update statuses/filter :param \*\*params: Parameters to send with your stream request Accepted params found at: https://dev.twitter.com/docs/api/1.1/post/statuses/filter """ self.params = params def dynamic_filter(self): """Stream statuses/filter with dynamic parameters""" url = 'https://stream.twitter.com/%s/statuses/filter.json' \ % self.streamer.api_version self.streamer._request(url, 'POST', params=self.params) twython-3.4.0/twython.egg-info/0000755000076500000240000000000012711075147020052 5ustar mikehelmickstaff00000000000000twython-3.4.0/twython.egg-info/dependency_links.txt0000644000076500000240000000000112711075146024117 0ustar mikehelmickstaff00000000000000 twython-3.4.0/twython.egg-info/PKG-INFO0000644000076500000240000006031112711075146021147 0ustar mikehelmickstaff00000000000000Metadata-Version: 1.1 Name: twython Version: 3.4.0 Summary: Actively maintained, pure Python wrapper for the Twitter API. Supports both normal and streaming Twitter APIs Home-page: https://github.com/ryanmcgrath/twython/tree/master Author: Ryan McGrath Author-email: ryan@venodesigns.net License: The MIT License Copyright (c) 2013 Ryan McGrath Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Description: Twython ======= .. image:: https://img.shields.io/pypi/v/twython.svg?style=flat-square :target: https://pypi.python.org/pypi/twython .. image:: https://img.shields.io/pypi/dw/twython.svg?style=flat-square :target: https://pypi.python.org/pypi/twython .. image:: https://img.shields.io/travis/ryanmcgrath/twython.svg?style=flat-square :target: https://travis-ci.org/ryanmcgrath/twython .. image:: https://img.shields.io/coveralls/ryanmcgrath/twython/master.svg?style=flat-square :target: https://coveralls.io/r/ryanmcgrath/twython?branch=master ``Twython`` is the premier Python library providing an easy (and up-to-date) way to access Twitter data. Actively maintained and featuring support for Python 2.6+ and Python 3. It's been battle tested by companies, educational institutions and individuals alike. Try it today! Features -------- - Query data for: - User information - Twitter lists - Timelines - Direct Messages - and anything found in `the docs `_ - Image Uploading: - Update user status with an image - Change user avatar - Change user background image - Change user banner image - OAuth 2 Application Only (read-only) Support - Support for Twitter's Streaming API - Seamless Python 3 support! Installation ------------ Install Twython via `pip `_ .. code-block:: bash $ pip install twython or, with `easy_install `_ .. code-block:: bash $ easy_install twython But, hey... `that's up to you `_. Or, if you want the code that is currently on GitHub .. code-block:: bash git clone git://github.com/ryanmcgrath/twython.git cd twython python setup.py install Documentation ------------- Documentation is available at https://twython.readthedocs.org/en/latest/ Starting Out ------------ First, you'll want to head over to https://dev.twitter.com/apps and register an application! After you register, grab your applications ``Consumer Key`` and ``Consumer Secret`` from the application details tab. The most common type of authentication is Twitter user authentication using OAuth 1. If you're a web app planning to have users sign up with their Twitter account and interact with their timelines, updating their status, and stuff like that this **is** the authentication for you! First, you'll want to import Twython .. code-block:: python from twython import Twython Authentication ~~~~~~~~~~~~~~ Obtain Authorization URL ^^^^^^^^^^^^^^^^^^^^^^^^ Now, you'll want to create a Twython instance with your ``Consumer Key`` and ``Consumer Secret`` Only pass *callback_url* to *get_authentication_tokens* if your application is a Web Application Desktop and Mobile Applications **do not** require a callback_url .. code-block:: python APP_KEY = 'YOUR_APP_KEY' APP_SECRET = 'YOUR_APP_SECRET' twitter = Twython(APP_KEY, APP_SECRET) auth = twitter.get_authentication_tokens(callback_url='http://mysite.com/callback') From the ``auth`` variable, save the ``oauth_token`` and ``oauth_token_secret`` for later use (these are not the final auth tokens). In Django or other web frameworks, you might want to store it to a session variable .. code-block:: python OAUTH_TOKEN = auth['oauth_token'] OAUTH_TOKEN_SECRET = auth['oauth_token_secret'] Send the user to the authentication url, you can obtain it by accessing .. code-block:: python auth['auth_url'] Handling the Callback ^^^^^^^^^^^^^^^^^^^^^ If your application is a Desktop or Mobile Application *oauth_verifier* will be the PIN code After they authorize your application to access some of their account details, they'll be redirected to the callback url you specified in ``get_authentication_tokens`` You'll want to extract the ``oauth_verifier`` from the url. Django example: .. code-block:: python oauth_verifier = request.GET['oauth_verifier'] Now that you have the ``oauth_verifier`` stored to a variable, you'll want to create a new instance of Twython and grab the final user tokens .. code-block:: python twitter = Twython(APP_KEY, APP_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET) final_step = twitter.get_authorized_tokens(oauth_verifier) Once you have the final user tokens, store them in a database for later use:: OAUTH_TOKEN = final_step['oauth_token'] OAUTH_TOKEN_SECRET = final_step['oauth_token_secret'] For OAuth 2 (Application Only, read-only) authentication, see `our documentation `_ Dynamic Function Arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~ Keyword arguments to functions are mapped to the functions available for each endpoint in the Twitter API docs. Doing this allows us to be incredibly flexible in querying the Twitter API, so changes to the API aren't held up from you using them by this library. Basic Usage ----------- **Function definitions (i.e. get_home_timeline()) can be found by reading over twython/endpoints.py** Create a Twython instance with your application keys and the users OAuth tokens .. code-block:: python from twython import Twython twitter = Twython(APP_KEY, APP_SECRET, OAUTH_TOKEN, OAUTH_TOKEN_SECRET) Authenticated Users Home Timeline ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Documentation: https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline .. code-block:: python twitter.get_home_timeline() Updating Status ~~~~~~~~~~~~~~~ This method makes use of dynamic arguments, `read more about them `_ Documentation: https://dev.twitter.com/docs/api/1/post/statuses/update .. code-block:: python twitter.update_status(status='See how easy using Twython is!') Searching ~~~~~~~~~ https://dev.twitter.com/docs/api/1.1/get/search/tweets says it takes "q" and "result_type" amongst other arguments .. code-block:: python twitter.search(q='twitter') twitter.search(q='twitter', result_type='popular') Advanced Usage -------------- - `Advanced Twython Usage `_ - `Streaming with Twython `_ Notes ----- - Twython 3.0.0 has been injected with 1000mgs of pure awesomeness! OAuth 2 application authentication is now supported. And a *whole lot* more! See the `CHANGELOG `_ for more details! Questions, Comments, etc? ------------------------- My hope is that Twython is so simple that you'd never *have* to ask any questions, but if you feel the need to contact me for this (or other) reasons, you can hit me up at ryan@venodesigns.net. Or if I'm to busy to answer, feel free to ping mikeh@ydekproductions.com as well. Follow us on Twitter: - `@ryanmcgrath `_ - `@mikehelmick `_ Want to help? ------------- Twython is useful, but ultimately only as useful as the people using it (say that ten times fast!). If you'd like to help, write example code, contribute patches, document things on the wiki, tweet about it. Your help is always appreciated! .. :changelog: History ------- 3.4.0 (2016-30-04) ++++++++++++++++++ - Added `upload_video` endpoint - Fix quoted status checks in `html_for_tweet` - Fix `html_for_tweet` method response when hashtag/mention is a substring of another 3.3.0 (2015-18-07) ++++++++++++++++++ - Added support for muting users - Fix typos in documentation - Updated documentation examples - Added dynamic filtering to streamer 3.2.0 (2014-10-30) ++++++++++++++++++ - PEP8'd some code - Added `lookup_status` function to `endpoints.py` - Added keyword argument to `cursor` to return full pages rather than individual results - `cursor` now uses while loop rather than recursion - Fixed issue where Twython was unnecessarily disabling compression - Using `responses` to mock API calls in tests - Fixed some typos in documentation - Added `retry_after` attribute to `TwythonRateLimitError` - Added `upload_media` method to `Twython` in favor of `update_with_media` - Deprecating `update_with_media` per Twitter API 1.1 (https://dev.twitter.com/rest/reference/post/statuses/update_with_media) - Unpin `requests` and `requests-oauthlib` in `requirements.txt` 3.1.2 (2013-12-05) ++++++++++++++++++ - Fixed Changelog (HISTORY.rst) 3.1.1 (2013-12-05) ++++++++++++++++++ - Update `requests` version to 2.1.0. - Fixed: Streaming issue where `Exceptions` in handlers or `on_success` which subclass `ValueError` would previously be caught and reported as a JSON decoding problem, and `on_error()` would be called (with status_code=200) - Fixed issue where XML was returned when bad tokens were passed to `get_authorized_tokens` - Fixed import for `setup` causing installation to fail on some devices (eg. Nokia N9/MeeGo) 3.1.0 (2013-09-25) ++++++++++++++++++ - Added ``html_for_tweet`` static method. This method accepts a tweet object returned from a Twitter API call and will return a string with urls, mentions and hashtags in the tweet replaced with HTML. - Pass ``client_args`` to the streaming ``__init__``, much like in core Twython (you can pass headers, timeout, hooks, proxies, etc.). - Streamer has new parameter ``handlers`` which accepts a list of strings related to functions that are apart of the Streaming class and start with "on\_". i.e. ['delete'] is passed, when 'delete' is received from a stream response; ``on_delete`` will be called. - When an actual request error happens and a ``RequestException`` is raised, it is caught and a ``TwythonError`` is raised instead for convenience. - Added "cursor"-like functionality. Endpoints with the attribute ``iter_mode`` will be able to be passed to ``Twython.cursor`` and returned as a generator. - ``Twython.search_gen`` has been deprecated. Please use ``twitter.cursor(twitter.search, q='your_query')`` instead, where ``twitter`` is your ``Twython`` instance. - Added methods ``get_list_memberships``, ``get_twitter_configuration``, ``get_supported_languages``, ``get_privacy_policy``, ``get_tos`` - Added ``auth_endpoint`` parameter to ``Twython.__init__`` for cases when the right parameters weren't being shown during the authentication step. - Fixed streaming issue where results wouldn't be returned for streams that weren't so active (See https://github.com/ryanmcgrath/twython/issues/202#issuecomment-19915708) - Streaming API now uses ``_transparent_params`` so when passed ``True`` or ``False`` or an array, etc. Twython formats it to meet Twitter parameter standards (i.e. ['ryanmcgrath', 'mikehelmick', 'twitterapi'] would convert to string 'ryanmcgrath,mikehelmick,twitterapi') 3.0.0 (2013-06-18) ++++++++++++++++++ - Changed ``twython/twython.py`` to ``twython/api.py`` in attempt to make structure look a little neater - Removed all camelCase function access (anything like ``getHomeTimeline`` is now ``get_home_timeline``) - Removed ``shorten_url``. With the ``requests`` library, shortening a URL on your own is simple enough - ``twitter_token``, ``twitter_secret`` and ``callback_url`` are no longer passed to ``Twython.__init__`` - ``twitter_token`` and ``twitter_secret`` have been replaced with ``app_key`` and ``app_secret`` respectively - ``callback_url`` is now passed through ``Twython.get_authentication_tokens`` - Update ``test_twython.py`` docstrings per http://www.python.org/dev/peps/pep-0257/ - Removed ``get_list_memberships``, method is Twitter API 1.0 deprecated - Developers can now pass an array as a parameter to Twitter API methods and they will be automatically joined by a comma and converted to a string - ``endpoints.py`` now contains ``EndpointsMixin`` (rather than the previous ``api_table`` dict) for Twython, which enables Twython to use functions declared in the Mixin. - Added OAuth 2 authentication (Application Only) for when you want to make read-only calls to Twitter without having to go through the whole user authentication ritual (see docs for usage) - Added ``obtain_access_token`` to obtain an OAuth 2 Application Only read-only access token - ``construct_api_url`` now accepts keyword arguments like other Twython methods (e.g. instead of passing ``{'q': 'twitter', 'result_type': 'recent'}``, pass ``q='twitter', result_type='recent'``) - Pass ``client_args`` to the Twython ``__init__`` to manipulate request variables. ``client_args`` accepts a dictionary of keywords and values that accepted by ``requests`` (`Session API `_) [ex. headers, proxies, verify(SSL verification)] and the "request" section directly below it. - Added ``get_application_rate_limit_status`` API method for returning the current rate limits for the specified source - Added ``invalidate_token`` API method which allows registed apps to revoke an access token presenting its client credentials - ``get_lastfunction_header`` now accepts a ``default_return_value`` parameter. This means that if you pass a second value (ex. ``Twython.get_lastfunction_header('x-rate-limit-remaining', 0)``) and the value is not found, it returns your default value 2.10.1 (2013-05-29) ++++++++++++++++++ - More test coverage! - Fix ``search_gen`` - Fixed ``get_lastfunction_header`` to actually do what its docstring says, returns ``None`` if header is not found - Updated some internal API code, ``__init__`` didn't need to have ``self.auth`` and ``self.headers`` because they were never used anywhere else but the ``__init__`` - Added ``disconnect`` method to ``TwythonStreamer``, allowing users to disconnect as they desire - Updated ``TwythonStreamError`` docstring, also allow importing it from ``twython`` - No longer raise ``TwythonStreamError`` when stream line can't be decoded. Instead, sends signal to ``TwythonStreamer.on_error`` - Allow for (int, long, float) params to be passed to Twython Twitter API functions in Python 2, and (int, float) in Python 3 2.10.0 (2013-05-21) ++++++++++++++++++ - Added ``get_retweeters_ids`` method - Fixed ``TwythonDeprecationWarning`` on camelCase functions if the camelCase was the same as the PEP8 function (i.e. ``Twython.retweet`` did not change) - Fixed error message bubbling when error message returned from Twitter was not an array (i.e. if you try to retweet something twice, the error is not found at index 0) - Added "transparent" parameters for making requests, meaning users can pass bool values (True, False) to Twython methods and we convert your params in the background to satisfy the Twitter API. Also, file objects can now be passed seamlessly (see examples in README and in /examples dir for details) - Callback URL is optional in ``get_authentication_tokens`` to accomedate those using OOB authorization (non web clients) - Not part of the python package, but tests are now available along with Travis CI hooks - Added ``__repr__`` definition for Twython, when calling only returning - Cleaned up ``Twython.construct_api_url``, uses "transparent" parameters (see 4th bullet in this version for explaination) - Update ``requests`` and ``requests-oauthlib`` requirements, fixing posting files AND post data together, making authenticated requests in general in Python 3.3 2.9.1 (2013-05-04) ++++++++++++++++++ - "PEP8" all the functions. Switch functions from camelCase() to underscore_funcs(). (i.e. ``updateStatus()`` is now ``update_status()``) 2.9.0 (2013-05-04) ++++++++++++++++++ - Fixed streaming issue #144, added ``TwythonStreamer`` to aid users in a friendly streaming experience (streaming examples in ``examples`` and README's have been updated as well) - ``Twython`` now requires ``requests-oauthlib`` 0.3.1, fixes #154 (unable to upload media when sending POST data with the file) 2.8.0 (2013-04-29) ++++++++++++++++++ - Added a ``HISTORY.rst`` to start tracking history of changes - Updated ``twitter_endpoints.py`` to ``endpoints.py`` for cleanliness - Removed twython3k directory, no longer needed - Added ``compat.py`` for compatability with Python 2.6 and greater - Added some ascii art, moved description of Twython and ``__author__`` to ``__init__.py`` - Added ``version.py`` to store the current Twython version, instead of repeating it twice -- it also had to go into it's own file because of dependencies of ``requests`` and ``requests-oauthlib``, install would fail because those libraries weren't installed yet (on fresh install of Twython) - Removed ``find_packages()`` from ``setup.py``, only one package (we can just define it) - added quick publish method for Ryan and I: ``python setup.py publish`` is faster to type and easier to remember than ``python setup.py sdist upload`` - Removed ``base_url`` from ``endpoints.py`` because we're just repeating it in ``Twython.__init__`` - ``Twython.get_authentication_tokens()`` now takes ``callback_url`` argument rather than passing the ``callback_url`` through ``Twython.__init__``, ``callback_url`` is only used in the ``get_authentication_tokens`` method and nowhere else (kept in init though for backwards compatability) - Updated README to better reflect current Twython codebase - Added ``warnings.simplefilter('default')`` line in ``twython.py`` for Python 2.7 and greater to display Deprecation Warnings in console - Added Deprecation Warnings for usage of ``twitter_token``, ``twitter_secret`` and ``callback_url`` in ``Twython.__init__`` - Headers now always include the User-Agent as Twython vXX unless User-Agent is overwritten - Removed senseless TwythonError thrown if method is not GET or POST, who cares -- if the user passes something other than GET or POST just let Twitter return the error that they messed up - Removed conversion to unicode of (int, bool) params passed to a requests. ``requests`` isn't greedy about variables that can't be converted to unicode anymore - Removed `bulkUserLookup` (please use `lookupUser` instead), removed `getProfileImageUrl` (will be completely removed from Twitter API on May 7th, 2013) - Updated shortenUrl to actually work for those using it, but it is being deprecated since `requests` makes it easy for developers to implement their own url shortening in their app (see https://github.com/ryanmcgrath/twython/issues/184) - Twython Deprecation Warnings will now be seen in shell when using Python 2.7 and greater - Twython now takes ``ssl_verify`` parameter, defaults True. Set False if you're having development server issues - Removed internal ``_media_update`` function, we could have always just used ``self.post`` 2.7.3 (2013-04-12) ++++++++++++++++++ - Fixed issue where Twython Exceptions were not being logged correctly 2.7.2 (2013-04-08) ++++++++++++++++++ - Fixed ``AttributeError`` when trying to decode the JSON response via ``Response.json()`` 2.7.1 (2013-04-08) ++++++++++++++++++ - Removed ``simplejson`` dependency - Fixed ``destroyDirectMessage``, ``createBlock``, ``destroyBlock`` endpoints in ``twitter_endpoints.py`` - Added ``getProfileBannerSizes`` method to ``twitter_endpoints.py`` - Made oauth_verifier argument required in ``get_authorized_tokens`` - Update ``updateProfileBannerImage`` to use v1.1 endpoint 2.7.0 (2013-04-04) ++++++++++++++++++ - New ``showOwnedLists`` method 2.7.0 (2013-03-31) ++++++++++++++++++ - Added missing slash to ``getMentionsTimeline`` in ``twitter_endpoints.py`` 2.6.0 (2013-03-29) ++++++++++++++++++ - Updated ``twitter_endpoints.py`` to better reflect order of API endpoints on the Twitter API v1.1 docs site Keywords: twitter search api tweet twython stream Platform: UNKNOWN Classifier: Development Status :: 4 - Beta Classifier: Intended Audience :: Developers Classifier: License :: OSI Approved :: MIT License Classifier: Topic :: Software Development :: Libraries :: Python Modules Classifier: Topic :: Communications :: Chat Classifier: Topic :: Internet twython-3.4.0/twython.egg-info/requires.txt0000644000076500000240000000005012711075146022444 0ustar mikehelmickstaff00000000000000requests>=2.1.0 requests_oauthlib>=0.4.0twython-3.4.0/twython.egg-info/SOURCES.txt0000644000076500000240000000066712711075147021747 0ustar mikehelmickstaff00000000000000HISTORY.rst LICENSE MANIFEST.in README.rst requirements.txt setup.py twython/__init__.py twython/advisory.py twython/api.py twython/compat.py twython/endpoints.py twython/exceptions.py twython/helpers.py twython.egg-info/PKG-INFO twython.egg-info/SOURCES.txt twython.egg-info/dependency_links.txt twython.egg-info/requires.txt twython.egg-info/top_level.txt twython/streaming/__init__.py twython/streaming/api.py twython/streaming/types.pytwython-3.4.0/twython.egg-info/top_level.txt0000644000076500000240000000001012711075146022572 0ustar mikehelmickstaff00000000000000twython