Skip to main content

A Python Library to interface with Tumblr v2 REST API & OAuth

Project description

Tumblpy
=======

.. image:: https://pypip.in/d/python-tumblpy/badge.png
:target: https://crate.io/packages/python-tumblpy/

Tumblpy is a Python library to help interface with Tumblr v2 REST API & OAuth

Features
--------

* Retrieve user information and blog information
* Common Tumblr methods
- Posting blog posts
- Unfollowing/following blogs
- Edit/delete/reblog posts
- And many more!!
* Photo Uploading
* Transparent *Python 3* Support!


Installation
------------

Installing Tumbply is simple:
::

$ pip install python-tumblpy


Usage
-----

Importing
~~~~~~~~~

.. code-block:: python

from tumblpy import Tumblpy

Authorization URL
~~~~~~~~~~~~~~~~~

.. code-block:: python

t = Tumblpy(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET)

auth_props = t.get_authentication_tokens(callback_url='http://michaelhelmick.com')
auth_url = auth_props['auth_url']

OAUTH_TOKEN_SECRET = auth_props['oauth_token_secret']

print 'Connect with Tumblr via: %s' % auth_url

Once you click "Allow" be sure that there is a URL set up to handle getting finalized tokens and possibly adding them to your database to use their information at a later date.

Handling the Callback
~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

# OAUTH_TOKEN_SECRET comes from the previous step
# if needed, store those in a session variable or something

# oauth_verifier and OAUTH_TOKEN are found in your callback url querystring
# In Django, you'd do something like
# OAUTH_TOKEN = request.GET.get('oauth_token')
# oauth_verifier = request.GET.get('oauth_verifier')


t = Tumblpy(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)

authorized_tokens = t.get_authorized_tokens(oauth_verifier)

final_oauth_token = authorized_tokens['oauth_token']
final_oauth_token_secret = authorized_tokens['oauth_token_secret']

# Save those tokens to the database for a later use?

Getting some User information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

# Get the final tokens from the database or wherever you have them stored

t = Tumblpy(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET,
OAUTH_TOKEN, OAUTH_TOKEN_SECRET)

# Print out the user info, let's get the first blog url...
blog_url = t.post('user/info')
blog_url = blog_url['user']['blogs'][0]['url']

Getting posts from a certain blog
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

# Assume you are using the blog_url and Tumblpy instance from the previous section
posts = t.get('posts', blog_url=blog_url)
print posts

Creating a post with a photo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::

# Assume you are using the blog_url and Tumblpy instance from the previous sections

photo = open('/path/to/file/image.png', 'rb')
post = t.post('post', blog_url=blog_url, params={'type':'photo', 'caption': 'Test Caption', 'data': photo})
print post # returns id if posted successfully

Posting an Edited Photo *(This example resizes a photo)*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

# Assume you are using the blog_url and Tumblpy instance from the previous sections

# Like I said in the previous section, you can pass any object that has a
# read() method

# Assume you are working with a JPEG

from PIL import Image
from StringIO import StringIO

photo = Image.open('/path/to/file/image.jpg')

basewidth = 320
wpercent = (basewidth / float(photo.size[0]))
height = int((float(photo.size[1]) * float(wpercent)))
photo = photo.resize((basewidth, height), Image.ANTIALIAS)

image_io = StringIO.StringIO()
photo.save(image_io, format='JPEG')

image_io.seek(0)

try:
post = t.post('post', blog_url=blog_url, params={'type':'photo', 'caption': 'Test Caption', 'data': photo})
print post
except TumblpyError, e:
# Maybe the file was invalid?
print e.message

Following a user
~~~~~~~~~~~~~~~~

.. code-block:: python

# Assume you are using the blog_url and Tumblpy instance from the previous sections
try:
follow = t.post('user/follow', params={'url': 'tumblpy.tumblr.com'})
except TumblpyError:
# if the url given in params is not valid,
# Tumblr will respond with a 404 and Tumblpy will raise a TumblpyError

Get a User Avatar URL *(No need for authentication for this method)*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

t = Tumblpy()
avatar = t.get_avatar_url(blog_url='tumblpy.tumblr.com', size=128)
print avatar['url']

# OR

avatar = t.get('avatar', blog_url='tumblpy.tumblr.com', extra_endpoints=['128'])
print avatar['url']

Catching errors
~~~~~~~~~~~~~~~

.. code-block:: python

try:
t.post('user/info')
except TumbplyError, e:
print e.message
print 'Something bad happened :('

Thanks for using Tumblpy!


.. :changelog:

History
-------

1.1.1 (2016-05-12)
++++++++++++++++++

- Fix issue where blogs using https:// were being parsed wrong


1.1.0 (2016-30-04)
++++++++++++++++++

- Add following and dashboard API methods


1.0.5 (2015-08-13)
++++++++++++++++++

- Add support for ``proxies`` keyword for requests


1.0.4 (2015-01-15)
++++++++++++++++++

- Fix request token decode issue in Python 3


1.0.3 (2014-10-17)
++++++++++++++++++

- Unpin ``requests`` and ``requests-oauthlib`` versions in ``setup.py``


1.0.2 (2013-05-31)
++++++++++++++++++

- Made the hotfix for posting photos a little more hotfixy... fixed posting just regular posts (as well as photos)

1.0.1 (2013-05-29)
++++++++++++++++++

- Hotfix image uploading (not sure why we have to pass ``params`` AND ``data`` to the POST, hotfix for the time being...)
- Allow for ints and floats (and longs in Python 2) to be passed as parameters to Tumblpy Tumblr API functions


1.0.0 (2013-05-23)
++++++++++++++++++

- Changed internal Tumblpy API structure, but Tumblpy functions should still work as they did before
- Updated README with more clear examples
- Added LICENSE
- ``_split_params_and_files`` has been moved to ``helpers.py``
- All ``Tumblpy`` exceptions are found in ``exceptions.py``
- Removed ``pool_maxsize`` from ``Tumblpy.__init__`` because it wasn't being used
- Removed ``timeout`` parameter from all request methods for the time being
- Removed ``TumblpyTimeout`` Exception
- Moved ``callback_url`` parameter from ``Tumblpy.__init__`` to ``get_authentication_tokens``
- All authentication and API calls over HTTPS
- Dropped Python 2.5 support
- Full, transparent Python 3.3 support

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python-tumblpy-1.1.1.tar.gz (8.3 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page