Pull (Sourcery refactored) (#5)

* Slightly improve documentation

* Deprecate force_sms and sign_up

On the 10th of February, Telegram sent the following message to
those with an application registered on https://my.telegram.org.

--

Telegram API Update. Hello [REDACTED]. Thank you for contributing to the
open Telegram ecosystem by developing your app, [REDACTED].

Please note that due to recent updates to Telegram's handling of SMS and
the integration of new SMS providers like Firebase, we are changing the
way login codes are handled in third-party apps based on the Telegram API.

Starting on 18.02.2023, users logging into third-party apps will only be
able to receive login codes via Telegram. It will no longer be possible
to request an SMS to log into your app - just like when logging into
Telegram's own desktop and web clients.

Exactly like with the Telegram Desktop and Web apps, if a user doesn't
have a Telegram account yet, they will need to create one first using
an official mobile Telegram app.

We kindly ask you to update your app's login and signup interfaces to
reflect these changes before they go live on 18.02.2023 at 13:00 UTC.

This change will not significantly affect users since, according to our
research, the vast majority of third-party app users also use official
Telegram apps. In the coming months, we expect to offer new tools for
third-party developers that will help streamline the login process.

* Fix ChatAction for groups with hidden members

* Move working with messages to the wiki

* 'Refactored by Sourcery'

---------

Co-authored-by: Lonami Exo <totufals@hotmail.com>
Co-authored-by: Devesh Pal <newdev0@outlook.com>

Author: 3 people

readthedocs/examples/working-with-messages.rst

@@ -2,125 +2,12 @@
 Working with messages
 =====================
 
-
 .. note::
 
     These examples assume you have read :ref:`full-api`.
 
-.. contents::
-
-
-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:
-
-.. code-block:: python
-
-    # Get all the sticker sets this user has
-    from telethon.tl.functions.messages import GetAllStickersRequest
-    sticker_sets = await client(GetAllStickersRequest(0))
-
-    # Choose a sticker set
-    from telethon.tl.functions.messages import GetStickerSetRequest
-    from telethon.tl.types import InputStickerSetID
-    sticker_set = sticker_sets.sets[0]
-
-    # Get the stickers for this sticker set
-    stickers = await client(GetStickerSetRequest(
-        stickerset=InputStickerSetID(
-            id=sticker_set.id, access_hash=sticker_set.access_hash
-        ),
-        hash=0
-    ))
-
-    # Stickers are nothing more than files, so send that
-    await client.send_file('me', stickers.documents[0])
-
-
-Sending reactions
-=================
-
-It works very similar to replying to a message. You need to specify the chat,
-message ID you wish to react to, and reaction, using :tl:`SendReaction`:
-
-.. code-block:: python
-
-    from telethon.tl.functions.messages import SendReactionRequest
-
-    await client(SendReactionRequest(
-        peer=chat,
-        msg_id=42,
-        reaction='❤️'
-    ))
-
-Note that you cannot use strings like ``:heart:`` for the reaction. You must
-use the desired emoji directly. You can most easily achieve this by
-copy-pasting the emoji from an official application such as Telegram Desktop.
-
-If for some reason you cannot embed emoji directly into the code, you can also
-use its unicode escape (which you can find using websites like
-`unicode-table.com`_), or install a different package, like `emoji`_:
-
-.. code-block:: python
-
-    # All of these work exactly the same (you only need one):
-    import emoji
-    reaction = emoji.emojize(':red_heart:')
-    reaction = '❤️'
-    reaction = '\u2764'
-
-    from telethon.tl.functions.messages import SendReactionRequest
-    await client(SendReactionRequest(
-        peer=chat,
-        msg_id=42,
-        reaction=reaction
-    ))
-
-Please make sure to check the help pages of the respective websites you use
-if you need a more in-depth explanation on how they work. Telethon only needs
-you to provide the emoji in some form. Some packages or websites can make this
-easier.
-
-
-Sending spoilers (hidden text)
-==============================
-
-The current markdown and HTML parsers do not offer a way to send spoilers yet.
-You need to use :tl:`MessageEntitySpoiler` so that parts of the message text
-are shown under a spoiler.
-
-The simplest way to do this is to `modify the builtin parsers`_ to support
-sending these new message entities with the features they already provide.
-
-
-Sending custom emoji
-====================
-
-The current markdown and HTML parsers do not offer a way to send custom emoji
-yet. You need to use :tl:`MessageEntityCustomEmoji` so that parts of the
-message text with emoji are replaced with a custom one instead.
-
-The simplest way to do this is to `modify the builtin parsers`_ to support
-sending these new message entities with the features they already provide.
-
-:tl:`MessageEntityCustomEmoji` must wrap an emoji in order to work (you can't
-put it around arbitrary ``"text"``, it won't work), so be sure to keep this in
-mind when using it.
-
-To find the ``document_id`` for the custom emoji, the simplest way is to send
-a message with an official client containing the custom emoji you want, and
-then print the ``message.entities`` to find the ``document_id``.
-
-If you prefer, you can also use :tl:`GetFeaturedEmojiStickers` to find about
-the ``document_id`` of featured custom emoji.
-
+This section has been `moved to the wiki`_, where it can be easily edited as new
+features arrive and the API changes. Please refer to the linked page to learn how
+to send spoilers, custom emoji, stickers, react to messages, and more things.
 
-.. _unicode-table.com: https://unicode-table.com/en/emoji/
-.. _emoji: https://pypi.org/project/emoji/
-.. _modify the builtin parsers: https://github.com/LonamiWebs/Telethon/wiki/Sending-spoilers-and-custom-emoji
+.. _moved to the wiki: https://github.com/LonamiWebs/Telethon/wiki/Sending-more-than-just-messages

readthedocs/quick-references/client-reference.rst

@@ -32,7 +32,6 @@ Auth
     send_code_request
     sign_in
     qr_login
-    sign_up
     log_out
     edit_2fa
 

readthedocs/quick-references/faq.rst

@@ -67,8 +67,7 @@ However, you may also be part of a limited country, such as Iran or Russia.
 In that case, we have bad news for you. Telegram is much more likely to ban
 these numbers, as they are often used to spam other accounts, likely through
 the use of libraries like this one. The best advice we can give you is to not
-abuse the API, like calling many requests really quickly, and to sign up with
-these phones through an official application.
+abuse the API, like calling many requests really quickly.
 
 We have also had reports from Kazakhstan and China, where connecting
 would fail. To solve these connection problems, you should use a proxy.

telethon/client/auth.py

@@ -34,12 +34,6 @@ def start(
         By default, this method will be interactive (asking for
         user input if needed), and will handle 2FA if enabled too.
 
-        If the phone doesn't belong to an existing account (and will hence
-        `sign_up` for a new one),  **you are agreeing to Telegram's
-        Terms of Service. This is required and your account
-        will be banned otherwise.** See https://telegram.org/tos
-        and https://core.telegram.org/api/terms.
-
         If the event loop is already running, this method returns a
         coroutine that you should await on your own code; otherwise
         the loop is ran until said coroutine completes.
@@ -188,7 +182,6 @@ async def _start(
         two_step_detected = False
 
         await self.send_code_request(phone, force_sms=force_sms)
-        sign_up = False  # assume login
         while attempts < max_attempts:
             try:
                 value = code_callback()
@@ -201,19 +194,12 @@ async def _start(
                 if not value:
                     raise errors.PhoneCodeEmptyError(request=None)
 
-                if sign_up:
-                    me = await self.sign_up(value, first_name, last_name)
-                else:
-                    # Raises SessionPasswordNeededError if 2FA enabled
-                    me = await self.sign_in(phone, code=value)
+                # Raises SessionPasswordNeededError if 2FA enabled
+                me = await self.sign_in(phone, code=value)
                 break
             except errors.SessionPasswordNeededError:
                 two_step_detected = True
                 break
-            except errors.PhoneNumberOccupiedError:
-                sign_up = False
-            except errors.PhoneNumberUnoccupiedError:
-                sign_up = True
             except (errors.PhoneCodeEmptyError,
                     errors.PhoneCodeExpiredError,
                     errors.PhoneCodeHashEmptyError,
@@ -381,91 +367,10 @@ async def sign_up(
             phone: str = None,
             phone_code_hash: str = None) -> 'types.User':
         """
-        Signs up to Telegram as a new user account.
-
-        Use this if you don't have an account yet.
-
-        You must call `send_code_request` first.
-
-        **By using this method you're agreeing to Telegram's
-        Terms of Service. This is required and your account
-        will be banned otherwise.** See https://telegram.org/tos
-        and https://core.telegram.org/api/terms.
-
-        Arguments
-            code (`str` | `int`):
-                The code sent by Telegram
-
-            first_name (`str`):
-                The first name to be used by the new account.
-
-            last_name (`str`, optional)
-                Optional last name.
-
-            phone (`str` | `int`, optional):
-                The phone to sign up. This will be the last phone used by
-                default (you normally don't need to set this).
-
-            phone_code_hash (`str`, optional):
-                The hash returned by `send_code_request`. This can be left as
-                `None` to use the last hash known for the phone to be used.
-
-        Returns
-            The new created :tl:`User`.
-
-        Example
-            .. code-block:: python
-
-                phone = '+34 123 123 123'
-                await client.send_code_request(phone)
-
-                code = input('enter code: ')
-                await client.sign_up(code, first_name='Anna', last_name='Banana')
+        This method can no longer be used, and will immediately raise a ``ValueError``.
+        See `issue #4050 <https://github.com/LonamiWebs/Telethon/issues/4050>`_ for context.
         """
-        me = await self.get_me()
-        if me:
-            return me
-
-        # To prevent abuse, one has to try to sign in before signing up. This
-        # is the current way in which Telegram validates the code to sign up.
-        #
-        # `sign_in` will set `_tos`, so if it's set we don't need to call it
-        # because the user already tried to sign in.
-        #
-        # We're emulating pre-layer 104 behaviour so except the right error:
-        if not self._tos:
-            try:
-                return await self.sign_in(
-                    phone=phone,
-                    code=code,
-                    phone_code_hash=phone_code_hash,
-                )
-            except errors.PhoneNumberUnoccupiedError:
-                pass  # code is correct and was used, now need to sign in
-
-        if self._tos and self._tos.text:
-            if self.parse_mode:
-                t = self.parse_mode.unparse(self._tos.text, self._tos.entities)
-            else:
-                t = self._tos.text
-            sys.stderr.write(f"{t}\n")
-            sys.stderr.flush()
-
-        phone, phone_code_hash = \
-                self._parse_phone_and_hash(phone, phone_code_hash)
-
-        result = await self(functions.auth.SignUpRequest(
-            phone_number=phone,
-            phone_code_hash=phone_code_hash,
-            first_name=first_name,
-            last_name=last_name
-        ))
-
-        if self._tos:
-            await self(
-                functions.help.AcceptTermsOfServiceRequest(self._tos.id))
-
-        return await self._on_login(result.user)
+        raise ValueError('Third-party applications cannot sign up for Telegram. See https://github.com/LonamiWebs/Telethon/issues/4050 for details')
 
     async def _on_login(self, user):
         """
@@ -496,7 +401,8 @@ async def send_code_request(
                 The phone to which the code will be sent.
 
             force_sms (`bool`, optional):
-                Whether to force sending as SMS.
+                Whether to force sending as SMS. This has been deprecated.
+                See `issue #4050 <https://github.com/LonamiWebs/Telethon/issues/4050>`_ for context.
 
         Returns
             An instance of :tl:`SentCode`.
@@ -508,6 +414,10 @@ async def send_code_request(
                 sent = await client.send_code_request(phone)
                 print(sent)
         """
+        if force_sms:
+            warnings.warn('force_sms has been deprecated and no longer works')
+            force_sms = False
+
         result = None
         phone = utils.parse_phone(phone) or self._phone
         phone_hash = self._phone_code_hash.get(phone)

telethon/client/downloads.py

@@ -223,7 +223,8 @@ async def download_profile_photo(
                 The output file path, directory, or stream-like object.
                 If the path exists and is a file, it will be overwritten.
                 If file is the type `bytes`, it will be downloaded in-memory
-                as a bytestring (e.g. ``file=bytes``).
+                and returned as a bytestring (i.e. ``file=bytes``, without
+                parentheses or quotes).
 
             download_big (`bool`, optional):
                 Whether to use the big version of the available photos.
@@ -335,7 +336,8 @@ async def download_media(
                 The output file path, directory, or stream-like object.
                 If the path exists and is a file, it will be overwritten.
                 If file is the type `bytes`, it will be downloaded in-memory
-                as a bytestring (e.g. ``file=bytes``).
+                and returned as a bytestring (i.e. ``file=bytes``, without
+                parentheses or quotes).
 
             progress_callback (`callable`, optional):
                 A callback function accepting two parameters:
@@ -378,6 +380,9 @@ async def download_media(
                 path = await message.download_media()
                 await message.download_media(filename)
 
+                # Downloading to memory
+                blob = await client.download_media(message, bytes)
+
                 # Printing download progress
                 def callback(current, total):
                     print('Downloaded', current, 'out of', total,

telethon/events/chataction.py

@@ -108,6 +108,17 @@ def build(cls, update, others=None, self_id=None):
                 return cls.Event(msg,
                                  new_score=action.score)
 
+        elif isinstance(update, types.UpdateChannelParticipant) \
+                and bool(update.new_participant) != bool(update.prev_participant):
+            # If members are hidden, bots will receive this update instead,
+            # as there won't be a service message. Promotions and demotions
+            # seem to have both new and prev participant, which are ignored
+            # by this event.
+            return cls.Event(types.PeerChannel(update.channel_id),
+                             users=update.user_id,
+                             added_by=update.actor_id if update.new_participant else None,
+                             kicked_by=update.actor_id if update.prev_participant else None)
+
     class Event(EventCommon):
         """
         Represents the event of a new chat action.
@@ -142,7 +153,7 @@ class Event(EventCommon):
 
             new_title (`str`, optional):
                 The new title string for the chat, if applicable.
-            
+
             new_score (`str`, optional):
                 The new score string for the game, if applicable.
 

telethon_examples/interactive_telegram_client.py

@@ -120,7 +120,7 @@ async def init(self):
             print('Initial connection failed. Retrying...')
             await self.connect()
 
-        # If the user hasn't called .sign_in() or .sign_up() yet, they won't
+        # If the user hasn't called .sign_in() yet, they won't
         # be authorized. The first thing you must do is authorize. Calling
         # .sign_in() should only be done once as the information is saved on
         # the *.session file so you don't need to enter the code every time.

telethon_generator/data/errors.csv

@@ -427,6 +427,7 @@ STICKER_FILE_INVALID,400,Sticker file invalid
 STICKER_GIF_DIMENSIONS,400,The specified video sticker has invalid dimensions
 STICKER_ID_INVALID,400,The provided sticker ID is invalid
 STICKER_INVALID,400,The provided sticker is invalid
+STICKER_MIME_INVALID,400,Make sure to pass a valid image file for the right InputFile parameter
 STICKER_PNG_DIMENSIONS,400,Sticker png dimensions invalid
 STICKER_PNG_NOPNG,400,Stickers must be a png file but the used image was not a png
 STICKER_TGS_NODOC,400,You must send the animated sticker as a document

telethon_generator/data/friendly.csv

@@ -1,7 +1,6 @@
 ns,friendly,raw
 account.AccountMethods,takeout,invokeWithTakeout account.initTakeoutSession account.finishTakeoutSession
 auth.AuthMethods,sign_in,auth.signIn auth.importBotAuthorization
-auth.AuthMethods,sign_up,auth.signUp
 auth.AuthMethods,send_code_request,auth.sendCode auth.resendCode
 auth.AuthMethods,log_out,auth.logOut
 auth.AuthMethods,edit_2fa,account.updatePasswordSettings

telethon_generator/data/methods.csv

@@ -332,7 +332,7 @@ phone.toggleGroupCallSettings,user,GROUPCALL_NOT_MODIFIED
 photos.deletePhotos,user,
 photos.getUserPhotos,both,MAX_ID_INVALID USER_ID_INVALID
 photos.updateProfilePhoto,user,PHOTO_ID_INVALID
-photos.uploadProfilePhoto,user,ALBUM_PHOTOS_TOO_MANY FILE_PARTS_INVALID IMAGE_PROCESS_FAILED PHOTO_CROP_SIZE_SMALL PHOTO_EXT_INVALID VIDEO_FILE_INVALID
+photos.uploadProfilePhoto,user,ALBUM_PHOTOS_TOO_MANY FILE_PARTS_INVALID IMAGE_PROCESS_FAILED PHOTO_CROP_SIZE_SMALL PHOTO_EXT_INVALID STICKER_MIME_INVALID VIDEO_FILE_INVALID
 ping,both,
 reqDHParams,both,
 reqPq,both,