Metadata-Version: 1.1
Name: python-tumblpy
Version: 1.0.4
Summary: A Python Library to interface with Tumblr v2 REST API & OAuth
Home-page: https://github.com/michaelhelmick/python-tumblpy/
Author: Mike Helmick
Author-email: me@michaelhelmick.com
License: Copyright (c) 2013, Mike Helmick
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Download-URL: https://github.com/michaelhelmick/python-tumblpy/zipball/master
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.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
        
Keywords: python tumblpy tumblr oauth api
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
