or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

account-management.mdasync-api.mdfile-upload.mdhtml-utilities.mdindex.mdlow-level-api.mdpage-operations.md
tile.json

tessl/pypi-telegraph

Python Telegraph API wrapper for creating and managing Telegraph pages and accounts

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/telegraph@2.2.x

To install, run

npx @tessl/cli install tessl/pypi-telegraph@2.2.0

index.mddocs/

Telegraph

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.

Package Information

  • Package Name: telegraph
  • Language: Python
  • Installation: pip install telegraph
  • Async Support: pip install 'telegraph[aio]'

Core Imports

from telegraph import Telegraph, TelegraphException

For asynchronous operations:

from telegraph.aio import Telegraph

For HTML utilities:

from telegraph.utils import (
    html_to_nodes, nodes_to_html, json_dumps, FilesOpener,
    ALLOWED_TAGS, VOID_ELEMENTS, BLOCK_ELEMENTS
)

For exception handling:

from telegraph.exceptions import (
    TelegraphException, RetryAfterError, 
    ParsingException, NotAllowedTag, InvalidHTML
)

Basic Usage

from telegraph import Telegraph

# Create a Telegraph client
telegraph = Telegraph()

# Create an account
response = telegraph.create_account(
    short_name='my-account',
    author_name='My Name',
    author_url='https://example.com'
)

# Create a page
response = telegraph.create_page(
    title='Hello World',
    html_content='<p>Hello, Telegraph!</p>'
)

print(f"Page URL: {response['url']}")

Async Usage

import asyncio
from telegraph.aio import Telegraph

async def main():
    telegraph = Telegraph()
    
    # Create an account
    await telegraph.create_account(short_name='async-account')
    
    # Create a page
    response = await telegraph.create_page(
        title='Async Hello',
        html_content='<p>Hello from async!</p>'
    )
    
    print(f"Page URL: {response['url']}")

asyncio.run(main())

Architecture

Telegraph provides two API layers:

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

Capabilities

Account Management

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

def create_account(short_name: str, author_name: str = None, author_url: str = None, replace_token: bool = True) -> dict
def edit_account_info(short_name: str = None, author_name: str = None, author_url: str = None) -> dict
def get_account_info(fields: list = None) -> dict
def revoke_access_token() -> dict
def get_access_token() -> str

Account Management

Page Operations

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

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
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
def get_page(path: str, return_content: bool = True, return_html: bool = True) -> dict
def get_page_list(offset: int = 0, limit: int = 50) -> dict
def get_views(path: str, year: int = None, month: int = None, day: int = None, hour: int = None) -> dict

Page Operations

File Upload

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

def upload_file(f) -> list

File Upload

Asynchronous API

Complete async/await interface mirroring all synchronous functionality.

async def create_account(short_name: str, author_name: str = None, author_url: str = None, replace_token: bool = True) -> dict
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
# ... all other methods with async signatures

Asynchronous API

HTML Utilities

HTML parsing and Telegraph node format conversion utilities.

def html_to_nodes(html_content: str) -> list
def nodes_to_html(nodes: list) -> str

HTML Utilities

Low-level API

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

class TelegraphApi:
    def __init__(access_token: str = None, domain: str = 'telegra.ph')
    def method(method: str, values: dict = None, path: str = '') -> dict
    def upload_file(f) -> list

Low-level API

Exception Types

class TelegraphException(Exception):
    """Base exception for Telegraph API errors"""
    pass

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

class ParsingException(Exception):
    """Base exception for HTML parsing errors"""
    pass

class NotAllowedTag(ParsingException):
    """Raised when HTML contains disallowed tags"""
    pass

class InvalidHTML(ParsingException):
    """Raised when HTML is malformed"""
    pass