code/twython
1
Fork 0
Code Issues 23 Pull requests 4 Projects Releases 5 Packages Wiki Activity Actions

Merge branch 'requests_image_posting' (Pull Request #91)

Browse source 
- Fixes for README
- Re-added a bulkUserLookup method that warns for deprecation
- Merged in @michaelhelmick's work on media and oauth2 deprecation

Conflicts:
	setup.py
	twython/twython.py
This commit is contained in:
Ryan McGrath 2012-06-25 05:02:57 +09:00
commit 068c504030
6 changed files with 354 additions and 290 deletions
Download patch file Download diff file Expand all files Collapse all files

2
MANIFEST.in
View file

@ -1,3 +1,3 @@
include LICENSE README.markdown README.txt include LICENSE README.md README.rst
recursive-include examples * recursive-include examples *
recursive-exclude examples *.pyc recursive-exclude examples *.pyc

149
README.markdown → README.md
View file

@ -1,61 +1,114 @@
Twython - Easy Twitter utilities in Python Twython
========================================================================================= =======
Ah, Twitter, your API used to be so awesome, before you went and implemented the crap known
as OAuth 1.0. However, since you decided to force your entire development community over a barrel
about it, I suppose Twython has to support this. So, that said...
Does Twython handle OAuth? ```Twython``` is library providing an easy (and up-to-date) way to access Twitter data in Python
=========================================================================================================
Yes, in a sense. There's a variety of builtin-methods that you can use to handle the authentication ritual. Features
There's an **[example Django application](https://github.com/ryanmcgrath/twython-django)** that showcases --------
this - feel free to peruse and use!
* Query data for:
- User information
- Twitter lists
- Timelines
- User avatar URL
- and anything found in `the docs <https://dev.twitter.com/docs/api>`_
* Image Uploading!
- **Update user status with an image**
- Change user avatar
- Change user background image
Installation Installation
----------------------------------------------------------------------------------------------------- ------------
Installing Twython is fairly easy. You can...
(pip install | easy_install) twython (pip install | easy_install) twython
...or, you can clone the repo and install it the old fashioned way. ... or, you can clone the repo and install it the old fashioned way
git clone git://github.com/ryanmcgrath/twython.git git clone git://github.com/ryanmcgrath/twython.git
cd twython cd twython
sudo python setup.py install sudo python setup.py install
Please note: Usage
----------------------------------------------------------------------------------------------------- -----
As of Twython 2.0.0, we have changed routes for functions to abide by the **[Twitter Spring 2012 clean up](https://dev.twitter.com/docs/deprecations/spring-2012)**.
Please make changes to your code accordingly. Authorization URL
Example Use
-----------------------------------------------------------------------------------------------------
```python ```python
from twython import Twython t = Twython(app_key=app_key,
app_secret=app_secret,
callback_url='http://google.com/')
twitter = Twython() auth_props = t.get_authentication_tokens()
results = twitter.search(q = "bert")
# More function definitions can be found by reading over twython/twitter_endpoints.py, as well oauth_token = auth_props['oauth_token']
# as skimming the source file. Both are kept human-readable, and are pretty well documented or oauth_token_secret = auth_props['oauth_token_secret']
# very self documenting.
print 'Connect to Twitter via: %s' % auth_props['auth_url']
```
Be sure you have a URL set up to handle the callback after the user has allowed your app to access their data, the callback can be used for storing their final OAuth Token and OAuth Token Secret in a database for use at a later date.
Handling the callback
```python
'''
oauth_token and oauth_token_secret come from the previous step
if needed, store those in a session variable or something
'''
t = Twython(app_key=app_key,
app_secret=app_secret,
oauth_token=oauth_token,
oauth_token_secret=oauth_token_secret)
auth_tokens = t.get_authorized_tokens()
print auth_tokens
```
*Function definitions (i.e. getHomeTimeline()) can be found by reading over twython/twitter_endpoints.py*
Getting a user home timeline
```python
'''
oauth_token and oauth_token_secret are the final tokens produced
from the `Handling the callback` step
'''
t = Twython(app_key=app_key,
app_secret=app_secret,
oauth_token=oauth_token,
oauth_token_secret=oauth_token_secret)
# Returns an dict of the user home timeline
print t.getHomeTimeline()
```
Get a user avatar url *(no authentication needed)*
```python
t = Twython()
print t.getProfileImageUrl('ryanmcgrath', size='bigger')
print t.getProfileImageUrl('mikehelmick')
```
Search Twitter *(no authentication needed)*
```python
t = Twython()
print t.search(q='python')
``` ```
Streaming API Streaming API
---------------------------------------------------------------------------------------------------- *Usage is as follows; it's designed to be open-ended enough that you can adapt it to higher-level (read: Twitter must give you access)
Twython, as of v1.5.0, now includes an experimental **[Twitter Streaming API](https://dev.twitter.com/docs/streaming-api)** handler. streams.*
Usage is as follows; it's designed to be open-ended enough that you can adapt it to higher-level (read: Twitter must give you access)
streams. This also exists in large part (read: pretty much in full) thanks to the excellent **[python-requests](http://docs.python-requests.org/en/latest/)** library by
Kenneth Reitz.
```python ```python
import json
from twython import Twython
def on_results(results): def on_results(results):
"""A callback to handle passed results. Wheeee.
""" """
A callback to handle passed results. Wheeee.
""" print results
print json.dumps(results)
Twython.stream({ Twython.stream({
'username': 'your_username', 'username': 'your_username',
@ -64,8 +117,12 @@ Twython.stream({
}, on_results) }, on_results)
``` ```
A note about the development of Twython (specifically, 1.3) Notes
---------------------------------------------------------------------------------------------------- -----
As of Twython 2.0.0, we have changed routes for functions to abide by the **[Twitter Spring 2012 clean up](https://dev.twitter.com/docs/deprecations/spring-2012)** Please make changes to your code accordingly.
Development of Twython (specifically, 1.3)
------------------------------------------
As of version 1.3, Twython has been extensively overhauled. Most API endpoint definitions are stored As of version 1.3, Twython has been extensively overhauled. Most API endpoint definitions are stored
in a separate Python file, and the class itself catches calls to methods that match up in said table. in a separate Python file, and the class itself catches calls to methods that match up in said table.
@ -85,7 +142,7 @@ Doing this allows us to be incredibly flexible in querying the Twitter API, so c
from you using them by this library. from you using them by this library.
Twython 3k Twython 3k
----------------------------------------------------------------------------------------------------- ----------
There's an experimental version of Twython that's made for Python 3k. This is currently not guaranteed to There's an experimental version of Twython that's made for Python 3k. This is currently not guaranteed to
work in all situations, but it's provided so that others can grab it and hack on it. work in all situations, but it's provided so that others can grab it and hack on it.
If you choose to try it out, be aware of this. If you choose to try it out, be aware of this.
@ -94,9 +151,8 @@ If you choose to try it out, be aware of this.
his [Python 3 branch for python-oauth2](https://github.com/hades/python-oauth2/tree/python3) to have it work, though.** his [Python 3 branch for python-oauth2](https://github.com/hades/python-oauth2/tree/python3) to have it work, though.**
Questions, Comments, etc? Questions, Comments, etc?
----------------------------------------------------------------------------------------------------- -------------------------
My hope is that Twython is so simple that you'd never *have* to ask any questions, but if 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
you feel the need to contact me for this (or other) reasons, you can hit me up
at ryan@venodesigns.net. at ryan@venodesigns.net.
You can also follow me on Twitter - **[@ryanmcgrath](http://twitter.com/ryanmcgrath)**. You can also follow me on Twitter - **[@ryanmcgrath](http://twitter.com/ryanmcgrath)**.
@ -104,10 +160,8 @@ You can also follow me on Twitter - **[@ryanmcgrath](http://twitter.com/ryanmcgr
Twython is released under an MIT License - see the LICENSE file for more information. Twython is released under an MIT License - see the LICENSE file for more information.
Want to help? Want to help?
----------------------------------------------------------------------------------------------------- -------------
Twython is useful, but ultimately only as useful as the people using it (say that ten times fast!). If you'd 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!
like to help, write example code, contribute patches, document things on the wiki, tweet about it. Your help
is always appreciated!
Special Thanks to... Special Thanks to...
@ -134,3 +188,6 @@ me and let me know (or just issue a pull request on GitHub, and leave a note abo
- **[mckellister](https://github.com/mckellister)**, Fixes to `Exception`s raised by Twython (Rate Limits, etc). - **[mckellister](https://github.com/mckellister)**, Fixes to `Exception`s raised by Twython (Rate Limits, etc).
- **[tatz_tsuchiya](http://d.hatena.ne.jp/tatz_tsuchiya/20120115/1326623451)**, Fix for `lambda` scoping in key injection phase. - **[tatz_tsuchiya](http://d.hatena.ne.jp/tatz_tsuchiya/20120115/1326623451)**, Fix for `lambda` scoping in key injection phase.
- **[Voulnet (Mohammed ALDOUB)](https://github.com/Voulnet)**, Fixes for `http`/`https` access endpoints - **[Voulnet (Mohammed ALDOUB)](https://github.com/Voulnet)**, Fixes for `http`/`https` access endpoints
- **[fumieval](https://github.com/fumieval)**, Re-added Proxy support for 2.3.0.
- **[terrycojones](https://github.com/terrycojones)**, Error cleanup and Exception processing in 2.3.0.
- **[Leandro Ferreira](https://github.com/leandroferreira)**, Fix for double-encoding of search queries in 2.3.0.

202
README.rst Normal file
View file

@ -0,0 +1,202 @@
Twython
=======
``Twython`` is library providing an easy (and up-to-date) way to access Twitter data in Python
Features
--------
* Query data for:
- User information
- Twitter lists
- Timelines
- User avatar URL
- and anything found in `the docs <https://dev.twitter.com/docs/api>`_
* Image Uploading!
- **Update user status with an image**
- Change user avatar
- Change user background image
Installation
------------
::
pip install twython
... or, you can clone the repo and install it the old fashioned way
::
git clone git://github.com/ryanmcgrath/twython.git
cd twython
sudo python setup.py install
Usage
-----
Authorization URL
~~~~~~~~~~~~~~~~~
::
t = Twython(app_key=app_key,
app_secret=app_secret,
callback_url='http://google.com/')
auth_props = t.get_authentication_tokens()
oauth_token = auth_props['oauth_token']
oauth_token_secret = auth_props['oauth_token_secret']
print 'Connect to Twitter via: %s' % auth_props['auth_url']
Be sure you have a URL set up to handle the callback after the user has allowed your app to access their data, the callback can be used for storing their final OAuth Token and OAuth Token Secret in a database for use at a later date.
Handling the callback
~~~~~~~~~~~~~~~~~~~~~
::
'''
oauth_token and oauth_token_secret come from the previous step
if needed, store those in a session variable or something
'''
t = Twython(app_key=app_key,
app_secret=app_secret,
oauth_token=oauth_token,
oauth_token_secret=oauth_token_secret)
auth_tokens = t.get_authorized_tokens()
print auth_tokens
*Function definitions (i.e. getHomeTimeline()) can be found by reading over twython/twitter_endpoints.py*
Getting a user home timeline
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
'''
oauth_token and oauth_token_secret are the final tokens produced
from the `Handling the callback` step
'''
t = Twython(app_key=app_key,
app_secret=app_secret,
oauth_token=oauth_token,
oauth_token_secret=oauth_token_secret)
# Returns an dict of the user home timeline
print t.getHomeTimeline()
Get a user avatar url *(no authentication needed)*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
t = Twython()
print t.getProfileImageUrl('ryanmcgrath', size='bigger')
print t.getProfileImageUrl('mikehelmick')
Search Twitter *(no authentication needed)*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
t = Twython()
print t.search(q='python')
Streaming API
~~~~~~~~~~~~~
*Usage is as follows; it's designed to be open-ended enough that you can adapt it to higher-level (read: Twitter must give you access)
streams.*
::
def on_results(results):
"""A callback to handle passed results. Wheeee.
"""
print results
Twython.stream({
'username': 'your_username',
'password': 'your_password',
'track': 'python'
}, on_results)
Notes
-----
* As of Twython 2.0.0, we have changed routes for functions to abide by the `Twitter Spring 2012 clean up <https://dev.twitter.com/docs/deprecations/spring-2012>`_ Please make changes to your code accordingly.
Twython && Django
-----------------
If you're using Twython with Django, there's a sample project showcasing OAuth and such **[that can be found here](https://github.com/ryanmcgrath/twython-django)**. Feel free to peruse!
Development of Twython (specifically, 1.3)
------------------------------------------
As of version 1.3, Twython has been extensively overhauled. Most API endpoint definitions are stored
in a separate Python file, and the class itself catches calls to methods that match up in said table.
Certain functions require a bit more legwork, and get to stay in the main file, but for the most part
it's all abstracted out.
As of Twython 1.3, the syntax has changed a bit as well. Instead of Twython.core, there's a main
Twython class to import and use. If you need to catch exceptions, import those from twython as well.
Arguments to functions are now exact keyword matches for the Twitter API documentation - that means that
whatever query parameter arguments you read on Twitter's documentation (http://dev.twitter.com/doc) gets mapped
as a named argument to any Twitter function.
For example: the search API looks for arguments under the name "q", so you pass q="query_here" to search().
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.
Twython 3k
----------
There's an experimental version of Twython that's made for Python 3k. This is currently not guaranteed to
work in all situations, but it's provided so that others can grab it and hack on it.
If you choose to try it out, be aware of this.
**OAuth is now working thanks to updates from [Hades](https://github.com/hades). You'll need to grab
his [Python 3 branch for python-oauth2](https://github.com/hades/python-oauth2/tree/python3) to have it work, though.**
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.
You can also follow me on Twitter - `@ryanmcgrath <https://twitter.com/ryanmcgrath>`_
*Twython is released under an MIT License - see the LICENSE file for more information.*
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!
Special Thanks to...
--------------------
This is a list of all those who have contributed code to Twython in some way, shape, or form. I think it's
exhaustive, but I could be wrong - if you think your name should be here and it's not, please contact
me and let me know (or just issue a pull request on GitHub, and leave a note about it so I can just accept it ;)).
- `Mike Helmick (michaelhelmick) <https://github.com/michaelhelmick>`_, multiple fixes and proper ``requests`` integration. Too much to list here.
- `kracekumar <https://github.com/kracekumar>`_, early ``requests`` work and various fixes.
- `Erik Scheffers (eriks5) <https://github.com/eriks5>`_, various fixes regarding OAuth callback URLs.
- `Jordan Bouvier (jbouvier) <https://github.com/jbouvier>`_, various fixes regarding OAuth callback URLs.
- `Dick Brouwer (dikbrouwer) <https://github.com/dikbrouwer>`_, fixes for OAuth Verifier in ``get_authorized_tokens``.
- `hades <https://github.com/hades>`_, Fixes to various initial OAuth issues and updates to ``Twython3k`` to stay current.
- `Alex Sutton (alexdsutton) <https://github.com/alexsdutton/twython/>`_, fix for parameter substitution regular expression (catch underscores!).
- `Levgen Pyvovarov (bsn) <https://github.com/bsn>`_, Various argument fixes, cyrillic text support.
- `Mark Liu (mliu7) <https://github.com/mliu7>`_, Missing parameter fix for ``addListMember``.
- `Randall Degges (rdegges) <https://github.com/rdegge>`_, PEP-8 fixes, MANIFEST.in, installer fixes.
- `Idris Mokhtarzada (idris) <https://github.com/idris>`_, Fixes for various example code pieces.
- `Jonathan Elsas (jelsas) <https://github.com/jelsas>`_, Fix for original Streaming API stub causing import errors.
- `LuqueDaniel <https://github.com/LuqueDaniel>`_, Extended example code where necessary.
- `Mesar Hameed (mhameed) <https://github.com/mhameed>`_, Commit to swap ``__getattr__`` trick for a more debuggable solution.
- `Remy DeCausemaker (decause) <https://github.com/decause>`_, PEP-8 contributions.
- `[mckellister](https://github.com/mckellister) <https://dev.twitter.com/docs/deprecations/spring-2012>`_, Fixes to ``Exception`` raised by Twython (Rate Limits, etc).
- `tatz_tsuchiya <http://d.hatena.ne.jp/tatz_tsuchiya/20120115/1326623451>`_, Fix for ``lambda`` scoping in key injection phase.
- `Voulnet (Mohammed ALDOUB) <https://github.com/Voulnet>`_, Fixes for ``http/https`` access endpoints.
- `fumieval <https://github.com/fumieval>`_, Re-added Proxy support for 2.3.0.
- `terrycojones <https://github.com/terrycojones>`_, Error cleanup and Exception processing in 2.3.0.
- `Leandro Ferreira <https://github.com/leandroferreira>`_, Fix for double-encoding of search queries in 2.3.0.

136
README.txt
View file

@ -1,136 +0,0 @@
Twython - Easy Twitter utilities in Python
=========================================================================================
Ah, Twitter, your API used to be so awesome, before you went and implemented the crap known
as OAuth 1.0. However, since you decided to force your entire development community over a barrel
about it, I suppose Twython has to support this. So, that said...
Does Twython handle OAuth?
=========================================================================================================
Yes, in a sense. There's a variety of builtin-methods that you can use to handle the authentication ritual.
There's an **[example Django application](https://github.com/ryanmcgrath/twython-django)** that showcases
this - feel free to peruse and use!
Installation
-----------------------------------------------------------------------------------------------------
Installing Twython is fairly easy. You can...
(pip install | easy_install) twython
...or, you can clone the repo and install it the old fashioned way.
git clone git://github.com/ryanmcgrath/twython.git
cd twython
sudo python setup.py install
Please note:
-----------------------------------------------------------------------------------------------------
As of Twython 2.0.0, we have changed routes for functions to abide by the **[Twitter Spring 2012 clean up](https://dev.twitter.com/docs/deprecations/spring-2012)**.
Please make changes to your code accordingly.
Example Use
-----------------------------------------------------------------------------------------------------
``` python
from twython import Twython
twitter = Twython()
results = twitter.search(q = "bert")
# More function definitions can be found by reading over twython/twitter_endpoints.py, as well
# as skimming the source file. Both are kept human-readable, and are pretty well documented or
# very self documenting.
```
Streaming API
----------------------------------------------------------------------------------------------------
Twython, as of v1.5.0, now includes an experimental **[Twitter Streaming API](https://dev.twitter.com/docs/streaming-api)** handler.
Usage is as follows; it's designed to be open-ended enough that you can adapt it to higher-level (read: Twitter must give you access)
streams. This also exists in large part (read: pretty much in full) thanks to the excellent **[python-requests](http://docs.python-requests.org/en/latest/)** library by
Kenneth Reitz.
``` python
import json
from twython import Twython
def on_results(results):
"""
A callback to handle passed results. Wheeee.
"""
print json.dumps(results)
Twython.stream({
'username': 'your_username',
'password': 'your_password',
'track': 'python'
}, on_results)
```
A note about the development of Twython (specifically, 1.3)
----------------------------------------------------------------------------------------------------
As of version 1.3, Twython has been extensively overhauled. Most API endpoint definitions are stored
in a separate Python file, and the class itself catches calls to methods that match up in said table.
Certain functions require a bit more legwork, and get to stay in the main file, but for the most part
it's all abstracted out.
As of Twython 1.3, the syntax has changed a bit as well. Instead of Twython.core, there's a main
Twython class to import and use. If you need to catch exceptions, import those from twython as well.
Arguments to functions are now exact keyword matches for the Twitter API documentation - that means that
whatever query parameter arguments you read on Twitter's documentation (http://dev.twitter.com/doc) gets mapped
as a named argument to any Twitter function.
For example: the search API looks for arguments under the name "q", so you pass q="query_here" to search().
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.
Twython 3k
-----------------------------------------------------------------------------------------------------
There's an experimental version of Twython that's made for Python 3k. This is currently not guaranteed to
work in all situations, but it's provided so that others can grab it and hack on it.
If you choose to try it out, be aware of this.
**OAuth is now working thanks to updates from [Hades](https://github.com/hades). You'll need to grab
his [Python 3 branch for python-oauth2](https://github.com/hades/python-oauth2/tree/python3) to have it work, though.**
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.
You can also follow me on Twitter - **[@ryanmcgrath](http://twitter.com/ryanmcgrath)**.
Twython is released under an MIT License - see the LICENSE file for more information.
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!
Special Thanks to...
-----------------------------------------------------------------------------------------------------
This is a list of all those who have contributed code to Twython in some way, shape, or form. I think it's
exhaustive, but I could be wrong - if you think your name should be here and it's not, please contact
me and let me know (or just issue a pull request on GitHub, and leave a note about it so I can just accept it ;)).
- **[Mike Helmick (michaelhelmick)](https://github.com/michaelhelmick)**, multiple fixes and proper `requests` integration.
- **[kracekumar](https://github.com/kracekumar)**, early `requests` work and various fixes.
- **[Erik Scheffers (eriks5)](https://github.com/eriks5)**, various fixes regarding OAuth callback URLs.
- **[Jordan Bouvier (jbouvier)](https://github.com/jbouvier)**, various fixes regarding OAuth callback URLs.
- **[Dick Brouwer (dikbrouwer)](https://github.com/dikbrouwer)**, fixes for OAuth Verifier in `get_authorized_tokens`.
- **[hades](https://github.com/hades)**, Fixes to various initial OAuth issues and updates to `Twython3k` to stay current.
- **[Alex Sutton (alexdsutton)](https://github.com/alexsdutton/twython/)**, fix for parameter substitution regular expression (catch underscores!).
- **[Levgen Pyvovarov (bsn)](https://github.com/bsn)**, Various argument fixes, cyrillic text support.
- **[Mark Liu (mliu7)](https://github.com/mliu7)**, Missing parameter fix for `addListMember`.
- **[Randall Degges (rdegges)](https://github.com/rdegges)**, PEP-8 fixes, MANIFEST.in, installer fixes.
- **[Idris Mokhtarzada (idris)](https://github.com/idris)**, Fixes for various example code pieces.
- **[Jonathan Elsas (jelsas)](https://github.com/jelsas)**, Fix for original Streaming API stub causing import errors.
- **[LuqueDaniel](https://github.com/LuqueDaniel)**, Extended example code where necessary.
- **[Mesar Hameed (mhameed)](https://github.com/mhameed)**, Commit to swap `__getattr__` trick for a more debuggable solution.
- **[Remy DeCausemaker (decause)](https://github.com/decause)**, PEP-8 contributions.
- **[mckellister](https://github.com/mckellister)**, Fixes to `Exception`s raised by Twython (Rate Limits, etc).
- **[tatz_tsuchiya](http://d.hatena.ne.jp/tatz_tsuchiya/20120115/1326623451)**, Fix for `lambda` scoping in key injection phase.
- **[Voulnet (Mohammed ALDOUB)](https://github.com/Voulnet)**, Fixes for `http`/`https` access endpoints

6
setup.py
View file

@ -4,7 +4,7 @@ from setuptools import setup
from setuptools import find_packages from setuptools import find_packages
__author__ = 'Ryan McGrath <ryan@venodesigns.net>' __author__ = 'Ryan McGrath <ryan@venodesigns.net>'
__version__ = '2.0.1' __version__ = '2.3.0'
setup( setup(
# Basic package information. # Basic package information.
@ -16,7 +16,7 @@ setup(
include_package_data=True, include_package_data=True,
# Package dependencies. # Package dependencies.
install_requires=['simplejson', 'oauth2', 'requests'], install_requires=['simplejson', 'requests>=0.13.0'],
# Metadata for PyPI. # Metadata for PyPI.
author='Ryan McGrath', author='Ryan McGrath',
@ -25,7 +25,7 @@ setup(
url='http://github.com/ryanmcgrath/twython/tree/master', url='http://github.com/ryanmcgrath/twython/tree/master',
keywords='twitter search api tweet twython', keywords='twitter search api tweet twython',
description='An easy (and up to date) way to access Twitter data with Python.', description='An easy (and up to date) way to access Twitter data with Python.',
long_description=open('README.markdown').read(), long_description=open('README.rst').read(),
classifiers=[ classifiers=[
'Development Status :: 4 - Beta', 'Development Status :: 4 - Beta',
'Intended Audience :: Developers', 'Intended Audience :: Developers',

127
twython/twython.py
View file

@ -9,15 +9,14 @@
""" """
__author__ = "Ryan McGrath <ryan@venodesigns.net>" __author__ = "Ryan McGrath <ryan@venodesigns.net>"
__version__ = "2.0.2" __version__ = "2.3.0"
import urllib import urllib
import re import re
import time import warnings
import requests import requests
from requests.auth import OAuth1 from requests.auth import OAuth1
import oauth2 as oauth
try: try:
from urlparse import parse_qsl from urlparse import parse_qsl
@ -96,8 +95,8 @@ class Twython(object):
:param app_key: (optional) Your applications key :param app_key: (optional) Your applications key
:param app_secret: (optional) Your applications secret key :param app_secret: (optional) Your applications secret key
:param oauth_token: (optional) Used with oauth_secret to make authenticated calls :param oauth_token: (optional) Used with oauth_token_secret to make authenticated calls
:param oauth_secret: (optional) Used with oauth_token to make authenticated calls :param oauth_token_secret: (optional) Used with oauth_token to make authenticated calls
:param headers: (optional) Custom headers to send along with the request :param headers: (optional) Custom headers to send along with the request
:param callback_url: (optional) If set, will overwrite the callback url set in your application :param callback_url: (optional) If set, will overwrite the callback url set in your application
:param proxies: (optional) A dictionary of proxies, for example {"http":"proxy.example.org:8080", "https":"proxy.example.org:8081"}. :param proxies: (optional) A dictionary of proxies, for example {"http":"proxy.example.org:8080", "https":"proxy.example.org:8081"}.
@ -123,9 +122,9 @@ class Twython(object):
if oauth_token is not None: if oauth_token is not None:
self.oauth_token = u'%s' % oauth_token self.oauth_token = u'%s' % oauth_token
self.oauth_secret = None self.oauth_token_secret = None
if oauth_token_secret is not None: if oauth_token_secret is not None:
self.oauth_secret = u'%s' % oauth_token_secret self.oauth_token_secret = u'%s' % oauth_token_secret
self.callback_url = callback_url self.callback_url = callback_url
@ -141,9 +140,9 @@ class Twython(object):
self.auth = OAuth1(self.app_key, self.app_secret, self.auth = OAuth1(self.app_key, self.app_secret,
signature_type='auth_header') signature_type='auth_header')
if self.oauth_token is not None and self.oauth_secret is not None: if self.oauth_token is not None and self.oauth_token_secret is not None:
self.auth = OAuth1(self.app_key, self.app_secret, self.auth = OAuth1(self.app_key, self.app_secret,
self.oauth_token, self.oauth_secret, self.oauth_token, self.oauth_token_secret,
signature_type='auth_header') signature_type='auth_header')
if self.client is None: if self.client is None:
@ -171,27 +170,29 @@ class Twython(object):
) )
method = fn['method'].lower() method = fn['method'].lower()
if not method in ('get', 'post', 'delete'): if not method in ('get', 'post'):
raise TwythonError('Method must be of GET, POST or DELETE') raise TwythonError('Method must be of GET or POST')
content = self._request(url, method=method, params=kwargs) content = self._request(url, method=method, params=kwargs)
return content return content
def _request(self, url, method='GET', params=None, api_call=None): def _request(self, url, method='GET', params=None, files=None, api_call=None):
'''Internal response generator, no sense in repeating the same '''Internal response generator, no sense in repeating the same
code twice, right? ;) code twice, right? ;)
''' '''
myargs = {} myargs = {}
method = method.lower() method = method.lower()
params = params or {}
if method == 'get': if method == 'get':
url = '%s?%s' % (url, urllib.urlencode(params)) url = '%s?%s' % (url, urllib.urlencode(params))
else: else:
myargs = params myargs = params
func = getattr(self.client, method) func = getattr(self.client, method)
response = func(url, data=myargs, auth=self.auth) response = func(url, data=myargs, files=files, headers=self.headers, auth=self.auth)
content = response.content.decode('utf-8') content = response.content.decode('utf-8')
# create stash for last function intel # create stash for last function intel
@ -239,31 +240,23 @@ class Twython(object):
we haven't gotten around to putting it in Twython yet. :) we haven't gotten around to putting it in Twython yet. :)
''' '''
def request(self, endpoint, method='GET', params=None, version=1): def request(self, endpoint, method='GET', params=None, files=None, version=1):
params = params or {}
# In case they want to pass a full Twitter URL # In case they want to pass a full Twitter URL
# i.e. http://search.twitter.com/ # i.e. https://search.twitter.com/
if endpoint.startswith('http://') or endpoint.startswith('https://'): if endpoint.startswith('http://') or endpoint.startswith('https://'):
url = endpoint url = endpoint
else: else:
url = '%s/%s.json' % (self.api_url % version, endpoint) url = '%s/%s.json' % (self.api_url % version, endpoint)
content = self._request(url, method=method, params=params, api_call=url) content = self._request(url, method=method, params=params, files=files, api_call=url)
return content return content
def get(self, endpoint, params=None, version=1): def get(self, endpoint, params=None, version=1):
params = params or {}
return self.request(endpoint, params=params, version=version) return self.request(endpoint, params=params, version=version)
def post(self, endpoint, params=None, version=1): def post(self, endpoint, params=None, files=None, version=1):
params = params or {} return self.request(endpoint, 'POST', params=params, files=files, version=version)
return self.request(endpoint, 'POST', params=params, version=version)
def delete(self, endpoint, params=None, version=1):
params = params or {}
return self.request(endpoint, 'DELETE', params=params, version=version)
# End Dynamic Request Methods # End Dynamic Request Methods
@ -320,7 +313,7 @@ class Twython(object):
def get_authorized_tokens(self): def get_authorized_tokens(self):
"""Returns authorized tokens after they go through the auth_url phase. """Returns authorized tokens after they go through the auth_url phase.
""" """
response = self.client.get(self.access_token_url, auth=self.auth) response = self.client.get(self.access_token_url, headers=self.headers, auth=self.auth)
authorized_tokens = dict(parse_qsl(response.content)) authorized_tokens = dict(parse_qsl(response.content))
if not authorized_tokens: if not authorized_tokens:
raise TwythonError('Unable to decode authorized tokens.') raise TwythonError('Unable to decode authorized tokens.')
@ -359,34 +352,6 @@ class Twython(object):
def constructApiURL(base_url, params): def constructApiURL(base_url, params):
return base_url + "?" + "&".join(["%s=%s" % (Twython.unicode2utf8(key), urllib.quote_plus(Twython.unicode2utf8(value))) for (key, value) in params.iteritems()]) return base_url + "?" + "&".join(["%s=%s" % (Twython.unicode2utf8(key), urllib.quote_plus(Twython.unicode2utf8(value))) for (key, value) in params.iteritems()])
def bulkUserLookup(self, ids=None, screen_names=None, version=1, **kwargs):
""" A method to do bulk user lookups against the Twitter API.
Documentation: https://dev.twitter.com/docs/api/1/get/users/lookup
:ids or screen_names: (required)
:param ids: (optional) A list of integers of Twitter User IDs
:param screen_names: (optional) A list of strings of Twitter Screen Names
:param include_entities: (optional) When set to either true, t or 1,
each tweet will include a node called
"entities,". This node offers a variety of
metadata about the tweet in a discreet structure
e.g x.bulkUserLookup(screen_names=['ryanmcgrath', 'mikehelmick'],
include_entities=1)
"""
if ids is None and screen_names is None:
raise TwythonError('Please supply either a list of ids or \
screen_names for this method.')
if ids is not None:
kwargs['user_id'] = ','.join(map(str, ids))
if screen_names is not None:
kwargs['screen_name'] = ','.join(screen_names)
return self.get('users/lookup', params=kwargs, version=version)
def search(self, **kwargs): def search(self, **kwargs):
""" Returns tweets that match a specified query. """ Returns tweets that match a specified query.
@ -472,6 +437,16 @@ class Twython(object):
{'image': (file_, open(file_, 'rb'))}, {'image': (file_, open(file_, 'rb'))},
params={'tile': tile}) params={'tile': tile})
def bulkUserLookup(self, **kwargs):
"""Stub for a method that has been deprecated, kept for now to raise errors
properly if people are relying on this (which they are...).
"""
warnings.warn(
"This function has been deprecated. Please migrate to .lookupUser() - params should be the same.",
DeprecationWarning,
stacklevel=2
)
def updateProfileImage(self, file_, version=1): def updateProfileImage(self, file_, version=1):
"""Updates the authenticating user's profile image (avatar). """Updates the authenticating user's profile image (avatar).
@ -500,44 +475,7 @@ class Twython(object):
**params) **params)
def _media_update(self, url, file_, params=None): def _media_update(self, url, file_, params=None):
params = params or {} return self.post(url, params=params, files=file_)
oauth_params = {
'oauth_timestamp': int(time.time()),
}
#create a fake request with your upload url and parameters
faux_req = oauth.Request(method='POST', url=url, parameters=oauth_params)
#sign the fake request.
signature_method = oauth.SignatureMethod_HMAC_SHA1()
class dotdict(dict):
"""
This is a helper func. because python-oauth2 wants a
dict in dot notation.
"""
def __getattr__(self, attr):
return self.get(attr, None)
__setattr__ = dict.__setitem__
__delattr__ = dict.__delitem__
consumer = {
'key': self.app_key,
'secret': self.app_secret
}
token = {
'key': self.oauth_token,
'secret': self.oauth_secret
}
faux_req.sign_request(signature_method, dotdict(consumer), dotdict(token))
#create a dict out of the fake request signed params
self.headers.update(faux_req.to_header())
req = requests.post(url, data=params, files=file_, headers=self.headers)
return req.content
def getProfileImageUrl(self, username, size='normal', version=1): def getProfileImageUrl(self, username, size='normal', version=1):
"""Gets the URL for the user's profile image. """Gets the URL for the user's profile image.
@ -612,7 +550,10 @@ class Twython(object):
for line in stream.iter_lines(): for line in stream.iter_lines():
if line: if line:
try:
callback(simplejson.loads(line)) callback(simplejson.loads(line))
except ValueError:
raise TwythonError('Response was not valid JSON, unable to decode.')
@staticmethod @staticmethod
def unicode2utf8(text): def unicode2utf8(text):