python-tumblpy

Name	python-tumblpy JSON
Version	1.1.4 JSON
	download
home_page	https://github.com/michaelhelmick/python-tumblpy/
Summary	A Python Library to interface with Tumblr v2 REST API & OAuth
upload_time	2017-02-08 22:01:53
maintainer
docs_url	None
author	Mike Helmick
requires_python
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.
keywords	python tumblpy tumblr oauth api
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            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
    # or you could use the `posts` method
    audio_posts = t.posts(blog_url, 'audio')
    print audio_posts
    all_posts = t.posts(blog_url)
    print all_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.4 (2016-02-08)
++++++++++++++++++

- Remove old api url string formatting.
- Added ``posts`` method to Tumblpy, see README for example.

1.1.3 (2016-01-17)
++++++++++++++++++

- Fix missing import

1.1.2 (2016-12-22)
++++++++++++++++++

- Fix missing import

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

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/michaelhelmick/python-tumblpy/",
    "name": "python-tumblpy",
    "maintainer": "",
    "docs_url": null,
    "requires_python": "",
    "maintainer_email": "",
    "keywords": "python tumblpy tumblr oauth api",
    "author": "Mike Helmick",
    "author_email": "me@michaelhelmick.com",
    "download_url": "https://files.pythonhosted.org/packages/32/f3/055815d8ca6c71882d5ef3b13b43731130c341ab6e02e252973f6d52677e/python-tumblpy-1.1.4.tar.gz",
    "platform": "",
    "description": "Tumblpy\n=======\n\n.. image:: https://pypip.in/d/python-tumblpy/badge.png\n        :target: https://crate.io/packages/python-tumblpy/\n\nTumblpy is a Python library to help interface with Tumblr v2 REST API & OAuth\n\nFeatures\n--------\n\n* Retrieve user information and blog information\n* Common Tumblr methods\n   - Posting blog posts\n   - Unfollowing/following blogs\n   - Edit/delete/reblog posts\n   - And many more!!\n* Photo Uploading\n* Transparent *Python 3* Support!\n\n\nInstallation\n------------\n\nInstalling Tumbply is simple:\n::\n\n    $ pip install python-tumblpy\n\n\nUsage\n-----\n\nImporting\n~~~~~~~~~\n\n.. code-block:: python\n\n    from tumblpy import Tumblpy\n\nAuthorization URL\n~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n    t = Tumblpy(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET)\n\n    auth_props = t.get_authentication_tokens(callback_url='http://michaelhelmick.com')\n    auth_url = auth_props['auth_url']\n\n    OAUTH_TOKEN_SECRET = auth_props['oauth_token_secret']\n\n    print 'Connect with Tumblr via: %s' % auth_url\n\nOnce 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.\n\nHandling the Callback\n~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n    # OAUTH_TOKEN_SECRET comes from the previous step\n    # if needed, store those in a session variable or something\n\n    # oauth_verifier and OAUTH_TOKEN are found in your callback url querystring\n    # In Django, you'd do something like\n    # OAUTH_TOKEN = request.GET.get('oauth_token')\n    # oauth_verifier = request.GET.get('oauth_verifier')\n\n\n    t = Tumblpy(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET,\n                OAUTH_TOKEN, OAUTH_TOKEN_SECRET)\n\n    authorized_tokens = t.get_authorized_tokens(oauth_verifier)\n\n    final_oauth_token = authorized_tokens['oauth_token']\n    final_oauth_token_secret = authorized_tokens['oauth_token_secret']\n\n    # Save those tokens to the database for a later use?\n\nGetting some User information\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n    # Get the final tokens from the database or wherever you have them stored\n\n    t = Tumblpy(YOUR_CONSUMER_KEY, YOUR_CONSUMER_SECRET,\n                OAUTH_TOKEN, OAUTH_TOKEN_SECRET)\n\n    # Print out the user info, let's get the first blog url...\n    blog_url = t.post('user/info')\n    blog_url = blog_url['user']['blogs'][0]['url']\n\nGetting posts from a certain blog\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n    # Assume you are using the blog_url and Tumblpy instance from the previous section\n    posts = t.get('posts', blog_url=blog_url)\n    print posts\n    # or you could use the `posts` method\n    audio_posts = t.posts(blog_url, 'audio')\n    print audio_posts\n    all_posts = t.posts(blog_url)\n    print all_posts\n\nCreating a post with a photo\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n::\n\n    # Assume you are using the blog_url and Tumblpy instance from the previous sections\n\n    photo = open('/path/to/file/image.png', 'rb')\n    post = t.post('post', blog_url=blog_url, params={'type':'photo', 'caption': 'Test Caption', 'data': photo})\n    print post  # returns id if posted successfully\n\nPosting an Edited Photo *(This example resizes a photo)*\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n    # Assume you are using the blog_url and Tumblpy instance from the previous sections\n\n    # Like I said in the previous section, you can pass any object that has a\n    # read() method\n\n    # Assume you are working with a JPEG\n\n    from PIL import Image\n    from StringIO import StringIO\n\n    photo = Image.open('/path/to/file/image.jpg')\n\n    basewidth = 320\n    wpercent = (basewidth / float(photo.size[0]))\n    height = int((float(photo.size[1]) * float(wpercent)))\n    photo = photo.resize((basewidth, height), Image.ANTIALIAS)\n\n    image_io = StringIO.StringIO()\n    photo.save(image_io, format='JPEG')\n\n    image_io.seek(0)\n\n    try:\n        post = t.post('post', blog_url=blog_url, params={'type':'photo', 'caption': 'Test Caption', 'data': photo})\n        print post\n    except TumblpyError, e:\n        # Maybe the file was invalid?\n        print e.message\n\nFollowing a user\n~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n    # Assume you are using the blog_url and Tumblpy instance from the previous sections\n    try:\n        follow = t.post('user/follow', params={'url': 'tumblpy.tumblr.com'})\n    except TumblpyError:\n        # if the url given in params is not valid,\n        # Tumblr will respond with a 404 and Tumblpy will raise a TumblpyError\n\nGet a User Avatar URL *(No need for authentication for this method)*\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n    t = Tumblpy()\n    avatar = t.get_avatar_url(blog_url='tumblpy.tumblr.com', size=128)\n    print avatar['url']\n\n    # OR\n\n    avatar = t.get('avatar', blog_url='tumblpy.tumblr.com', extra_endpoints=['128'])\n    print avatar['url']\n\nCatching errors\n~~~~~~~~~~~~~~~\n\n.. code-block:: python\n\n    try:\n        t.post('user/info')\n    except TumbplyError, e:\n        print e.message\n        print 'Something bad happened :('\n\nThanks for using Tumblpy!\n\n\n.. :changelog:\n\nHistory\n-------\n\n1.1.4 (2016-02-08)\n++++++++++++++++++\n\n- Remove old api url string formatting.\n- Added ``posts`` method to Tumblpy, see README for example.\n\n1.1.3 (2016-01-17)\n++++++++++++++++++\n\n- Fix missing import\n\n1.1.2 (2016-12-22)\n++++++++++++++++++\n\n- Fix missing import\n\n1.1.1 (2016-05-12)\n++++++++++++++++++\n\n- Fix issue where blogs using https:// were being parsed wrong\n\n\n1.1.0 (2016-30-04)\n++++++++++++++++++\n\n- Add following and dashboard API methods\n\n\n1.0.5 (2015-08-13)\n++++++++++++++++++\n\n- Add support for ``proxies`` keyword for requests\n\n\n1.0.4 (2015-01-15)\n++++++++++++++++++\n\n- Fix request token decode issue in Python 3\n\n\n1.0.3 (2014-10-17)\n++++++++++++++++++\n\n- Unpin ``requests`` and ``requests-oauthlib`` versions in ``setup.py``\n\n\n1.0.2 (2013-05-31)\n++++++++++++++++++\n\n- Made the hotfix for posting photos a little more hotfixy... fixed posting just regular posts (as well as photos)\n\n1.0.1 (2013-05-29)\n++++++++++++++++++\n\n- Hotfix image uploading (not sure why we have to pass ``params`` AND ``data`` to the POST, hotfix for the time being...)\n- Allow for ints and floats (and longs in Python 2) to be passed as parameters to Tumblpy Tumblr API functions\n\n\n1.0.0 (2013-05-23)\n++++++++++++++++++\n\n- Changed internal Tumblpy API structure, but Tumblpy functions should still work as they did before\n- Updated README with more clear examples\n- Added LICENSE\n- ``_split_params_and_files`` has been moved to ``helpers.py``\n- All ``Tumblpy`` exceptions are found in ``exceptions.py``\n- Removed ``pool_maxsize`` from ``Tumblpy.__init__`` because it wasn't being used\n- Removed ``timeout`` parameter from all request methods for the time being\n- Removed ``TumblpyTimeout`` Exception\n- Moved ``callback_url`` parameter from ``Tumblpy.__init__`` to ``get_authentication_tokens``\n- All authentication and API calls over HTTPS\n- Dropped Python 2.5 support\n- Full, transparent Python 3.3 support\n",
    "bugtrack_url": null,
    "license": "Copyright (c) 2013, Mike Helmick\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.\n* 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.\n\nTHIS 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.",
    "summary": "A Python Library to interface with Tumblr v2 REST API & OAuth",
    "version": "1.1.4",
    "split_keywords": [
        "python",
        "tumblpy",
        "tumblr",
        "oauth",
        "api"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "e5f228b02eda82ec5fb2579cce646343",
                "sha256": "433882cc518ad479e0e38f1af56cc8b75f9b0d94131bc04234a0cd0d242e7cf9"
            },
            "downloads": -1,
            "filename": "python-tumblpy-1.1.4.tar.gz",
            "has_sig": false,
            "md5_digest": "e5f228b02eda82ec5fb2579cce646343",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 8587,
            "upload_time": "2017-02-08T22:01:53",
            "upload_time_iso_8601": "2017-02-08T22:01:53.005557Z",
            "url": "https://files.pythonhosted.org/packages/32/f3/055815d8ca6c71882d5ef3b13b43731130c341ab6e02e252973f6d52677e/python-tumblpy-1.1.4.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2017-02-08 22:01:53",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "github_user": "michaelhelmick",
    "github_project": "python-tumblpy",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": false,
    "lcname": "python-tumblpy"
}