diff --git a/README.rst b/README.rst index a24c06eb..14fc52a5 100755 --- a/README.rst +++ b/README.rst @@ -53,16 +53,16 @@ if you're new with ``asyncio``. await client.send_file('username', '/home/myself/Pictures/holidays.jpg') await client.download_profile_photo(me) - total, messages, senders = await client.get_message_history('username') + messages = await client.get_message_history('username') await client.download_media(messages[0]) Next steps ---------- -Do you like how Telethon looks? Check the -`wiki over GitHub `_ for a -more in-depth explanation, with examples, troubleshooting issues, and more -useful information. Note that the examples there are written for the threaded -version, not the one using asyncio. However, you just need to await every -remote call. +Do you like how Telethon looks? Check out +`Read The Docs `_ +for a more in-depth explanation, with examples, troubleshooting issues, +and more useful information. Note that the examples there are written for +the threaded version, not the one using asyncio. However, you just need to +await every remote call. diff --git a/docs/docs_writer.py b/docs/docs_writer.py index f9042f00..9eec6cd7 100644 --- a/docs/docs_writer.py +++ b/docs/docs_writer.py @@ -90,7 +90,7 @@ class DocsWriter: def end_menu(self): """Ends an opened menu""" if not self.menu_began: - raise ValueError('No menu had been started in the first place.') + raise RuntimeError('No menu had been started in the first place.') self.write('') def write_title(self, title, level=1): diff --git a/readthedocs/extra/basic/accessing-the-full-api.rst b/readthedocs/extra/advanced-usage/accessing-the-full-api.rst similarity index 58% rename from readthedocs/extra/basic/accessing-the-full-api.rst rename to readthedocs/extra/advanced-usage/accessing-the-full-api.rst index ab6682db..04659bdb 100644 --- a/readthedocs/extra/basic/accessing-the-full-api.rst +++ b/readthedocs/extra/advanced-usage/accessing-the-full-api.rst @@ -1,33 +1,41 @@ .. _accessing-the-full-api: -========================== +====================== Accessing the Full API -========================== +====================== -The ``TelegramClient`` doesn’t offer a method for every single request -the Telegram API supports. However, it’s very simple to ``.invoke()`` -any request. Whenever you need something, don’t forget to `check the + +The ``TelegramClient`` doesn't offer a method for every single request +the Telegram API supports. However, it's very simple to *call* or *invoke* +any request. Whenever you need something, don't forget to `check the documentation`__ and look for the `method you need`__. There you can go through a sorted list of everything you can do. + +.. note:: + + Removing the hand crafted documentation for methods is still + a work in progress! + + You should also refer to the documentation to see what the objects (constructors) Telegram returns look like. Every constructor inherits -from a common type, and that’s the reason for this distinction. +from a common type, and that's the reason for this distinction. -Say ``client.send_message()`` didn’t exist, we could use the `search`__ -to look for “message”. There we would find `SendMessageRequest`__, +Say ``client.send_message()`` didn't exist, we could use the `search`__ +to look for "message". There we would find `SendMessageRequest`__, which we can work with. Every request is a Python class, and has the parameters needed for you to invoke it. You can also call ``help(request)`` for information on -what input parameters it takes. Remember to “Copy import to the -clipboard”, or your script won’t be aware of this class! Now we have: +what input parameters it takes. Remember to "Copy import to the +clipboard", or your script won't be aware of this class! Now we have: .. code-block:: python from telethon.tl.functions.messages import SendMessageRequest -If you’re going to use a lot of these, you may do: +If you're going to use a lot of these, you may do: .. code-block:: python @@ -53,20 +61,20 @@ Or we call ``.get_input_entity()``: peer = client.get_input_entity('someone') -When you’re going to invoke an API method, most require you to pass an +When you're going to invoke an API method, most require you to pass an ``InputUser``, ``InputChat``, or so on, this is why using -``.get_input_entity()`` is more straightforward (and sometimes -immediate, if you know the ID of the user for instance). If you also -need to have information about the whole user, use ``.get_entity()`` -instead: +``.get_input_entity()`` is more straightforward (and often +immediate, if you've seen the user before, know their ID, etc.). +If you also need to have information about the whole user, use +``.get_entity()`` instead: .. code-block:: python entity = client.get_entity('someone') In the later case, when you use the entity, the library will cast it to -its “input” version for you. If you already have the complete user and -want to cache its input version so the library doesn’t have to do this +its "input" version for you. If you already have the complete user and +want to cache its input version so the library doesn't have to do this every time its used, simply call ``.get_input_peer``: .. code-block:: python @@ -83,10 +91,9 @@ request we do: result = client(SendMessageRequest(peer, 'Hello there!')) # __call__ is an alias for client.invoke(request). Both will work -Message sent! Of course, this is only an example. -There are nearly 250 methods available as of layer 73, -and you can use every single of them as you wish. -Remember to use the right types! To sum up: +Message sent! Of course, this is only an example. There are nearly 250 +methods available as of layer 73, and you can use every single of them +as you wish. Remember to use the right types! To sum up: .. code-block:: python @@ -97,16 +104,16 @@ Remember to use the right types! To sum up: .. note:: - Note that some requests have a "hash" parameter. This is **not** your ``api_hash``! - It likely isn't your self-user ``.access_hash`` either. - It's a special hash used by Telegram to only send a difference of new data - that you don't already have with that request, - so you can leave it to 0, and it should work (which means no hash is known yet). + Note that some requests have a "hash" parameter. This is **not** + your ``api_hash``! It likely isn't your self-user ``.access_hash`` either. - For those requests having a "limit" parameter, - you can often set it to zero to signify "return as many items as possible". - This won't work for all of them though, - for instance, in "messages.search" it will actually return 0 items. + It's a special hash used by Telegram to only send a difference of new data + that you don't already have with that request, so you can leave it to 0, + and it should work (which means no hash is known yet). + + For those requests having a "limit" parameter, you can often set it to + zero to signify "return default amount". This won't work for all of them + though, for instance, in "messages.search" it will actually return 0 items. __ https://lonamiwebs.github.io/Telethon @@ -114,4 +121,4 @@ __ https://lonamiwebs.github.io/Telethon/methods/index.html __ https://lonamiwebs.github.io/Telethon/?q=message __ https://lonamiwebs.github.io/Telethon/methods/messages/send_message.html __ https://lonamiwebs.github.io/Telethon/types/input_peer.html -__ https://lonamiwebs.github.io/Telethon/constructors/input_peer_user.html \ No newline at end of file +__ https://lonamiwebs.github.io/Telethon/constructors/input_peer_user.html diff --git a/readthedocs/extra/advanced-usage/sessions.rst b/readthedocs/extra/advanced-usage/sessions.rst new file mode 100644 index 00000000..7f1ded9b --- /dev/null +++ b/readthedocs/extra/advanced-usage/sessions.rst @@ -0,0 +1,46 @@ +.. _sessions: + +============== +Session Files +============== + +The first parameter you pass the the constructor of the ``TelegramClient`` is +the ``session``, and defaults to be the session name (or full path). That is, +if you create a ``TelegramClient('anon')`` instance and connect, an +``anon.session`` file will be created on the working directory. + +These database files using ``sqlite3`` contain the required information to +talk to the Telegram servers, such as to which IP the client should connect, +port, authorization key so that messages can be encrypted, and so on. + +These files will by default also save all the input entities that you've seen, +so that you can get information about an user or channel by just their ID. +Telegram will **not** send their ``access_hash`` required to retrieve more +information about them, if it thinks you have already seem them. For this +reason, the library needs to store this information offline. + +The library will by default too save all the entities (chats and channels +with their name and username, and users with the phone too) in the session +file, so that you can quickly access them by username or phone number. + +If you're not going to work with updates, or don't need to cache the +``access_hash`` associated with the entities' ID, you can disable this +by setting ``client.session.save_entities = False``, or pass it as a +parameter to the ``TelegramClient``. + +If you don't want to save the files as a database, you can also create +your custom ``Session`` subclass and override the ``.save()`` and ``.load()`` +methods. For example, you could save it on a database: + + .. code-block:: python + + class DatabaseSession(Session): + def save(): + # serialize relevant data to the database + + def load(): + # load relevant data to the database + + +You should read the ````session.py```` source file to know what "relevant +data" you need to keep track of. diff --git a/readthedocs/extra/advanced-usage/signing-in.rst b/readthedocs/extra/advanced-usage/signing-in.rst deleted file mode 100644 index 08f4fe3d..00000000 --- a/readthedocs/extra/advanced-usage/signing-in.rst +++ /dev/null @@ -1,58 +0,0 @@ -========================= -Signing In -========================= - -.. note:: - Make sure you have gone through :ref:`prelude` already! - - -Two Factor Authorization (2FA) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you have Two Factor Authorization (from now on, 2FA) enabled on your account, calling -:meth:`telethon.TelegramClient.sign_in` will raise a `SessionPasswordNeededError`. -When this happens, just :meth:`telethon.TelegramClient.sign_in` again with a ``password=``: - - .. code-block:: python - - import getpass - from telethon.errors import SessionPasswordNeededError - - client.sign_in(phone) - try: - client.sign_in(code=input('Enter code: ')) - except SessionPasswordNeededError: - client.sign_in(password=getpass.getpass()) - -Enabling 2FA -************* - -If you don't have 2FA enabled, but you would like to do so through Telethon, take as example the following code snippet: - - .. code-block:: python - - import os - from hashlib import sha256 - from telethon.tl.functions import account - from telethon.tl.types.account import PasswordInputSettings - - new_salt = client(account.GetPasswordRequest()).new_salt - salt = new_salt + os.urandom(8) # new random salt - - pw = 'secret'.encode('utf-8') # type your new password here - hint = 'hint' - - pw_salted = salt + pw + salt - pw_hash = sha256(pw_salted).digest() - - result = client(account.UpdatePasswordSettingsRequest( - current_password_hash=salt, - new_settings=PasswordInputSettings( - new_salt=salt, - new_password_hash=pw_hash, - hint=hint - ) - )) - -Thanks to `Issue 259 `_ for the tip! - diff --git a/readthedocs/extra/advanced-usage/users-and-chats.rst b/readthedocs/extra/advanced-usage/users-and-chats.rst deleted file mode 100644 index a48a2857..00000000 --- a/readthedocs/extra/advanced-usage/users-and-chats.rst +++ /dev/null @@ -1,324 +0,0 @@ -========================= -Users and Chats -========================= - -.. note:: - Make sure you have gone through :ref:`prelude` already! - -.. contents:: - :depth: 2 - -.. _retrieving-an-entity: - -Retrieving an entity (user or group) -************************************** -An “entity” is used to refer to either an `User`__ or a `Chat`__ -(which includes a `Channel`__). The most straightforward way to get -an entity is to use ``TelegramClient.get_entity()``. This method accepts -either a string, which can be a username, phone number or `t.me`__-like -link, or an integer that will be the ID of an **user**. You can use it -like so: - - .. code-block:: python - - # all of these work - lonami = client.get_entity('lonami') - lonami = client.get_entity('t.me/lonami') - lonami = client.get_entity('https://telegram.dog/lonami') - - # other kind of entities - channel = client.get_entity('telegram.me/joinchat/AAAAAEkk2WdoDrB4-Q8-gg') - contact = client.get_entity('+34xxxxxxxxx') - friend = client.get_entity(friend_id) - -For the last one to work, the library must have “seen” the user at least -once. The library will “see” the user as long as any request contains -them, so if you’ve called ``.get_dialogs()`` for instance, and your -friend was there, the library will know about them. For more, read about -the :ref:`sessions`. - -If you want to get a channel or chat by ID, you need to specify that -they are a channel or a chat. The library can’t infer what they are by -just their ID (unless the ID is marked, but this is only done -internally), so you need to wrap the ID around a `Peer`__ object: - - .. code-block:: python - - from telethon.tl.types import PeerUser, PeerChat, PeerChannel - my_user = client.get_entity(PeerUser(some_id)) - my_chat = client.get_entity(PeerChat(some_id)) - my_channel = client.get_entity(PeerChannel(some_id)) - -**Note** that most requests don’t ask for an ``User``, or a ``Chat``, -but rather for ``InputUser``, ``InputChat``, and so on. If this is the -case, you should prefer ``.get_input_entity()`` over ``.get_entity()``, -as it will be immediate if you provide an ID (whereas ``.get_entity()`` -may need to find who the entity is first). - -Via your open “chats” (dialogs) -------------------------------- - -.. note:: - Please read here: :ref:`retrieving-all-dialogs`. - -Via ResolveUsernameRequest --------------------------- - -This is the request used by ``.get_entity`` internally, but you can also -use it by hand: - -.. code-block:: python - - from telethon.tl.functions.contacts import ResolveUsernameRequest - - result = client(ResolveUsernameRequest('username')) - found_chats = result.chats - found_users = result.users - # result.peer may be a PeerUser, PeerChat or PeerChannel - -See `Peer`__ for more information about this result. - -Via MessageFwdHeader --------------------- - -If all you have is a `MessageFwdHeader`__ after you retrieved a bunch -of messages, this gives you access to the ``from_id`` (if forwarded from -an user) and ``channel_id`` (if forwarded from a channel). Invoking -`GetMessagesRequest`__ also returns a list of ``chats`` and -``users``, and you can find the desired entity there: - - .. code-block:: python - - # Logic to retrieve messages with `GetMessagesRequest´ - messages = foo() - fwd_header = bar() - - user = next(u for u in messages.users if u.id == fwd_header.from_id) - channel = next(c for c in messages.chats if c.id == fwd_header.channel_id) - -Or you can just call ``.get_entity()`` with the ID, as you should have -seen that user or channel before. A call to ``GetMessagesRequest`` may -still be neeed. - -Via GetContactsRequest ----------------------- - -The library will call this for you if you pass a phone number to -``.get_entity``, but again, it can be done manually. If the user you -want to talk to is a contact, you can use `GetContactsRequest`__: - - .. code-block:: python - - from telethon.tl.functions.contacts import GetContactsRequest - from telethon.tl.types.contacts import Contacts - - contacts = client(GetContactsRequest(0)) - if isinstance(contacts, Contacts): - users = contacts.users - contacts = contacts.contacts - -__ https://lonamiwebs.github.io/Telethon/types/user.html -__ https://lonamiwebs.github.io/Telethon/types/chat.html -__ https://lonamiwebs.github.io/Telethon/constructors/channel.html -__ https://t.me -__ https://lonamiwebs.github.io/Telethon/types/peer.html -__ https://lonamiwebs.github.io/Telethon/types/peer.html -__ https://lonamiwebs.github.io/Telethon/constructors/message_fwd_header.html -__ https://lonamiwebs.github.io/Telethon/methods/messages/get_messages.html -__ https://lonamiwebs.github.io/Telethon/methods/contacts/get_contacts.html - - -.. _retrieving-all-dialogs: - -Retrieving all dialogs -*********************** - -There are several ``offset_xyz=`` parameters that have no effect at all, -but there's not much one can do since this is something the server should handle. -Currently, the only way to get all dialogs -(open chats, conversations, etc.) is by using the ``offset_date``: - - .. code-block:: python - - from telethon.tl.functions.messages import GetDialogsRequest - from telethon.tl.types import InputPeerEmpty - from time import sleep - - dialogs = [] - users = [] - chats = [] - - last_date = None - chunk_size = 20 - while True: - result = client(GetDialogsRequest( - offset_date=last_date, - offset_id=0, - offset_peer=InputPeerEmpty(), - limit=chunk_size - )) - dialogs.extend(result.dialogs) - users.extend(result.users) - chats.extend(result.chats) - if not result.messages: - break - last_date = min(msg.date for msg in result.messages) - sleep(2) - - -Joining a chat or channel -******************************* - -Note that `Chat`__\ s are normal groups, and `Channel`__\ s are a -special form of `Chat`__\ s, -which can also be super-groups if their ``megagroup`` member is -``True``. - -Joining a public channel ------------------------- - -Once you have the :ref:`entity ` -of the channel you want to join to, you can -make use of the `JoinChannelRequest`__ to join such channel: - - .. code-block:: python - - from telethon.tl.functions.channels import JoinChannelRequest - client(JoinChannelRequest(channel)) - - # In the same way, you can also leave such channel - from telethon.tl.functions.channels import LeaveChannelRequest - client(LeaveChannelRequest(input_channel)) - -For more on channels, check the `channels namespace`__. - -Joining a private chat or channel ---------------------------------- - -If all you have is a link like this one: -``https://t.me/joinchat/AAAAAFFszQPyPEZ7wgxLtd``, you already have -enough information to join! The part after the -``https://t.me/joinchat/``, this is, ``AAAAAFFszQPyPEZ7wgxLtd`` on this -example, is the ``hash`` of the chat or channel. Now you can use -`ImportChatInviteRequest`__ as follows: - - .. -block:: python - - from telethon.tl.functions.messages import ImportChatInviteRequest - updates = client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg')) - -Adding someone else to such chat or channel -------------------------------------------- - -If you don’t want to add yourself, maybe because you’re already in, you -can always add someone else with the `AddChatUserRequest`__, which -use is very straightforward: - - .. code-block:: python - - from telethon.tl.functions.messages import AddChatUserRequest - - client(AddChatUserRequest( - chat_id, - user_to_add, - fwd_limit=10 # allow the user to see the 10 last messages - )) - -Checking a link without joining -------------------------------- - -If you don’t need to join but rather check whether it’s a group or a -channel, you can use the `CheckChatInviteRequest`__, which takes in -the `hash`__ of said channel or group. - -__ https://lonamiwebs.github.io/Telethon/constructors/chat.html -__ https://lonamiwebs.github.io/Telethon/constructors/channel.html -__ https://lonamiwebs.github.io/Telethon/types/chat.html -__ https://lonamiwebs.github.io/Telethon/methods/channels/join_channel.html -__ https://lonamiwebs.github.io/Telethon/methods/channels/index.html -__ https://lonamiwebs.github.io/Telethon/methods/messages/import_chat_invite.html -__ https://lonamiwebs.github.io/Telethon/methods/messages/add_chat_user.html -__ https://lonamiwebs.github.io/Telethon/methods/messages/check_chat_invite.html -__ https://github.com/LonamiWebs/Telethon/wiki/Joining-a-chat-or-channel#joining-a-private-chat-or-channel - - -Retrieving all chat members (channels too) -****************************************** - -In order to get all the members from a mega-group or channel, you need -to use `GetParticipantsRequest`__. As we can see it needs an -`InputChannel`__, (passing the mega-group or channel you’re going to -use will work), and a mandatory `ChannelParticipantsFilter`__. The -closest thing to “no filter” is to simply use -`ChannelParticipantsSearch`__ with an empty ``'q'`` string. - -If we want to get *all* the members, we need to use a moving offset and -a fixed limit: - - .. code-block:: python - - from telethon.tl.functions.channels import GetParticipantsRequest - from telethon.tl.types import ChannelParticipantsSearch - from time import sleep - - offset = 0 - limit = 100 - all_participants = [] - - while True: - participants = client.invoke(GetParticipantsRequest( - channel, ChannelParticipantsSearch(''), offset, limit - )) - if not participants.users: - break - all_participants.extend(participants.users) - offset += len(participants.users) - # sleep(1) # This line seems to be optional, no guarantees! - -Note that ``GetParticipantsRequest`` returns `ChannelParticipants`__, -which may have more information you need (like the role of the -participants, total count of members, etc.) - -__ https://lonamiwebs.github.io/Telethon/methods/channels/get_participants.html -__ https://lonamiwebs.github.io/Telethon/methods/channels/get_participants.html -__ https://lonamiwebs.github.io/Telethon/types/channel_participants_filter.html -__ https://lonamiwebs.github.io/Telethon/constructors/channel_participants_search.html -__ https://lonamiwebs.github.io/Telethon/constructors/channels/channel_participants.html - - -Recent Actions -******************** - -“Recent actions” is simply the name official applications have given to -the “admin log”. Simply use `GetAdminLogRequest`__ for that, and -you’ll get AdminLogResults.events in return which in turn has the final -`.action`__. - -__ https://lonamiwebs.github.io/Telethon/methods/channels/get_admin_log.html -__ https://lonamiwebs.github.io/Telethon/types/channel_admin_log_event_action.html - - -Increasing View Count in a Channel -**************************************** - -It has been asked `quite`__ `a few`__ `times`__ (really, `many`__), and -while I don’t understand why so many people ask this, the solution is to -use `GetMessagesViewsRequest`__, setting ``increment=True``: - - .. code-block:: python - - - # Obtain `channel' through dialogs or through client.get_entity() or anyhow. - # Obtain `msg_ids' through `.get_message_history()` or anyhow. Must be a list. - - client(GetMessagesViewsRequest( - peer=channel, - id=msg_ids, - increment=True - )) - -__ https://github.com/LonamiWebs/Telethon/issues/233 -__ https://github.com/LonamiWebs/Telethon/issues/305 -__ https://github.com/LonamiWebs/Telethon/issues/409 -__ https://github.com/LonamiWebs/Telethon/issues/447 -__ https://lonamiwebs.github.io/Telethon/methods/messages/get_messages_views.html \ No newline at end of file diff --git a/readthedocs/extra/advanced.rst b/readthedocs/extra/advanced.rst deleted file mode 100644 index 4433116d..00000000 --- a/readthedocs/extra/advanced.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _prelude: - -Prelude ---------- - -Before reading any specific example, make sure to read the following common steps: - -All the examples assume that you have successfully created a client and you're authorized as follows: - - .. code-block:: python - - from telethon import TelegramClient - - # Use your own values here - api_id = 12345 - api_hash = '0123456789abcdef0123456789abcdef' - phone_number = '+34600000000' - - client = TelegramClient('some_name', api_id, api_hash) - client.connect() # Must return True, otherwise, try again - - if not client.is_user_authorized(): - client.send_code_request(phone_number) - # .sign_in() may raise PhoneNumberUnoccupiedError - # In that case, you need to call .sign_up() to get a new account - client.sign_in(phone_number, input('Enter code: ')) - - # The `client´ is now ready - -Although Python will probably clean up the resources used by the ``TelegramClient``, -you should always ``.disconnect()`` it once you're done: - - .. code-block:: python - - try: - # Code using the client goes here - except: - # No matter what happens, always disconnect in the end - client.disconnect() - -If the examples aren't enough, you're strongly advised to read the source code -for the InteractiveTelegramClient_ for an overview on how you could build your next script. -This example shows a basic usage more than enough in most cases. Even reading the source -for the TelegramClient_ may help a lot! - - -.. _InteractiveTelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon_examples/interactive_telegram_client.py -.. _TelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon/telegram_client.py diff --git a/readthedocs/extra/basic/creating-a-client.rst b/readthedocs/extra/basic/creating-a-client.rst index 997386db..81e19c83 100644 --- a/readthedocs/extra/basic/creating-a-client.rst +++ b/readthedocs/extra/basic/creating-a-client.rst @@ -1,24 +1,28 @@ .. _creating-a-client: -=================== +================= Creating a Client -=================== +================= + Before working with Telegram's API, you need to get your own API ID and hash: -1. Follow `this link `_ and login with your phone number. +1. Follow `this link `_ and login with your + phone number. 2. Click under API Development tools. -3. A *Create new application* window will appear. Fill in your application details. -There is no need to enter any *URL*, and only the first two fields (*App title* and *Short name*) -can be changed later as far as I'm aware. +3. A *Create new application* window will appear. Fill in your application + details. There is no need to enter any *URL*, and only the first two + fields (*App title* and *Short name*) can currently be changed later. -4. Click on *Create application* at the end. Remember that your **API hash is secret** -and Telegram won't let you revoke it. Don't post it anywhere! +4. Click on *Create application* at the end. Remember that your + **API hash is secret** and Telegram won't let you revoke it. + Don't post it anywhere! Once that's ready, the next step is to create a ``TelegramClient``. -This class will be your main interface with Telegram's API, and creating one is very simple: +This class will be your main interface with Telegram's API, and creating +one is very simple: .. code-block:: python @@ -31,14 +35,18 @@ This class will be your main interface with Telegram's API, and creating one is client = TelegramClient('some_name', api_id, api_hash) -Note that ``'some_name'`` will be used to save your session (persistent information such as access key and others) -as ``'some_name.session'`` in your disk. This is simply a JSON file which you can (but shouldn't) modify. -Before using the client, you must be connected to Telegram. Doing so is very easy: +Note that ``'some_name'`` will be used to save your session (persistent +information such as access key and others) as ``'some_name.session'`` in +your disk. This is by default a database file using Python's ``sqlite3``. + +Before using the client, you must be connected to Telegram. +Doing so is very easy: ``client.connect() # Must return True, otherwise, try again`` -You may or may not be authorized yet. You must be authorized before you're able to send any request: +You may or may not be authorized yet. You must be authorized +before you're able to send any request: ``client.is_user_authorized() # Returns True if you can send requests`` @@ -52,13 +60,25 @@ If you're not authorized, you need to ``.sign_in()``: # If .sign_in raises SessionPasswordNeeded error, call .sign_in(password=...) # You can import both exceptions from telethon.errors. -``myself`` is your Telegram user. -You can view all the information about yourself by doing ``print(myself.stringify())``. -You're now ready to use the client as you wish! +``myself`` is your Telegram user. You can view all the information about +yourself by doing ``print(myself.stringify())``. You're now ready to use +the client as you wish! Remember that any object returned by the API has +mentioned ``.stringify()`` method, and printing these might prove useful. + +As a full example: + + .. code-block:: python + + client = TelegramClient('anon', api_id, api_hash) + assert client.connect() + if not client.is_user_authorized(): + client.send_code_request(phone_number) + me = client.sign_in(phone_number, input('Enter code: ')) + .. note:: - If you want to use a **proxy**, you have to `install PySocks`__ (via pip or manual) - and then set the appropriated parameters: + If you want to use a **proxy**, you have to `install PySocks`__ + (via pip or manual) and then set the appropriated parameters: .. code-block:: python @@ -72,5 +92,58 @@ You're now ready to use the client as you wish! consisting of parameters described `here`__. + +Two Factor Authorization (2FA) +****************************** + +If you have Two Factor Authorization (from now on, 2FA) enabled on your +account, calling :meth:`telethon.TelegramClient.sign_in` will raise a +``SessionPasswordNeededError``. When this happens, just +:meth:`telethon.TelegramClient.sign_in` again with a ``password=``: + + .. code-block:: python + + import getpass + from telethon.errors import SessionPasswordNeededError + + client.sign_in(phone) + try: + client.sign_in(code=input('Enter code: ')) + except SessionPasswordNeededError: + client.sign_in(password=getpass.getpass()) + + +If you don't have 2FA enabled, but you would like to do so through the library, +take as example the following code snippet: + + .. code-block:: python + + import os + from hashlib import sha256 + from telethon.tl.functions import account + from telethon.tl.types.account import PasswordInputSettings + + new_salt = client(account.GetPasswordRequest()).new_salt + salt = new_salt + os.urandom(8) # new random salt + + pw = 'secret'.encode('utf-8') # type your new password here + hint = 'hint' + + pw_salted = salt + pw + salt + pw_hash = sha256(pw_salted).digest() + + result = client(account.UpdatePasswordSettingsRequest( + current_password_hash=salt, + new_settings=PasswordInputSettings( + new_salt=salt, + new_password_hash=pw_hash, + hint=hint + ) + )) + +Thanks to `Issue 259 `_ +for the tip! + + __ https://github.com/Anorov/PySocks#installation -__ https://github.com/Anorov/PySocks#usage-1%3E \ No newline at end of file +__ https://github.com/Anorov/PySocks#usage-1 diff --git a/readthedocs/extra/basic/entities.rst b/readthedocs/extra/basic/entities.rst new file mode 100644 index 00000000..bc87539a --- /dev/null +++ b/readthedocs/extra/basic/entities.rst @@ -0,0 +1,87 @@ +========================= +Users, Chats and Channels +========================= + + +Introduction +************ + +The library widely uses the concept of "entities". An entity will refer +to any ``User``, ``Chat`` or ``Channel`` object that the API may return +in response to certain methods, such as ``GetUsersRequest``. + +To save bandwidth, the API also makes use of their "input" versions. +The input version of an entity (e.g. ``InputPeerUser``, ``InputChat``, +etc.) only contains the minimum required information that's required +for Telegram to be able to identify who you're referring to: their ID +and hash. This ID/hash pair is unique per user, so if you use the pair +given by another user **or bot** it will **not** work. + +To save *even more* bandwidth, the API also makes use of the ``Peer`` +versions, which just have an ID. This serves to identify them, but +peers alone are not enough to use them. You need to know their hash +before you can "use them". + +Luckily, the library tries to simplify this mess the best it can. + + +Getting entities +**************** + +Through the use of the :ref:`sessions`, the library will automatically +remember the ID and hash pair, along with some extra information, so +you're able to just do this: + + .. code-block:: python + + # Dialogs are the "conversations you have open". + # This method returns a list of Dialog, which + # has the .entity attribute and other information. + dialogs = client.get_dialogs(limit=200) + + # All of these work and do the same. + lonami = client.get_entity('lonami') + lonami = client.get_entity('t.me/lonami') + lonami = client.get_entity('https://telegram.dog/lonami') + + # Other kind of entities. + channel = client.get_entity('telegram.me/joinchat/AAAAAEkk2WdoDrB4-Q8-gg') + contact = client.get_entity('+34xxxxxxxxx') + friend = client.get_entity(friend_id) + + # Using Peer/InputPeer (note that the API may return these) + # users, chats and channels may all have the same ID, so it's + # necessary to wrap (at least) chat and channels inside Peer. + from telethon.tl.types import PeerUser, PeerChat, PeerChannel + my_user = client.get_entity(PeerUser(some_id)) + my_chat = client.get_entity(PeerChat(some_id)) + my_channel = client.get_entity(PeerChannel(some_id)) + + +All methods in the :ref:`telegram-client` call ``.get_entity()`` to further +save you from the hassle of doing so manually, so doing things like +``client.send_message('lonami', 'hi!')`` is possible. + +Every entity the library "sees" (in any response to any call) will by +default be cached in the ``.session`` file, to avoid performing +unnecessary API calls. If the entity cannot be found, some calls +like ``ResolveUsernameRequest`` or ``GetContactsRequest`` may be +made to obtain the required information. + + +Entities vs. Input Entities +*************************** + +As we mentioned before, API calls don't need to know the whole information +about the entities, only their ID and hash. For this reason, another method, +``.get_input_entity()`` is available. This will always use the cache while +possible, making zero API calls most of the time. When a request is made, +if you provided the full entity, e.g. an ``User``, the library will convert +it to the required ``InputPeer`` automatically for you. + +**You should always favour** ``.get_input_entity()`` **over** ``.get_entity()`` +for this reason! Calling the latter will always make an API call to get +the most recent information about said entity, but invoking requests don't +need this information, just the ``InputPeer``. Only use ``.get_entity()`` +if you need to get actual information, like the username, name, title, etc. +of the entity. diff --git a/readthedocs/extra/basic/getting-started.rst b/readthedocs/extra/basic/getting-started.rst index bad3ea30..88a6247c 100644 --- a/readthedocs/extra/basic/getting-started.rst +++ b/readthedocs/extra/basic/getting-started.rst @@ -3,13 +3,13 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +=============== +Getting Started +=============== -================= -Getting Started! -================= Simple Installation -********************* +******************* ``pip install telethon`` @@ -17,7 +17,7 @@ Simple Installation Creating a client -************** +***************** .. code-block:: python @@ -39,8 +39,9 @@ Creating a client **More details**: :ref:`creating-a-client` -Simple Stuff -************** +Basic Usage +*********** + .. code-block:: python print(me.stringify()) @@ -49,6 +50,7 @@ Simple Stuff client.send_file('username', '/home/myself/Pictures/holidays.jpg') client.download_profile_photo(me) - total, messages, senders = client.get_message_history('username') + messages = client.get_message_history('username') client.download_media(messages[0]) + **More details**: :ref:`telegram-client` diff --git a/readthedocs/extra/basic/installation.rst b/readthedocs/extra/basic/installation.rst index ecad699b..b4fb1ac2 100644 --- a/readthedocs/extra/basic/installation.rst +++ b/readthedocs/extra/basic/installation.rst @@ -1,18 +1,20 @@ .. _installation: -================= +============ Installation -================= +============ Automatic Installation -^^^^^^^^^^^^^^^^^^^^^^^ +********************** + To install Telethon, simply do: ``pip install telethon`` -If you get something like ``"SyntaxError: invalid syntax"`` or any other error while installing, -it's probably because ``pip`` defaults to Python 2, which is not supported. Use ``pip3`` instead. +If you get something like ``"SyntaxError: invalid syntax"`` or any other +error while installing/importing the library, it's probably because ``pip`` +defaults to Python 2, which is not supported. Use ``pip3`` instead. If you already have the library installed, upgrade with: @@ -20,7 +22,7 @@ If you already have the library installed, upgrade with: You can also install the library directly from GitHub or a fork: - .. code-block:: python + .. code-block:: sh # pip install git+https://github.com/LonamiWebs/Telethon.git or @@ -32,13 +34,15 @@ If you don't have root access, simply pass the ``--user`` flag to the pip comman Manual Installation -^^^^^^^^^^^^^^^^^^^^ +******************* -1. Install the required ``pyaes`` (`GitHub`__ | `PyPi`__) and ``rsa`` (`GitHub`__ | `PyPi`__) modules: +1. Install the required ``pyaes`` (`GitHub`__ | `PyPi`__) and + ``rsa`` (`GitHub`__ | `PyPi`__) modules: ``sudo -H pip install pyaes rsa`` -2. Clone Telethon's GitHub repository: ``git clone https://github.com/LonamiWebs/Telethon.git`` +2. Clone Telethon's GitHub repository: + ``git clone https://github.com/LonamiWebs/Telethon.git`` 3. Enter the cloned repository: ``cd Telethon`` @@ -50,22 +54,14 @@ To generate the documentation, ``cd docs`` and then ``python3 generate.py``. Optional dependencies -^^^^^^^^^^^^^^^^^^^^^^^^ - -If you're using the library under ARM (or even if you aren't), -you may want to install ``sympy`` through ``pip`` for a substantial speed-up -when generating the keys required to connect to Telegram -(you can of course do this on desktop too). See `issue #199`__ for more. - -If ``libssl`` is available on your system, it will also be used wherever encryption is needed. - -If neither of these are available, a pure Python callback will be used instead, -so you can still run the library wherever Python is available! +********************* +If ``libssl`` is available on your system, it will be used wherever encryption +is needed, but otherwise it will fall back to pure Python implementation so it +will also work without it. __ https://github.com/ricmoo/pyaes __ https://pypi.python.org/pypi/pyaes __ https://github.com/sybrenstuvel/python-rsa/ __ https://pypi.python.org/pypi/rsa/3.4.2 -__ https://github.com/LonamiWebs/Telethon/issues/199 \ No newline at end of file diff --git a/readthedocs/extra/basic/sending-requests.rst b/readthedocs/extra/basic/sending-requests.rst deleted file mode 100644 index 160e2259..00000000 --- a/readthedocs/extra/basic/sending-requests.rst +++ /dev/null @@ -1,55 +0,0 @@ -.. _sending-requests: - -================== -Sending Requests -================== - -Since we're working with Python, one must not forget that they can do ``help(client)`` or ``help(TelegramClient)`` -at any time for a more detailed description and a list of all the available methods. -Calling ``help()`` from an interactive Python session will always list all the methods for any object, even yours! - -Interacting with the Telegram API is done through sending **requests**, -this is, any "method" listed on the API. There are a few methods on the ``TelegramClient`` class -that abstract you from the need of manually importing the requests you need. - -For instance, retrieving your own user can be done in a single line: - - ``myself = client.get_me()`` - -Internally, this method has sent a request to Telegram, who replied with the information about your own user. - -If you want to retrieve any other user, chat or channel (channels are a special subset of chats), -you want to retrieve their "entity". This is how the library refers to either of these: - - .. code-block:: python - - # The method will infer that you've passed an username - # It also accepts phone numbers, and will get the user - # from your contact list. - lonami = client.get_entity('lonami') - -Note that saving and using these entities will be more important when Accessing the Full API. -For now, this is a good way to get information about an user or chat. - -Other common methods for quick scripts are also available: - - .. code-block:: python - - # Sending a message (use an entity/username/etc) - client.send_message('TheAyyBot', 'ayy') - - # Sending a photo, or a file - client.send_file(myself, '/path/to/the/file.jpg', force_document=True) - - # Downloading someone's profile photo. File is saved to 'where' - where = client.download_profile_photo(someone) - - # Retrieving the message history - total, messages, senders = client.get_message_history(someone) - - # Downloading the media from a specific message - # You can specify either a directory, a filename, or nothing at all - where = client.download_media(message, '/path/to/output') - -Remember that you can call ``.stringify()`` to any object Telegram returns to pretty print it. -Calling ``str(result)`` does the same operation, but on a single line. diff --git a/readthedocs/extra/basic/sessions.rst b/readthedocs/extra/basic/sessions.rst deleted file mode 100644 index 0f9d458a..00000000 --- a/readthedocs/extra/basic/sessions.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _sessions: - -============== -Session Files -============== - -The first parameter you pass the the constructor of the -``TelegramClient`` is the ``session``, and defaults to be the session -name (or full path). That is, if you create a ``TelegramClient('anon')`` -instance and connect, an ``anon.session`` file will be created on the -working directory. - -These JSON session files contain the required information to talk to the -Telegram servers, such as to which IP the client should connect, port, -authorization key so that messages can be encrypted, and so on. - -These files will by default also save all the input entities that you’ve -seen, so that you can get information about an user or channel by just -their ID. Telegram will **not** send their ``access_hash`` required to -retrieve more information about them, if it thinks you have already seem -them. For this reason, the library needs to store this information -offline. - -The library will by default too save all the entities (users with their -name, username, chats and so on) **in memory**, not to disk, so that you -can quickly access them by username or phone number. This can be -disabled too. Run ``help(client.session.entities)`` to see the available -methods (or ``help(EntityDatabase)``). - -If you’re not going to work without updates, or don’t need to cache the -``access_hash`` associated with the entities’ ID, you can disable this -by setting ``client.session.save_entities = False``. - -If you don’t want to save the files as JSON, you can also create your -custom ``Session`` subclass and override the ``.save()`` and ``.load()`` -methods. For example, you could save it on a database: - - .. code-block:: python - - class DatabaseSession(Session): - def save(): - # serialize relevant data to the database - - def load(): - # load relevant data to the database - -You should read the ``session.py`` source file to know what “relevant -data” you need to keep track of. \ No newline at end of file diff --git a/readthedocs/extra/basic/telegram-client.rst b/readthedocs/extra/basic/telegram-client.rst new file mode 100644 index 00000000..5663f533 --- /dev/null +++ b/readthedocs/extra/basic/telegram-client.rst @@ -0,0 +1,99 @@ +.. _telegram-client: + +============== +TelegramClient +============== + + +Introduction +************ + +The ``TelegramClient`` is the central class of the library, the one +you will be using most of the time. For this reason, it's important +to know what it offers. + +Since we're working with Python, one must not forget that we can do +``help(client)`` or ``help(TelegramClient)`` at any time for a more +detailed description and a list of all the available methods. Calling +``help()`` from an interactive Python session will always list all the +methods for any object, even yours! + +Interacting with the Telegram API is done through sending **requests**, +this is, any "method" listed on the API. There are a few methods (and +growing!) on the ``TelegramClient`` class that abstract you from the +need of manually importing the requests you need. + +For instance, retrieving your own user can be done in a single line: + + ``myself = client.get_me()`` + +Internally, this method has sent a request to Telegram, who replied with +the information about your own user, and then the desired information +was extracted from their response. + +If you want to retrieve any other user, chat or channel (channels are a +special subset of chats), you want to retrieve their "entity". This is +how the library refers to either of these: + + .. code-block:: python + + # The method will infer that you've passed an username + # It also accepts phone numbers, and will get the user + # from your contact list. + lonami = client.get_entity('lonami') + +The so called "entities" are another important whole concept on its own, +and you should +Note that saving and using these entities will be more important when +Accessing the Full API. For now, this is a good way to get information +about an user or chat. + +Other common methods for quick scripts are also available: + + .. code-block:: python + + # Sending a message (use an entity/username/etc) + client.send_message('TheAyyBot', 'ayy') + + # Sending a photo, or a file + client.send_file(myself, '/path/to/the/file.jpg', force_document=True) + + # Downloading someone's profile photo. File is saved to 'where' + where = client.download_profile_photo(someone) + + # Retrieving the message history + messages = client.get_message_history(someone) + + # Downloading the media from a specific message + # You can specify either a directory, a filename, or nothing at all + where = client.download_media(message, '/path/to/output') + + # Call .disconnect() when you're done + client.disconnect() + +Remember that you can call ``.stringify()`` to any object Telegram returns +to pretty print it. Calling ``str(result)`` does the same operation, but on +a single line. + + +Available methods +***************** + +This page lists all the "handy" methods available for you to use in the +``TelegramClient`` class. These are simply wrappers around the "raw" +Telegram API, making it much more manageable and easier to work with. + +Please refer to :ref:`accessing-the-full-api` if these aren't enough, +and don't be afraid to read the source code of the InteractiveTelegramClient_ +or even the TelegramClient_ itself to learn how it works. + + +.. _InteractiveTelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon_examples/interactive_telegram_client.py +.. _TelegramClient: https://github.com/LonamiWebs/Telethon/blob/master/telethon/telegram_client.py + + + +.. automodule:: telethon.telegram_client + :members: + :undoc-members: + :show-inheritance: diff --git a/readthedocs/extra/basic/working-with-updates.rst b/readthedocs/extra/basic/working-with-updates.rst index c5d9e919..bb78eb97 100644 --- a/readthedocs/extra/basic/working-with-updates.rst +++ b/readthedocs/extra/basic/working-with-updates.rst @@ -14,23 +14,24 @@ The library can run in four distinguishable modes: - With several worker threads that run your update handlers. - A mix of the above. -Since this section is about updates, we'll describe the simplest way to work with them. - -.. warning:: - Remember that you should always call ``client.disconnect()`` once you're done. +Since this section is about updates, we'll describe the simplest way to +work with them. Using multiple workers -^^^^^^^^^^^^^^^^^^^^^^^ +********************** -When you create your client, simply pass a number to the ``update_workers`` parameter: +When you create your client, simply pass a number to the +``update_workers`` parameter: ``client = TelegramClient('session', api_id, api_hash, update_workers=4)`` -4 workers should suffice for most cases (this is also the default on `Python Telegram Bot`__). -You can set this value to more, or even less if you need. +4 workers should suffice for most cases (this is also the default on +`Python Telegram Bot`__). You can set this value to more, or even less +if you need. -The next thing you want to do is to add a method that will be called when an `Update`__ arrives: +The next thing you want to do is to add a method that will be called when +an `Update`__ arrives: .. code-block:: python @@ -41,7 +42,8 @@ The next thing you want to do is to add a method that will be called when an `Up # do more work here, or simply sleep! That's it! Now let's do something more interesting. -Every time an user talks to use, let's reply to them with the same text reversed: +Every time an user talks to use, let's reply to them with the same +text reversed: .. code-block:: python @@ -56,16 +58,18 @@ Every time an user talks to use, let's reply to them with the same text reversed input('Press enter to stop this!') client.disconnect() -We only ask you one thing: don't keep this running for too long, or your contacts will go mad. +We only ask you one thing: don't keep this running for too long, or your +contacts will go mad. Spawning no worker at all -^^^^^^^^^^^^^^^^^^^^^^^^^^ +************************* -All the workers do is loop forever and poll updates from a queue that is filled from the ``ReadThread``, -responsible for reading every item off the network. -If you only need a worker and the ``MainThread`` would be doing no other job, -this is the preferred way. You can easily do the same as the workers like so: +All the workers do is loop forever and poll updates from a queue that is +filled from the ``ReadThread``, responsible for reading every item off +the network. If you only need a worker and the ``MainThread`` would be +doing no other job, this is the preferred way. You can easily do the same +as the workers like so: .. code-block:: python @@ -81,24 +85,27 @@ this is the preferred way. You can easily do the same as the workers like so: client.disconnect() -Note that ``poll`` accepts a ``timeout=`` parameter, -and it will return ``None`` if other thread got the update before you could or if the timeout expired, -so it's important to check ``if not update``. +Note that ``poll`` accepts a ``timeout=`` parameter, and it will return +``None`` if other thread got the update before you could or if the timeout +expired, so it's important to check ``if not update``. -This can coexist with the rest of ``N`` workers, or you can set it to ``0`` additional workers: +This can coexist with the rest of ``N`` workers, or you can set it to ``0`` +additional workers: ``client = TelegramClient('session', api_id, api_hash, update_workers=0)`` -You **must** set it to ``0`` (or other number), as it defaults to ``None`` and there is a different. -``None`` workers means updates won't be processed *at all*, -so you must set it to some value (0 or greater) if you want ``client.updates.poll()`` to work. +You **must** set it to ``0`` (or other number), as it defaults to ``None`` +and there is a different. ``None`` workers means updates won't be processed +*at all*, so you must set it to some value (``0`` or greater) if you want +``client.updates.poll()`` to work. Using the main thread instead the ``ReadThread`` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +************************************************ -If you have no work to do on the ``MainThread`` and you were planning to have a ``while True: sleep(1)``, -don't do that. Instead, don't spawn the secondary ``ReadThread`` at all like so: +If you have no work to do on the ``MainThread`` and you were planning to have +a ``while True: sleep(1)``, don't do that. Instead, don't spawn the secondary +``ReadThread`` at all like so: .. code-block:: python @@ -111,8 +118,8 @@ And then ``.idle()`` from the ``MainThread``: ``client.idle()`` -You can stop it with :kbd:`Control+C`, -and you can configure the signals to be used in a similar fashion to `Python Telegram Bot`__. +You can stop it with :kbd:`Control+C`, and you can configure the signals +to be used in a similar fashion to `Python Telegram Bot`__. As a complete example: @@ -132,4 +139,4 @@ As a complete example: __ https://python-telegram-bot.org/ __ https://lonamiwebs.github.io/Telethon/types/update.html -__ https://github.com/python-telegram-bot/python-telegram-bot/blob/4b3315db6feebafb94edcaa803df52bb49999ced/telegram/ext/updater.py#L460 \ No newline at end of file +__ https://github.com/python-telegram-bot/python-telegram-bot/blob/4b3315db6feebafb94edcaa803df52bb49999ced/telegram/ext/updater.py#L460 diff --git a/readthedocs/extra/developing/api-status.rst b/readthedocs/extra/developing/api-status.rst new file mode 100644 index 00000000..492340a4 --- /dev/null +++ b/readthedocs/extra/developing/api-status.rst @@ -0,0 +1,54 @@ +========== +API Status +========== + + +In an attempt to help everyone who works with the Telegram API, the +library will by default report all *Remote Procedure Call* errors to +`RPC PWRTelegram `__, a public database +anyone can query, made by `Daniil `__. All the +information sent is a ``GET`` request with the error code, error message +and method used. + +If you still would like to opt out, simply set +``client.session.report_errors = False`` to disable this feature, or +pass ``report_errors=False`` as a named parameter when creating a +``TelegramClient`` instance. However Daniil would really thank you if +you helped him (and everyone) by keeping it on! + +Querying the API status +*********************** + +The API is accessed through ``GET`` requests, which can be made for +instance through ``curl``. A JSON response will be returned. + +**All known errors and their description**: + +.. code:: bash + + curl https://rpc.pwrtelegram.xyz/?all + +**Error codes for a specific request**: + +.. code:: bash + + curl https://rpc.pwrtelegram.xyz/?for=messages.sendMessage + +**Number of** ``RPC_CALL_FAIL``: + +.. code:: bash + + curl https://rpc.pwrtelegram.xyz/?rip # last hour + curl https://rpc.pwrtelegram.xyz/?rip=$(time()-60) # last minute + +**Description of errors**: + +.. code:: bash + + curl https://rpc.pwrtelegram.xyz/?description_for=SESSION_REVOKED + +**Code of a specific error**: + +.. code:: bash + + curl https://rpc.pwrtelegram.xyz/?code_for=STICKERSET_INVALID diff --git a/readthedocs/extra/developing/coding-style.rst b/readthedocs/extra/developing/coding-style.rst new file mode 100644 index 00000000..c629034c --- /dev/null +++ b/readthedocs/extra/developing/coding-style.rst @@ -0,0 +1,22 @@ +============ +Coding Style +============ + + +Basically, make it **readable**, while keeping the style similar to the +code of whatever file you're working on. + +Also note that not everyone has 4K screens for their primary monitors, +so please try to stick to the 80-columns limit. This makes it easy to +``git diff`` changes from a terminal before committing changes. If the +line has to be long, please don't exceed 120 characters. + +For the commit messages, please make them *explanatory*. Not only +they're helpful to troubleshoot when certain issues could have been +introduced, but they're also used to construct the change log once a new +version is ready. + +If you don't know enough Python, I strongly recommend reading `Dive Into +Python 3 `__, available online for +free. For instance, remember to do ``if x is None`` or +``if x is not None`` instead ``if x == None``! diff --git a/readthedocs/extra/developing/philosophy.rst b/readthedocs/extra/developing/philosophy.rst new file mode 100644 index 00000000..f779be2b --- /dev/null +++ b/readthedocs/extra/developing/philosophy.rst @@ -0,0 +1,25 @@ +========== +Philosophy +========== + + +The intention of the library is to have an existing MTProto library +existing with hardly any dependencies (indeed, wherever Python is +available, you can run this library). + +Being written in Python means that performance will be nowhere close to +other implementations written in, for instance, Java, C++, Rust, or +pretty much any other compiled language. However, the library turns out +to actually be pretty decent for common operations such as sending +messages, receiving updates, or other scripting. Uploading files may be +notably slower, but if you would like to contribute, pull requests are +appreciated! + +If ``libssl`` is available on your system, the library will make use of +it to speed up some critical parts such as encrypting and decrypting the +messages. Files will notably be sent and downloaded faster. + +The main focus is to keep everything clean and simple, for everyone to +understand how working with MTProto and Telegram works. Don't be afraid +to read the source, the code won't bite you! It may prove useful when +using the library on your own use cases. diff --git a/readthedocs/extra/developing/project-structure.rst b/readthedocs/extra/developing/project-structure.rst new file mode 100644 index 00000000..d40c6031 --- /dev/null +++ b/readthedocs/extra/developing/project-structure.rst @@ -0,0 +1,43 @@ +================= +Project Structure +================= + + +Main interface +************** + +The library itself is under the ``telethon/`` directory. The +``__init__.py`` file there exposes the main ``TelegramClient``, a class +that servers as a nice interface with the most commonly used methods on +Telegram such as sending messages, retrieving the message history, +handling updates, etc. + +The ``TelegramClient`` inherits the ``TelegramBareClient``. The later is +basically a pruned version of the ``TelegramClient``, which knows basic +stuff like ``.invoke()``\ 'ing requests, downloading files, or switching +between data centers. This is primary to keep the method count per class +and file low and manageable. + +Both clients make use of the ``network/mtproto_sender.py``. The +``MtProtoSender`` class handles packing requests with the ``salt``, +``id``, ``sequence``, etc., and also handles how to process responses +(i.e. pong, RPC errors). This class communicates through Telegram via +its ``.connection`` member. + +The ``Connection`` class uses a ``extensions/tcp_client``, a C#-like +``TcpClient`` to ease working with sockets in Python. All the +``TcpClient`` know is how to connect through TCP and writing/reading +from the socket with optional cancel. + +The ``Connection`` class bundles up all the connections modes and sends +and receives the messages accordingly (TCP full, obfuscated, +intermediate…). + +Auto-generated code +******************* + +The files under ``telethon_generator/`` are used to generate the code +that gets placed under ``telethon/tl/``. The ``TLGenerator`` takes in a +``.tl`` file, and spits out the generated classes which represent, as +Python classes, the request and types defined in the ``.tl`` file. It +also constructs an index so that they can be imported easily. diff --git a/readthedocs/extra/developing/telegram-api-in-other-languages.rst b/readthedocs/extra/developing/telegram-api-in-other-languages.rst new file mode 100644 index 00000000..0adeb988 --- /dev/null +++ b/readthedocs/extra/developing/telegram-api-in-other-languages.rst @@ -0,0 +1,64 @@ +=============================== +Telegram API in Other Languages +=============================== + + +Telethon was made for **Python**, and as far as I know, there is no +*exact* port to other languages. However, there *are* other +implementations made by awesome people (one needs to be awesome to +understand the official Telegram documentation) on several languages +(even more Python too), listed below: + +C +* + +Possibly the most well-known unofficial open source implementation out +there by `**@vysheng** `__, +```tgl`` `__, and its console client +```telegram-cli`` `__. Latest development +has been moved to `BitBucket `__. + +JavaScript +********** + +`**@zerobias** `__ is working on +```telegram-mtproto`` `__, +a work-in-progress JavaScript library installable via +```npm`` `__. + +Kotlin +****** + +`Kotlogram `__ is a Telegram +implementation written in Kotlin (the now +`official `__ +language for +`Android `__) by +`**@badoualy** `__, currently as a beta– +yet working. + +PHP +*** + +A PHP implementation is also available thanks to +`**@danog** `__ and his +`MadelineProto `__ project, with +a very nice `online +documentation `__ too. + +Python +****** + +A fairly new (as of the end of 2017) Telegram library written from the +ground up in Python by +`**@delivrance** `__ and his +`Pyrogram `__ library! No hard +feelings Dan and good luck dealing with some of your users ;) + +Rust +**** + +Yet another work-in-progress implementation, this time for Rust thanks +to `**@JuanPotato** `__ under the fancy +name of `Vail `__. This one is very +early still, but progress is being made at a steady rate. diff --git a/readthedocs/extra/developing/test-servers.rst b/readthedocs/extra/developing/test-servers.rst new file mode 100644 index 00000000..2ba66897 --- /dev/null +++ b/readthedocs/extra/developing/test-servers.rst @@ -0,0 +1,32 @@ +============ +Test Servers +============ + + +To run Telethon on a test server, use the following code: + + .. code-block:: python + + client = TelegramClient(None, api_id, api_hash) + client.session.server_address = '149.154.167.40' + client.connect() + +You can check your ``'test ip'`` on https://my.telegram.org. + +You should set ``None`` session so to ensure you're generating a new +authorization key for it (it would fail if you used a session where you +had previously connected to another data center). + +Once you're connected, you'll likely need to ``.sign_up()``. Remember +`anyone can access the phone you +choose `__, +so don't store sensitive data here: + + .. code-block:: python + + from random import randint + + dc_id = '2' # Change this to the DC id of the test server you chose + phone = '99966' + dc_id + str(randint(9999)).zfill(4) + client.send_code_request(phone) + client.sign_up(dc_id * 5, 'Some', 'Name') diff --git a/readthedocs/extra/developing/tips-for-porting-the-project.rst b/readthedocs/extra/developing/tips-for-porting-the-project.rst new file mode 100644 index 00000000..c7135096 --- /dev/null +++ b/readthedocs/extra/developing/tips-for-porting-the-project.rst @@ -0,0 +1,17 @@ +============================ +Tips for Porting the Project +============================ + + +If you're going to use the code on this repository to guide you, please +be kind and don't forget to mention it helped you! + +You should start by reading the source code on the `first +release `__ of +the project, and start creating a ``MtProtoSender``. Once this is made, +you should write by hand the code to authenticate on the Telegram's +server, which are some steps required to get the key required to talk to +them. Save it somewhere! Then, simply mimic, or reinvent other parts of +the code, and it will be ready to go within a few days. + +Good luck! diff --git a/readthedocs/extra/developing/understanding-the-type-language.rst b/readthedocs/extra/developing/understanding-the-type-language.rst new file mode 100644 index 00000000..c82063ef --- /dev/null +++ b/readthedocs/extra/developing/understanding-the-type-language.rst @@ -0,0 +1,35 @@ +=============================== +Understanding the Type Language +=============================== + + +`Telegram's Type Language `__ +(also known as TL, found on ``.tl`` files) is a concise way to define +what other programming languages commonly call classes or structs. + +Every definition is written as follows for a Telegram object is defined +as follows: + +.. code:: tl + + name#id argument_name:argument_type = CommonType + +This means that in a single line you know what the ``TLObject`` name is. +You know it's unique ID, and you know what arguments it has. It really +isn't that hard to write a generator for generating code to any +platform! + +The generated code should also be able to *encode* the ``TLObject`` (let +this be a request or a type) into bytes, so they can be sent over the +network. This isn't a big deal either, because you know how the +``TLObject``\ 's are made, and how the types should be serialized. + +You can either write your own code generator, or use the one this +library provides, but please be kind and keep some special mention to +this project for helping you out. + +This is only a introduction. The ``TL`` language is not *that* easy. But +it's not that hard either. You're free to sniff the +``telethon_generator/`` files and learn how to parse other more complex +lines, such as ``flags`` (to indicate things that may or may not be +written at all) and ``vector``\ 's. diff --git a/readthedocs/extra/advanced-usage/bots.rst b/readthedocs/extra/examples/bots.rst similarity index 77% rename from readthedocs/extra/advanced-usage/bots.rst rename to readthedocs/extra/examples/bots.rst index 091eada1..b231e200 100644 --- a/readthedocs/extra/advanced-usage/bots.rst +++ b/readthedocs/extra/examples/bots.rst @@ -1,13 +1,14 @@ -====== +==== Bots -====== +==== + Talking to Inline Bots -^^^^^^^^^^^^^^^^^^^^^^ +********************** -You can query an inline bot, such as `@VoteBot`__ -(note, *query*, not *interact* with a voting message), by making use of -the `GetInlineBotResultsRequest`__ request: +You can query an inline bot, such as `@VoteBot`__ (note, *query*, +not *interact* with a voting message), by making use of the +`GetInlineBotResultsRequest`__ request: .. code-block:: python @@ -32,11 +33,10 @@ And you can select any of their results by using Talking to Bots with special reply markup -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +***************************************** To interact with a message that has a special reply markup, such as -`@VoteBot`__ polls, you would use -`GetBotCallbackAnswerRequest`__: +`@VoteBot`__ polls, you would use `GetBotCallbackAnswerRequest`__: .. code-block:: python @@ -48,7 +48,7 @@ To interact with a message that has a special reply markup, such as data=msg.reply_markup.rows[wanted_row].buttons[wanted_button].data )) -It’s a bit verbose, but it has all the information you would need to +It's a bit verbose, but it has all the information you would need to show it visually (button rows, and buttons within each row, each with its own data). @@ -56,4 +56,4 @@ __ https://t.me/vote __ https://lonamiwebs.github.io/Telethon/methods/messages/get_inline_bot_results.html __ https://lonamiwebs.github.io/Telethon/methods/messages/send_inline_bot_result.html __ https://lonamiwebs.github.io/Telethon/methods/messages/get_bot_callback_answer.html -__ https://t.me/vote \ No newline at end of file +__ https://t.me/vote diff --git a/readthedocs/extra/examples/chats-and-channels.rst b/readthedocs/extra/examples/chats-and-channels.rst new file mode 100644 index 00000000..1bafec80 --- /dev/null +++ b/readthedocs/extra/examples/chats-and-channels.rst @@ -0,0 +1,205 @@ +=============================== +Working with Chats and Channels +=============================== + + +Joining a chat or channel +************************* + +Note that `Chat`__\ s are normal groups, and `Channel`__\ s are a +special form of `Chat`__\ s, +which can also be super-groups if their ``megagroup`` member is +``True``. + + +Joining a public channel +************************ + +Once you have the :ref:`entity ` of the channel you want to join +to, you can make use of the `JoinChannelRequest`__ to join such channel: + + .. code-block:: python + + from telethon.tl.functions.channels import JoinChannelRequest + client(JoinChannelRequest(channel)) + + # In the same way, you can also leave such channel + from telethon.tl.functions.channels import LeaveChannelRequest + client(LeaveChannelRequest(input_channel)) + + +For more on channels, check the `channels namespace`__. + + +Joining a private chat or channel +********************************* + +If all you have is a link like this one: +``https://t.me/joinchat/AAAAAFFszQPyPEZ7wgxLtd``, you already have +enough information to join! The part after the +``https://t.me/joinchat/``, this is, ``AAAAAFFszQPyPEZ7wgxLtd`` on this +example, is the ``hash`` of the chat or channel. Now you can use +`ImportChatInviteRequest`__ as follows: + + .. -block:: python + + from telethon.tl.functions.messages import ImportChatInviteRequest + updates = client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg')) + + +Adding someone else to such chat or channel +******************************************* + +If you don't want to add yourself, maybe because you're already in, +you can always add someone else with the `AddChatUserRequest`__, +which use is very straightforward: + + .. code-block:: python + + from telethon.tl.functions.messages import AddChatUserRequest + + client(AddChatUserRequest( + chat_id, + user_to_add, + fwd_limit=10 # allow the user to see the 10 last messages + )) + + +Checking a link without joining +******************************* + +If you don't need to join but rather check whether it's a group or a +channel, you can use the `CheckChatInviteRequest`__, which takes in +the `hash`__ of said channel or group. + +__ https://lonamiwebs.github.io/Telethon/constructors/chat.html +__ https://lonamiwebs.github.io/Telethon/constructors/channel.html +__ https://lonamiwebs.github.io/Telethon/types/chat.html +__ https://lonamiwebs.github.io/Telethon/methods/channels/join_channel.html +__ https://lonamiwebs.github.io/Telethon/methods/channels/index.html +__ https://lonamiwebs.github.io/Telethon/methods/messages/import_chat_invite.html +__ https://lonamiwebs.github.io/Telethon/methods/messages/add_chat_user.html +__ https://lonamiwebs.github.io/Telethon/methods/messages/check_chat_invite.html +__ https://github.com/LonamiWebs/Telethon/wiki/Joining-a-chat-or-channel#joining-a-private-chat-or-channel + + +Retrieving all chat members (channels too) +****************************************** + +In order to get all the members from a mega-group or channel, you need +to use `GetParticipantsRequest`__. As we can see it needs an +`InputChannel`__, (passing the mega-group or channel you're going to +use will work), and a mandatory `ChannelParticipantsFilter`__. The +closest thing to "no filter" is to simply use +`ChannelParticipantsSearch`__ with an empty ``'q'`` string. + +If we want to get *all* the members, we need to use a moving offset and +a fixed limit: + + .. code-block:: python + + from telethon.tl.functions.channels import GetParticipantsRequest + from telethon.tl.types import ChannelParticipantsSearch + from time import sleep + + offset = 0 + limit = 100 + all_participants = [] + + while True: + participants = client.invoke(GetParticipantsRequest( + channel, ChannelParticipantsSearch(''), offset, limit + )) + if not participants.users: + break + all_participants.extend(participants.users) + offset += len(participants.users) + + +Note that ``GetParticipantsRequest`` returns `ChannelParticipants`__, +which may have more information you need (like the role of the +participants, total count of members, etc.) + +__ https://lonamiwebs.github.io/Telethon/methods/channels/get_participants.html +__ https://lonamiwebs.github.io/Telethon/methods/channels/get_participants.html +__ https://lonamiwebs.github.io/Telethon/types/channel_participants_filter.html +__ https://lonamiwebs.github.io/Telethon/constructors/channel_participants_search.html +__ https://lonamiwebs.github.io/Telethon/constructors/channels/channel_participants.html + + +Recent Actions +************** + +"Recent actions" is simply the name official applications have given to +the "admin log". Simply use `GetAdminLogRequest`__ for that, and +you'll get AdminLogResults.events in return which in turn has the final +`.action`__. + +__ https://lonamiwebs.github.io/Telethon/methods/channels/get_admin_log.html +__ https://lonamiwebs.github.io/Telethon/types/channel_admin_log_event_action.html + + +Admin Permissions +***************** + +Giving or revoking admin permissions can be done with the `EditAdminRequest`__: + + .. code-block:: python + + from telethon.tl.functions.channels import EditAdminRequest + from telethon.tl.types import ChannelAdminRights + + # You need both the channel and who to grant permissions + # They can either be channel/user or input channel/input user. + # + # ChannelAdminRights is a list of granted permissions. + # Set to True those you want to give. + rights = ChannelAdminRights( + post_messages=None, + add_admins=None, + invite_users=None, + change_info=True, + ban_users=None, + delete_messages=True, + pin_messages=True, + invite_link=None, + edit_messages=None + ) + + client(EditAdminRequest(channel, who, rights)) + + +Thanks to `@Kyle2142`__ for `pointing out`__ that you **cannot** set +to ``True`` the ``post_messages`` and ``edit_messages`` fields. Those that +are ``None`` can be omitted (left here so you know `which are available`__. + +__ https://lonamiwebs.github.io/Telethon/methods/channels/edit_admin.html +__ https://github.com/Kyle2142 +__ https://github.com/LonamiWebs/Telethon/issues/490 +__ https://lonamiwebs.github.io/Telethon/constructors/channel_admin_rights.html + + +Increasing View Count in a Channel +********************************** + +It has been asked `quite`__ `a few`__ `times`__ (really, `many`__), and +while I don't understand why so many people ask this, the solution is to +use `GetMessagesViewsRequest`__, setting ``increment=True``: + + .. code-block:: python + + + # Obtain `channel' through dialogs or through client.get_entity() or anyhow. + # Obtain `msg_ids' through `.get_message_history()` or anyhow. Must be a list. + + client(GetMessagesViewsRequest( + peer=channel, + id=msg_ids, + increment=True + )) + +__ https://github.com/LonamiWebs/Telethon/issues/233 +__ https://github.com/LonamiWebs/Telethon/issues/305 +__ https://github.com/LonamiWebs/Telethon/issues/409 +__ https://github.com/LonamiWebs/Telethon/issues/447 +__ https://lonamiwebs.github.io/Telethon/methods/messages/get_messages_views.html diff --git a/readthedocs/extra/advanced-usage/working-with-messages.rst b/readthedocs/extra/examples/working-with-messages.rst similarity index 65% rename from readthedocs/extra/advanced-usage/working-with-messages.rst rename to readthedocs/extra/examples/working-with-messages.rst index 2c141406..880bac6f 100644 --- a/readthedocs/extra/advanced-usage/working-with-messages.rst +++ b/readthedocs/extra/examples/working-with-messages.rst @@ -1,20 +1,18 @@ -========================= +===================== Working with messages -========================= - -.. note:: - Make sure you have gone through :ref:`prelude` already! +===================== Forwarding messages ******************* -Note that ForwardMessageRequest_ (note it's Message, singular) will *not* work if channels are involved. -This is because channel (and megagroups) IDs are not unique, so you also need to know who the sender is -(a parameter this request doesn't have). +Note that ForwardMessageRequest_ (note it's Message, singular) will *not* +work if channels are involved. This is because channel (and megagroups) IDs +are not unique, so you also need to know who the sender is (a parameter this +request doesn't have). -Either way, you are encouraged to use ForwardMessagesRequest_ (note it's Message*s*, plural) *always*, -since it is more powerful, as follows: +Either way, you are encouraged to use ForwardMessagesRequest_ (note it's +Message*s*, plural) *always*, since it is more powerful, as follows: .. code-block:: python @@ -31,14 +29,16 @@ since it is more powerful, as follows: to_peer=to_entity # who are we forwarding them to? )) -The named arguments are there for clarity, although they're not needed because they appear in order. -You can obviously just wrap a single message on the list too, if that's all you have. +The named arguments are there for clarity, although they're not needed because +they appear in order. You can obviously just wrap a single message on the list +too, if that's all you have. Searching Messages ******************* -Messages are searched through the obvious SearchRequest_, but you may run into issues_. A valid example would be: +Messages are searched through the obvious SearchRequest_, but you may run +into issues_. A valid example would be: .. code-block:: python @@ -46,27 +46,32 @@ Messages are searched through the obvious SearchRequest_, but you may run into i entity, 'query', InputMessagesFilterEmpty(), None, None, 0, 0, 100 )) -It's important to note that the optional parameter ``from_id`` has been left omitted and thus defaults to ``None``. -Changing it to InputUserEmpty_, as one could think to specify "no user", won't work because this parameter is a flag, +It's important to note that the optional parameter ``from_id`` has been left +omitted and thus defaults to ``None``. Changing it to InputUserEmpty_, as one +could think to specify "no user", won't work because this parameter is a flag, and it being unspecified has a different meaning. -If one were to set ``from_id=InputUserEmpty()``, it would filter messages from "empty" senders, -which would likely match no users. +If one were to set ``from_id=InputUserEmpty()``, it would filter messages +from "empty" senders, which would likely match no users. -If you get a ``ChatAdminRequiredError`` on a channel, it's probably because you tried setting the ``from_id`` filter, -and as the error says, you can't do that. Leave it set to ``None`` and it should work. +If you get a ``ChatAdminRequiredError`` on a channel, it's probably because +you tried setting the ``from_id`` filter, and as the error says, you can't +do that. Leave it set to ``None`` and it should work. -As with every method, make sure you use the right ID/hash combination for your ``InputUser`` or ``InputChat``, -or you'll likely run into errors like ``UserIdInvalidError``. +As with every method, make sure you use the right ID/hash combination for +your ``InputUser`` or ``InputChat``, or you'll likely run into errors like +``UserIdInvalidError``. Sending stickers -***************** +**************** -Stickers are nothing else than ``files``, and when you successfully retrieve the stickers for a certain sticker set, -all you will have are ``handles`` to these files. Remember, the files Telegram holds on their servers can be referenced -through this pair of ID/hash (unique per user), and you need to use this handle when sending a "document" message. -This working example will send yourself the very first sticker you have: +Stickers are nothing else than ``files``, and when you successfully retrieve +the stickers for a certain sticker set, all you will have are ``handles`` to +these files. Remember, the files Telegram holds on their servers can be +referenced through this pair of ID/hash (unique per user), and you need to +use this handle when sending a "document" message. This working example will +send yourself the very first sticker you have: .. code-block:: python diff --git a/readthedocs/extra/troubleshooting/deleted-limited-or-deactivated-accounts.rst b/readthedocs/extra/troubleshooting/deleted-limited-or-deactivated-accounts.rst index 1ad3da19..6426ada9 100644 --- a/readthedocs/extra/troubleshooting/deleted-limited-or-deactivated-accounts.rst +++ b/readthedocs/extra/troubleshooting/deleted-limited-or-deactivated-accounts.rst @@ -1,6 +1,6 @@ -========================================= +======================================== Deleted, Limited or Deactivated Accounts -========================================= +======================================== If you're from Iran or Russian, we have bad news for you. Telegram is much more likely to ban these numbers, @@ -23,4 +23,4 @@ For more discussion, please see `issue 297`__. __ https://t.me/SpamBot -__ https://github.com/LonamiWebs/Telethon/issues/297 \ No newline at end of file +__ https://github.com/LonamiWebs/Telethon/issues/297 diff --git a/readthedocs/extra/troubleshooting/enable-logging.rst b/readthedocs/extra/troubleshooting/enable-logging.rst index a6d45d00..897052e2 100644 --- a/readthedocs/extra/troubleshooting/enable-logging.rst +++ b/readthedocs/extra/troubleshooting/enable-logging.rst @@ -1,15 +1,18 @@ ================ -Enable Logging +Enabling Logging ================ Telethon makes use of the `logging`__ module, and you can enable it as follows: - .. code-block:: python +.. code:: python - import logging - logging.basicConfig(level=logging.DEBUG) + import logging + logging.basicConfig(level=logging.DEBUG) -You can also use it in your own project very easily: +The library has the `NullHandler`__ added by default so that no log calls +will be printed unless you explicitly enable it. + +You can also `use the module`__ on your own project very easily: .. code-block:: python @@ -21,4 +24,17 @@ You can also use it in your own project very easily: logger.warning('This is a warning!') -__ https://docs.python.org/3/library/logging.html \ No newline at end of file +If you want to enable ``logging`` for your project *but* use a different +log level for the library: + + .. code-block:: python + + import logging + logging.basicConfig(level=logging.DEBUG) + # For instance, show only warnings and above + logging.getLogger('telethon').setLevel(level=logging.WARNING) + + +__ https://docs.python.org/3/library/logging.html +__ https://docs.python.org/3/howto/logging.html#configuring-logging-for-a-library +__ https://docs.python.org/3/howto/logging.html diff --git a/readthedocs/extra/troubleshooting/rpc-errors.rst b/readthedocs/extra/troubleshooting/rpc-errors.rst index 6e8a59f0..55a21d7b 100644 --- a/readthedocs/extra/troubleshooting/rpc-errors.rst +++ b/readthedocs/extra/troubleshooting/rpc-errors.rst @@ -3,17 +3,17 @@ RPC Errors ========== RPC stands for Remote Procedure Call, and when Telethon raises an -``RPCError``, it’s most likely because you have invoked some of the API +``RPCError``, it's most likely because you have invoked some of the API methods incorrectly (wrong parameters, wrong permissions, or even -something went wrong on Telegram’s server). The most common are: +something went wrong on Telegram's server). The most common are: -- ``FloodError`` (420), the same request was repeated many times. Must - wait ``.seconds``. +- ``FloodWaitError`` (420), the same request was repeated many times. + Must wait ``.seconds`` (you can access this parameter). - ``SessionPasswordNeededError``, if you have setup two-steps verification on Telegram. - ``CdnFileTamperedError``, if the media you were trying to download from a CDN has been altered. -- ``ChatAdminRequiredError``, you don’t have permissions to perform +- ``ChatAdminRequiredError``, you don't have permissions to perform said operation on a chat or channel. Try avoiding filters, i.e. when searching messages. @@ -22,6 +22,6 @@ The generic classes for different error codes are: \* ``InvalidDCError`` ``BadRequestError`` (400), the request contained errors. \* ``UnauthorizedError`` (401), the user is not authorized yet. \* ``ForbiddenError`` (403), privacy violation error. \* ``NotFoundError`` -(404), make sure you’re invoking ``Request``\ ’s! +(404), make sure you're invoking ``Request``\ 's! -If the error is not recognised, it will only be an ``RPCError``. \ No newline at end of file +If the error is not recognised, it will only be an ``RPCError``. diff --git a/readthedocs/extra/wall-of-shame.rst b/readthedocs/extra/wall-of-shame.rst new file mode 100644 index 00000000..95ad3e04 --- /dev/null +++ b/readthedocs/extra/wall-of-shame.rst @@ -0,0 +1,62 @@ +============= +Wall of Shame +============= + + +This project has an +`issues `__ section for +you to file **issues** whenever you encounter any when working with the +library. Said section is **not** for issues on *your* program but rather +issues with Telethon itself. + +If you have not made the effort to 1. `read through the +wiki `__ and 2. `look for +the method you need `__, you +will end up on the `Wall of +Shame `__, +i.e. all issues labeled +`"RTFM" `__: + +> > **rtfm** +> > Literally "Read The F\ **king Manual"; a term showing the +frustration of being bothered with questions so trivial that the asker +could have quickly figured out the answer on their own with minimal +effort, usually by reading readily-available documents. People who +say"RTFM!" might be considered rude, but the true rude ones are the +annoying people who take absolutely no self-responibility and expect to +have all the answers handed to them personally. +> > *"Damn, that's the twelveth time that somebody posted this question +to the messageboard today! RTFM, already!"* +> > **\ by Bill M. July 27, 2004*\* + +If you have indeed read the wiki, and have tried looking for the method, +and yet you didn't find what you need, **that's fine**. Telegram's API +can have some obscure names at times, and for this reason, there is a +`"question" +label `__ +with questions that are okay to ask. Just state what you've tried so +that we know you've made an effort, or you'll go to the Wall of Shame. + +Of course, if the issue you're going to open is not even a question but +a real issue with the library (thankfully, most of the issues have been +that!), you won't end up here. Don't worry. + +Current winner +-------------- + +The current winner is `issue +213 `__: + +**Issue:** + + .. figure:: https://user-images.githubusercontent.com/6297805/29822978-9a9a6ef0-8ccd-11e7-9ec5-934ea0f57681.jpg + :alt: Winner issue + + Winner issue + +**Answer:** + + .. figure:: https://user-images.githubusercontent.com/6297805/29822983-9d523402-8ccd-11e7-9fb1-5783740ee366.jpg + :alt: Winner issue answer + + Winner issue answer diff --git a/readthedocs/index.rst b/readthedocs/index.rst index b5c77e6b..8e5c6053 100644 --- a/readthedocs/index.rst +++ b/readthedocs/index.rst @@ -3,11 +3,14 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +==================================== Welcome to Telethon's documentation! ==================================== -Pure Python 3 Telegram client library. Official Site `here `_. +Pure Python 3 Telegram client library. +Official Site `here `_. +Please follow the links below to get you started. .. _installation-and-usage: @@ -19,10 +22,9 @@ Pure Python 3 Telegram client library. Official Site `here = 2 and argv[1] == 'pypi': + # (Re)generate the code to make sure we don't push without it + gen_tl() + + # Try importing the telethon module to assert it has no errors + try: + import telethon + except: + print('Packaging for PyPi aborted, importing the module failed.') + return + # Need python3.5 or higher, but Telethon is supposed to support 3.x # Place it here since noone should be running ./setup.py pypi anyway from subprocess import run diff --git a/telethon/crypto/__init__.py b/telethon/crypto/__init__.py index d151a96c..aa470adf 100644 --- a/telethon/crypto/__init__.py +++ b/telethon/crypto/__init__.py @@ -1,3 +1,8 @@ +""" +This module contains several utilities regarding cryptographic purposes, +such as the AES IGE mode used by Telegram, the authorization key bound with +their data centers, and so on. +""" from .aes import AES from .aes_ctr import AESModeCTR from .auth_key import AuthKey diff --git a/telethon/crypto/aes.py b/telethon/crypto/aes.py index c09add56..191cde15 100644 --- a/telethon/crypto/aes.py +++ b/telethon/crypto/aes.py @@ -1,3 +1,6 @@ +""" +AES IGE implementation in Python. This module may use libssl if available. +""" import os import pyaes from . import libssl @@ -9,10 +12,15 @@ if libssl.AES is not None: else: # Fallback to a pure Python implementation class AES: + """ + Class that servers as an interface to encrypt and decrypt + text through the AES IGE mode. + """ @staticmethod def decrypt_ige(cipher_text, key, iv): - """Decrypts the given text in 16-bytes blocks by using the - given key and 32-bytes initialization vector + """ + Decrypts the given text in 16-bytes blocks by using the + given key and 32-bytes initialization vector. """ iv1 = iv[:len(iv) // 2] iv2 = iv[len(iv) // 2:] @@ -42,8 +50,9 @@ else: @staticmethod def encrypt_ige(plain_text, key, iv): - """Encrypts the given text in 16-bytes blocks by using the - given key and 32-bytes initialization vector + """ + Encrypts the given text in 16-bytes blocks by using the + given key and 32-bytes initialization vector. """ # Add random padding iff it's not evenly divisible by 16 already diff --git a/telethon/crypto/aes_ctr.py b/telethon/crypto/aes_ctr.py index 7bd7b79a..34422904 100644 --- a/telethon/crypto/aes_ctr.py +++ b/telethon/crypto/aes_ctr.py @@ -1,3 +1,6 @@ +""" +This module holds the AESModeCTR wrapper class. +""" import pyaes @@ -6,6 +9,12 @@ class AESModeCTR: # TODO Maybe make a pull request to pyaes to support iv on CTR def __init__(self, key, iv): + """ + Initializes the AES CTR mode with the given key/iv pair. + + :param key: the key to be used as bytes. + :param iv: the bytes initialization vector. Must have a length of 16. + """ # TODO Use libssl if available assert isinstance(key, bytes) self._aes = pyaes.AESModeOfOperationCTR(key) @@ -15,7 +24,19 @@ class AESModeCTR: self._aes._counter._counter = list(iv) def encrypt(self, data): + """ + Encrypts the given plain text through AES CTR. + + :param data: the plain text to be encrypted. + :return: the encrypted cipher text. + """ return self._aes.encrypt(data) def decrypt(self, data): + """ + Decrypts the given cipher text through AES CTR + + :param data: the cipher text to be decrypted. + :return: the decrypted plain text. + """ return self._aes.decrypt(data) diff --git a/telethon/crypto/auth_key.py b/telethon/crypto/auth_key.py index 17a7f8ca..679e62ff 100644 --- a/telethon/crypto/auth_key.py +++ b/telethon/crypto/auth_key.py @@ -1,3 +1,6 @@ +""" +This module holds the AuthKey class. +""" import struct from hashlib import sha1 @@ -6,7 +9,16 @@ from ..extensions import BinaryReader class AuthKey: + """ + Represents an authorization key, used to encrypt and decrypt + messages sent to Telegram's data centers. + """ def __init__(self, data): + """ + Initializes a new authorization key. + + :param data: the data in bytes that represent this auth key. + """ self.key = data with BinaryReader(sha1(self.key).digest()) as reader: @@ -15,8 +27,12 @@ class AuthKey: self.key_id = reader.read_long(signed=False) def calc_new_nonce_hash(self, new_nonce, number): - """Calculates the new nonce hash based on - the current class fields' values + """ + Calculates the new nonce hash based on the current attributes. + + :param new_nonce: the new nonce to be hashed. + :param number: number to prepend before the hash. + :return: the hash for the given new nonce. """ new_nonce = new_nonce.to_bytes(32, 'little', signed=True) data = new_nonce + struct.pack(' 'y!'. + """ + Gets the inner text that's surrounded by the given entity or entities. + For instance: text = 'hey!', entity = MessageEntityBold(2, 2) -> 'y!'. + + :param text: the original text. + :param entity: the entity or entities that must be matched. + :return: a single result or a list of the text surrounded by the entities. """ if isinstance(entity, TLObject): entity = (entity,) diff --git a/telethon/extensions/tcp_client.py b/telethon/extensions/tcp_client.py index 94de544d..a705555b 100644 --- a/telethon/extensions/tcp_client.py +++ b/telethon/extensions/tcp_client.py @@ -1,3 +1,6 @@ +""" +This module holds a rough implementation of the C# TCP client. +""" # Python rough implementation of a C# TCP client import asyncio import errno @@ -13,7 +16,14 @@ CONN_RESET_ERRNOS = { class TcpClient: + """A simple TCP client to ease the work with sockets and proxies.""" def __init__(self, proxy=None, timeout=timedelta(seconds=5), loop=None): + """ + Initializes the TCP client. + + :param proxy: the proxy to be used, if any. + :param timeout: the timeout for connect, read and write operations. + """ self.proxy = proxy self._socket = None self._loop = loop if loop else asyncio.get_event_loop() @@ -23,7 +33,7 @@ class TcpClient: elif isinstance(timeout, (int, float)): self.timeout = float(timeout) else: - raise ValueError('Invalid timeout type', type(timeout)) + raise TypeError('Invalid timeout type: {}'.format(type(timeout))) def _recreate_socket(self, mode): if self.proxy is None: @@ -39,8 +49,11 @@ class TcpClient: self._socket.setblocking(False) async def connect(self, ip, port): - """Connects to the specified IP and port number. - 'timeout' must be given in seconds + """ + Tries connecting forever to IP:port unless an OSError is raised. + + :param ip: the IP to connect to. + :param port: the port to connect to. """ if ':' in ip: # IPv6 # The address needs to be surrounded by [] as discussed on PR#425 @@ -78,12 +91,13 @@ class TcpClient: raise def _get_connected(self): + """Determines whether the client is connected or not.""" return self._socket is not None and self._socket.fileno() >= 0 connected = property(fget=_get_connected) def close(self): - """Closes the connection""" + """Closes the connection.""" try: if self._socket is not None: self._socket.shutdown(socket.SHUT_RDWR) @@ -94,7 +108,11 @@ class TcpClient: self._socket = None async def write(self, data): - """Writes (sends) the specified bytes to the connected peer""" + """ + Writes (sends) the specified bytes to the connected peer. + + :param data: the data to send. + """ if self._socket is None: self._raise_connection_reset() @@ -106,7 +124,7 @@ class TcpClient: ) except asyncio.TimeoutError as e: raise TimeoutError() from e - except BrokenPipeError: + except ConnectionError: self._raise_connection_reset() except OSError as e: if e.errno in CONN_RESET_ERRNOS: @@ -115,8 +133,11 @@ class TcpClient: raise async def read(self, size): - """Reads (receives) a whole block of 'size bytes - from the connected peer. + """ + Reads (receives) a whole block of size bytes from the connected peer. + + :param size: the size of the block to be read. + :return: the read data with len(data) == size. """ with BufferedWriter(BytesIO(), buffer_size=size) as buffer: @@ -132,6 +153,8 @@ class TcpClient: ) except asyncio.TimeoutError as e: raise TimeoutError() from e + except ConnectionError: + self._raise_connection_reset() except OSError as e: if e.errno in CONN_RESET_ERRNOS: self._raise_connection_reset() @@ -149,6 +172,7 @@ class TcpClient: return buffer.raw.getvalue() def _raise_connection_reset(self): + """Disconnects the client and raises ConnectionResetError.""" self.close() # Connection reset -> flag as socket closed raise ConnectionResetError('The server has closed the connection.') diff --git a/telethon/network/__init__.py b/telethon/network/__init__.py index 77bd4406..d2538924 100644 --- a/telethon/network/__init__.py +++ b/telethon/network/__init__.py @@ -1,3 +1,7 @@ +""" +This module contains several classes regarding network, low level connection +with Telegram's servers and the protocol used (TCP full, abridged, etc.). +""" from .mtproto_plain_sender import MtProtoPlainSender from .authenticator import do_authentication from .mtproto_sender import MtProtoSender diff --git a/telethon/network/authenticator.py b/telethon/network/authenticator.py index e56e4c44..65d6e357 100644 --- a/telethon/network/authenticator.py +++ b/telethon/network/authenticator.py @@ -1,3 +1,7 @@ +""" +This module contains several functions that authenticate the client machine +with Telegram's servers, effectively creating an authorization key. +""" import os import time from hashlib import sha1 @@ -18,6 +22,14 @@ from ..tl.functions import ( async def do_authentication(connection, retries=5): + """ + Performs the authentication steps on the given connection. + Raises an error if all attempts fail. + + :param connection: the connection to be used (must be connected). + :param retries: how many times should we retry on failure. + :return: + """ if not retries or retries < 0: retries = 1 @@ -32,9 +44,11 @@ async def do_authentication(connection, retries=5): async def _do_authentication(connection): - """Executes the authentication process with the Telegram servers. - If no error is raised, returns both the authorization key and the - time offset. + """ + Executes the authentication process with the Telegram servers. + + :param connection: the connection to be used (must be connected). + :return: returns a (authorization key, time offset) tuple. """ sender = MtProtoPlainSender(connection) @@ -195,8 +209,12 @@ async def _do_authentication(connection): def get_int(byte_array, signed=True): - """Gets the specified integer from its byte array. - This should be used by the authenticator, - who requires the data to be in big endian + """ + Gets the specified integer from its byte array. + This should be used by this module alone, as it works with big endian. + + :param byte_array: the byte array representing th integer. + :param signed: whether the number is signed or not. + :return: the integer representing the given byte array. """ return int.from_bytes(byte_array, byteorder='big', signed=signed) diff --git a/telethon/network/connection.py b/telethon/network/connection.py index 9ffdd453..afd1e878 100644 --- a/telethon/network/connection.py +++ b/telethon/network/connection.py @@ -1,3 +1,7 @@ +""" +This module holds both the Connection class and the ConnectionMode enum, +which specifies the protocol to be used by the Connection. +""" import errno import os import struct @@ -34,16 +38,24 @@ class ConnectionMode(Enum): class Connection: - """Represents an abstract connection (TCP, TCP abridged...). - 'mode' must be any of the ConnectionMode enumeration. + """ + Represents an abstract connection (TCP, TCP abridged...). + 'mode' must be any of the ConnectionMode enumeration. - Note that '.send()' and '.recv()' refer to messages, which - will be packed accordingly, whereas '.write()' and '.read()' - work on plain bytes, with no further additions. + Note that '.send()' and '.recv()' refer to messages, which + will be packed accordingly, whereas '.write()' and '.read()' + work on plain bytes, with no further additions. """ def __init__(self, mode=ConnectionMode.TCP_FULL, proxy=None, timeout=timedelta(seconds=5), loop=None): + """ + Initializes a new connection. + + :param mode: the ConnectionMode to be used. + :param proxy: whether to use a proxy or not. + :param timeout: timeout to be used for all operations. + """ self._mode = mode self._send_counter = 0 self._aes_encrypt, self._aes_decrypt = None, None @@ -74,6 +86,12 @@ class Connection: setattr(self, 'read', self._read_plain) async def connect(self, ip, port): + """ + Estabilishes a connection to IP:port. + + :param ip: the IP to connect to. + :param port: the port to connect to. + """ try: await self.conn.connect(ip, port) except OSError as e: @@ -91,9 +109,13 @@ class Connection: await self._setup_obfuscation() def get_timeout(self): + """Returns the timeout used by the connection.""" return self.conn.timeout async def _setup_obfuscation(self): + """ + Sets up the obfuscated protocol. + """ # Obfuscated messages secrets cannot start with any of these keywords = (b'PVrG', b'GET ', b'POST', b'\xee' * 4) while True: @@ -121,13 +143,19 @@ class Connection: await self.conn.write(bytes(random)) def is_connected(self): + """ + Determines whether the connection is alive or not. + + :return: true if it's connected. + """ return self.conn.connected def close(self): + """Closes the connection.""" self.conn.close() def clone(self): - """Creates a copy of this Connection""" + """Creates a copy of this Connection.""" return Connection( mode=self._mode, proxy=self.conn.proxy, timeout=self.conn.timeout ) @@ -140,6 +168,15 @@ class Connection: raise ValueError('Invalid connection mode specified: ' + str(self._mode)) async def _recv_tcp_full(self): + """ + Receives a message from the network, + internally encoded using the TCP full protocol. + + May raise InvalidChecksumError if the received data doesn't + match its valid checksum. + + :return: the read message payload. + """ # TODO We don't want another call to this method that could # potentially await on another self.read(n). Is this guaranteed # by asyncio? @@ -156,9 +193,21 @@ class Connection: return body async def _recv_intermediate(self): + """ + Receives a message from the network, + internally encoded using the TCP intermediate protocol. + + :return: the read message payload. + """ return await self.read(struct.unpack('= 127: length = struct.unpack('> 2 if length < 127: length = struct.pack('B', length) @@ -203,9 +270,21 @@ class Connection: raise ValueError('Invalid connection mode specified: ' + str(self._mode)) async def _read_plain(self, length): + """ + Reads data from the socket connection. + + :param length: how many bytes should be read. + :return: a byte sequence with len(data) == length + """ return await self.conn.read(length) async def _read_obfuscated(self, length): + """ + Reads data and decrypts from the socket connection. + + :param length: how many bytes should be read. + :return: the decrypted byte sequence with len(data) == length + """ return self._aes_decrypt.encrypt(await self.conn.read(length)) # endregion @@ -216,9 +295,20 @@ class Connection: raise ValueError('Invalid connection mode specified: ' + str(self._mode)) async def _write_plain(self, data): + """ + Writes the given data through the socket connection. + + :param data: the data in bytes to be written. + """ await self.conn.write(data) async def _write_obfuscated(self, data): + """ + Writes the given data through the socket connection, + using the obfuscated mode (AES encryption is applied on top). + + :param data: the data in bytes to be written. + """ await self.conn.write(self._aes_encrypt.encrypt(data)) # endregion diff --git a/telethon/network/mtproto_plain_sender.py b/telethon/network/mtproto_plain_sender.py index 9089a72d..004d571d 100644 --- a/telethon/network/mtproto_plain_sender.py +++ b/telethon/network/mtproto_plain_sender.py @@ -1,3 +1,7 @@ +""" +This module contains the class used to communicate with Telegram's servers +in plain text, when no authorization key has been created yet. +""" import struct import time @@ -6,32 +10,47 @@ from ..extensions import BinaryReader class MtProtoPlainSender: - """MTProto Mobile Protocol plain sender - (https://core.telegram.org/mtproto/description#unencrypted-messages) + """ + MTProto Mobile Protocol plain sender + (https://core.telegram.org/mtproto/description#unencrypted-messages) """ def __init__(self, connection): + """ + Initializes the MTProto plain sender. + + :param connection: the Connection to be used. + """ self._sequence = 0 self._time_offset = 0 self._last_msg_id = 0 self._connection = connection async def connect(self): + """Connects to Telegram's servers.""" await self._connection.connect() def disconnect(self): + """Disconnects from Telegram's servers.""" self._connection.close() async def send(self, data): - """Sends a plain packet (auth_key_id = 0) containing the - given message body (data) + """ + Sends a plain packet (auth_key_id = 0) containing the + given message body (data). + + :param data: the data to be sent. """ await self._connection.send( struct.pack(' self.session.flood_sleep_threshold | 0: raise - self._logger.debug( - 'Sleep of %d seconds below threshold, sleeping' % e.seconds - ) await asyncio.sleep(e.seconds, loop=self._loop) return None @@ -540,6 +562,9 @@ class TelegramBareClient: part_size_kb = get_appropriated_part_size(file_size) file_name = os.path.basename(file_path) """ + if isinstance(file, (InputFile, InputFileBig)): + return file # Already uploaded + if isinstance(file, str): file_size = os.path.getsize(file) elif isinstance(file, bytes): @@ -548,6 +573,7 @@ class TelegramBareClient: file = file.read() file_size = len(file) + # File will now either be a string or bytes if not part_size_kb: part_size_kb = get_appropriated_part_size(file_size) @@ -558,16 +584,40 @@ class TelegramBareClient: if part_size % 1024 != 0: raise ValueError('The part size must be evenly divisible by 1024') + # Set a default file name if None was specified + file_id = utils.generate_random_long() + if not file_name: + if isinstance(file, str): + file_name = os.path.basename(file) + else: + file_name = str(file_id) + # Determine whether the file is too big (over 10MB) or not # Telegram does make a distinction between smaller or larger files is_large = file_size > 10 * 1024 * 1024 + if not is_large: + # Calculate the MD5 hash before anything else. + # As this needs to be done always for small files, + # might as well do it before anything else and + # check the cache. + if isinstance(file, str): + with open(file, 'rb') as stream: + file = stream.read() + hash_md5 = md5(file) + tuple_ = self.session.get_file(hash_md5.digest(), file_size) + if tuple_: + __log__.info('File was already cached, not uploading again') + return InputFile(name=file_name, + md5_checksum=tuple_[0], id=tuple_[2], parts=tuple_[3]) + else: + hash_md5 = None + part_count = (file_size + part_size - 1) // part_size + __log__.info('Uploading file of %d bytes in %d chunks of %d', + file_size, part_count, part_size) - file_id = utils.generate_random_long() - hash_md5 = md5() - - stream = open(file, 'rb') if isinstance(file, str) else BytesIO(file) - try: + with open(file, 'rb') if isinstance(file, str) else BytesIO(file) \ + as stream: for part_index in range(part_count): # Read the file by in chunks of size part_size part = stream.read(part_size) @@ -582,28 +632,19 @@ class TelegramBareClient: result = await self(request) if result: - if not is_large: - # No need to update the hash if it's a large file - hash_md5.update(part) - + __log__.debug('Uploaded %d/%d', part_index + 1, part_count) if progress_callback: progress_callback(stream.tell(), file_size) else: - raise ValueError('Failed to upload file part {}.' - .format(part_index)) - finally: - stream.close() - - # Set a default file name if None was specified - if not file_name: - if isinstance(file, str): - file_name = os.path.basename(file) - else: - file_name = str(file_id) + raise RuntimeError( + 'Failed to upload file part {}.'.format(part_index)) if is_large: return InputFileBig(file_id, part_count, file_name) else: + self.session.cache_file( + hash_md5.digest(), file_size, file_id, part_count) + return InputFile(file_id, part_count, file_name, md5_checksum=hash_md5.hexdigest()) @@ -650,6 +691,7 @@ class TelegramBareClient: client = self cdn_decrypter = None + __log__.info('Downloading file in chunks of %d bytes', part_size) try: offset = 0 while True: @@ -662,6 +704,7 @@ class TelegramBareClient: )) if isinstance(result, FileCdnRedirect): + __log__.info('File lives in a CDN') cdn_decrypter, result = \ await CdnDecrypter.prepare_decrypter( client, @@ -670,6 +713,7 @@ class TelegramBareClient: ) except FileMigrateError as e: + __log__.info('File lives in another DC') client = await self._get_exported_client(e.new_dc) continue @@ -682,6 +726,7 @@ class TelegramBareClient: return getattr(result, 'type', '') f.write(result.bytes) + __log__.debug('Saved %d more bytes', len(result.bytes)) if progress_callback: progress_callback(f.tell(), file_size) finally: @@ -736,28 +781,30 @@ class TelegramBareClient: self._ping_loop = None async def _recv_loop_impl(self): + __log__.info('Starting to wait for items from the network') need_reconnect = False while self._user_connected: try: if need_reconnect: + __log__.info('Attempting reconnection from read loop') need_reconnect = False while self._user_connected and not await self._reconnect(): # Retry forever, this is instant messaging await asyncio.sleep(0.1, loop=self._loop) + __log__.debug('Receiving items from the network...') await self._sender.receive(update_state=self.updates) except TimeoutError: # No problem. - pass + __log__.info('Receiving items from the network timed out') except ConnectionError as error: - self._logger.debug(error) need_reconnect = True + __log__.error('Connection was reset while receiving items') await asyncio.sleep(1, loop=self._loop) except Exception as error: # Unknown exception, pass it to the main thread - self._logger.exception( - 'Unknown error on the read loop, please report.' - ) + __log__.exception('Unknown exception in the read thread! ' + 'Disconnecting and leaving it to main thread') try: import socks diff --git a/telethon/telegram_client.py b/telethon/telegram_client.py index 094c92d6..5d1431e4 100644 --- a/telethon/telegram_client.py +++ b/telethon/telegram_client.py @@ -1,5 +1,7 @@ +import itertools import os import time +from collections import OrderedDict, UserList from datetime import datetime, timedelta from mimetypes import guess_type @@ -13,13 +15,12 @@ except ImportError: from . import TelegramBareClient from . import helpers, utils from .errors import ( - RPCError, UnauthorizedError, InvalidParameterError, PhoneCodeEmptyError, - PhoneCodeExpiredError, PhoneCodeHashEmptyError, PhoneCodeInvalidError + RPCError, UnauthorizedError, PhoneCodeEmptyError, PhoneCodeExpiredError, + PhoneCodeHashEmptyError, PhoneCodeInvalidError, LocationInvalidError ) from .network import ConnectionMode from .tl import TLObject -from .tl.custom import Draft -from .tl.entity_database import EntityDatabase +from .tl.custom import Draft, Dialog from .tl.functions.account import ( GetPasswordRequest ) @@ -31,7 +32,7 @@ from .tl.functions.contacts import ( GetContactsRequest, ResolveUsernameRequest ) from .tl.functions.messages import ( - GetDialogsRequest, GetHistoryRequest, ReadHistoryRequest, SendMediaRequest, + GetDialogsRequest, GetHistoryRequest, SendMediaRequest, SendMessageRequest, GetChatsRequest, GetAllDraftsRequest, CheckChatInviteRequest ) @@ -43,7 +44,7 @@ from .tl.functions.users import ( GetUsersRequest ) from .tl.functions.channels import ( - GetChannelsRequest + GetChannelsRequest, GetFullChannelRequest ) from .tl.types import ( DocumentAttributeAudio, DocumentAttributeFilename, @@ -53,14 +54,74 @@ from .tl.types import ( InputUserSelf, UserProfilePhoto, ChatPhoto, UpdateMessageID, UpdateNewChannelMessage, UpdateNewMessage, UpdateShortSentMessage, PeerUser, InputPeerUser, InputPeerChat, InputPeerChannel, MessageEmpty, - ChatInvite, ChatInviteAlready, PeerChannel + ChatInvite, ChatInviteAlready, PeerChannel, Photo ) from .tl.types.messages import DialogsSlice from .extensions import markdown class TelegramClient(TelegramBareClient): - """Full featured TelegramClient meant to extend the basic functionality""" + """ + Initializes the Telegram client with the specified API ID and Hash. + + Args: + session (:obj:`str` | :obj:`Session` | :obj:`None`): + The file name of the session file to be used if a string is + given (it may be a full path), or the Session instance to be + used otherwise. If it's ``None``, the session will not be saved, + and you should call :meth:`.log_out()` when you're done. + + api_id (:obj:`int` | :obj:`str`): + The API ID you obtained from https://my.telegram.org. + + api_hash (:obj:`str`): + The API ID you obtained from https://my.telegram.org. + + connection_mode (:obj:`ConnectionMode`, optional): + The connection mode to be used when creating a new connection + to the servers. Defaults to the ``TCP_FULL`` mode. + This will only affect how messages are sent over the network + and how much processing is required before sending them. + + use_ipv6 (:obj:`bool`, optional): + Whether to connect to the servers through IPv6 or not. + By default this is ``False`` as IPv6 support is not + too widespread yet. + + proxy (:obj:`tuple` | :obj:`dict`, optional): + A tuple consisting of ``(socks.SOCKS5, 'host', port)``. + See https://github.com/Anorov/PySocks#usage-1 for more. + + update_workers (:obj:`int`, optional): + If specified, represents how many extra threads should + be spawned to handle incoming updates, and updates will + be kept in memory until they are processed. Note that + you must set this to at least ``0`` if you want to be + able to process updates through :meth:`updates.poll()`. + + timeout (:obj:`int` | :obj:`float` | :obj:`timedelta`, optional): + The timeout to be used when receiving responses from + the network. Defaults to 5 seconds. + + spawn_read_thread (:obj:`bool`, optional): + Whether to use an extra background thread or not. Defaults + to ``True`` so receiving items from the network happens + instantly, as soon as they arrive. Can still be disabled + if you want to run the library without any additional thread. + + Kwargs: + Extra parameters will be forwarded to the ``Session`` file. + Most relevant parameters are: + + .. code-block:: python + + device_model = platform.node() + system_version = platform.system() + app_version = TelegramClient.__version__ + lang_code = 'en' + system_lang_code = lang_code + report_errors = True + """ # region Initialization @@ -71,26 +132,6 @@ class TelegramClient(TelegramBareClient): timeout=timedelta(seconds=5), loop=None, **kwargs): - """Initializes the Telegram client with the specified API ID and Hash. - - Session can either be a `str` object (filename for the .session) - or it can be a `Session` instance (in which case list_sessions() - would probably not work). Pass 'None' for it to be a temporary - session - remember to '.log_out()'! - - The 'connection_mode' should be any value under ConnectionMode. - This will only affect how messages are sent over the network - and how much processing is required before sending them. - - If more named arguments are provided as **kwargs, they will be - used to update the Session instance. Most common settings are: - device_model = platform.node() - system_version = platform.system() - app_version = TelegramClient.__version__ - lang_code = 'en' - system_lang_code = lang_code - report_errors = True - """ super().__init__( session, api_id, api_hash, connection_mode=connection_mode, @@ -112,59 +153,71 @@ class TelegramClient(TelegramBareClient): # region Authorization requests async def send_code_request(self, phone, force_sms=False): - """Sends a code request to the specified phone number. + """ + Sends a code request to the specified phone number. - :param str | int phone: - The phone to which the code will be sent. - :param bool force_sms: - Whether to force sending as SMS. You should call it at least - once before without this set to True first. - :return auth.SentCode: + Args: + phone (:obj:`str` | :obj:`int`): + The phone to which the code will be sent. + + force_sms (:obj:`bool`, optional): + Whether to force sending as SMS. + + Returns: Information about the result of the request. """ - phone = EntityDatabase.parse_phone(phone) or self._phone - if force_sms: - if not self._phone_code_hash: - raise ValueError( - 'You must call this method without force_sms at least once.' - ) - result = await self(ResendCodeRequest(phone, self._phone_code_hash)) - else: + phone = utils.parse_phone(phone) or self._phone + + if not self._phone_code_hash: result = await self(SendCodeRequest(phone, self.api_id, self.api_hash)) self._phone_code_hash = result.phone_code_hash + else: + force_sms = True self._phone = phone + + if force_sms: + result = await self(ResendCodeRequest(phone, self._phone_code_hash)) + self._phone_code_hash = result.phone_code_hash + return result async def sign_in(self, phone=None, code=None, - password=None, bot_token=None, phone_code_hash=None): + password=None, bot_token=None, phone_code_hash=None): """ Starts or completes the sign in process with the given phone number or code that Telegram sent. - :param str | int phone: - The phone to send the code to if no code was provided, or to - override the phone that was previously used with these requests. - :param str | int code: - The code that Telegram sent. - :param str password: - 2FA password, should be used if a previous call raised - SessionPasswordNeededError. - :param str bot_token: - Used to sign in as a bot. Not all requests will be available. - This should be the hash the @BotFather gave you. - :param str phone_code_hash: - The hash returned by .send_code_request. This can be set to None - to use the last hash known. + Args: + phone (:obj:`str` | :obj:`int`): + The phone to send the code to if no code was provided, + or to override the phone that was previously used with + these requests. - :return auth.SentCode | User: - The signed in user, or the information about .send_code_request(). + code (:obj:`str` | :obj:`int`): + The code that Telegram sent. + + password (:obj:`str`): + 2FA password, should be used if a previous call raised + SessionPasswordNeededError. + + bot_token (:obj:`str`): + Used to sign in as a bot. Not all requests will be available. + This should be the hash the @BotFather gave you. + + phone_code_hash (:obj:`str`): + The hash returned by .send_code_request. This can be set to None + to use the last hash known. + + Returns: + The signed in user, or the information about + :meth:`.send_code_request()`. """ if phone and not code: return await self.send_code_request(phone) elif code: - phone = EntityDatabase.parse_phone(phone) or self._phone + phone = utils.parse_phone(phone) or self._phone phone_code_hash = phone_code_hash or self._phone_code_hash if not phone: raise ValueError( @@ -206,10 +259,18 @@ class TelegramClient(TelegramBareClient): Signs up to Telegram if you don't have an account yet. You must call .send_code_request(phone) first. - :param str | int code: The code sent by Telegram - :param str first_name: The first name to be used by the new account. - :param str last_name: Optional last name. - :return User: The new created user. + Args: + code (:obj:`str` | :obj:`int`): + The code sent by Telegram + + first_name (:obj:`str`): + The first name to be used by the new account. + + last_name (:obj:`str`, optional) + Optional last name. + + Returns: + The new created user. """ result = await self(SignUpRequest( phone_number=self._phone, @@ -223,9 +284,11 @@ class TelegramClient(TelegramBareClient): return result.user async def log_out(self): - """Logs out Telegram and deletes the current *.session file. + """ + Logs out Telegram and deletes the current *.session file. - :return bool: True if the operation was successful. + Returns: + True if the operation was successful. """ try: await self(LogOutRequest()) @@ -242,7 +305,8 @@ class TelegramClient(TelegramBareClient): Gets "me" (the self user) which is currently authenticated, or None if the request fails (hence, not authenticated). - :return User: Your own user. + Returns: + Your own user. """ try: return (await self(GetUsersRequest([InputUserSelf()])))[0] @@ -253,34 +317,46 @@ class TelegramClient(TelegramBareClient): # region Dialogs ("chats") requests - async def get_dialogs(self, - limit=10, - offset_date=None, - offset_id=0, - offset_peer=InputPeerEmpty()): + async def get_dialogs(self, limit=10, offset_date=None, offset_id=0, + offset_peer=InputPeerEmpty()): """ Gets N "dialogs" (open "chats" or conversations with other people). - :param limit: - How many dialogs to be retrieved as maximum. Can be set to None - to retrieve all dialogs. Note that this may take whole minutes - if you have hundreds of dialogs, as Telegram will tell the library - to slow down through a FloodWaitError. - :param offset_date: - The offset date to be used. - :param offset_id: - The message ID to be used as an offset. - :param offset_peer: - The peer to be used as an offset. - :return: A tuple of lists ([dialogs], [entities]). + Args: + limit (:obj:`int` | :obj:`None`): + How many dialogs to be retrieved as maximum. Can be set to + ``None`` to retrieve all dialogs. Note that this may take + whole minutes if you have hundreds of dialogs, as Telegram + will tell the library to slow down through a + ``FloodWaitError``. + + offset_date (:obj:`datetime`, optional): + The offset date to be used. + + offset_id (:obj:`int`, optional): + The message ID to be used as an offset. + + offset_peer (:obj:`InputPeer`, optional): + The peer to be used as an offset. + + Returns: + A list dialogs, with an additional .total attribute on the list. """ limit = float('inf') if limit is None else int(limit) if limit == 0: - return [], [] + # Special case, get a single dialog and determine count + dialogs = await self(GetDialogsRequest( + offset_date=offset_date, + offset_id=offset_id, + offset_peer=offset_peer, + limit=1 + )) + result = UserList() + result.total = getattr(dialogs, 'count', len(dialogs.dialogs)) + return result - dialogs = {} # Use peer id as identifier to avoid dupes - messages = {} # Used later for sorting TODO also return these? - entities = {} + total_count = 0 + dialogs = OrderedDict() # Use peer id as identifier to avoid dupes while len(dialogs) < limit: real_limit = min(limit - len(dialogs), 100) r = await self(GetDialogsRequest( @@ -290,16 +366,14 @@ class TelegramClient(TelegramBareClient): limit=real_limit )) - for d in r.dialogs: - dialogs[utils.get_peer_id(d.peer, True)] = d - for m in r.messages: - messages[m.id] = m + total_count = getattr(r, 'count', len(r.dialogs)) + messages = {m.id: m for m in r.messages} + entities = {utils.get_peer_id(x): x + for x in itertools.chain(r.users, r.chats)} - # We assume users can't have the same ID as a chat - for u in r.users: - entities[u.id] = u - for c in r.chats: - entities[c.id] = c + for d in r.dialogs: + dialogs[utils.get_peer_id(d.peer)] = \ + Dialog(self, d, entities, messages) if len(r.dialogs) < real_limit or not isinstance(r, DialogsSlice): # Less than we requested means we reached the end, or @@ -307,35 +381,23 @@ class TelegramClient(TelegramBareClient): break offset_date = r.messages[-1].date - offset_peer = utils.find_user_or_chat( - r.dialogs[-1].peer, entities, entities - ) + offset_peer = entities[utils.get_peer_id(r.dialogs[-1].peer)] offset_id = r.messages[-1].id & 4294967296 # Telegram/danog magic - # Sort by message date. Windows will raise if timestamp is 0, - # so we need to set at least one day ahead while still being - # the smallest date possible. - no_date = datetime.fromtimestamp(86400) - ds = list(sorted( - dialogs.values(), - key=lambda d: getattr(messages[d.top_message], 'date', no_date) - )) - if limit < float('inf'): - ds = ds[:limit] - return ( - ds, - [utils.find_user_or_chat(d.peer, entities, entities) for d in ds] + dialogs = UserList( + itertools.islice(dialogs.values(), min(limit, len(dialogs))) ) + dialogs.total = total_count + return dialogs async def get_drafts(self): # TODO: Ability to provide a `filter` """ Gets all open draft messages. - Returns a list of custom `Draft` objects that are easy to work with: - You can call `draft.set_message('text')` to change the message, - or delete it through `draft.delete()`. - - :return List[telethon.tl.custom.Draft]: A list of open drafts + Returns: + A list of custom ``Draft`` objects that are easy to work with: + You can call :meth:`draft.set_message('text')` to change the message, + or delete it through :meth:`draft.delete()`. """ response = await self(GetAllDraftsRequest()) self.session.process_entities(response) @@ -343,28 +405,48 @@ class TelegramClient(TelegramBareClient): drafts = [Draft._from_update(self, u) for u in response.updates] return drafts - async def send_message(self, - entity, - message, - reply_to=None, - parse_mode=None, - link_preview=True): + @staticmethod + def _get_response_message(request, result): + """Extracts the response message known a request and Update result""" + # Telegram seems to send updateMessageID first, then updateNewMessage, + # however let's not rely on that just in case. + msg_id = None + for update in result.updates: + if isinstance(update, UpdateMessageID): + if update.random_id == request.random_id: + msg_id = update.id + break + + for update in result.updates: + if isinstance(update, (UpdateNewChannelMessage, UpdateNewMessage)): + if update.message.id == msg_id: + return update.message + + async def send_message(self, entity, message, reply_to=None, + parse_mode=None, link_preview=True): """ Sends the given message to the specified entity (user/chat/channel). - :param str | int | User | Chat | Channel entity: - To who will it be sent. - :param str message: - The message to be sent. - :param int | Message reply_to: - Whether to reply to a message or not. - :param str parse_mode: - Can be 'md' or 'markdown' for markdown-like parsing, in a similar - fashion how official clients work. - :param link_preview: - Should the link preview be shown? + Args: + entity (:obj:`entity`): + To who will it be sent. - :return Message: the sent message + message (:obj:`str`): + The message to be sent. + + reply_to (:obj:`int` | :obj:`Message`, optional): + Whether to reply to a message or not. If an integer is provided, + it should be the ID of the message that it should reply to. + + parse_mode (:obj:`str`, optional): + Can be 'md' or 'markdown' for markdown-like parsing, in a similar + fashion how official clients work. + + link_preview (:obj:`bool`, optional): + Should the link preview be shown? + + Returns: + the sent message """ entity = await self.get_input_entity(entity) if parse_mode: @@ -372,7 +454,7 @@ class TelegramClient(TelegramBareClient): if parse_mode in {'md', 'markdown'}: message, msg_entities = markdown.parse(message) else: - raise ValueError('Unknown parsing mode', parse_mode) + raise ValueError('Unknown parsing mode: {}'.format(parse_mode)) else: msg_entities = [] @@ -396,39 +478,29 @@ class TelegramClient(TelegramBareClient): entities=result.entities ) - # Telegram seems to send updateMessageID first, then updateNewMessage, - # however let's not rely on that just in case. - msg_id = None - for update in result.updates: - if isinstance(update, UpdateMessageID): - if update.random_id == request.random_id: - msg_id = update.id - break - - for update in result.updates: - if isinstance(update, (UpdateNewChannelMessage, UpdateNewMessage)): - if update.message.id == msg_id: - return update.message - - return None # Should not happen + return self._get_response_message(request, result) async def delete_messages(self, entity, message_ids, revoke=True): """ - Deletes a message from a chat, optionally "for everyone" with argument - `revoke` set to `True`. + Deletes a message from a chat, optionally "for everyone". - The `revoke` argument has no effect for Channels and Megagroups, - where it inherently behaves as being `True`. + Args: + entity (:obj:`entity`): + From who the message will be deleted. This can actually + be ``None`` for normal chats, but **must** be present + for channels and megagroups. - Note: The `entity` argument can be `None` for normal chats, but it's - mandatory to delete messages from Channels and Megagroups. It is also - possible to supply a chat_id which will be automatically resolved to - the right type of InputPeer. + message_ids (:obj:`list` | :obj:`int` | :obj:`Message`): + The IDs (or ID) or messages to be deleted. - :param entity: ID or Entity of the chat - :param list message_ids: ID(s) or `Message` object(s) of the message(s) to delete - :param revoke: Delete the message for everyone or just this client - :returns .messages.AffectedMessages: Messages affected by deletion. + revoke (:obj:`bool`, optional): + Whether the message should be deleted for everyone or not. + By default it has the opposite behaviour of official clients, + and it will delete the message for everyone. + This has no effect on channels or megagroups. + + Returns: + The affected messages. """ if not isinstance(message_ids, list): @@ -445,41 +517,51 @@ class TelegramClient(TelegramBareClient): else: return await self(messages.DeleteMessagesRequest(message_ids, revoke=revoke)) - async def get_message_history(self, - entity, - limit=20, - offset_date=None, - offset_id=0, - max_id=0, - min_id=0, - add_offset=0): + async def get_message_history(self, entity, limit=20, offset_date=None, + offset_id=0, max_id=0, min_id=0, + add_offset=0): """ Gets the message history for the specified entity - :param entity: - The entity from whom to retrieve the message history. - :param limit: - Number of messages to be retrieved. Due to limitations with the API - retrieving more than 3000 messages will take longer than half a - minute (or even more based on previous calls). The limit may also - be None, which would eventually return the whole history. - :param offset_date: - Offset date (messages *previous* to this date will be retrieved). - :param offset_id: - Offset message ID (only messages *previous* to the given ID will - be retrieved). - :param max_id: - All the messages with a higher (newer) ID or equal to this will - be excluded - :param min_id: - All the messages with a lower (older) ID or equal to this will - be excluded. - :param add_offset: - Additional message offset - (all of the specified offsets + this offset = older messages). + Args: + entity (:obj:`entity`): + The entity from whom to retrieve the message history. - :return: A tuple containing total message count and two more lists ([messages], [senders]). - Note that the sender can be null if it was not found! + limit (:obj:`int` | :obj:`None`, optional): + Number of messages to be retrieved. Due to limitations with + the API retrieving more than 3000 messages will take longer + than half a minute (or even more based on previous calls). + The limit may also be ``None``, which would eventually return + the whole history. + + offset_date (:obj:`datetime`): + Offset date (messages *previous* to this date will be + retrieved). Exclusive. + + offset_id (:obj:`int`): + Offset message ID (only messages *previous* to the given + ID will be retrieved). Exclusive. + + max_id (:obj:`int`): + All the messages with a higher (newer) ID or equal to this will + be excluded + + min_id (:obj:`int`): + All the messages with a lower (older) ID or equal to this will + be excluded. + + add_offset (:obj:`int`): + Additional message offset (all of the specified offsets + + this offset = older messages). + + Returns: + A list of messages with extra attributes: + + * ``.total`` = (on the list) total amount of messages sent. + * ``.sender`` = entity of the sender. + * ``.fwd_from.sender`` = if fwd_from, who sent it originally. + * ``.fwd_from.channel`` = if fwd_from, original channel. + * ``.to`` = entity to which the message was sent. """ entity = await self.get_input_entity(entity) limit = float('inf') if limit is None else int(limit) @@ -492,7 +574,7 @@ class TelegramClient(TelegramBareClient): return getattr(result, 'count', len(result.messages)), [], [] total_messages = 0 - messages = [] + messages = UserList() entities = {} while len(messages) < limit: # Telegram has a hard limit of 100 @@ -504,7 +586,8 @@ class TelegramClient(TelegramBareClient): offset_id=offset_id, max_id=max_id, min_id=min_id, - add_offset=add_offset + add_offset=add_offset, + hash=0 )) messages.extend( m for m in result.messages if not isinstance(m, MessageEmpty) @@ -514,9 +597,9 @@ class TelegramClient(TelegramBareClient): # TODO We can potentially use self.session.database, but since # it might be disabled, use a local dictionary. for u in result.users: - entities[utils.get_peer_id(u, add_mark=True)] = u + entities[utils.get_peer_id(u)] = u for c in result.chats: - entities[utils.get_peer_id(c, add_mark=True)] = c + entities[utils.get_peer_id(c)] = c if len(result.messages) < real_limit: break @@ -531,51 +614,60 @@ class TelegramClient(TelegramBareClient): if limit > 3000: await asyncio.sleep(1, loop=self._loop) - # In a new list with the same length as the messages append - # their senders, so people can zip(messages, senders). - senders = [] + # Add a few extra attributes to the Message to make it friendlier. + messages.total = total_messages for m in messages: - if m.from_id: - who = entities[utils.get_peer_id(m.from_id, add_mark=True)] - elif getattr(m, 'fwd_from', None): - # .from_id is optional, so this is the sanest fallback. - who = entities[utils.get_peer_id( - m.fwd_from.from_id or PeerChannel(m.fwd_from.channel_id), - add_mark=True - )] - else: - # If there's not even a FwdHeader, fallback to the sender - # being where the message was sent. - who = entities[utils.get_peer_id(m.to_id, add_mark=True)] - senders.append(who) + # TODO Better way to return a total without tuples? + m.sender = (None if not m.from_id else + entities[utils.get_peer_id(m.from_id)]) - return total_messages, messages, senders + if getattr(m, 'fwd_from', None): + m.fwd_from.sender = ( + None if not m.fwd_from.from_id else + entities[utils.get_peer_id(m.fwd_from.from_id)] + ) + m.fwd_from.channel = ( + None if not m.fwd_from.channel_id else + entities[utils.get_peer_id( + PeerChannel(m.fwd_from.channel_id) + )] + ) - async def send_read_acknowledge(self, entity, messages=None, max_id=None): + m.to = entities[utils.get_peer_id(m.to_id)] + + return messages + + async def send_read_acknowledge(self, entity, message=None, max_id=None): """ Sends a "read acknowledge" (i.e., notifying the given peer that we've read their messages, also known as the "double check"). - :param entity: The chat where these messages are located. - :param messages: Either a list of messages or a single message. - :param max_id: Overrides messages, until which message should the - acknowledge should be sent. - :return: + Args: + entity (:obj:`entity`): + The chat where these messages are located. + + message (:obj:`list` | :obj:`Message`): + Either a list of messages or a single message. + + max_id (:obj:`int`): + Overrides messages, until which message should the + acknowledge should be sent. """ if max_id is None: if not messages: - raise InvalidParameterError( + raise ValueError( 'Either a message list or a max_id must be provided.') - if isinstance(messages, list): - max_id = max(msg.id for msg in messages) + if hasattr(message, '__iter__'): + max_id = max(msg.id for msg in message) else: - max_id = messages.id + max_id = message.id - return await self(ReadHistoryRequest( - peer=await self.get_input_entity(entity), - max_id=max_id - )) + entity = await self.get_input_entity(entity) + if entity == InputPeerChannel: + return await self(channels.ReadHistoryRequest(entity, max_id=max_id)) + else: + return await self(messages.ReadHistoryRequest(entity, max_id=max_id)) @staticmethod def _get_reply_to(reply_to): @@ -591,7 +683,7 @@ class TelegramClient(TelegramBareClient): # hex(crc32(b'Message')) = 0x790009e3 return reply_to.id - raise ValueError('Invalid reply_to type: ', type(reply_to)) + raise TypeError('Invalid reply_to type: {}'.format(type(reply_to))) # endregion @@ -601,37 +693,52 @@ class TelegramClient(TelegramBareClient): force_document=False, progress_callback=None, reply_to=None, attributes=None, + thumb=None, **kwargs): """ Sends a file to the specified entity. - :param entity: - Who will receive the file. - :param file: - The path of the file, byte array, or stream that will be sent. - Note that if a byte array or a stream is given, a filename - or its type won't be inferred, and it will be sent as an - "unnamed application/octet-stream". + Args: + entity (:obj:`entity`): + Who will receive the file. - Subsequent calls with the very same file will result in - immediate uploads, unless .clear_file_cache() is called. - :param caption: - Optional caption for the sent media message. - :param force_document: - If left to False and the file is a path that ends with .png, .jpg - and such, the file will be sent as a photo. Otherwise always as - a document. - :param progress_callback: - A callback function accepting two parameters: (sent bytes, total) - :param reply_to: - Same as reply_to from .send_message(). - :param attributes: - Optional attributes that override the inferred ones, like - DocumentAttributeFilename and so on. - :param kwargs: + file (:obj:`str` | :obj:`bytes` | :obj:`file`): + The path of the file, byte array, or stream that will be sent. + Note that if a byte array or a stream is given, a filename + or its type won't be inferred, and it will be sent as an + "unnamed application/octet-stream". + + Subsequent calls with the very same file will result in + immediate uploads, unless ``.clear_file_cache()`` is called. + + caption (:obj:`str`, optional): + Optional caption for the sent media message. + + force_document (:obj:`bool`, optional): + If left to ``False`` and the file is a path that ends with + ``.png``, ``.jpg`` and such, the file will be sent as a photo. + Otherwise always as a document. + + progress_callback (:obj:`callable`, optional): + A callback function accepting two parameters: + ``(sent bytes, total)``. + + reply_to (:obj:`int` | :obj:`Message`): + Same as reply_to from .send_message(). + + attributes (:obj:`list`, optional): + Optional attributes that override the inferred ones, like + ``DocumentAttributeFilename`` and so on. + + thumb (:obj:`str` | :obj:`bytes` | :obj:`file`): + Optional thumbnail (for videos). + + Kwargs: If "is_voice_note" in kwargs, despite its value, and the file is sent as a document, it will be sent as a voice note. - :return: + + Returns: + The message containing the sent file. """ as_photo = False if isinstance(file, str): @@ -641,13 +748,9 @@ class TelegramClient(TelegramBareClient): for ext in ('.png', '.jpg', '.gif', '.jpeg') ) - file_hash = hash(file) - if file_hash in self._upload_cache: - file_handle = self._upload_cache[file_hash] - else: - self._upload_cache[file_hash] = file_handle = await self.upload_file( - file, progress_callback=progress_callback - ) + file_handle = await self.upload_file( + file, progress_callback=progress_callback + ) if as_photo and not force_document: media = InputMediaUploadedPhoto(file_handle, caption) @@ -686,20 +789,28 @@ class TelegramClient(TelegramBareClient): if not mime_type: mime_type = 'application/octet-stream' + input_kw = {} + if thumb: + input_kw['thumb'] = await self.upload_file(thumb) + media = InputMediaUploadedDocument( file=file_handle, mime_type=mime_type, attributes=list(attr_dict.values()), - caption=caption + caption=caption, + **input_kw ) # Once the media type is properly specified and the file uploaded, # send the media message to the desired entity. - await self(SendMediaRequest( + request = SendMediaRequest( peer=await self.get_input_entity(entity), media=media, reply_to_msg_id=self._get_reply_to(reply_to) - )) + ) + result = await self(request) + + return self._get_response_message(request, result) async def send_voice_note(self, entity, file, caption='', upload_progress=None, reply_to=None): @@ -709,14 +820,6 @@ class TelegramClient(TelegramBareClient): reply_to=reply_to, is_voice_note=()) # empty tuple is enough - def clear_file_cache(self): - """Calls to .send_file() will cache the remote location of the - uploaded files so that subsequent files can be immediate, so - uploading the same file path will result in using the cached - version. To avoid this a call to this method should be made. - """ - self._upload_cache.clear() - # endregion # region Downloading media requests @@ -725,17 +828,22 @@ class TelegramClient(TelegramBareClient): """ Downloads the profile photo of the given entity (user/chat/channel). - :param entity: - From who the photo will be downloaded. - :param file: - The output file path, directory, or stream-like object. - If the path exists and is a file, it will be overwritten. - :param download_big: - Whether to use the big version of the available photos. - :return: - None if no photo was provided, or if it was Empty. On success + Args: + entity (:obj:`entity`): + From who the photo will be downloaded. + + file (:obj:`str` | :obj:`file`, optional): + The output file path, directory, or stream-like object. + If the path exists and is a file, it will be overwritten. + + download_big (:obj:`bool`, optional): + Whether to use the big version of the available photos. + + Returns: + ``None`` if no photo was provided, or if it was Empty. On success the file path is returned since it may differ from the one given. """ + photo = entity possible_names = [] if not isinstance(entity, TLObject) or type(entity).SUBCLASS_OF_ID in ( 0x2da17977, 0xc5af5d94, 0x1f4661b9, 0xd49a2697 @@ -761,44 +869,61 @@ class TelegramClient(TelegramBareClient): for attr in ('username', 'first_name', 'title'): possible_names.append(getattr(entity, attr, None)) - entity = entity.photo + photo = entity.photo - if not isinstance(entity, UserProfilePhoto) and \ - not isinstance(entity, ChatPhoto): + if not isinstance(photo, UserProfilePhoto) and \ + not isinstance(photo, ChatPhoto): return None - if download_big: - photo_location = entity.photo_big - else: - photo_location = entity.photo_small - + photo_location = photo.photo_big if download_big else photo.photo_small file = self._get_proper_filename( file, 'profile_photo', '.jpg', possible_names=possible_names ) # Download the media with the largest size input file location - await self.download_file( - InputFileLocation( - volume_id=photo_location.volume_id, - local_id=photo_location.local_id, - secret=photo_location.secret - ), - file - ) + try: + await self.download_file( + InputFileLocation( + volume_id=photo_location.volume_id, + local_id=photo_location.local_id, + secret=photo_location.secret + ), + file + ) + except LocationInvalidError: + # See issue #500, Android app fails as of v4.6.0 (1155). + # The fix seems to be using the full channel chat photo. + ie = await self.get_input_entity(entity) + if isinstance(ie, InputPeerChannel): + full = await self(GetFullChannelRequest(ie)) + return await self._download_photo( + full.full_chat.chat_photo, file, + date=None, progress_callback=None + ) + else: + # Until there's a report for chats, no need to. + return None return file async def download_media(self, message, file=None, progress_callback=None): """ Downloads the given media, or the media from a specified Message. - :param message: + + message (:obj:`Message` | :obj:`Media`): The media or message containing the media that will be downloaded. - :param file: + + file (:obj:`str` | :obj:`file`, optional): The output file path, directory, or stream-like object. If the path exists and is a file, it will be overwritten. - :param progress_callback: - A callback function accepting two parameters: (recv bytes, total) - :return: + + progress_callback (:obj:`callable`, optional): + A callback function accepting two parameters: + ``(recv bytes, total)``. + + Returns: + ``None`` if no media was provided, or if it was Empty. On success + the file path is returned since it may differ from the one given. """ # TODO This won't work for messageService if isinstance(message, Message): @@ -808,7 +933,7 @@ class TelegramClient(TelegramBareClient): date = datetime.now() media = message - if isinstance(media, MessageMediaPhoto): + if isinstance(media, (MessageMediaPhoto, Photo)): return await self._download_photo( media, file, date, progress_callback ) @@ -821,11 +946,15 @@ class TelegramClient(TelegramBareClient): media, file ) - async def _download_photo(self, mm_photo, file, date, progress_callback): + async def _download_photo(self, photo, file, date, progress_callback): """Specialized version of .download_media() for photos""" # Determine the photo and its largest size - photo = mm_photo.photo + if isinstance(photo, MessageMediaPhoto): + photo = photo.photo + if not isinstance(photo, Photo): + return + largest_size = photo.sizes[-1] file_size = largest_size.size largest_size = largest_size.location @@ -947,6 +1076,8 @@ class TelegramClient(TelegramBareClient): name = None if not name: + if not date: + date = datetime.now() name = '{}_{}-{:02}-{:02}_{:02}-{:02}-{:02}'.format( kind, date.year, date.month, date.day, @@ -976,12 +1107,12 @@ class TelegramClient(TelegramBareClient): # region Small utilities to make users' life easier - async def get_entity(self, entity, force_fetch=False): + async def get_entity(self, entity): """ Turns the given entity into a valid Telegram user or chat. - :param entity: - The entity to be transformed. + entity (:obj:`str` | :obj:`int` | :obj:`Peer` | :obj:`InputPeer`): + The entity (or iterable of entities) to be transformed. If it's a string which can be converted to an integer or starts with '+' it will be resolved as if it were a phone number. @@ -995,58 +1126,75 @@ class TelegramClient(TelegramBareClient): If the entity is neither, and it's not a TLObject, an error will be raised. - :param force_fetch: - If True, the entity cache is bypassed and the entity is fetched - again with an API call. Defaults to False to avoid unnecessary - calls, but since a cached version would be returned, the entity - may be out of date. - :return: + Returns: + ``User``, ``Chat`` or ``Channel`` corresponding to the input + entity. """ - if not force_fetch: - # Try to use cache unless we want to force a fetch - try: - return self.session.entities[entity] - except KeyError: - pass + if not isinstance(entity, str) and hasattr(entity, '__iter__'): + single = False + else: + single = True + entity = (entity,) - if isinstance(entity, int) or ( - isinstance(entity, TLObject) and - # crc32(b'InputPeer') and crc32(b'Peer') - type(entity).SUBCLASS_OF_ID in (0xc91c90b6, 0x2d45687)): - ie = await self.get_input_entity(entity) - if isinstance(ie, InputPeerUser): - await self(GetUsersRequest([ie])) - elif isinstance(ie, InputPeerChat): - await self(GetChatsRequest([ie.chat_id])) - elif isinstance(ie, InputPeerChannel): - await self(GetChannelsRequest([ie])) - try: - # session.process_entities has been called in the MtProtoSender - # with the result of these calls, so they should now be on the - # entities database. - return self.session.entities[ie] - except KeyError: - pass + # Group input entities by string (resolve username), + # input users (get users), input chat (get chats) and + # input channels (get channels) to get the most entities + # in the less amount of calls possible. + inputs = [ + x if isinstance(x, str) else await self.get_input_entity(x) + for x in entity + ] + users = [x for x in inputs if isinstance(x, InputPeerUser)] + chats = [x.chat_id for x in inputs if isinstance(x, InputPeerChat)] + channels = [x for x in inputs if isinstance(x, InputPeerChannel)] + if users: + # GetUsersRequest has a limit of 200 per call + tmp = [] + while users: + curr, users = users[:200], users[200:] + tmp.extend(await self(GetUsersRequest(curr))) + users = tmp + if chats: # TODO Handle chats slice? + chats = (await self(GetChatsRequest(chats))).chats + if channels: + channels = (await self(GetChannelsRequest(channels))).chats - if isinstance(entity, str): - return await self._get_entity_from_string(entity) + # Merge users, chats and channels into a single dictionary + id_entity = { + utils.get_peer_id(x): x + for x in itertools.chain(users, chats, channels) + } - raise ValueError( - 'Cannot turn "{}" into any entity (user or chat)'.format(entity) - ) + # We could check saved usernames and put them into the users, + # chats and channels list from before. While this would reduce + # the amount of ResolveUsername calls, it would fail to catch + # username changes. + result = [ + await self._get_entity_from_string(x) if isinstance(x, str) + else id_entity[utils.get_peer_id(x)] + for x in inputs + ] + return result[0] if single else result async def _get_entity_from_string(self, string): - """Gets an entity from the given string, which may be a phone or - an username, and processes all the found entities on the session. """ - phone = EntityDatabase.parse_phone(string) + Gets a full entity from the given string, which may be a phone or + an username, and processes all the found entities on the session. + The string may also be a user link, or a channel/chat invite link. + This method has the side effect of adding the found users to the + session database, so it can be queried later without API calls, + if this option is enabled on the session. + Returns the found entity, or raises TypeError if not found. + """ + phone = utils.parse_phone(string) if phone: - entity = phone - await self(GetContactsRequest(0)) + for user in (await self(GetContactsRequest(0))).users: + if user.phone == phone: + return user else: - entity, is_join_chat = EntityDatabase.parse_username(string) + string, is_join_chat = utils.parse_username(string) if is_join_chat: - invite = await self(CheckChatInviteRequest(entity)) + invite = await self(CheckChatInviteRequest(string)) if isinstance(invite, ChatInvite): # If it's an invite to a chat, the user must join before # for the link to be resolved and work, otherwise raise. @@ -1055,39 +1203,36 @@ class TelegramClient(TelegramBareClient): elif isinstance(invite, ChatInviteAlready): return invite.chat else: - await self(ResolveUsernameRequest(entity)) - # MtProtoSender will call .process_entities on the requests made + result = await self(ResolveUsernameRequest(string)) + for entity in itertools.chain(result.users, result.chats): + if entity.username.lower() == string: + return entity - try: - return self.session.entities[entity] - except KeyError: - raise ValueError( - 'Could not find user with username {}'.format(entity) - ) + raise TypeError( + 'Cannot turn "{}" into any entity (user or chat)'.format(string) + ) async def get_input_entity(self, peer): """ Turns the given peer into its input entity version. Most requests use this kind of InputUser, InputChat and so on, so this is the most suitable call to make for those cases. - - :param peer: + entity (:obj:`str` | :obj:`int` | :obj:`Peer` | :obj:`InputPeer`): The integer ID of an user or otherwise either of a - PeerUser, PeerChat or PeerChannel, for which to get its - Input* version. - - If this Peer hasn't been seen before by the library, the top + ``PeerUser``, ``PeerChat`` or ``PeerChannel``, for + which to get its ``Input*`` version. + If this ``Peer`` hasn't been seen before by the library, the top dialogs will be loaded and their entities saved to the session file (unless this feature was disabled explicitly). - If in the end the access hash required for the peer was not found, a ValueError will be raised. - :return: + Returns: + ``InputPeerUser``, ``InputPeerChat`` or ``InputPeerChannel``. """ try: # First try to get the entity from cache, otherwise figure it out - return self.session.entities.get_input_entity(peer) - except KeyError: + return self.session.get_input_entity(peer) + except ValueError: pass if isinstance(peer, str): @@ -1103,32 +1248,32 @@ class TelegramClient(TelegramBareClient): if not is_peer: try: return utils.get_input_peer(peer) - except ValueError: + except TypeError: pass if not is_peer: - raise ValueError( + raise TypeError( 'Cannot turn "{}" into an input entity.'.format(peer) ) - if self.session.save_entities: - # Not found, look in the latest dialogs. - # This is useful if for instance someone just sent a message but - # the updates didn't specify who, as this person or chat should - # be in the latest dialogs. - await self(GetDialogsRequest( - offset_date=None, - offset_id=0, - offset_peer=InputPeerEmpty(), - limit=0, - exclude_pinned=True - )) - try: - return self.session.entities.get_input_entity(peer) - except KeyError: - pass + # Not found, look in the latest dialogs. + # This is useful if for instance someone just sent a message but + # the updates didn't specify who, as this person or chat should + # be in the latest dialogs. + dialogs = await self(GetDialogsRequest( + offset_date=None, + offset_id=0, + offset_peer=InputPeerEmpty(), + limit=0, + exclude_pinned=True + )) - raise ValueError( + target = utils.get_peer_id(peer) + for entity in itertools.chain(dialogs.users, dialogs.chats): + if utils.get_peer_id(entity) == target: + return utils.get_input_peer(entity) + + raise TypeError( 'Could not find the input entity corresponding to "{}".' 'Make sure you have encountered this peer before.'.format(peer) ) diff --git a/telethon/tl/custom/__init__.py b/telethon/tl/custom/__init__.py index 40914f16..5b6bf44d 100644 --- a/telethon/tl/custom/__init__.py +++ b/telethon/tl/custom/__init__.py @@ -1 +1,2 @@ from .draft import Draft +from .dialog import Dialog diff --git a/telethon/tl/custom/dialog.py b/telethon/tl/custom/dialog.py new file mode 100644 index 00000000..2cce89a3 --- /dev/null +++ b/telethon/tl/custom/dialog.py @@ -0,0 +1,37 @@ +from . import Draft +from ... import utils + + +class Dialog: + """ + Custom class that encapsulates a dialog (an open "conversation" with + someone, a group or a channel) providing an abstraction to easily + access the input version/normal entity/message etc. The library will + return instances of this class when calling `client.get_dialogs()`. + """ + def __init__(self, client, dialog, entities, messages): + # Both entities and messages being dicts {ID: item} + self._client = client + self.dialog = dialog + self.pinned = bool(dialog.pinned) + self.message = messages.get(dialog.top_message, None) + self.date = getattr(self.message, 'date', None) + + self.entity = entities[utils.get_peer_id(dialog.peer)] + self.input_entity = utils.get_input_peer(self.entity) + self.name = utils.get_display_name(self.entity) + + self.unread_count = dialog.unread_count + self.unread_mentions_count = dialog.unread_mentions_count + + if dialog.draft: + self.draft = Draft(client, dialog.peer, dialog.draft) + else: + self.draft = None + + async def send_message(self, *args, **kwargs): + """ + Sends a message to this dialog. This is just a wrapper around + client.send_message(dialog.input_entity, *args, **kwargs). + """ + return await self._client.send_message(self.input_entity, *args, **kwargs) diff --git a/telethon/tl/custom/draft.py b/telethon/tl/custom/draft.py index c50baa78..c3e354fc 100644 --- a/telethon/tl/custom/draft.py +++ b/telethon/tl/custom/draft.py @@ -21,7 +21,7 @@ class Draft: @classmethod def _from_update(cls, client, update): if not isinstance(update, UpdateDraftMessage): - raise ValueError( + raise TypeError( 'You can only create a new `Draft` from a corresponding ' '`UpdateDraftMessage` object.' ) @@ -29,14 +29,14 @@ class Draft: return cls(client=client, peer=update.peer, draft=update.draft) @property - def entity(self): - return self._client.get_entity(self._peer) + async def entity(self): + return await self._client.get_entity(self._peer) @property - def input_entity(self): - return self._client.get_input_entity(self._peer) + async def input_entity(self): + return await self._client.get_input_entity(self._peer) - def set_message(self, text, no_webpage=None, reply_to_msg_id=None, entities=None): + async def set_message(self, text, no_webpage=None, reply_to_msg_id=None, entities=None): """ Changes the draft message on the Telegram servers. The changes are reflected in this object. Changing only individual attributes like for @@ -56,7 +56,7 @@ class Draft: :param list entities: A list of formatting entities :return bool: `True` on success """ - result = self._client(SaveDraftRequest( + result = await self._client(SaveDraftRequest( peer=self._peer, message=text, no_webpage=no_webpage, @@ -72,9 +72,9 @@ class Draft: return result - def delete(self): + async def delete(self): """ Deletes this draft :return bool: `True` on success """ - return self.set_message(text='') + return await self.set_message(text='') diff --git a/telethon/tl/entity_database.py b/telethon/tl/entity_database.py deleted file mode 100644 index 296383b2..00000000 --- a/telethon/tl/entity_database.py +++ /dev/null @@ -1,248 +0,0 @@ -import re - -from ..tl import TLObject -from ..tl.types import ( - User, Chat, Channel, PeerUser, PeerChat, PeerChannel, - InputPeerUser, InputPeerChat, InputPeerChannel -) -from .. import utils # Keep this line the last to maybe fix #357 - - -USERNAME_RE = re.compile( - r'@|(?:https?://)?(?:telegram\.(?:me|dog)|t\.me)/(joinchat/)?' -) - - -class EntityDatabase: - def __init__(self, input_list=None, enabled=True, enabled_full=True): - """Creates a new entity database with an initial load of "Input" - entities, if any. - - If 'enabled', input entities will be saved. The whole entity - will be saved if both 'enabled' and 'enabled_full' are True. - """ - self.enabled = enabled - self.enabled_full = enabled_full - self._entities = {} # marked_id: user|chat|channel - - if input_list: - # TODO For compatibility reasons some sessions were saved with - # 'access_hash': null in the JSON session file. Drop these, as - # it means we don't have access to such InputPeers. Issue #354. - self._input_entities = { - k: v for k, v in input_list if v is not None - } - else: - self._input_entities = {} # marked_id: hash - - # TODO Allow disabling some extra mappings - self._username_id = {} # username: marked_id - self._phone_id = {} # phone: marked_id - - def process(self, tlobject): - """Processes all the found entities on the given TLObject, - unless .enabled is False. - - Returns True if new input entities were added. - """ - if not self.enabled: - return False - - # Save all input entities we know of - if not isinstance(tlobject, TLObject) and hasattr(tlobject, '__iter__'): - # This may be a list of users already for instance - return self.expand(tlobject) - - entities = [] - if hasattr(tlobject, 'chats') and hasattr(tlobject.chats, '__iter__'): - entities.extend(tlobject.chats) - if hasattr(tlobject, 'users') and hasattr(tlobject.users, '__iter__'): - entities.extend(tlobject.users) - - return self.expand(entities) - - def expand(self, entities): - """Adds new input entities to the local database unconditionally. - Unknown types will be ignored. - """ - if not entities or not self.enabled: - return False - - new = [] # Array of entities (User, Chat, or Channel) - new_input = {} # Dictionary of {entity_marked_id: access_hash} - for e in entities: - if not isinstance(e, TLObject): - continue - - try: - p = utils.get_input_peer(e, allow_self=False) - marked_id = utils.get_peer_id(p, add_mark=True) - - has_hash = False - if isinstance(p, InputPeerChat): - # Chats don't have a hash - new_input[marked_id] = 0 - has_hash = True - elif p.access_hash: - # Some users and channels seem to be returned without - # an 'access_hash', meaning Telegram doesn't want you - # to access them. This is the reason behind ensuring - # that the 'access_hash' is non-zero. See issue #354. - new_input[marked_id] = p.access_hash - has_hash = True - - if self.enabled_full and has_hash: - if isinstance(e, (User, Chat, Channel)): - new.append(e) - except ValueError: - pass - - before = len(self._input_entities) - self._input_entities.update(new_input) - for e in new: - self._add_full_entity(e) - return len(self._input_entities) != before - - def _add_full_entity(self, entity): - """Adds a "full" entity (User, Chat or Channel, not "Input*"), - despite the value of self.enabled and self.enabled_full. - - Not to be confused with UserFull, ChatFull, or ChannelFull, - "full" means simply not "Input*". - """ - marked_id = utils.get_peer_id( - utils.get_input_peer(entity, allow_self=False), add_mark=True - ) - try: - old_entity = self._entities[marked_id] - old_entity.__dict__.update(entity.__dict__) # Keep old references - - # Update must delete old username and phone - username = getattr(old_entity, 'username', None) - if username: - del self._username_id[username.lower()] - - phone = getattr(old_entity, 'phone', None) - if phone: - del self._phone_id[phone] - except KeyError: - # Add new entity - self._entities[marked_id] = entity - - # Always update username or phone if any - username = getattr(entity, 'username', None) - if username: - self._username_id[username.lower()] = marked_id - - phone = getattr(entity, 'phone', None) - if phone: - self._phone_id[phone] = marked_id - - def _parse_key(self, key): - """Parses the given string, integer or TLObject key into a - marked user ID ready for use on self._entities. - - If a callable key is given, the entity will be passed to the - function, and if it returns a true-like value, the marked ID - for such entity will be returned. - - Raises ValueError if it cannot be parsed. - """ - if isinstance(key, str): - phone = EntityDatabase.parse_phone(key) - try: - if phone: - return self._phone_id[phone] - else: - username, _ = EntityDatabase.parse_username(key) - return self._username_id[username.lower()] - except KeyError as e: - raise ValueError() from e - - if isinstance(key, int): - return key # normal IDs are assumed users - - if isinstance(key, TLObject): - return utils.get_peer_id(key, add_mark=True) - - if callable(key): - for k, v in self._entities.items(): - if key(v): - return k - - raise ValueError() - - def __getitem__(self, key): - """See the ._parse_key() docstring for possible values of the key""" - try: - return self._entities[self._parse_key(key)] - except (ValueError, KeyError) as e: - raise KeyError(key) from e - - def __delitem__(self, key): - try: - old = self._entities.pop(self._parse_key(key)) - # Try removing the username and phone (if pop didn't fail), - # since the entity may have no username or phone, just ignore - # errors. It should be there if we popped the entity correctly. - try: - del self._username_id[getattr(old, 'username', None)] - except KeyError: - pass - - try: - del self._phone_id[getattr(old, 'phone', None)] - except KeyError: - pass - - except (ValueError, KeyError) as e: - raise KeyError(key) from e - - @staticmethod - def parse_phone(phone): - """Parses the given phone, or returns None if it's invalid""" - if isinstance(phone, int): - return str(phone) - else: - phone = re.sub(r'[+()\s-]', '', str(phone)) - if phone.isdigit(): - return phone - - @staticmethod - def parse_username(username): - """Parses the given username or channel access hash, given - a string, username or URL. Returns a tuple consisting of - both the stripped username and whether it is a joinchat/ hash. - """ - username = username.strip() - m = USERNAME_RE.match(username) - if m: - return username[m.end():], bool(m.group(1)) - else: - return username, False - - def get_input_entity(self, peer): - try: - i = utils.get_peer_id(peer, add_mark=True) - h = self._input_entities[i] # we store the IDs marked - i, k = utils.resolve_id(i) # removes the mark and returns kind - - if k == PeerUser: - return InputPeerUser(i, h) - elif k == PeerChat: - return InputPeerChat(i) - elif k == PeerChannel: - return InputPeerChannel(i, h) - - except ValueError as e: - raise KeyError(peer) from e - raise KeyError(peer) - - def get_input_list(self): - return list(self._input_entities.items()) - - def clear(self, target=None): - if target is None: - self._entities.clear() - else: - del self[target] diff --git a/telethon/tl/session.py b/telethon/tl/session.py index 468e05a6..e082a421 100644 --- a/telethon/tl/session.py +++ b/telethon/tl/session.py @@ -1,12 +1,20 @@ import json import os import platform +import sqlite3 import time -from base64 import b64encode, b64decode +from base64 import b64decode from os.path import isfile as file_exists -from .entity_database import EntityDatabase -from .. import helpers +from .. import utils, helpers +from ..tl import TLObject +from ..tl.types import ( + PeerUser, PeerChat, PeerChannel, + InputPeerUser, InputPeerChat, InputPeerChannel +) + +EXTENSION = '.session' +CURRENT_VERSION = 2 # database version class Session: @@ -17,33 +25,34 @@ class Session: If you think the session has been compromised, close all the sessions through an official Telegram client to revoke the authorization. """ - def __init__(self, session_user_id): + def __init__(self, session_id): """session_user_id should either be a string or another Session. Note that if another session is given, only parameters like those required to init a connection will be copied. """ # These values will NOT be saved - if isinstance(session_user_id, Session): - self.session_user_id = None - - # For connection purposes - session = session_user_id - self.device_model = session.device_model - self.system_version = session.system_version - self.app_version = session.app_version - self.lang_code = session.lang_code - self.system_lang_code = session.system_lang_code - self.lang_pack = session.lang_pack - self.report_errors = session.report_errors - self.save_entities = session.save_entities - self.flood_sleep_threshold = session.flood_sleep_threshold + self.filename = ':memory:' + # For connection purposes + if isinstance(session_id, Session): + self.device_model = session_id.device_model + self.system_version = session_id.system_version + self.app_version = session_id.app_version + self.lang_code = session_id.lang_code + self.system_lang_code = session_id.system_lang_code + self.lang_pack = session_id.lang_pack + self.report_errors = session_id.report_errors + self.save_entities = session_id.save_entities + self.flood_sleep_threshold = session_id.flood_sleep_threshold else: # str / None - self.session_user_id = session_user_id + if session_id: + self.filename = session_id + if not self.filename.endswith(EXTENSION): + self.filename += EXTENSION system = platform.uname() - self.device_model = system.system if system.system else 'Unknown' - self.system_version = system.release if system.release else '1.0' + self.device_model = system.system or 'Unknown' + self.system_version = system.release or '1.0' self.app_version = '1.0' # '0' will provoke error self.lang_code = 'en' self.system_lang_code = self.lang_code @@ -52,43 +61,177 @@ class Session: self.save_entities = True self.flood_sleep_threshold = 60 - self.id = helpers.generate_random_long(signed=False) + self.id = helpers.generate_random_long(signed=True) self._sequence = 0 self.time_offset = 0 self._last_msg_id = 0 # Long + self.salt = 0 # Long # These values will be saved - self.server_address = None - self.port = None - self.auth_key = None - self.layer = 0 - self.salt = 0 # Unsigned long - self.entities = EntityDatabase() # Known and cached entities + self._dc_id = 0 + self._server_address = None + self._port = None + self._auth_key = None + + # Migrating from .json -> SQL + entities = self._check_migrate_json() + + self._conn = sqlite3.connect(self.filename, check_same_thread=False) + c = self._conn.cursor() + c.execute("select name from sqlite_master " + "where type='table' and name='version'") + if c.fetchone(): + # Tables already exist, check for the version + c.execute("select version from version") + version = c.fetchone()[0] + if version != CURRENT_VERSION: + self._upgrade_database(old=version) + c.execute("delete from version") + c.execute("insert into version values (?)", (CURRENT_VERSION,)) + self.save() + + # These values will be saved + c.execute('select * from sessions') + tuple_ = c.fetchone() + if tuple_: + self._dc_id, self._server_address, self._port, key, = tuple_ + from ..crypto import AuthKey + self._auth_key = AuthKey(data=key) + + c.close() + else: + # Tables don't exist, create new ones + c.execute("create table version (version integer)") + c.execute("insert into version values (?)", (CURRENT_VERSION,)) + c.execute( + """create table sessions ( + dc_id integer primary key, + server_address text, + port integer, + auth_key blob + ) without rowid""" + ) + c.execute( + """create table entities ( + id integer primary key, + hash integer not null, + username text, + phone integer, + name text + ) without rowid""" + ) + # Save file_size along with md5_digest + # to make collisions even more unlikely. + c.execute( + """create table sent_files ( + md5_digest blob, + file_size integer, + file_id integer, + part_count integer, + primary key(md5_digest, file_size) + ) without rowid""" + ) + # Migrating from JSON -> new table and may have entities + if entities: + c.executemany( + 'insert or replace into entities values (?,?,?,?,?)', + entities + ) + c.close() + self.save() + + def _check_migrate_json(self): + if file_exists(self.filename): + try: + with open(self.filename, encoding='utf-8') as f: + data = json.load(f) + self.delete() # Delete JSON file to create database + + self._port = data.get('port', self._port) + self._server_address = \ + data.get('server_address', self._server_address) + + from ..crypto import AuthKey + if data.get('auth_key_data', None) is not None: + key = b64decode(data['auth_key_data']) + self._auth_key = AuthKey(data=key) + + rows = [] + for p_id, p_hash in data.get('entities', []): + rows.append((p_id, p_hash, None, None, None)) + return rows + except UnicodeDecodeError: + return [] # No entities + + def _upgrade_database(self, old): + if old == 1: + self._conn.execute( + """create table sent_files ( + md5_digest blob, + file_size integer, + file_id integer, + part_count integer, + primary key(md5_digest, file_size) + ) without rowid""" + ) + old = 2 + + # Data from sessions should be kept as properties + # not to fetch the database every time we need it + def set_dc(self, dc_id, server_address, port): + self._dc_id = dc_id + self._server_address = server_address + self._port = port + self._update_session_table() + + # Fetch the auth_key corresponding to this data center + c = self._conn.cursor() + c.execute('select auth_key from sessions') + tuple_ = c.fetchone() + if tuple_: + from ..crypto import AuthKey + self._auth_key = AuthKey(data=tuple_[0]) + else: + self._auth_key = None + c.close() + + @property + def server_address(self): + return self._server_address + + @property + def port(self): + return self._port + + @property + def auth_key(self): + return self._auth_key + + @auth_key.setter + def auth_key(self, value): + self._auth_key = value + self._update_session_table() + + def _update_session_table(self): + c = self._conn.cursor() + c.execute('insert or replace into sessions values (?,?,?,?)', ( + self._dc_id, + self._server_address, + self._port, + self._auth_key.key if self._auth_key else b'' + )) + c.close() def save(self): """Saves the current session object as session_user_id.session""" - if not self.session_user_id: - return - - with open('{}.session'.format(self.session_user_id), 'w') as file: - out_dict = { - 'port': self.port, - 'salt': self.salt, - 'layer': self.layer, - 'server_address': self.server_address, - 'auth_key_data': - b64encode(self.auth_key.key).decode('ascii') - if self.auth_key else None - } - if self.save_entities: - out_dict['entities'] = self.entities.get_input_list() - - json.dump(out_dict, file) + self._conn.commit() def delete(self): """Deletes the current session file""" + if self.filename == ':memory:': + return True try: - os.remove('{}.session'.format(self.session_user_id)) + os.remove(self.filename) return True except OSError: return False @@ -99,43 +242,7 @@ class Session: using this client and never logged out """ return [os.path.splitext(os.path.basename(f))[0] - for f in os.listdir('.') if f.endswith('.session')] - - @staticmethod - def try_load_or_create_new(session_user_id): - """Loads a saved session_user_id.session or creates a new one. - If session_user_id=None, later .save()'s will have no effect. - """ - if session_user_id is None: - return Session(None) - else: - path = '{}.session'.format(session_user_id) - result = Session(session_user_id) - if not file_exists(path): - return result - - try: - with open(path, 'r') as file: - data = json.load(file) - result.port = data.get('port', result.port) - result.salt = data.get('salt', result.salt) - result.layer = data.get('layer', result.layer) - result.server_address = \ - data.get('server_address', result.server_address) - - # FIXME We need to import the AuthKey here or otherwise - # we get cyclic dependencies. - from ..crypto import AuthKey - if data.get('auth_key_data', None) is not None: - key = b64decode(data['auth_key_data']) - result.auth_key = AuthKey(data=key) - - result.entities = EntityDatabase(data.get('entities', [])) - - except (json.decoder.JSONDecodeError, UnicodeDecodeError): - pass - - return result + for f in os.listdir('.') if f.endswith(EXTENSION)] def generate_sequence(self, content_related): """Thread safe method to generates the next sequence number, @@ -173,9 +280,119 @@ class Session: correct = correct_msg_id >> 32 self.time_offset = correct - now - def process_entities(self, tlobject): - try: - if self.entities.process(tlobject): - self.save() # Save if any new entities got added - except: - pass + # Entity processing + + def process_entities(self, tlo): + """Processes all the found entities on the given TLObject, + unless .enabled is False. + + Returns True if new input entities were added. + """ + if not self.save_entities: + return + + if not isinstance(tlo, TLObject) and hasattr(tlo, '__iter__'): + # This may be a list of users already for instance + entities = tlo + else: + entities = [] + if hasattr(tlo, 'chats') and hasattr(tlo.chats, '__iter__'): + entities.extend(tlo.chats) + if hasattr(tlo, 'users') and hasattr(tlo.users, '__iter__'): + entities.extend(tlo.users) + if not entities: + return + + rows = [] # Rows to add (id, hash, username, phone, name) + for e in entities: + if not isinstance(e, TLObject): + continue + try: + p = utils.get_input_peer(e, allow_self=False) + marked_id = utils.get_peer_id(p) + except ValueError: + continue + + p_hash = getattr(p, 'access_hash', 0) + if p_hash is None: + # Some users and channels seem to be returned without + # an 'access_hash', meaning Telegram doesn't want you + # to access them. This is the reason behind ensuring + # that the 'access_hash' is non-zero. See issue #354. + continue + + username = getattr(e, 'username', None) or None + if username is not None: + username = username.lower() + phone = getattr(e, 'phone', None) + name = utils.get_display_name(e) or None + rows.append((marked_id, p_hash, username, phone, name)) + if not rows: + return + + self._conn.executemany( + 'insert or replace into entities values (?,?,?,?,?)', rows + ) + self.save() + + def get_input_entity(self, key): + """Parses the given string, integer or TLObject key into a + marked entity ID, which is then used to fetch the hash + from the database. + + If a callable key is given, every row will be fetched, + and passed as a tuple to a function, that should return + a true-like value when the desired row is found. + + Raises ValueError if it cannot be found. + """ + if isinstance(key, TLObject): + try: + # Try to early return if this key can be casted as input peer + return utils.get_input_peer(key) + except TypeError: + # Otherwise, get the ID of the peer + key = utils.get_peer_id(key) + + c = self._conn.cursor() + if isinstance(key, str): + phone = utils.parse_phone(key) + if phone: + c.execute('select id, hash from entities where phone=?', + (phone,)) + else: + username, _ = utils.parse_username(key) + c.execute('select id, hash from entities where username=?', + (username,)) + + if isinstance(key, int): + c.execute('select id, hash from entities where id=?', (key,)) + + result = c.fetchone() + c.close() + if result: + i, h = result # unpack resulting tuple + i, k = utils.resolve_id(i) # removes the mark and returns kind + if k == PeerUser: + return InputPeerUser(i, h) + elif k == PeerChat: + return InputPeerChat(i) + elif k == PeerChannel: + return InputPeerChannel(i, h) + else: + raise ValueError('Could not find input entity with key ', key) + + # File processing + + def get_file(self, md5_digest, file_size): + return self._conn.execute( + 'select * from sent_files ' + 'where md5_digest = ? and file_size = ?', (md5_digest, file_size) + ).fetchone() + + def cache_file(self, md5_digest, file_size, file_id, part_count): + self._conn.execute( + 'insert into sent_files values (?,?,?,?)', + (md5_digest, file_size, file_id, part_count) + ) + self.save() diff --git a/telethon/tl/tlobject.py b/telethon/tl/tlobject.py index 9ba9f3dd..f07d4bb9 100644 --- a/telethon/tl/tlobject.py +++ b/telethon/tl/tlobject.py @@ -1,9 +1,9 @@ -from datetime import datetime +import struct +from datetime import datetime, date class TLObject: def __init__(self): - self.request_msg_id = 0 # Long self.confirm_received = None self.rpc_error = None @@ -97,7 +97,8 @@ class TLObject: if isinstance(data, str): data = data.encode('utf-8') else: - raise ValueError('bytes or str expected, not', type(data)) + raise TypeError( + 'bytes or str expected, not {}'.format(type(data))) r = [] if len(data) < 254: @@ -124,6 +125,23 @@ class TLObject: r.append(bytes(padding)) return b''.join(r) + @staticmethod + def serialize_datetime(dt): + if not dt: + return b'\0\0\0\0' + + if isinstance(dt, datetime): + dt = int(dt.timestamp()) + elif isinstance(dt, date): + dt = int(datetime(dt.year, dt.month, dt.day).timestamp()) + elif isinstance(dt, float): + dt = int(dt) + + if isinstance(dt, int): + return struct.pack(' log works - return -(i + pow(10, math.floor(math.log10(i) + 3))) - else: - return i + # Concat -100 through math tricks, .to_supergroup() on Madeline + # IDs will be strictly positive -> log works + return -(i + pow(10, math.floor(math.log10(i) + 3))) _raise_cast_fail(peer, 'int') @@ -353,28 +388,6 @@ def resolve_id(marked_id): return -marked_id, PeerChat -def find_user_or_chat(peer, users, chats): - """Finds the corresponding user or chat given a peer. - Returns None if it was not found""" - if isinstance(peer, PeerUser): - peer, where = peer.user_id, users - else: - where = chats - if isinstance(peer, PeerChat): - peer = peer.chat_id - elif isinstance(peer, PeerChannel): - peer = peer.channel_id - - if isinstance(peer, int): - if isinstance(where, dict): - return where.get(peer) - else: - try: - return next(x for x in where if x.id == peer) - except StopIteration: - pass - - def get_appropriated_part_size(file_size): """Gets the appropriated part size when uploading or downloading files, given an initial file size""" diff --git a/telethon/version.py b/telethon/version.py index 096fbd6c..e7fcc442 100644 --- a/telethon/version.py +++ b/telethon/version.py @@ -1,3 +1,3 @@ # Versions should comply with PEP440. # This line is parsed in setup.py: -__version__ = '0.15.5' +__version__ = '0.16' diff --git a/telethon_examples/interactive_telegram_client.py b/telethon_examples/interactive_telegram_client.py index 52c2c356..501d557b 100644 --- a/telethon_examples/interactive_telegram_client.py +++ b/telethon_examples/interactive_telegram_client.py @@ -138,15 +138,15 @@ class InteractiveTelegramClient(TelegramClient): # Entities represent the user, chat or channel # corresponding to the dialog on the same index. - dialogs, entities = self.get_dialogs(limit=dialog_count) + dialogs = self.get_dialogs(limit=dialog_count) i = None while i is None: print_title('Dialogs window') # Display them so the user can choose - for i, entity in enumerate(entities, start=1): - sprint('{}. {}'.format(i, get_display_name(entity))) + for i, dialog in enumerate(dialogs, start=1): + sprint('{}. {}'.format(i, get_display_name(dialog.entity))) # Let the user decide who they want to talk to print() @@ -177,7 +177,7 @@ class InteractiveTelegramClient(TelegramClient): i = None # Retrieve the selected user (or chat, or channel) - entity = entities[i] + entity = dialogs[i].entity # Show some information print_title('Chat with "{}"'.format(get_display_name(entity))) diff --git a/telethon_generator/parser/tl_parser.py b/telethon_generator/parser/tl_parser.py index a08521db..8c24cbf4 100644 --- a/telethon_generator/parser/tl_parser.py +++ b/telethon_generator/parser/tl_parser.py @@ -17,11 +17,13 @@ class TLParser: # Read all the lines from the .tl file for line in file: + # Strip comments from the line + comment_index = line.find('//') + if comment_index != -1: + line = line[:comment_index] + line = line.strip() - - # Ensure that the line is not a comment - if line and not line.startswith('//'): - + if line: # Check whether the line is a type change # (types <-> functions) or not match = re.match('---(\w+)---', line) diff --git a/telethon_generator/scheme.tl b/telethon_generator/scheme.tl index 2ecb31b4..1d03c281 100644 --- a/telethon_generator/scheme.tl +++ b/telethon_generator/scheme.tl @@ -166,11 +166,9 @@ inputMediaGifExternal#4843b0fd url:string q:string = InputMedia; inputMediaPhotoExternal#922aec1 flags:# url:string caption:string ttl_seconds:flags.0?int = InputMedia; inputMediaDocumentExternal#b6f74335 flags:# url:string caption:string ttl_seconds:flags.0?int = InputMedia; inputMediaGame#d33f43f3 id:InputGame = InputMedia; -inputMediaInvoice#92153685 flags:# title:string description:string photo:flags.0?InputWebDocument invoice:Invoice payload:bytes provider:string start_param:string = InputMedia; +inputMediaInvoice#f4e096c3 flags:# title:string description:string photo:flags.0?InputWebDocument invoice:Invoice payload:bytes provider:string provider_data:DataJSON start_param:string = InputMedia; inputMediaGeoLive#7b1a118f geo_point:InputGeoPoint period:int = InputMedia; -inputSingleMedia#5eaa7809 media:InputMedia random_id:long = InputSingleMedia; - inputChatPhotoEmpty#1ca48f57 = InputChatPhoto; inputChatUploadedPhoto#927c55b4 file:InputFile = InputChatPhoto; inputChatPhoto#8953ad37 id:InputPhoto = InputChatPhoto; @@ -345,6 +343,7 @@ messages.dialogsSlice#71e094f3 count:int dialogs:Vector messages:Vector< messages.messages#8c718e87 messages:Vector chats:Vector users:Vector = messages.Messages; messages.messagesSlice#b446ae3 count:int messages:Vector chats:Vector users:Vector = messages.Messages; messages.channelMessages#99262e37 flags:# pts:int count:int messages:Vector chats:Vector users:Vector = messages.Messages; +messages.messagesNotModified#74535f21 count:int = messages.Messages; messages.chats#64ff9fd5 chats:Vector = messages.Chats; messages.chatsSlice#9cd81144 count:int chats:Vector = messages.Chats; @@ -357,7 +356,6 @@ inputMessagesFilterEmpty#57e2f66c = MessagesFilter; inputMessagesFilterPhotos#9609a51c = MessagesFilter; inputMessagesFilterVideo#9fc00e65 = MessagesFilter; inputMessagesFilterPhotoVideo#56e9f0e4 = MessagesFilter; -inputMessagesFilterPhotoVideoDocuments#d95e73bb = MessagesFilter; inputMessagesFilterDocument#9eddf188 = MessagesFilter; inputMessagesFilterUrl#7ef0dd87 = MessagesFilter; inputMessagesFilterGif#ffc86587 = MessagesFilter; @@ -368,8 +366,8 @@ inputMessagesFilterPhoneCalls#80c99768 flags:# missed:flags.0?true = MessagesFil inputMessagesFilterRoundVoice#7a7c17a4 = MessagesFilter; inputMessagesFilterRoundVideo#b549da53 = MessagesFilter; inputMessagesFilterMyMentions#c1f8e69a = MessagesFilter; -inputMessagesFilterContacts#e062db83 = MessagesFilter; inputMessagesFilterGeo#e7026d0d = MessagesFilter; +inputMessagesFilterContacts#e062db83 = MessagesFilter; updateNewMessage#1f2b0afd message:Message pts:int pts_count:int = Update; updateMessageID#4e90bfd6 id:int random_id:long = Update; @@ -463,7 +461,7 @@ upload.fileCdnRedirect#ea52fe5a dc_id:int file_token:bytes encryption_key:bytes dcOption#5d8c6cc flags:# ipv6:flags.0?true media_only:flags.1?true tcpo_only:flags.2?true cdn:flags.3?true static:flags.4?true id:int ip_address:string port:int = DcOption; -config#9c840964 flags:# phonecalls_enabled:flags.1?true date:int expires:int test_mode:Bool this_dc:int dc_options:Vector chat_size_max:int megagroup_size_max:int forwarded_count_max:int online_update_period_ms:int offline_blur_timeout_ms:int offline_idle_timeout_ms:int online_cloud_timeout_ms:int notify_cloud_delay_ms:int notify_default_delay_ms:int chat_big_size:int push_chat_period_ms:int push_chat_limit:int saved_gifs_limit:int edit_time_limit:int rating_e_decay:int stickers_recent_limit:int stickers_faved_limit:int channels_read_media_period:int tmp_sessions:flags.0?int pinned_dialogs_count_max:int call_receive_timeout_ms:int call_ring_timeout_ms:int call_connect_timeout_ms:int call_packet_timeout_ms:int me_url_prefix:string suggested_lang_code:flags.2?string lang_pack_version:flags.2?int disabled_features:Vector = Config; +config#9c840964 flags:# phonecalls_enabled:flags.1?true default_p2p_contacts:flags.3?true date:int expires:int test_mode:Bool this_dc:int dc_options:Vector chat_size_max:int megagroup_size_max:int forwarded_count_max:int online_update_period_ms:int offline_blur_timeout_ms:int offline_idle_timeout_ms:int online_cloud_timeout_ms:int notify_cloud_delay_ms:int notify_default_delay_ms:int chat_big_size:int push_chat_period_ms:int push_chat_limit:int saved_gifs_limit:int edit_time_limit:int rating_e_decay:int stickers_recent_limit:int stickers_faved_limit:int channels_read_media_period:int tmp_sessions:flags.0?int pinned_dialogs_count_max:int call_receive_timeout_ms:int call_ring_timeout_ms:int call_connect_timeout_ms:int call_packet_timeout_ms:int me_url_prefix:string suggested_lang_code:flags.2?string lang_pack_version:flags.2?int disabled_features:Vector = Config; nearestDc#8e1a1775 country:string this_dc:int nearest_dc:int = NearestDc; @@ -524,7 +522,7 @@ sendMessageGamePlayAction#dd6a8f48 = SendMessageAction; sendMessageRecordRoundAction#88f27fbc = SendMessageAction; sendMessageUploadRoundAction#243e1c66 progress:int = SendMessageAction; -contacts.found#1aa1f784 results:Vector chats:Vector users:Vector = contacts.Found; +contacts.found#b3134d9d my_results:Vector results:Vector chats:Vector users:Vector = contacts.Found; inputPrivacyKeyStatusTimestamp#4f96cb18 = InputPrivacyKey; inputPrivacyKeyChatInvite#bdfb0426 = InputPrivacyKey; @@ -723,7 +721,7 @@ auth.sentCodeTypeSms#c000bba2 length:int = auth.SentCodeType; auth.sentCodeTypeCall#5353e5a7 length:int = auth.SentCodeType; auth.sentCodeTypeFlashCall#ab03c6d9 pattern:string = auth.SentCodeType; -messages.botCallbackAnswer#36585ea4 flags:# alert:flags.1?true has_url:flags.3?true message:flags.0?string url:flags.2?string cache_time:int = messages.BotCallbackAnswer; +messages.botCallbackAnswer#36585ea4 flags:# alert:flags.1?true has_url:flags.3?true native_ui:flags.4?true message:flags.0?string url:flags.2?string cache_time:int = messages.BotCallbackAnswer; messages.messageEditData#26b5dde6 flags:# caption:flags.0?true = messages.MessageEditData; @@ -825,7 +823,7 @@ dataJSON#7d748d04 data:string = DataJSON; labeledPrice#cb296bf8 label:string amount:long = LabeledPrice; -invoice#c30aa358 flags:# test:flags.0?true name_requested:flags.1?true phone_requested:flags.2?true email_requested:flags.3?true shipping_address_requested:flags.4?true flexible:flags.5?true currency:string prices:Vector = Invoice; +invoice#c30aa358 flags:# test:flags.0?true name_requested:flags.1?true phone_requested:flags.2?true email_requested:flags.3?true shipping_address_requested:flags.4?true flexible:flags.5?true phone_to_provider:flags.6?true email_to_provider:flags.7?true currency:string prices:Vector = Invoice; paymentCharge#ea02c27e id:string provider_charge_id:string = PaymentCharge; @@ -856,6 +854,8 @@ payments.savedInfo#fb8fe43c flags:# has_saved_credentials:flags.1?true saved_inf inputPaymentCredentialsSaved#c10eb2cf id:string tmp_password:bytes = InputPaymentCredentials; inputPaymentCredentials#3417d728 flags:# save:flags.0?true data:DataJSON = InputPaymentCredentials; +inputPaymentCredentialsApplePay#aa1c39f payment_data:DataJSON = InputPaymentCredentials; +inputPaymentCredentialsAndroidPay#ca05d50e payment_token:DataJSON google_transaction_id:string = InputPaymentCredentials; account.tmpPassword#db64fd34 tmp_password:bytes valid_until:int = account.TmpPassword; @@ -893,7 +893,7 @@ langPackDifference#f385c1f6 lang_code:string from_version:int version:int string langPackLanguage#117698f1 name:string native_name:string lang_code:string = LangPackLanguage; -channelAdminRights#5d7ceba5 flags:# change_info:flags.0?true post_messages:flags.1?true edit_messages:flags.2?true delete_messages:flags.3?true ban_users:flags.4?true invite_users:flags.5?true invite_link:flags.6?true pin_messages:flags.7?true add_admins:flags.9?true = ChannelAdminRights; +channelAdminRights#5d7ceba5 flags:# change_info:flags.0?true post_messages:flags.1?true edit_messages:flags.2?true delete_messages:flags.3?true ban_users:flags.4?true invite_users:flags.5?true invite_link:flags.6?true pin_messages:flags.7?true add_admins:flags.9?true manage_call:flags.10?true = ChannelAdminRights; channelBannedRights#58cf4249 flags:# view_messages:flags.0?true send_messages:flags.1?true send_media:flags.2?true send_stickers:flags.3?true send_gifs:flags.4?true send_games:flags.5?true send_inline:flags.6?true embed_links:flags.7?true until_date:int = ChannelBannedRights; @@ -927,13 +927,15 @@ cdnFileHash#77eec38f offset:int limit:int hash:bytes = CdnFileHash; messages.favedStickersNotModified#9e8fa6d3 = messages.FavedStickers; messages.favedStickers#f37f2f16 hash:int packs:Vector stickers:Vector = messages.FavedStickers; -help.recentMeUrls#e0310d7 urls:Vector chats:Vector users:Vector = help.RecentMeUrls; - +recentMeUrlUnknown#46e1d13d url:string = RecentMeUrl; recentMeUrlUser#8dbc3336 url:string user_id:int = RecentMeUrl; recentMeUrlChat#a01b22f9 url:string chat_id:int = RecentMeUrl; -recentMeUrlStickerSet#bc0a57dc url:string set:StickerSetCovered = RecentMeUrl; recentMeUrlChatInvite#eb49081d url:string chat_invite:ChatInvite = RecentMeUrl; -recentMeUrlUnknown#46e1d13d url:string = RecentMeUrl; +recentMeUrlStickerSet#bc0a57dc url:string set:StickerSetCovered = RecentMeUrl; + +help.recentMeUrls#e0310d7 urls:Vector chats:Vector users:Vector = help.RecentMeUrls; + +inputSingleMedia#5eaa7809 media:InputMedia random_id:long = InputSingleMedia; ---functions--- @@ -961,8 +963,8 @@ auth.resendCode#3ef1a9bf phone_number:string phone_code_hash:string = auth.SentC auth.cancelCode#1f040578 phone_number:string phone_code_hash:string = Bool; auth.dropTempAuthKeys#8e48a188 except_auth_keys:Vector = Bool; -account.registerDevice#637ea878 token_type:int token:string = Bool; -account.unregisterDevice#65c55b40 token_type:int token:string = Bool; +account.registerDevice#f75874d1 token_type:int token:string other_uids:Vector = Bool; +account.unregisterDevice#3076c4bf token_type:int token:string other_uids:Vector = Bool; account.updateNotifySettings#84be5b93 peer:InputNotifyPeer settings:InputPeerNotifySettings = Bool; account.getNotifySettings#12b3ad31 peer:InputNotifyPeer = PeerNotifySettings; account.resetNotifySettings#db7e1747 = Bool; @@ -1010,7 +1012,7 @@ contacts.resetSaved#879537f1 = Bool; messages.getMessages#4222fa74 id:Vector = messages.Messages; messages.getDialogs#191ba9c5 flags:# exclude_pinned:flags.0?true offset_date:int offset_id:int offset_peer:InputPeer limit:int = messages.Dialogs; -messages.getHistory#afa92846 peer:InputPeer offset_id:int offset_date:int add_offset:int limit:int max_id:int min_id:int = messages.Messages; +messages.getHistory#dcbb8260 peer:InputPeer offset_id:int offset_date:int add_offset:int limit:int max_id:int min_id:int hash:int = messages.Messages; messages.search#39e9ea0 flags:# peer:InputPeer q:string from_id:flags.0?InputUser filter:MessagesFilter min_date:int max_date:int offset_id:int add_offset:int limit:int max_id:int min_id:int = messages.Messages; messages.readHistory#e306d3a peer:InputPeer max_id:int = messages.AffectedMessages; messages.deleteHistory#1c015b09 flags:# just_clear:flags.0?true peer:InputPeer max_id:int = messages.AffectedHistory; @@ -1067,7 +1069,7 @@ messages.setInlineBotResults#eb5ea206 flags:# gallery:flags.0?true private:flags messages.sendInlineBotResult#b16e06fe flags:# silent:flags.5?true background:flags.6?true clear_draft:flags.7?true peer:InputPeer reply_to_msg_id:flags.0?int random_id:long query_id:long id:string = Updates; messages.getMessageEditData#fda68d36 peer:InputPeer id:int = messages.MessageEditData; messages.editMessage#5d1b8dd flags:# no_webpage:flags.1?true stop_geo_live:flags.12?true peer:InputPeer id:int message:flags.11?string reply_markup:flags.2?ReplyMarkup entities:flags.3?Vector geo_point:flags.13?InputGeoPoint = Updates; -messages.editInlineBotMessage#130c2c85 flags:# no_webpage:flags.1?true id:InputBotInlineMessageID message:flags.11?string reply_markup:flags.2?ReplyMarkup entities:flags.3?Vector = Bool; +messages.editInlineBotMessage#b0e08243 flags:# no_webpage:flags.1?true stop_geo_live:flags.12?true id:InputBotInlineMessageID message:flags.11?string reply_markup:flags.2?ReplyMarkup entities:flags.3?Vector geo_point:flags.13?InputGeoPoint = Bool; messages.getBotCallbackAnswer#810a9fec flags:# game:flags.1?true peer:InputPeer msg_id:int data:flags.0?bytes = messages.BotCallbackAnswer; messages.setBotCallbackAnswer#d58f130a flags:# alert:flags.1?true query_id:long message:flags.0?string url:flags.2?string cache_time:int = Bool; messages.getPeerDialogs#2d9776b9 peers:Vector = messages.PeerDialogs; @@ -1098,9 +1100,10 @@ messages.sendScreenshotNotification#c97df020 peer:InputPeer reply_to_msg_id:int messages.getFavedStickers#21ce0b0e hash:int = messages.FavedStickers; messages.faveSticker#b9ffc55b id:InputDocument unfave:Bool = Bool; messages.getUnreadMentions#46578472 peer:InputPeer offset_id:int add_offset:int limit:int max_id:int min_id:int = messages.Messages; -messages.getRecentLocations#249431e2 peer:InputPeer limit:int = messages.Messages; messages.readMentions#f0189d3 peer:InputPeer = messages.AffectedHistory; +messages.getRecentLocations#249431e2 peer:InputPeer limit:int = messages.Messages; messages.sendMultiMedia#2095512f flags:# silent:flags.5?true background:flags.6?true clear_draft:flags.7?true peer:InputPeer reply_to_msg_id:flags.0?int multi_media:Vector = Updates; +messages.uploadEncryptedFile#5057c497 peer:InputEncryptedChat file:InputEncryptedFile = EncryptedFile; updates.getState#edd4882a = updates.State; updates.getDifference#25939651 flags:# pts:int pts_total_limit:flags.0?int date:int qts:int = updates.Difference; @@ -1153,7 +1156,7 @@ channels.inviteToChannel#199f3a6c channel:InputChannel users:Vector = channels.exportInvite#c7560885 channel:InputChannel = ExportedChatInvite; channels.deleteChannel#c0111fe3 channel:InputChannel = Updates; channels.toggleInvites#49609307 channel:InputChannel enabled:Bool = Updates; -channels.exportMessageLink#c846d22d channel:InputChannel id:int = ExportedMessageLink; +channels.exportMessageLink#ceb77163 channel:InputChannel id:int grouped:Bool = ExportedMessageLink; channels.toggleSignatures#1f69b606 channel:InputChannel enabled:Bool = Updates; channels.updatePinnedMessage#a72ded52 flags:# silent:flags.0?true channel:InputChannel id:int = Updates; channels.getAdminedPublicChannels#8d8d82d7 = messages.Chats; @@ -1193,4 +1196,4 @@ langpack.getStrings#2e1ee318 lang_code:string keys:Vector = Vector; -// LAYER 73 +// LAYER 74 diff --git a/telethon_generator/tl_generator.py b/telethon_generator/tl_generator.py index 60f07bd6..3116003a 100644 --- a/telethon_generator/tl_generator.py +++ b/telethon_generator/tl_generator.py @@ -311,8 +311,10 @@ class TLGenerator: for ra in repeated_args.values(): if len(ra) > 1: - cnd1 = ('self.{}'.format(a.name) for a in ra) - cnd2 = ('not self.{}'.format(a.name) for a in ra) + cnd1 = ('(self.{0} or self.{0} is not None)' + .format(a.name) for a in ra) + cnd2 = ('(self.{0} is None or self.{0} is False)' + .format(a.name) for a in ra) builder.writeln( "assert ({}) or ({}), '{} parameters must all " "be False-y (like None) or all me True-y'".format( @@ -464,9 +466,11 @@ class TLGenerator: # Vector flags are special since they consist of 3 values, # so we need an extra join here. Note that empty vector flags # should NOT be sent either! - builder.write("b'' if not {} else b''.join((".format(name)) + builder.write("b'' if {0} is None or {0} is False " + "else b''.join((".format(name)) else: - builder.write("b'' if not {} else (".format(name)) + builder.write("b'' if {0} is None or {0} is False " + "else (".format(name)) if arg.is_vector: if arg.use_vector_id: @@ -495,11 +499,14 @@ class TLGenerator: # There's a flag indicator, but no flag arguments so it's 0 builder.write(r"b'\0\0\0\0'") else: - builder.write("struct.pack('