tessl/pypi-pytumblr

A Python API v2 wrapper for Tumblr providing comprehensive methods for user, blog, and post operations with OAuth authentication

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Blog Operations

Name: tessl/pypi-pytumblr
Author: tessl

Comprehensive blog management functionality including information retrieval, post access, follower management, queue and draft handling, and blog-specific content operations. These methods can operate on any public blog or authenticated user's own blogs.

Capabilities

Blog Information

Retrieve detailed information about any blog including description, avatar, post counts, and settings.

def blog_info(self, blogname: str) -> dict:
    """
    Get information about a specific blog.
    
    Args:
        blogname (str): Blog URL (e.g., 'example.tumblr.com' or 'example')
        
    Returns:
        dict: Blog information including name, description, post count, and settings
    """

def avatar(self, blogname: str, size: int = 64) -> dict:
    """
    Get blog's avatar URL.
    
    Args:
        blogname (str): Blog URL (e.g., 'example.tumblr.com' or 'example')
        size (int, optional): Avatar size in pixels (16, 24, 30, 40, 48, 64, 96, 128, 512)
        
    Returns:
        dict: Avatar URL and metadata
    """

Usage examples:

# Get blog information
blog_info = client.blog_info('codingjester.tumblr.com')
print(f"Blog: {blog_info['response']['blog']['title']}")
print(f"Posts: {blog_info['response']['blog']['posts']}")

# Get different avatar sizes
small_avatar = client.avatar('example-blog', size=30)
large_avatar = client.avatar('example-blog', size=512)

Post Retrieval

Access posts from any blog with comprehensive filtering, pagination, and content format options.

def posts(self, blogname: str, type: str = None, **kwargs) -> dict:
    """
    Get posts from a blog.
    
    Args:
        blogname (str): Blog URL (e.g., 'example.tumblr.com' or 'example')
        type (str, optional): Filter by post type ('text', 'photo', 'quote', 'link', 'chat', 'audio', 'video')
        
    Parameters:
        id (int, optional): Specific post ID to retrieve
        tag (str, optional): Filter posts by tag
        limit (int, optional): Number of posts to return (default: 20, max: 20)
        offset (int, optional): Post number to start at for pagination
        before (int, optional): Timestamp for posts before this time
        reblog_info (bool, optional): Include reblog information
        notes_info (bool, optional): Include notes information  
        filter (str, optional): Post format ('html', 'text', 'raw')
        api_key (str, optional): For public access without authentication
        npf (bool, optional): Returns posts in Neue Post Format
        
    Returns:
        dict: Blog posts and metadata
    """

Usage examples:

# Get latest posts from a blog
posts = client.posts('codingjester.tumblr.com', limit=10)

# Get only photo posts
photos = client.posts('photography-blog', type='photo', limit=20)

# Get specific post by ID
specific_post = client.posts('example-blog', id=123456789)

# Get posts with specific tag
tagged_posts = client.posts('art-blog', tag='digital-art', limit=15)

# Get posts in text format
text_posts = client.posts('writing-blog', type='text', filter='text')

Social Connections

Manage and view blog relationships including followers and following lists.

def followers(self, blogname: str, **kwargs) -> dict:
    """
    Get followers of a blog.
    
    Args:
        blogname (str): Blog URL (e.g., 'example.tumblr.com' or 'example')
        
    Parameters:
        limit (int, optional): Number of followers to return (default: 20, max: 20)
        offset (int, optional): Follower number to start at for pagination
        
    Returns:
        dict: List of followers and total count
    """

def blog_following(self, blogname: str, **kwargs) -> dict:
    """
    Get publicly exposed blogs that a blog follows.
    
    Args:
        blogname (str): Blog URL (e.g., 'example.tumblr.com' or 'example')
        
    Parameters:
        limit (int, optional): Number of blogs to return (default: 20, max: 20)
        offset (int, optional): Blog number to start at for pagination
        
    Returns:
        dict: List of followed blogs
    """

def blog_likes(self, blogname: str, **kwargs) -> dict:
    """
    Get liked posts from a blog (if publicly visible).
    
    Args:
        blogname (str): Blog URL (e.g., 'example.tumblr.com' or 'example')
        
    Parameters:
        limit (int, optional): Number of likes to return (default: 20, max: 20)  
        offset (int, optional): DEPRECATED - Like number to start at
        before (int, optional): Timestamp for likes before this time
        after (int, optional): Timestamp for likes after this time
        
    Returns:
        dict: Liked posts if publicly visible
    """

Usage examples:

# Get blog followers
followers = client.followers('popular-blog.tumblr.com', limit=50)
print(f"Followers: {followers['response']['total_users']}")

# Get blogs that a blog follows (if public)
following = client.blog_following('example-blog')

# Get public likes from a blog
likes = client.blog_likes('public-blog', limit=10)

Content Management

Access and manage blog content including queued posts, drafts, and submissions (requires blog ownership).

def queue(self, blogname: str, **kwargs) -> dict:
    """
    Get queued posts for a blog (requires ownership).
    
    Args:
        blogname (str): Blog URL (e.g., 'example.tumblr.com' or 'example')
        
    Parameters:
        limit (int, optional): Number of posts to return (default: 20, max: 20)
        offset (int, optional): Post number to start at for pagination
        filter (str, optional): Post format ('html', 'text', 'raw')
        npf (bool, optional): Returns posts in Neue Post Format
        
    Returns:
        dict: Queued posts for the blog
    """

def drafts(self, blogname: str, **kwargs) -> dict:
    """
    Get draft posts for a blog (requires ownership).
    
    Args:
        blogname (str): Blog URL (e.g., 'example.tumblr.com' or 'example')
        
    Parameters:
        filter (str, optional): Post format ('html', 'text', 'raw')
        npf (bool, optional): Returns posts in Neue Post Format
        
    Returns:
        dict: Draft posts for the blog
    """

def submission(self, blogname: str, **kwargs) -> dict:
    """
    Get submission posts for a blog (requires ownership).
    
    Args:
        blogname (str): Blog URL (e.g., 'example.tumblr.com' or 'example')
        
    Parameters:
        offset (int, optional): Post number to start at for pagination
        filter (str, optional): Post format ('html', 'text', 'raw')
        npf (bool, optional): Returns posts in Neue Post Format
        
    Returns:
        dict: Submission posts for the blog
    """

Usage examples:

# Get queued posts (own blog only)
queue = client.queue('my-blog.tumblr.com', limit=10)

# Get draft posts (own blog only)
drafts = client.drafts('my-blog.tumblr.com', filter='html')

# Get submissions (own blog only)
submissions = client.submission('my-blog.tumblr.com')

Blog Name Validation

PyTumblr automatically normalizes blog names by adding the .tumblr.com suffix when needed:

# These are equivalent:
client.blog_info('example')
client.blog_info('example.tumblr.com')

# Custom domains work too:
client.blog_info('myblog.com')

Error Handling

Blog operation methods return JSON responses with standard error handling:

response = client.blog_info('nonexistent-blog')
if response.get('meta', {}).get('status') != 200:
    print(f"Error: {response.get('meta', {}).get('msg')}")

Common error responses: