Easy Twitter integration for Django.
Project description
ECL Twitter
===========
About
-----
ECL Twitter is an awesome Twitter library for Python 2.7+. It makes the Twitter
API a joy to use, and Django integration is baked in. To find out more, read
on!
If you have an issue to report or a feature request, add it to our
`issue tracker <https://github.com/elmcitylabs/ECL-Twitter/issues>`_.
.. _installation:
Installation
------------
ECL Twitter is on PyPi, so we recommend installing via `pip`_::
$ pip install ecl-twitter
.. _pip: http://www.pip-installer.org/en/latest/
.. _configuration:
Configuration
-------------
If you'd like to use ECL Twitter for a stand alone application (e.g., in a
script you're writing to download your tweets), you'll need to set the
environment variables ``TWITTER_KEY``, ``TWITTER_SECRET``, and
``TWITTER_REDIRECT_URL`` with the values appropriate for your Twitter
application.::
export TWITTER_KEY="Gmxb5Rh7gpOpzunQ7SQcOA"
export TWITTER_SECRET="irhZg1W5NO2r7M9IRwhjHKpzKPjJ3HXc6RYCbrM0"
export TWITTER_REDIRECT_URL="http://example.com/oauth/complete"
If you're only interested in integration with Django, read :ref:`django`.
.. _authentication:
Authentication
--------------
We've made authentication very simple. Probably too simple, to be honest.::
>>> from twitter import Twitter
>>> twitter = Twitter()
>>> url, token, secret = twitter.generate_authorization()
>>> url
https://api.twitter.com/oauth/authorize?oauth_token=XXX
After opening this URL in your browser and allowing the application, you'll be redirected to a page with a PIN. This is your ``verifier``.::
>>> twitter = Twitter(token, secret)
>>> data = twitter.oauth.access_token(oauth_verifier=verifier)
>>> data
<Objectifier#dict oauth_token_secret=unicode user_id=unicode oauth_token=unicode screen_name=unicode>
Congratulations, you have successfully authenticated with Twitter (told you it was easy). ``data`` is an ``Objectifier`` object which should contain your token, secret, user id, and screen name.
To call the API, use your newly-acquired access token and access token secret::
>>> twitter = Twitter(data.oauth_token, data.oauth_token_secret)
>>> tweets = twitter.statuses.user_timeline()
>>> tweets
<Objectifier#list elements:20>
So, yeah. That's it. Be fruitful and multiply.
.. _django:
Integrating with Django
-----------------------
What we did above is easy. For Django projects, we've made it even easier. In your views file::
from django.contrib.auth import authenticate, login
from django.http import HttpResponseRedirect
from ecl_twitter import twitter_begin, twitter_callback
from .models import User
# ...
@twitter_begin
def oauth_twitter_begin(request):
pass
@twitter_callback
def oauth_twitter_complete(request, data):
user, _ = User.objects.get_or_create(screen_name=data.screen_name, defaults={
'access_token': data.oauth_token,
'access_token_secret': data.oauth_token_secret })
user = authenticate(id=user.id)
login(request, user)
return HttpResponseRedirect(reverse('home'))
Add these values to your settings.::
# The User model that you'll be using to authenticate with Twitter.
PRIMARY_USER_MODEL = "app.User"
AUTHENTICATION_BACKENDS = (
# ...
'ecl_twitter.backends.TwitterAuthBackend',
)
TWITTER_KEY = "Gmxb5Rh7gpOpzunQ7SQcOA"
TWITTER_SECRET = "irhZg1W5NO2r7M9IRwhjHKpzKPjJ3HXc6RYCbrM0"
TWITTER_REDIRECT_URL = "http://example.com/oauth/complete"
Then map the above views in your urls.py::
# ...
urlpatterns = patterns('app.views',
# ...
url(r'^oauth/twitter/begin$', 'oauth_twitter_begin'),
url(r'^oauth/twitter/complete$', 'oauth_twitter_complete'),
)
You're done. Oh, you might also want to add some fields for storing the
Twitter-related fields in your user model.
Contributing, feedback, and questions
-------------------------------------
* Bitbucket: https://bitbucket.com/elmcitylabs
* Github: https://github.com/elmcitylabs
* Email: opensource@elmcitylabs.com.
* Twitter: `@elmcitylabs <http://twitter.com/elmcitylabs>`_
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
===========
About
-----
ECL Twitter is an awesome Twitter library for Python 2.7+. It makes the Twitter
API a joy to use, and Django integration is baked in. To find out more, read
on!
If you have an issue to report or a feature request, add it to our
`issue tracker <https://github.com/elmcitylabs/ECL-Twitter/issues>`_.
.. _installation:
Installation
------------
ECL Twitter is on PyPi, so we recommend installing via `pip`_::
$ pip install ecl-twitter
.. _pip: http://www.pip-installer.org/en/latest/
.. _configuration:
Configuration
-------------
If you'd like to use ECL Twitter for a stand alone application (e.g., in a
script you're writing to download your tweets), you'll need to set the
environment variables ``TWITTER_KEY``, ``TWITTER_SECRET``, and
``TWITTER_REDIRECT_URL`` with the values appropriate for your Twitter
application.::
export TWITTER_KEY="Gmxb5Rh7gpOpzunQ7SQcOA"
export TWITTER_SECRET="irhZg1W5NO2r7M9IRwhjHKpzKPjJ3HXc6RYCbrM0"
export TWITTER_REDIRECT_URL="http://example.com/oauth/complete"
If you're only interested in integration with Django, read :ref:`django`.
.. _authentication:
Authentication
--------------
We've made authentication very simple. Probably too simple, to be honest.::
>>> from twitter import Twitter
>>> twitter = Twitter()
>>> url, token, secret = twitter.generate_authorization()
>>> url
https://api.twitter.com/oauth/authorize?oauth_token=XXX
After opening this URL in your browser and allowing the application, you'll be redirected to a page with a PIN. This is your ``verifier``.::
>>> twitter = Twitter(token, secret)
>>> data = twitter.oauth.access_token(oauth_verifier=verifier)
>>> data
<Objectifier#dict oauth_token_secret=unicode user_id=unicode oauth_token=unicode screen_name=unicode>
Congratulations, you have successfully authenticated with Twitter (told you it was easy). ``data`` is an ``Objectifier`` object which should contain your token, secret, user id, and screen name.
To call the API, use your newly-acquired access token and access token secret::
>>> twitter = Twitter(data.oauth_token, data.oauth_token_secret)
>>> tweets = twitter.statuses.user_timeline()
>>> tweets
<Objectifier#list elements:20>
So, yeah. That's it. Be fruitful and multiply.
.. _django:
Integrating with Django
-----------------------
What we did above is easy. For Django projects, we've made it even easier. In your views file::
from django.contrib.auth import authenticate, login
from django.http import HttpResponseRedirect
from ecl_twitter import twitter_begin, twitter_callback
from .models import User
# ...
@twitter_begin
def oauth_twitter_begin(request):
pass
@twitter_callback
def oauth_twitter_complete(request, data):
user, _ = User.objects.get_or_create(screen_name=data.screen_name, defaults={
'access_token': data.oauth_token,
'access_token_secret': data.oauth_token_secret })
user = authenticate(id=user.id)
login(request, user)
return HttpResponseRedirect(reverse('home'))
Add these values to your settings.::
# The User model that you'll be using to authenticate with Twitter.
PRIMARY_USER_MODEL = "app.User"
AUTHENTICATION_BACKENDS = (
# ...
'ecl_twitter.backends.TwitterAuthBackend',
)
TWITTER_KEY = "Gmxb5Rh7gpOpzunQ7SQcOA"
TWITTER_SECRET = "irhZg1W5NO2r7M9IRwhjHKpzKPjJ3HXc6RYCbrM0"
TWITTER_REDIRECT_URL = "http://example.com/oauth/complete"
Then map the above views in your urls.py::
# ...
urlpatterns = patterns('app.views',
# ...
url(r'^oauth/twitter/begin$', 'oauth_twitter_begin'),
url(r'^oauth/twitter/complete$', 'oauth_twitter_complete'),
)
You're done. Oh, you might also want to add some fields for storing the
Twitter-related fields in your user model.
Contributing, feedback, and questions
-------------------------------------
* Bitbucket: https://bitbucket.com/elmcitylabs
* Github: https://github.com/elmcitylabs
* Email: opensource@elmcitylabs.com.
* Twitter: `@elmcitylabs <http://twitter.com/elmcitylabs>`_
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
ecl_twitter-1.0.9.tar.gz
(6.7 kB
view hashes)