Quickstart

Nyaa~! Welcome to the Kawaii tumblrdotcom API Client documentation! This is, like, the most adorbs way to interact with Tumblr’s API. Nya~! 😺

Install

pip install tumblrdotcom

You will also need to generate Oauth1 access tokens. See the Tumblr API documentation for more.

Usage

tumblrdotcom provides a Tumblr class that manages getting and retrieving posts and reblogs. Tumblr objects are initialised with the current user blog, and Oauth1 tokens, for example using python-dotenv:

import os

from dotenv import load_dotenv
from tumblr import *

load_dotenv()

tumblr = Tumblr(
    blog="staff",  # or "staff.tumblr.com" – use the blog you want to post from
    client_key=os.getenv("CONSUMER_KEY"),
    client_secret=os.getenv("CONSUMER_SECRET"),
    oauth_key=os.getenv("OAUTH_TOKEN"),
    oauth_secret=os.getenv("OAUTH_SECRET"),
)

Posts or reblogs can be constructed with several content blocks. There are several types of content blocks all defined in the content module. For example:

res = tumblr.post(
    content=(
        Heading("Making Posts on Tumblr"),
        Text("It's something to do."),
        Poll(
            question="What do you think?",
            options=[
                "I agree with this",
                "I do NOT agree with this",
                "My thoughts on this are complex",
            ],
        ),
    ),
    tags=["thoughts", "tumbler"]
)

post_id = res["response"]["id"]

Here, content is given as a tuple of content blocks.

This post can then be retrieved using its ID (this is also used in the url to the post):

res = tumblr.get_post(post_id)

This post could also be reblogged:

res = tumblr.reblog(
    from_id=post_id,
    from_blog="staff",
    content=(Text("I think this post is a little too controversial"),),
    tags=["drama"]
)

The poll results can also be obtained:

from pprint import pprint

res = tumblr.poll_results(post_id)

pprint(res["answers"])

Would produce something like:

[{'answer_text': 'I agree with this',
  'client_id': 'b5efe07b-94f4-4a96-b8c8-9e4175aa5035',
  'votes': 123},
 {'answer_text': 'I do NOT agree with this',
  'client_id': '175a5d27-ebf8-44df-a2b2-9e16dff722de',
  'votes': 8},
 {'answer_text': 'My thoughts on this are complex',
  'client_id': 'f26e1d84-8740-42ef-90b4-d0026627ad24',
  'votes': 987}]