From a5b107e6c9416f7ceecd006a2e034e6c5cfeeea9 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Sat, 5 Jan 2019 17:31:26 +0100 Subject: [PATCH] Update documentation with takeout, add new known errors --- README.rst | 3 +- .../extra/examples/telegram-client.rst | 30 +++++++++++++++++++ telethon_generator/data/errors.csv | 3 ++ telethon_generator/data/methods.csv | 4 +-- 4 files changed, 37 insertions(+), 3 deletions(-) diff --git a/README.rst b/README.rst index b73c6aa6..b8cb0a2b 100755 --- a/README.rst +++ b/README.rst @@ -5,7 +5,8 @@ Telethon ⭐️ Thanks **everyone** who has starred the project, it means a lot! |logo| **Telethon** is an asyncio_ **Python 3** -MTProto_ library to interact with Telegram_'s API. +MTProto_ library to interact with Telegram_'s API +as a user or through a bot account (bot API alternative). .. important:: diff --git a/readthedocs/extra/examples/telegram-client.rst b/readthedocs/extra/examples/telegram-client.rst index b9e08665..3f7ecdfb 100644 --- a/readthedocs/extra/examples/telegram-client.rst +++ b/readthedocs/extra/examples/telegram-client.rst @@ -262,6 +262,36 @@ Or just some IDs: message_1337 = client.get_messages(chats, ids=1337) +Exporting Messages +****************** + +If you plan on exporting data from your Telegram account, such as the entire +message history from your private conversations, chats or channels, or if you +plan to download a lot of media, you may prefer to do this within a *takeout* +session. Takeout sessions let you export data from your account with lower +flood wait limits. + +To start a takeout session, simply call `client.takeout() +`: + +.. code-block:: python + + from telethon import errors + + try: + with client.takeout() as takeout: + for message in takeout.iter_messages(chat, wait_time=0): + ... # Do something with the message + + except errors.TakeoutInitDelayError as e: + print('Must wait', e.seconds, 'before takeout') + + +Depending on the condition of the session (for example, when it's very +young and the method has not been called before), you may or not need +to ``except errors.TakeoutInitDelayError``. However, it is good practice. + + Sending Messages **************** diff --git a/telethon_generator/data/errors.csv b/telethon_generator/data/errors.csv index 54aa8791..36cb735f 100644 --- a/telethon_generator/data/errors.csv +++ b/telethon_generator/data/errors.csv @@ -20,6 +20,7 @@ BOT_INLINE_DISABLED,400,This bot can't be used in inline mode BOT_INVALID,400,This is not a valid bot BOT_METHOD_INVALID,400,The API access for bot users is restricted. The method you tried to invoke cannot be executed as a bot BOT_MISSING,400,This method can only be run by a bot +BOT_POLLS_DISABLED,400,You cannot create polls under a bot account BUTTON_DATA_INVALID,400,The provided button data is invalid BUTTON_TYPE_INVALID,400,The type of one of the buttons you provided is invalid BUTTON_URL_INVALID,400,Button URL invalid @@ -187,6 +188,7 @@ RPC_CALL_FAIL,,"Telegram is having internal issues, please try again later." RPC_MCGET_FAIL,,"Telegram is having internal issues, please try again later." RSA_DECRYPT_FAILED,400,Internal RSA decryption failed SEARCH_QUERY_EMPTY,400,The search query is empty +SEND_MESSAGE_MEDIA_INVALID,400,The message media was invalid or not specified SEND_MESSAGE_TYPE_INVALID,400,The message type is invalid SESSION_EXPIRED,401,The authorization has expired SESSION_PASSWORD_NEEDED,401,Two-steps verification is enabled and a password is required @@ -205,6 +207,7 @@ STICKER_PNG_DIMENSIONS,400,Sticker png dimensions invalid STORAGE_CHECK_FAILED,500,Server storage check failed STORE_INVALID_SCALAR_TYPE,500, TAKEOUT_INIT_DELAY_X,420,A wait of {seconds} seconds is required before being able to initiate the takeout +TAKEOUT_INVALID,400,The takeout session has been invalidated by another data export session TAKEOUT_REQUIRED,400,You must initialize a takeout request first TEMP_AUTH_KEY_EMPTY,400,No temporary auth key provided Timeout,-503,A timeout occurred while fetching data from the bot diff --git a/telethon_generator/data/methods.csv b/telethon_generator/data/methods.csv index 02e9b1c2..0ec74cf9 100644 --- a/telethon_generator/data/methods.csv +++ b/telethon_generator/data/methods.csv @@ -139,7 +139,7 @@ messages.sendEncrypted,unknown,CHAT_ID_INVALID DATA_INVALID ENCRYPTION_DECLINED messages.sendEncryptedFile,unknown,MSG_WAIT_FAILED messages.sendEncryptedService,unknown,DATA_INVALID ENCRYPTION_DECLINED MSG_WAIT_FAILED USER_IS_BLOCKED messages.sendInlineBotResult,user,CHAT_WRITE_FORBIDDEN INLINE_RESULT_EXPIRED PEER_ID_INVALID QUERY_ID_EMPTY WEBPAGE_CURL_FAILED WEBPAGE_MEDIA_EMPTY -messages.sendMedia,unknown,CHANNEL_INVALID CHANNEL_PRIVATE CHAT_ADMIN_REQUIRED CHAT_SEND_MEDIA_FORBIDDEN CHAT_WRITE_FORBIDDEN EXTERNAL_URL_INVALID FILE_PARTS_INVALID FILE_PART_LENGTH_INVALID INPUT_USER_DEACTIVATED MEDIA_CAPTION_TOO_LONG MEDIA_EMPTY PEER_ID_INVALID PHOTO_EXT_INVALID PHOTO_INVALID_DIMENSIONS PHOTO_SAVE_FILE_INVALID RANDOM_ID_DUPLICATE STORAGE_CHECK_FAILED Timeout USER_BANNED_IN_CHANNEL USER_IS_BLOCKED USER_IS_BOT WEBPAGE_CURL_FAILED WEBPAGE_MEDIA_EMPTY +messages.sendMedia,unknown,BOT_POLLS_DISABLED CHANNEL_INVALID CHANNEL_PRIVATE CHAT_ADMIN_REQUIRED CHAT_SEND_MEDIA_FORBIDDEN CHAT_WRITE_FORBIDDEN EXTERNAL_URL_INVALID FILE_PARTS_INVALID FILE_PART_LENGTH_INVALID INPUT_USER_DEACTIVATED MEDIA_CAPTION_TOO_LONG MEDIA_EMPTY PEER_ID_INVALID PHOTO_EXT_INVALID PHOTO_INVALID_DIMENSIONS PHOTO_SAVE_FILE_INVALID RANDOM_ID_DUPLICATE STORAGE_CHECK_FAILED Timeout USER_BANNED_IN_CHANNEL USER_IS_BLOCKED USER_IS_BOT WEBPAGE_CURL_FAILED WEBPAGE_MEDIA_EMPTY messages.sendMessage,unknown,AUTH_KEY_DUPLICATED BUTTON_DATA_INVALID BUTTON_TYPE_INVALID BUTTON_URL_INVALID CHANNEL_INVALID CHANNEL_PRIVATE CHAT_ADMIN_REQUIRED CHAT_ID_INVALID CHAT_RESTRICTED CHAT_WRITE_FORBIDDEN ENTITY_MENTION_USER_INVALID INPUT_USER_DEACTIVATED MESSAGE_EMPTY MESSAGE_TOO_LONG PEER_ID_INVALID RANDOM_ID_DUPLICATE REPLY_MARKUP_INVALID REPLY_MARKUP_TOO_LONG Timeout USER_BANNED_IN_CHANNEL USER_IS_BLOCKED USER_IS_BOT YOU_BLOCKED_USER messages.sendScreenshotNotification,user,PEER_ID_INVALID messages.setBotCallbackAnswer,unknown,QUERY_ID_INVALID URL_INVALID @@ -147,7 +147,7 @@ messages.setBotPrecheckoutResults,unknown,ERROR_TEXT_EMPTY messages.setBotShippingResults,unknown,QUERY_ID_INVALID messages.setEncryptedTyping,user,CHAT_ID_INVALID messages.setGameScore,unknown,PEER_ID_INVALID USER_BOT_REQUIRED -messages.setInlineBotResults,unknown,ARTICLE_TITLE_EMPTY BUTTON_DATA_INVALID BUTTON_TYPE_INVALID BUTTON_URL_INVALID MESSAGE_EMPTY QUERY_ID_INVALID REPLY_MARKUP_INVALID RESULT_TYPE_INVALID SEND_MESSAGE_TYPE_INVALID START_PARAM_INVALID USER_BOT_INVALID +messages.setInlineBotResults,unknown,ARTICLE_TITLE_EMPTY BUTTON_DATA_INVALID BUTTON_TYPE_INVALID BUTTON_URL_INVALID MESSAGE_EMPTY QUERY_ID_INVALID REPLY_MARKUP_INVALID RESULT_TYPE_INVALID SEND_MESSAGE_MEDIA_INVALID SEND_MESSAGE_TYPE_INVALID START_PARAM_INVALID USER_BOT_INVALID messages.setInlineGameScore,unknown,MESSAGE_ID_INVALID USER_BOT_REQUIRED messages.setTyping,unknown,CHANNEL_INVALID CHANNEL_PRIVATE CHAT_ID_INVALID CHAT_WRITE_FORBIDDEN PEER_ID_INVALID USER_BANNED_IN_CHANNEL USER_IS_BLOCKED USER_IS_BOT messages.startBot,user,BOT_INVALID PEER_ID_INVALID START_PARAM_EMPTY START_PARAM_INVALID