0
# Telegraph
1

2
A Python wrapper for the Telegraph API that enables developers to programmatically create and manage Telegraph pages and accounts. It provides both synchronous and asynchronous interfaces through a clean, intuitive API that simplifies Telegraph's publishing platform integration.
3

4
## Package Information
5

6
- **Package Name**: telegraph
7
- **Language**: Python
8
- **Installation**: `pip install telegraph`
9
- **Async Support**: `pip install 'telegraph[aio]'`
10

11
## Core Imports
12

13
```python
14
from telegraph import Telegraph, TelegraphException
15
```
16

17
For asynchronous operations:
18

19
```python
20
from telegraph.aio import Telegraph
21
```
22

23
For HTML utilities:
24

25
```python
26
from telegraph.utils import (
27
    html_to_nodes, nodes_to_html, json_dumps, FilesOpener,
28
    ALLOWED_TAGS, VOID_ELEMENTS, BLOCK_ELEMENTS
29
)
30
```
31

32
For exception handling:
33

34
```python
35
from telegraph.exceptions import (
36
    TelegraphException, RetryAfterError, 
37
    ParsingException, NotAllowedTag, InvalidHTML
38
)
39
```
40

41
## Basic Usage
42

43
```python
44
from telegraph import Telegraph
45

46
# Create a Telegraph client
47
telegraph = Telegraph()
48

49
# Create an account
50
response = telegraph.create_account(
51
    short_name='my-account',
52
    author_name='My Name',
53
    author_url='https://example.com'
54
)
55

56
# Create a page
57
response = telegraph.create_page(
58
    title='Hello World',
59
    html_content='<p>Hello, Telegraph!</p>'
60
)
61

62
print(f"Page URL: {response['url']}")
63
```
64

65
## Async Usage
66

67
```python
68
import asyncio
69
from telegraph.aio import Telegraph
70

71
async def main():
72
    telegraph = Telegraph()
73
    
74
    # Create an account
75
    await telegraph.create_account(short_name='async-account')
76
    
77
    # Create a page
78
    response = await telegraph.create_page(
79
        title='Async Hello',
80
        html_content='<p>Hello from async!</p>'
81
    )
82
    
83
    print(f"Page URL: {response['url']}")
84

85
asyncio.run(main())
86
```
87

88
## Architecture
89

90
Telegraph provides two API layers:
91

92
- **High-level API**: `Telegraph` class with convenient methods for account and page management
93
- **Low-level API**: `TelegraphApi` class for direct API calls with custom parameters
94
- **Utilities**: HTML parsing and conversion functions for Telegraph's node format
95
- **Dual Interface**: Complete synchronous (requests) and asynchronous (httpx) implementations
96

97
## Capabilities
98

99
### Account Management
100

101
Comprehensive Telegraph account operations including creation, editing, token management, and information retrieval.
102

103
```python { .api }
104
def create_account(short_name: str, author_name: str = None, author_url: str = None, replace_token: bool = True) -> dict
105
def edit_account_info(short_name: str = None, author_name: str = None, author_url: str = None) -> dict
106
def get_account_info(fields: list = None) -> dict
107
def revoke_access_token() -> dict
108
def get_access_token() -> str
109
```
110

111
[Account Management](./account-management.md)
112

113
### Page Operations
114

115
Full page lifecycle management including creation, editing, retrieval, and view analytics.
116

117
```python { .api }
118
def create_page(title: str, content: list = None, html_content: str = None, author_name: str = None, author_url: str = None, return_content: bool = False) -> dict
119
def edit_page(path: str, title: str, content: list = None, html_content: str = None, author_name: str = None, author_url: str = None, return_content: bool = False) -> dict
120
def get_page(path: str, return_content: bool = True, return_html: bool = True) -> dict
121
def get_page_list(offset: int = 0, limit: int = 50) -> dict
122
def get_views(path: str, year: int = None, month: int = None, day: int = None, hour: int = None) -> dict
123
```
124

125
[Page Operations](./page-operations.md)
126

127
### File Upload
128

129
File upload functionality for images and media content (unofficial API).
130

131
```python { .api }
132
def upload_file(f) -> list
133
```
134

135
[File Upload](./file-upload.md)
136

137
### Asynchronous API
138

139
Complete async/await interface mirroring all synchronous functionality.
140

141
```python { .api }
142
async def create_account(short_name: str, author_name: str = None, author_url: str = None, replace_token: bool = True) -> dict
143
async def create_page(title: str, content: list = None, html_content: str = None, author_name: str = None, author_url: str = None, return_content: bool = False) -> dict
144
# ... all other methods with async signatures
145
```
146

147
[Asynchronous API](./async-api.md)
148

149
### HTML Utilities
150

151
HTML parsing and Telegraph node format conversion utilities.
152

153
```python { .api }
154
def html_to_nodes(html_content: str) -> list
155
def nodes_to_html(nodes: list) -> str
156
```
157

158
[HTML Utilities](./html-utilities.md)
159

160
### Low-level API
161

162
Direct Telegraph API access for advanced use cases and custom implementations.
163

164
```python { .api }
165
class TelegraphApi:
166
    def __init__(access_token: str = None, domain: str = 'telegra.ph')
167
    def method(method: str, values: dict = None, path: str = '') -> dict
168
    def upload_file(f) -> list
169
```
170

171
[Low-level API](./low-level-api.md)
172

173
## Exception Types
174

175
```python { .api }
176
class TelegraphException(Exception):
177
    """Base exception for Telegraph API errors"""
178
    pass
179

180
class RetryAfterError(TelegraphException):
181
    """Raised when rate limiting occurs"""
182
    def __init__(self, retry_after: int):
183
        self.retry_after = retry_after
184

185
class ParsingException(Exception):
186
    """Base exception for HTML parsing errors"""
187
    pass
188

189
class NotAllowedTag(ParsingException):
190
    """Raised when HTML contains disallowed tags"""
191
    pass
192

193
class InvalidHTML(ParsingException):
194
    """Raised when HTML is malformed"""
195
    pass
196
```