DOCSEARCHbyAlgolia
Submit Docs

PyTumblr Documentation

repository·master·Indexed 20 days ago

https://github.com/tumblr/pytumblr

A Python client library for the Tumblr API v2 (version 0.1.2) that allows developers to interact with user accounts, blogs, and posts. It provides the TumblrRestClient for API interactions and supports creating, editing, reblogging, and deleting various post types including photo, text, quote, link, chat, audio, and video posts.

Tokens
1.9K
Snippets
8
Records
8
Agent score
23%

What's inside PyTumblr

  1. Initialize a TumblrRestClient

    master

    The pytumblr.TumblrRestClient is the primary object used to interact with the Tumblr API. You must provide your OAuth credentials to instantiate it.

    Credentials:

    • consumer_key
    • consumer_secret
    • oauth_token
    • oauth_secret

    You can obtain these via the Tumblr API console or the included interactive_console.py tool.

    import pytumblr

client = pytumblr.TumblrRestClient(
    '<consumer_key>',
    '<consumer_secret>',
    '<oauth_token>',
    '<oauth_secret>',
)

client.info() # Grabs the current user information

  3. Use the interactive console for OAuth

    master

    The interactive_console.py tool guides you through the OAuth process to obtain your tokens. Tokens are stored in ~/.tumblr and are compatible with other Tumblr API clients (like the Ruby client).

    Requirement: You must have pyyaml installed.

    $ python interactive_console.py

  4. Edit, Reblog, and Delete posts

    master

    Editing a post

    To update a post, you must specify the type (e.g., text, photo) and the id.

    client.edit_post(blogName, id=post_id, type="text", title="Updated")

    Reblogging a post

    Requires the id and the reblog_key (found in the post's JSON object).

    client.reblog(blogName, id=125356, reblog_key="reblog_key")

    Deleting a post

    Requires the blogName and the id of a post you own.

    client.delete_post(blogName, 123456)

  5. Create various post types

    master

    PyTumblr supports multiple post types. Most creation methods accept these default parameters:

    • state: String. Post state: published, draft, queue, or private.
    • tags: A list of strings (e.g., ['tag1', 'tag2']). Note: Do not use a comma-separated string.
    • tweet: String. Custom tweet text.
    • date: String. Customized GMT date.
    • format: String. Post format: html or markdown.
    • slug: String. URL slug for the post.

    Photo Posts

    Supports caption (string), link (click-through URL), source (URL for photo), and data (filepath or list of filepaths for multipart upload).

    # Using a source URL
client.create_photo(blogName, state="published", tags=["testing"], source="https://example.com/image.jpg")

# Using local filepaths (Photoset)
client.create_photo(blogName, state="draft", data=["/path/to/img1.jpg", "/path/to/img2.jpg"], caption="## Title")

    Text Posts

    Supports title (string) and body (string).

    client.create_text(blogName, state="published", title="My Title", body="My content")

    Quote Posts

    Supports quote (string) and source (string).

    client.create_quote(blogName, quote="I am the Walrus", source="Ringo")

    Link Posts

    Supports title (string), url (string), and description (string).

    client.create_link(blogName, title="Title", url="https://example.com", description="Desc")

    Chat Posts

    Supports title (string) and conversation (string with dialogue labels, no HTML).

    chat = "\nJohn: Hello!\nJane: Hi!\n"
client.create_chat(blogName, title="Chat Title", conversation=chat)

    Audio Posts

    Supports caption (string). Use either external_url (string) or data (filepath), but not both.

    # From URL
client.create_audio(blogName, caption="Music", external_url="https://soundcloud.com/...")

# From local file
client.create_audio(blogName, caption="Music", data="/path/to/audio.mp3")

    Video Posts

    Supports caption (string). Use either embed (HTML embed code) or data (filepath), but not both.

    # From YouTube
client.create_video(blogName, caption="Video", embed="http://www.youtube.com/watch?v=...")

# From local file
client.create_video(blogName, caption="Video", data="/path/to/video.mov")
    # Example: Creating a photo post using a source URL
client.create_photo(blogName, state="published", tags=["testing", "ok"],
                    source="https://68.media.tumblr.com/b965fbb2e501610a29d80ffb6fb3e1ad/tumblr_n55vdeTse11rn1906o1_500.jpg")

  6. Get post notes and tagged posts

    master

    Getting notes for a post

    Requires the blogName and the post id.

    data = client.notes(blogName, id='123456')

# To paginate using the timestamp from the response:
if "_links" in data and "next" in data["_links"]:
    next_timestamp = data["_links"]["next"]["query_params"]["before_timestamp"]
    data = client.notes(blogName, id='123456', before_timestamp=next_timestamp)

    Getting posts by tag

    Use the tagged method to find posts associated with a specific tag.

    client.tagged(tag, **params)
    data = client.notes(blogName, id='123456')

  7. User Methods Reference

    master

    Use these methods to interact with the authenticated user's account and social actions.

    client.info() # get information about the authenticating user
client.dashboard() # get the dashboard for the authenticating user
client.likes() # get the likes for the authenticating user
client.following() # get the blogs followed by the authenticating user

client.follow('blogname.tumblr.com') # follow a blog
client.unfollow('blogname.tumblr.com') # unfollow a blog

client.like(id, reblogkey) # like a post
client.unlike(id, reblogkey) # unlike a post

  8. Blog Methods Reference

    master

    Use these methods to retrieve information or content from specific blogs.

    client.blog_info(blogName) # get information about a blog
client.posts(blogName, **params) # get posts for a blog
client.avatar(blogName) # get the avatar for a blog
client.blog_likes(blogName) # get the likes on a blog
client.followers(blogName) # get the followers of a blog
client.blog_following(blogName) # get the publicly exposed blogs that [blogName] follows
client.queue(blogName) # get the queue for a given blog
client.submission(blogName) # get the submissions for a given blog