Fix broken links, add more examples and a new section

readthedocs/extra/basic/entities.rst

@@ -20,6 +20,13 @@ in response to certain methods, such as :tl:`GetUsersRequest`.
     or even entire :tl:`User`, :tl:`Chat` and :tl:`Channel` objects and even
     phone numbers from people you have in your contacts.
 
+    To "encounter" an ID, you would have to "find it" like you would in the
+    normal app. If the peer is in your dialogs, you would need to
+    `client.get_dialogs() <telethon.telegram_client.TelegramClient.get_dialogs>`.
+    If the peer is someone in a group, you would similarly
+    `client.get_participants(group) <telethon.telegram_client.TelegramClient.get_participants>`.
+
+
 Getting entities
 ****************
 

readthedocs/extra/basic/telegram-client.rst

@@ -58,6 +58,11 @@ Many other common methods for quick scripts are also available:
         # Note that you can use 'me' or 'self' to message yourself
         client.send_message('username', 'Hello World from Telethon!')
 
+        # .send_message's parse mode defaults to markdown, so you
+        # can use **bold**, __italics__, [links](https://example.com), `code`,
+        # and even [mentions](@username)/[mentions](tg://user?id=123456789)
+        client.send_message('username', '**Using** __markdown__ `too`!')
+
         client.send_file('username', '/home/myself/Pictures/holidays.jpg')
 
         # The utils package has some goodies, like .get_display_name()
@@ -83,15 +88,16 @@ a single line.
 Available methods
 *****************
 
-This page lists all the "handy" methods available for you to use in the
+The :ref:`reference <telethon-package>` lists all the "handy" methods
-``TelegramClient`` class. These are simply wrappers around the "raw"
+available for you to use in the ``TelegramClient`` class. These are simply
-Telegram API, making it much more manageable and easier to work with.
+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.
 
-To see the methods available in the client, see :ref:`telethon-package`.
+See the mentioned :ref:`telethon-package` to find the available methods.
 
 .. _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

readthedocs/extra/examples/chats-and-channels.rst

@@ -35,6 +35,10 @@ to, you can make use of the `JoinChannelRequest`__ to join such channel:
 For more on channels, check the `channels namespace`__.
 
 
+__ https://lonamiwebs.github.io/Telethon/methods/channels/join_channel.html
+__ https://lonamiwebs.github.io/Telethon/methods/channels/index.html
+
+
 Joining a private chat or channel
 *********************************
 
@@ -51,6 +55,9 @@ example, is the ``hash`` of the chat or channel. Now you can use
         updates = client(ImportChatInviteRequest('AAAAAEHbEkejzxUjAUCfYg'))
 
 
+__ https://lonamiwebs.github.io/Telethon/methods/messages/import_chat_invite.html
+
+
 Adding someone else to such chat or channel
 *******************************************
 
@@ -63,13 +70,15 @@ use is very straightforward, or `InviteToChannelRequest`__ for channels:
         # For normal chats
         from telethon.tl.functions.messages import AddChatUserRequest
 
+        # Note that ``user_to_add`` is NOT the name of the parameter.
+        # It's the user you want to add (``user_id=user_to_add``).
         client(AddChatUserRequest(
             chat_id,
             user_to_add,
             fwd_limit=10  # Allow the user to see the 10 last messages
         ))
 
-        # For channels
+        # For channels (which includes megagroups)
         from telethon.tl.functions.channels import InviteToChannelRequest
 
         client(InviteToChannelRequest(
@@ -78,6 +87,9 @@ use is very straightforward, or `InviteToChannelRequest`__ for channels:
         ))
 
 
+__ https://lonamiwebs.github.io/Telethon/methods/messages/add_chat_user.html
+__ https://lonamiwebs.github.io/Telethon/methods/channels/invite_to_channel.html
+
 
 Checking a link without joining
 *******************************
@@ -86,14 +98,7 @@ 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/channels/invite_to_channel.html
 __ https://lonamiwebs.github.io/Telethon/methods/messages/check_chat_invite.html
 
 
@@ -151,7 +156,7 @@ 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/input_channel.html
 __ https://lonamiwebs.github.io/Telethon/types/channel_participants_filter.html
 __ https://lonamiwebs.github.io/Telethon/constructors/channel_participants_search.html
 __ https://github.com/LonamiWebs/Telethon/issues/573
@@ -208,20 +213,88 @@ Giving or revoking admin permissions can be done with the `EditAdminRequest`__:
 
         # User will now be able to change group info, delete other people's
         # messages and pin messages.
-        
+
-|  Thanks to `@Kyle2142`__ for `pointing out`__ that you **cannot** set all
+
-|  parameters to ``True`` to give a user full permissions, as not all
+.. note::
-|  permissions are related to both broadcast channels/megagroups.
+
-|
+    Thanks to `@Kyle2142`__ for `pointing out`__ that you **cannot** set all
-|  E.g. trying to set ``post_messages=True`` in a megagroup will raise an
+    parameters to ``True`` to give a user full permissions, as not all
-|  error. It is recommended to always use keyword arguments, and to set only
+    permissions are related to both broadcast channels/megagroups.
-|  the permissions the user needs. If you don't need to change a permission,
+
-|  it can be omitted (full list `here`__).
+    E.g. trying to set ``post_messages=True`` in a megagroup will raise an
+    error. It is recommended to always use keyword arguments, and to set only
+    the permissions the user needs. If you don't need to change a permission,
+    it can be omitted (full list `here`__).
+
+
+Restricting Users
+*****************
+
+Similar to how you give or revoke admin permissions, you can edit the
+banned rights of an user through `EditAdminRequest`__ and its parameter
+`ChannelBannedRights`__:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.channels import EditBannedRequest
+        from telethon.tl.types import ChannelBannedRights
+
+        from datetime import datetime, timedelta
+
+        # Restricting an user for 7 days, only allowing view/send messages.
+        #
+        # Note that it's "reversed". You must set to ``True`` the permissions
+        # you want to REMOVE, and leave as ``None`` those you want to KEEP.
+        rights = ChannelBannedRights(
+            until_date=datetime.now() + timedelta(days=7),
+            view_messages=None,
+            send_messages=None,
+            send_media=True,
+            send_stickers=True,
+            send_gifs=True,
+            send_games=True,
+            send_inline=True,
+            embed_links=True
+        )
+
+        # The above is equivalent to
+        rights = ChannelBannedRights(
+            until_date=datetime.now() + timedelta(days=7),
+            send_media=True,
+            send_stickers=True,
+            send_gifs=True,
+            send_games=True,
+            send_inline=True,
+            embed_links=True
+        )
+
+        client(EditBannedRequest(channel, user, rights))
+
+
+Kicking a member
+****************
+
+Telegram doesn't actually have a request to kick an user from a group.
+Instead, you need to restrict them so they can't see messages. Any date
+is enough:
+
+    .. code-block:: python
+
+        from telethon.tl.functions.channels import EditBannedRequest
+        from telethon.tl.types import ChannelBannedRights
+
+        client(EditBannedRequest(channel, user, ChannelBannedRights(
+            until_date=None,
+            view_messages=True
+        )))
+
 
 __ 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
+__ https://lonamiwebs.github.io/Telethon/methods/channels/edit_banned.html
+__ https://lonamiwebs.github.io/Telethon/constructors/channel_banned_rights.html
 
 
 Increasing View Count in a Channel

readthedocs/extra/examples/projects-using-telethon.rst

@@ -0,0 +1,41 @@
+=======================
+Projects using Telethon
+=======================
+
+This page lists some real world examples showcasing what can be built with
+the library.
+
+.. note::
+
+    Do you have a project that uses the library or know of any that's not
+    listed here? Feel free to leave a comment at
+    `issue 744 <https://github.com/LonamiWebs/Telethon/issues/744>`_
+    so it can be included in the next revision of the documentation!
+
+
+telegram-export
+***************
+
+`Link <https://github.com/expectocode/telegram-export>`_ /
+`Author's website <https://github.com/expectocode>`_
+
+A tool to download Telegram data (users, chats, messages, and media)
+into a database (and display the saved data).
+
+
+mautrix-telegram
+****************
+
+`Link <https://github.com/tulir/mautrix-telegram>`_ /
+`Author's website <https://maunium.net/>`_
+
+A Matrix-Telegram hybrid puppeting/relaybot bridge.
+
+
+TelegramTUI
+***********
+
+`Link <https://github.com/bad-day/TelegramTUI>`_ /
+`Author's website <https://github.com/bad-day>`_
+
+A Telegram client on your terminal.

readthedocs/index.rst

@@ -62,6 +62,7 @@ heavy job for you, so you can focus on developing an application.
    extra/examples/working-with-messages
    extra/examples/chats-and-channels
    extra/examples/bots
+   extra/examples/projects-using-telethon
 
 
 .. _Troubleshooting:

telethon/telegram_client.py

@@ -712,6 +712,13 @@ class TelegramClient(TelegramBareClient):
         """
         Sends the given message to the specified entity (user/chat/channel).
 
+        The default parse mode is the same as the official applications
+        (a custom flavour of markdown). ``**bold**, `code` or __italic__``
+        are available. In addition you can send ``[links](https://example.com)``
+        and ``[mentions](@username)`` (or using IDs like in the Bot API:
+        ``[mention](tg://user?id=123456789)``) and ``pre`` blocks with three
+        backticks.
+
         Args:
             entity (`entity`):
                 To who will it be sent.