0
# PyTumblr
1

2
A comprehensive Python client library for the Tumblr API v2, providing OAuth authentication and complete access to user, blog, and post operations. PyTumblr enables developers to build applications that can authenticate users, manage blog content, and perform social media operations programmatically.
3

4
## Package Information
5

6
- **Package Name**: pytumblr
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install pytumblr`
10

11
## Core Imports
12

13
```python
14
import pytumblr
15
```
16

17
Direct class import:
18

19
```python
20
from pytumblr import TumblrRestClient
21
```
22

23
Creating a client:
24

25
```python
26
client = pytumblr.TumblrRestClient(
27
    consumer_key='<consumer_key>',
28
    consumer_secret='<consumer_secret>',
29
    oauth_token='<oauth_token>',
30
    oauth_secret='<oauth_secret>'
31
)
32
```
33

34
## Basic Usage
35

36
```python
37
import pytumblr
38

39
# Create authenticated client
40
client = pytumblr.TumblrRestClient(
41
    consumer_key='your_consumer_key',
42
    consumer_secret='your_consumer_secret',
43
    oauth_token='your_oauth_token',
44
    oauth_secret='your_oauth_secret'
45
)
46

47
# Get current user info
48
user_info = client.info()
49
print(f"User: {user_info['response']['user']['name']}")
50

51
# Get user's dashboard
52
dashboard = client.dashboard(limit=10)
53

54
# Get blog information
55
blog_info = client.blog_info('codingjester.tumblr.com')
56

57
# Create a text post
58
client.create_text(
59
    'your-blog.tumblr.com',
60
    title='Hello World',
61
    body='This is my first post using PyTumblr!',
62
    state='published',
63
    tags=['python', 'tumblr', 'api']
64
)
65

66
# Like a post
67
client.like(post_id, reblog_key)
68
```
69

70
## Architecture
71

72
PyTumblr is built around three core components:
73

74
- **TumblrRestClient**: Main client class providing high-level API methods for all Tumblr operations
75
- **TumblrRequest**: Internal request handler managing OAuth authentication and HTTP communication
76
- **Helper Functions**: Validation utilities for parameters and blog name normalization
77

78
The client wraps the complete Tumblr API v2 surface, organizing functionality into logical groups: user operations, blog management, and post creation/editing. All methods return parsed JSON responses from the Tumblr API.
79

80
## Capabilities
81

82
### User Operations
83

84
Core functionality for authenticated user operations including account information, dashboard access, likes management, following/unfollowing blogs, and social interactions.
85

86
```python { .api }
87
def info(self) -> dict:
88
    """Get information about the current authenticated user"""
89

90
def dashboard(self, **kwargs) -> dict:
91
    """Get dashboard posts for authenticated user"""
92

93
def likes(self, **kwargs) -> dict:
94
    """Get liked posts for authenticated user"""
95

96
def following(self, **kwargs) -> dict:
97
    """Get blogs followed by authenticated user"""
98

99
def follow(self, blogname: str) -> dict:
100
    """Follow a blog"""
101

102
def unfollow(self, blogname: str) -> dict:
103
    """Unfollow a blog"""
104

105
def like(self, id: int, reblog_key: str) -> dict:
106
    """Like a post"""
107

108
def unlike(self, id: int, reblog_key: str) -> dict:
109
    """Unlike a post"""
110
```
111

112
[User Operations](./user-operations.md)
113

114
### Blog Operations
115

116
Comprehensive blog management including information retrieval, post access, follower management, queue and draft handling, and blog-specific content operations.
117

118
```python { .api }
119
def blog_info(self, blogname: str) -> dict:
120
    """Get information about a specific blog"""
121

122
def posts(self, blogname: str, type: str = None, **kwargs) -> dict:
123
    """Get posts from a blog"""
124

125
def avatar(self, blogname: str, size: int = 64) -> dict:
126
    """Get blog's avatar URL"""
127

128
def followers(self, blogname: str, **kwargs) -> dict:
129
    """Get followers of a blog"""
130

131
def blog_following(self, blogname: str, **kwargs) -> dict:
132
    """Get publicly exposed blogs that a blog follows"""
133

134
def blog_likes(self, blogname: str, **kwargs) -> dict:
135
    """Get liked posts from a blog"""
136

137
def queue(self, blogname: str, **kwargs) -> dict:
138
    """Get queued posts for a blog"""
139

140
def drafts(self, blogname: str, **kwargs) -> dict:
141
    """Get draft posts for a blog"""
142

143
def submission(self, blogname: str, **kwargs) -> dict:
144
    """Get submission posts for a blog"""
145
```
146

147
[Blog Operations](./blog-operations.md)
148

149
### Post Management
150

151
Complete post lifecycle management including creation of all Tumblr post types (text, photo, quote, link, chat, audio, video), editing, reblogging, deletion, and notes retrieval.
152

153
```python { .api }
154
def create_text(self, blogname: str, **kwargs) -> dict:
155
    """Create a text post"""
156

157
def create_photo(self, blogname: str, **kwargs) -> dict:
158
    """Create a photo post"""
159

160
def create_quote(self, blogname: str, **kwargs) -> dict:
161
    """Create a quote post"""
162

163
def create_link(self, blogname: str, **kwargs) -> dict:
164
    """Create a link post"""
165

166
def create_chat(self, blogname: str, **kwargs) -> dict:
167
    """Create a chat post"""
168

169
def create_audio(self, blogname: str, **kwargs) -> dict:
170
    """Create an audio post"""
171

172
def create_video(self, blogname: str, **kwargs) -> dict:
173
    """Create a video post"""
174

175
def edit_post(self, blogname: str, **kwargs) -> dict:
176
    """Edit an existing post"""
177

178
def reblog(self, blogname: str, **kwargs) -> dict:
179
    """Reblog a post"""
180

181
def delete_post(self, blogname: str, id: int) -> dict:
182
    """Delete a post"""
183

184
def notes(self, blogname: str, id: str, **kwargs) -> dict:
185
    """Get notes for a specific post"""
186
```
187

188
[Post Management](./post-management.md)
189

190
### Tagged Content
191

192
Discovery and retrieval of posts by tags across the entire Tumblr platform.
193

194
```python { .api }
195
def tagged(self, tag: str, **kwargs) -> dict:
196
    """Get posts with a specific tag"""
197
```
198

199
### Low-level API Access
200

201
Direct access to the underlying API request mechanism for custom operations and endpoints not covered by the high-level methods.
202

203
```python { .api }
204
def send_api_request(self, method: str, url: str, params: dict = {}, 
205
                    valid_parameters: list = [], needs_api_key: bool = False) -> dict:
206
    """
207
    Send a direct API request to Tumblr endpoints.
208
    
209
    Args:
210
        method (str): HTTP method ('get', 'post', 'delete')
211
        url (str): API endpoint URL (relative to base URL)
212
        params (dict): Request parameters
213
        valid_parameters (list): List of allowed parameter names
214
        needs_api_key (bool): Whether to inject API key for public access
215
        
216
    Returns:
217
        dict: Parsed JSON response from API
218
    """
219
```
220

221
## Types
222

223
```python { .api }
224
class TumblrRestClient:
225
    """
226
    Main client class for Tumblr API v2 operations.
227
    
228
    Args:
229
        consumer_key (str): Consumer key from Tumblr application
230
        consumer_secret (str): Consumer secret from Tumblr application  
231
        oauth_token (str): User-specific OAuth token
232
        oauth_secret (str): User-specific OAuth secret
233
        host (str): API host URL, defaults to https://api.tumblr.com
234
    """
235
    def __init__(self, consumer_key: str, consumer_secret: str = "", 
236
                 oauth_token: str = "", oauth_secret: str = "",
237
                 host: str = "https://api.tumblr.com"): ...
238
```
239

240
Common parameter types used across post creation methods:
241

242
```python { .api }
243
# Common post parameters (available for all post creation methods)
244
PostCommonParams = {
245
    'state': str,        # Post state: 'published', 'draft', 'queue', 'private'
246
    'tags': list,        # List of tag strings
247
    'tweet': str,        # Custom tweet text
248
    'date': str,         # GMT date and time
249
    'format': str,       # Post format: 'html' or 'markdown'  
250
    'slug': str         # URL slug for the post
251
}
252

253
# Pagination parameters
254
PaginationParams = {
255
    'limit': int,        # Number of results to return
256
    'offset': int,       # Starting offset for pagination
257
    'before': int,       # Timestamp for posts before this time
258
    'after': int         # Timestamp for posts after this time
259
}
260
```