Update documentation with takeout, add new known errors

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::
 

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()
+<telethon.client.account.AccountMethods.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
 ****************
 

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

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