{"id":10282,"library":"telegraph","title":"Telegraph API Wrapper","description":"The `telegraph` library is a Python wrapper for the Telegraph publishing platform API, allowing programmatic creation and management of Telegraph pages and accounts. It supports both synchronous and asynchronous operations. The current version is 2.2.0, with releases occurring every few months for new features and bug fixes.","status":"active","version":"2.2.0","language":"en","source_language":"en","source_url":"https://github.com/python273/telegraph","tags":["telegraph","api","wrapper","async","publishing"],"install":[{"cmd":"pip install telegraph","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"Telegraph (sync client)","correct":"from telegraph import Telegraph"},{"note":"Async client moved to `telegraph.aio` module for clarity and to avoid name clashes.","wrong":"from telegraph import Telegraph as AsyncTelegraph","symbol":"Telegraph (async client)","correct":"from telegraph.aio import Telegraph"},{"symbol":"exceptions","correct":"from telegraph.exceptions import RetryAfterError"}],"quickstart":{"code":"import os\nfrom telegraph import Telegraph\n\n# Create a Telegraph instance (can reuse existing access_token if available)\n# For a fresh start, omit access_token to create a new one.\naccess_token = os.environ.get('TELEGRAPH_ACCESS_TOKEN', None)\ntelegraph = Telegraph(access_token=access_token)\n\nif not telegraph.get_access_token():\n    # If no access token is set, create a new account\n    account_info = telegraph.create_account(\n        short_name='MyTestAccount',\n        author_name='Test User',\n        author_url='https://example.com'\n    )\n    telegraph.access_token = account_info['access_token']\n    print(f\"New Telegraph account created. Access Token: {telegraph.access_token}\")\nelse:\n    print(f\"Using existing Telegraph account with Access Token: {telegraph.access_token}\")\n\n# Create a new Telegraph page\nresponse = telegraph.create_page(\n    title='My First Telegraph Page',\n    author_name='Test User',\n    content='<p>Hello from <b>Python</b>!</p><p>This is a test page created programmatically.</p>',\n    return_content=True\n)\n\nprint(f\"Page created: {response['url']}\")\nprint(f\"Page views: {response['views']}\")\n","lang":"python","description":"Initializes the Telegraph client, creates a new account if no access token is provided (or uses an existing one), and then publishes a simple page. Ensure `TELEGRAPH_ACCESS_TOKEN` is set as an environment variable to reuse an existing token."},"warnings":[{"fix":"Upgrade your Python environment to Python 3.6+ to use `telegraph` versions 2.0.0 or later.","message":"Python 2.x is no longer supported. Version 2.0.0 and above require Python 3.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use the `Telegraph.upload_file` *method* instead, accessible via an instantiated `Telegraph` object (e.g., `telegraph_instance.upload_file(...)`).","message":"The standalone `telegraph.upload_file` function is deprecated.","severity":"deprecated","affected_versions":">=2.1.0"},{"fix":"Refer to the Telegraph API documentation for a list of supported HTML tags and attributes. Use simple `p`, `h3`, `a`, `b`, `i`, `strong`, `em`, `ul`, `ol`, `li`, `br`, `img`, `iframe` for best compatibility.","message":"When providing HTML content to `create_page`, ensure it is valid Telegraph-compatible HTML. Invalid or unsupported tags/attributes will raise `telegraph.exceptions.NotAllowedTag`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure you are using `from telegraph.aio import Telegraph` for the async client. If you see this with the correct import, verify your `telegraph` library version is 2.1.0 or newer.","cause":"Attempting to import the asynchronous client incorrectly or using an outdated import path.","error":"ModuleNotFoundError: No module named 'telegraph.aio'"},{"fix":"Instantiate a `Telegraph` object and call the `upload_file` method on it: `telegraph_instance = Telegraph(); telegraph_instance.upload_file(...)`.","cause":"Trying to use the old top-level `upload_file` function after version 2.1.0, where it was deprecated and moved.","error":"AttributeError: module 'telegraph' has no attribute 'upload_file'"},{"fix":"Implement a retry mechanism with backoff, respecting the `retry_after` seconds provided in the exception. For example, use `asyncio.sleep` or `time.sleep`.","cause":"The Telegraph API rate limits requests. You've sent too many requests in a short period.","error":"telegraph.exceptions.RetryAfterError: Flood control exceeded. Retry in X seconds."}]}