tumblr.tumblr

Provides Tumblr, User, and Blog classes for interacting with various API endpoints outlined in the Tumblr API documentation: https://www.tumblr.com/docs/en/api/v2

Classes

`Tumblr`(client_key, client_secret, oauth_key, ...)	Base tumblr class.
`User`(client_key, client_secret, oauth_key, ...)	Provides methods for user-specific actions such as following, liking, and filtering tags
`Blog`(blog, client_key, client_secret, ...)	Provides methods for blog-specific actions such as posting, and getting blog info.

class Tumblr(client_key: str, client_secret: str, oauth_key: str, oauth_secret: str)

Base tumblr class. Handles authentication and raw method calls. Exposes the generic “tagged” search feature.

See also

https://www.tumblr.com/docs/en/api/v2#tagged-method

Provides methods for the following endpoints:

/tagged – Get Posts with Tag

Parameters:

client_key – AKA Consumer Key
client_secret – AKA Consumer Secret
oauth_key – AKA Token
oauth_secret – AKA Token Secret

tagged(tag: str, before: int = None, limit: int = 20, post_format: str = 'HTML')

Retrieves posts with the given tag.

See: https://www.tumblr.com/docs/en/api/v2#tagged-method

Parameters:

tag – the search tag
before – shows posts from before this timestamp
limit – Number of posts to get (between 1–20)
post_format – HTML, plain, or raw.

class User(client_key: str, client_secret: str, oauth_key: str, oauth_secret: str)

Provides methods for user-specific actions such as following, liking, and filtering tags

See also

https://www.tumblr.com/docs/en/api/v2#user-methods

Provides methods for the following endpoints:

/user/info – Get a User’s Information
/user/limits – Get a User’s Limits
/user/dashboard – Retrieve a User’s Dashboard
/user/likes — Retrieve a User’s Likes
/user/following – Retrieve the Blogs a User Is Following
/user/follow – Follow a blog
/user/unfollow – Unfollow a blog
/user/like – Like a Post
/user/unlike – Unlike a Post
/user/filtered_tags - Tag Filtering
/user/filtered_content - Content Filtering

info()

Returns general information about the user.

See: https://www.tumblr.com/docs/en/api/v2#userinfo–get-a-users-information

limits()

Returns general information about the user limits (posts, sideblogs, etc.)

See: https://www.tumblr.com/docs/en/api/v2#userlimits–get-a-users-limits

dashboard()

Retrieves the user’s dashboard

See: https://www.tumblr.com/docs/en/api/v2#userdashboard–retrieve-a-users-dashboard

likes()

Retrieves the post liked by the user

See: https://www.tumblr.com/docs/en/api/v2#userlikes–retrieve-a-users-likes

following()

Retrieves the blogs the user is following

See: https://www.tumblr.com/docs/en/api/v2#userfollowing–retrieve-the-blogs-a-user-is-following

follow(url: str)

Follows a blog

See: https://www.tumblr.com/docs/en/api/v2#userfollow–follow-a-blog

Parameters:: url – The URL of the blog (can also be a blog name, e.g. “staff”)

follow_email(email: str)

Follows a blog by email address. A blog is only followable by email if it has the Let people find your blogs through this address. setting enabled on tumblr.com/settings/account.

See: https://www.tumblr.com/docs/en/api/v2#userfollow–follow-a-blog

Parameters:: email – The email of the user to follow

unfollow(url: str)

Unfollows a blog

See: https://www.tumblr.com/docs/en/api/v2#userunfollow–unfollow-a-blog

Parameters:: url – The URL of the blog (can also be a blog name, e.g. “staff”)

like(post_id: str, from_blog: str)

Likes a post

See: https://www.tumblr.com/docs/en/api/v2#userlike–like-a-post

Parameters:

post_id – The ID of the post to like
from_blog – The blog name of the blog that made the post

unlike(post_id: str, from_blog: str)

Unlikes a post

See: https://www.tumblr.com/docs/en/api/v2#userunlike–unlike-a-post

Parameters:

post_id – The ID of the post to like
from_blog – The blog name of the blog that made the post

filtered_tags()

Retrieves the user’s filtered tags

See: https://www.tumblr.com/docs/en/api/v2#userfiltered_tags—tag-filtering

add_filtered_tags(tags: list[str])

Adds the given tags to the user’s filtered tags

See: https://www.tumblr.com/docs/en/api/v2#userfiltered_tags—tag-filtering

Parameters:: tags – The tags to add to the filtered tags

remove_filtered_tag(tag: str)

Removes the given tag from the user’s filtered tags

See: https://www.tumblr.com/docs/en/api/v2#userfiltered_tags—tag-filtering

Parameters:: tag – the tag to be removed

filtered_content()

Retrieves the user’s list of filtered content

See: https://www.tumblr.com/docs/en/api/v2#userfiltered_content—content-filtering

add_filtered_content(filtered_content: str | list[str])

Adds the given filtered content to the user’s filtered content

See: https://www.tumblr.com/docs/en/api/v2#userfiltered_content—content-filtering

Parameters:: filtered_content – one or more string to add to the filtered content

remove_filtered_content(filtered_content: str)

Removes the given content from the user’s filtered content

See: https://www.tumblr.com/docs/en/api/v2#userfiltered_content—content-filtering

Parameters:: filtered_content – a string to remove from the filtered content

get_post(post_id: str, from_blog: str, post_format: str = 'npf') → Mapping[str, Any]

Retrieves a post

See: https://www.tumblr.com/docs/en/api/v2#postspost-id—fetching-a-post-neue-post-format

Parameters:

post_id – The ID of the post
from_blog – The blog name of the blog that made the post
post_format – The format to retrieve content: npf or legacy

class Blog(blog: str, client_key: str, client_secret: str, oauth_key: str, oauth_secret: str)

Provides methods for blog-specific actions such as posting, and getting blog info.

See also

https://www.tumblr.com/docs/en/api/v2#blog-methods

Provides methods for the following endpoints:

/info - Retrieve Blog Info
/avatar — Retrieve a Blog Avatar
/blocks – Retrieve Blog’s Blocks
/blocks – Block a Blog
/blocks/bulk – Block a list of Blogs
/blocks – Remove a Block
/likes — Retrieve Blog’s Likes
/following — Retrieve Blog’s following
/followers — Retrieve a Blog’s Followers
/followed_by — Check If Followed By Blog
/posts/queue — Retrieve Queued Posts
/posts/queue/reorder — Reorder Queued Posts
/posts/queue/shuffle — Shuffle Queued Posts
/posts – Retrieve Published Posts
/posts/draft — Retrieve Draft Posts
/posts/submission — Retrieve Submission Posts
/notifications — Retrieve Blog’s Activity Feed
/posts - Create/Reblog a Post
/posts/{post-id} - Fetching a Post
/posts/{post-id} - Editing a Post
/post/delete – Delete a Post
/posts/{post-id}/mute - Muting a Post’s Notifications
/notes - Get notes for a specific Post

Also includes support for undocumented Poll APIs:

/polls/{blog}/{post_id}/{poll_id}/results

See the poll_results() and raw_poll_results() methods

Parameters:

blog – The name of the blog (one you have auth for)
client_key – AKA Consumer Key
client_secret – AKA Consumer Secret
oauth_key – AKA Token
oauth_secret – AKA Token Secret

info(fields: Iterable[str] = ()) → Mapping[str, Any]

Retrieves information about the blog

See: https://www.tumblr.com/docs/en/api/v2#info—retrieve-blog-info

Parameters:: fields – optional additional info fields that can be requested
Returns:: The JSON encoded response
Raises:: HTTPError – if the request fails

avatar(size: int = 64) → bytes

Retrieves the blog’s avatar

See: https://www.tumblr.com/docs/en/api/v2#avatar–retrieve-a-blog-avatar

Parameters:: size – The nxn size of the image to download. Must be one of: 16, 24, 30, 40, 48, 64, 96, 128, 512
Returns:: The JSON encoded response
Raises:: HTTPError – if the request fails

blocks(offset: int = 0, limit: int = 20, fields: Iterable[str] = ()) → Mapping[str, Any]

Retrieves this blog’s blocked blogs

See: https://www.tumblr.com/docs/en/api/v2#blocks–retrieve-blogs-blocks

Parameters:

offset – The blocked blog number to start at
limit – The number of blocked blogs to retrieve (between 1–20 inclusive)
fields – Blog fields of the blocked blog to retrieve

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

block(tumblelog: str = None, post_id: str = None) → Mapping[str, Any]

Blocks the specified blog or poster of the given ID

See: https://www.tumblr.com/docs/en/api/v2#blocks–block-a-blog

Parameters:

tumblelog – The blog identifier of the blog to block
post_id – The post id of a post posted by the blog to block

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

bulk_block(tumblelogs: Iterable, force: bool = False) → Mapping[str, Any]

Blocks several blogs at once

See: https://www.tumblr.com/docs/en/api/v2#blocksbulk–block-a-list-of-blogs

Parameters:

tumblelogs – the blog identifiers of the blogs to block
force – whether to force the block even if this cancels a Post+ subscription

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

unblock(tumblelog: str = None, anonymous: bool = None) → Mapping[str, Any]

Unblocks a blog

See: https://www.tumblr.com/docs/en/api/v2#blocks–remove-a-block

Parameters:

tumblelog – The blog identifier of the blog to unblock
anonymous – If tumblelog is not given and this is True, will unblock all anonymous blocks

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

likes(limit: int = None, offset: int = None, before: int = None, after: int = None, fields: Iterable[str] = ()) → Mapping[str, Any]

Retrieves this blogs likes

See: https://www.tumblr.com/docs/en/api/v2#likes–retrieve-blogs-likes

Parameters:

limit – the number of likes to retrieve
offset – the liked post to start at
before – the timestamp of likes to retrieve before
after – the timestamp of likes to retrieve after
fields – the blog fields to retrieve with this request

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

following(limit: int = 20, offset: int = 0, fields: Iterable[str] = ()) → Mapping[str, Any]

Retrieves the blogs this blog follows

See: https://www.tumblr.com/docs/en/api/v2#following–retrieve-blogs-following

Parameters:

limit – the number of blogs to retrieve
offset – the blog to start at
fields – the blog fields to retrieve with this request

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

followers(limit: int = 20, offset: int = 0) → Mapping[str, Any]

Retrieves the users following this blog

See: https://www.tumblr.com/docs/en/api/v2#followers–retrieve-a-blogs-followers

Parameters:

limit – the number of blogs to retrieve
offset – the blog number to start at

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

followed_by(blog: str)

Retrieves the following status of the given blog

See: https://www.tumblr.com/docs/en/api/v2#followed_by–check-if-followed-by-blog

Parameters:: blog – the blog that may be following this blog
Returns:: The JSON encoded response
Raises:: HTTPError – if the request fails

queue(offset: int = 0, limit: int = 20, post_format: str = 'npf') → Mapping[str, Any]

Retrieves the list of currently queued posts

See: https://www.tumblr.com/docs/en/api/v2#postsqueue–retrieve-queued-posts

Parameters:

offset – the post number to start at
limit – the number of posts to retrieve
post_format – the post format: npf, HTML, text, raw

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

reorder_queue(post_id: str | int, insert_after: str | int = 0) → Mapping[str, Any]

Reorders posts in the queue

See: https://www.tumblr.com/docs/en/api/v2#postsqueuereorder–reorder-queued-posts

Parameters:

post_id – the ID of the post to reorder
insert_after – the id of the post to insert this post after or 0 to move to the top

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

shuffle_queue()

Randomly shuffles the queue

See: https://www.tumblr.com/docs/en/api/v2#postsqueueshuffle—shuffle-queued-posts

Returns:: The JSON encoded response
Raises:: HTTPError – if the request fails

posts(post_type: str = None, post_id: int | str = None, tag: str | list[str] = None, limit: int = None, offset: int = None, reblog_info: bool = None, notes_info: bool = None, post_format: str = 'npf', before: int = None, fields: Iterable[str] = ()) → Mapping[str, Any]

Retrieves published posts

See: https://www.tumblr.com/docs/en/api/v2#posts–retrieve-published-posts

Parameters:

post_type – the type of post to return: text, quote, link, answer, video, audio, photo, chat
post_id – the ID of a specific post
tag – one or more tags to filter by
limit – the number of posts to retrieve
offset – the post number to start at
reblog_info – whether to return reblog information
notes_info – whether to return notes information
post_format – the post format to return: HTML, text, raw, or npf
before – retrieves posts before this timestamp
fields – the blog fields to retrieve

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

drafts(before_id: int | str = 0, post_format: str = 'npf', fields: Iterable[str] = ()) → Mapping[str, Any]

Retrieves drafted posts

See: https://www.tumblr.com/docs/en/api/v2#postsdraft–retrieve-draft-posts

Parameters:

before_id – gets posts created before the post with the given ID
post_format – the post format to retrieve: npf, HTML, text, raw
fields – the blog fields to retrieve

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

submissions(offset: int | str = 0, post_format: str = 'npf', fields: Iterable[str] = ()) → Mapping[str, Any]

Retrieves post submissions

See: https://www.tumblr.com/docs/en/api/v2#postssubmission–retrieve-submission-posts

Parameters:

offset – the post offset
post_format – the post format to retrieve: npf, HTML, text, raw
fields – the blog fields to retrieve

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

notifications(before: int = None, types: Iterable[str] = None, rollups: bool = None, omit_post_ids: Iterable[str] = None) → Mapping[str, Any]

Retrieves the blog’s activity feed

See: https://www.tumblr.com/docs/en/api/v2#notifications–retrieve-blogs-activity-feed

Parameters:

before – a timestamp to retrieve notifications before
types – one or more notification types to filter by (see API docs)
rollups – whether similar activity should be grouped
omit_post_ids – an array of post IDs to omit

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

get_post(post_id: str, from_blog: str = None, post_format: str = 'npf') → Mapping[str, Any]

Retrieves a specific post

See: https://www.tumblr.com/docs/en/api/v2#postspost-id—fetching-a-post-neue-post-format

Parameters:

post_id – the ID of the desired post
from_blog – the blog that made the post (the current blog if not provided)
post_format – the post format to retrieve: npf, HTML, text, raw

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

post(content: Iterable[Block], state: str = None, publish_on: str = None, date: str = None, tags: Iterable[str] = (), source_url: str = None, send_to_twitter: bool = None, is_private: bool = None, slug: str = None, interactability_reblog: str = None) → Mapping[str, Any]

Creates a new post

See: https://www.tumblr.com/docs/en/api/v2#posts—createreblog-a-post-neue-post-format

Parameters:

content – the content blocks of the post’s body
state – the state to post in: published, queue, draft, private, unapproved
publish_on – if the publish-state is “queue”, will use this ISO 8601 format timestamp as the publish date
date – the ISO 8601 format datetime to backdate the post
tags – an iterable of tags to give the post
source_url – a source attribution for the post content
send_to_twitter – whether to share this post to a connected Twitter account
is_private – whether the post, if it is an answer, should be a private
slug – Custom URL for the post
interactability_reblog – who can interact with this post: everyone, or noone

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

reblog(from_id: str | int, content: Iterable[Block], from_blog: str = None, state: str = None, publish_on: str = None, date: str = None, tags: Iterable[str] = (), source_url: str = None, send_to_twitter: bool = None, is_private: bool = None, slug: str = None, interactability_reblog: str = None)

Creates a reblog

See: https://www.tumblr.com/docs/en/api/v2#posts—createreblog-a-post-neue-post-format

Parameters:

from_id – the post ID to reblog
content – the content blocks of the post’s body
from_blog – the blog that made the reblogged post
state – the state to post in: published, queue, draft, private, unapproved
publish_on – if the publish-state is “queue”, will use this ISO 8601 format timestamp as the publish date
date – the ISO 8601 format datetime to backdate the post
tags – an iterable of tags to give the post
source_url – a source attribution for the post content
send_to_twitter – whether to share this post to a connected Twitter account
is_private – whether the post, if it is an answer, should be a private
slug – Custom URL for the post
interactability_reblog – who can interact with this post: everyone, or noone

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

edit_post(post_id: str | int, content: Iterable[Block] = None, state: str = None, publish_on: str = None, date: str = None, tags: Iterable[str] = (), source_url: str = None, send_to_twitter: bool = None, is_private: bool = None, slug: str = None, interactability_reblog: str = None)

Edits an existing post

See: https://www.tumblr.com/docs/en/api/v2#postspost-id—editing-a-post-neue-post-format

Parameters:

post_id – the ID of the post to edit (posted by the current blog)
content – the content blocks of the post’s body
state – the state to post in: published, queue, draft, private, unapproved
publish_on – if the publish-state is “queue”, will use this ISO 8601 format timestamp as the publish date
date – the ISO 8601 format datetime to backdate the post
tags – an iterable of tags to give the post
source_url – a source attribution for the post content
send_to_twitter – whether to share this post to a connected Twitter account
is_private – whether the post, if it is an answer, should be a private
slug – Custom URL for the post
interactability_reblog – who can interact with this post: everyone, or noone

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

delete_post(post_id: str | int) → Mapping[str, Any]

Deletes a post posted by this blog

See: https://www.tumblr.com/docs/en/api/v2#postdelete–delete-a-post

Parameters:: post_id – the ID of the post to delete
Returns:: The JSON encoded response
Raises:: HTTPError – if the request fails

mute_post(post_id: str | int, mute_length_seconds: int = 0) → Mapping[str, Any]

Mutes notifications for a post

See: https://www.tumblr.com/docs/en/api/v2#postspost-idmute—muting-a-posts-notifications

Parameters:

post_id – the ID of the post to mute
mute_length_seconds – the time the post should remain muted (0 for forever)

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

unmute_post(post_id: str | int) → Mapping[str, Any]

Unmutes the notifications for a post

See: https://www.tumblr.com/docs/en/api/v2#postspost-idmute—muting-a-posts-notifications

Parameters:: post_id – the ID of the post to unmute
Returns:: The JSON encoded response
Raises:: HTTPError – if the request fails

notes(post_id: str | int, before: int = None, mode: str = 'all') → Mapping[str, Any]

Retrieves the notes for a specific post

See: https://www.tumblr.com/docs/en/api/v2#notes—get-notes-for-a-specific-post

Parameters:

post_id – the ID of the post
before – the timestamp in seconds to retrieve notes before
mode – the type of note to retrieve (see API docs)

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

poll_results(post_id: str | int, blog: str = None) → Mapping[str, Any]

Returns a poll object zipped with answer text. Finds the first poll in the given post and returns its results + labels

Parameters:

post_id – The post that contains the poll
blog – The blog for the post – defaults to the blog given to the Blog object

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails

raw_poll_results(post_id: str | int, poll_id: str, blog: str = None) → Mapping[str, Any]

Not defined in the API yet – seems to return a mapping of answer client_ids to the votes for each answer.

Parameters:

post_id – The post that contains the poll
poll_id – AKA the poll client_id
blog – The blog for the post – defaults to the blog given to the tumblr object

Returns:

The JSON encoded response

Raises:

HTTPError – if the request fails