diff --git a/docs/sitemap.py b/docs/sitemap.py index 4def886f..d4abeb32 100644 --- a/docs/sitemap.py +++ b/docs/sitemap.py @@ -27,6 +27,7 @@ dirs = { "start": ("weekly", 0.9), "api": ("weekly", 0.8), "topics": ("weekly", 0.8), + "releases": ("weekly", 0.8), "telegram": ("weekly", 0.6) } diff --git a/docs/source/topics/advanced-usage.rst b/docs/source/topics/advanced-usage.rst index ff1afa5c..9c794be0 100644 --- a/docs/source/topics/advanced-usage.rst +++ b/docs/source/topics/advanced-usage.rst @@ -103,9 +103,9 @@ sending messages with IDs only thanks to cached access hashes. There are three different InputPeer types, one for each kind of Telegram entity. Whenever an InputPeer is needed you must pass one of these: - - :class:`~pyrogram.api.types.InputPeerUser` - Users - - :class:`~pyrogram.api.types.InputPeerChat` - Basic Chats - - :class:`~pyrogram.api.types.InputPeerChannel` - Either Channels or Supergroups +- :class:`~pyrogram.api.types.InputPeerUser` - Users +- :class:`~pyrogram.api.types.InputPeerChat` - Basic Chats +- :class:`~pyrogram.api.types.InputPeerChannel` - Either Channels or Supergroups But you don't necessarily have to manually instantiate each object because, luckily for you, Pyrogram already provides :meth:`~pyrogram.Client.resolve_peer` as a convenience utility method that returns the correct InputPeer @@ -120,9 +120,9 @@ kind of ID. For example, given the ID *123456789*, here's how Pyrogram can tell entities apart: - - ``+ID`` User: *123456789* - - ``-ID`` Chat: *-123456789* - - ``-100ID`` Channel or Supergroup: *-100123456789* +- ``+ID`` User: *123456789* +- ``-ID`` Chat: *-123456789* +- ``-100ID`` Channel or Supergroup: *-100123456789* So, every time you take a raw ID, make sure to translate it into the correct ID when you want to use it with an high-level method. diff --git a/docs/source/topics/config-file.rst b/docs/source/topics/config-file.rst index 14ae9fb6..a28025db 100644 --- a/docs/source/topics/config-file.rst +++ b/docs/source/topics/config-file.rst @@ -1,14 +1,14 @@ Configuration File ================== -As already mentioned in previous sections, Pyrogram can be configured by the use of an INI file. -This page explains how this file is structured in Pyrogram, how to use it and why. +As already mentioned in previous pages, Pyrogram can be configured by the use of an INI file. +This page explains how this file is structured, how to use it and why. Introduction ------------ The idea behind using a configuration file is to help keeping your code free of private settings information such as -the API Key and Proxy without having you to even deal with how to load such settings. The configuration file, usually +the API Key and Proxy, without having you to even deal with how to load such settings. The configuration file, usually referred as ``config.ini`` file, is automatically loaded from the root of your working directory; all you need to do is fill in the necessary parts. diff --git a/docs/source/topics/create-filters.rst b/docs/source/topics/create-filters.rst index 0252221c..6cb33a50 100644 --- a/docs/source/topics/create-filters.rst +++ b/docs/source/topics/create-filters.rst @@ -13,9 +13,10 @@ Custom Filters -------------- An example to demonstrate how custom filters work is to show how to create and use one for the -:class:`~pyrogram.CallbackQueryHandler`. Note that callback queries updates are only received by bots; create and -:doc:`authorize your bot <../start/auth>`, then send a message with an inline keyboard to yourself. This allows you to -test your filter by pressing the inline button: +:class:`~pyrogram.CallbackQueryHandler`. Note that callback queries updates are only received by bots as result of a +user pressing an inline button attached to the bot's message; create and :doc:`authorize your bot <../start/auth>`, +then send a message with an inline keyboard to yourself. This allows you to test your filter by pressing the inline +button: .. code-block:: python @@ -25,7 +26,7 @@ test your filter by pressing the inline button: "username", # Change this to your username or id "Pyrogram's custom filter test", reply_markup=InlineKeyboardMarkup( - [[InlineKeyboardButton("Press me", b"pyrogram")]] + [[InlineKeyboardButton("Press me", "pyrogram")]] ) ) @@ -36,13 +37,13 @@ For this basic filter we will be using only the first two parameters of :meth:`~ The code below creates a simple filter for hardcoded, static callback data. This filter will only allow callback queries containing "Pyrogram" as data, that is, the function *func* you pass returns True in case the callback query data -equals to ``b"Pyrogram"``. +equals to ``"Pyrogram"``. .. code-block:: python static_data = Filters.create( name="StaticdData", - func=lambda flt, callback_query: callback_query.data == b"Pyrogram" + func=lambda flt, query: query.data == "Pyrogram" ) The ``lambda`` operator in python is used to create small anonymous functions and is perfect for this example, the same @@ -50,8 +51,8 @@ could be achieved with a normal function, but we don't really need it as it make .. code-block:: python - def func(flt, callback_query): - return callback_query.data == b"Pyrogram" + def func(flt, query): + return query.data == "Pyrogram" static_data = Filters.create( name="StaticData", @@ -63,8 +64,8 @@ The filter usage remains the same: .. code-block:: python @app.on_callback_query(static_data) - def pyrogram_data(client, callback_query): - client.answer_callback_query(callback_query.id, "it works!") + def pyrogram_data(_, query): + query.answer("it works!") Filters with Arguments ---------------------- @@ -79,14 +80,14 @@ This is how a dynamic custom filter looks like: def dynamic_data(data): return Filters.create( name="DynamicData", - func=lambda flt, callback_query: flt.data == callback_query.data, - data=data # "data" kwarg is accessed with "filter.data" + func=lambda flt, query: flt.data == query.data, + data=data # "data" kwarg is accessed with "flt.data" ) And its usage: .. code-block:: python - @app.on_callback_query(dynamic_data(b"Pyrogram")) - def pyrogram_data(client, callback_query): - client.answer_callback_query(callback_query.id, "it works!") \ No newline at end of file + @app.on_callback_query(dynamic_data("Pyrogram")) + def pyrogram_data(_, query): + query.answer("it works!") diff --git a/docs/source/topics/more-on-updates.rst b/docs/source/topics/more-on-updates.rst index df0aff7d..f23e692e 100644 --- a/docs/source/topics/more-on-updates.rst +++ b/docs/source/topics/more-on-updates.rst @@ -29,7 +29,7 @@ For example, take these two handlers: print("Just Text") Here, ``just_text`` is never executed because ``text_or_sticker``, which has been registered first, already handles -texts (``Filters.text`` is shared and conflicting). To enable it, register the function using a different group: +texts (``Filters.text`` is shared and conflicting). To enable it, register the handler using a different group: .. code-block:: python @@ -37,7 +37,7 @@ texts (``Filters.text`` is shared and conflicting). To enable it, register the f def just_text(client, message): print("Just Text") -Or, if you want ``just_text`` to be fired *before* ``text_or_sticker`` (note ``-1``, which is less than ``0``): +Or, if you want ``just_text`` to be executed *before* ``text_or_sticker`` (note ``-1``, which is less than ``0``): .. code-block:: python diff --git a/docs/source/topics/use-filters.rst b/docs/source/topics/use-filters.rst index c23a98df..d481b393 100644 --- a/docs/source/topics/use-filters.rst +++ b/docs/source/topics/use-filters.rst @@ -25,7 +25,8 @@ Let's start right away with a simple example: def my_handler(client, message): print(message) -- or, without decorators. Here filters are passed as the second argument of the handler constructor: +- or, without decorators. Here filters are passed as the second argument of the handler constructor; the first is the + callback function itself: .. code-block:: python :emphasize-lines: 8 diff --git a/pyrogram/__init__.py b/pyrogram/__init__.py index 1269174c..ddf7c275 100644 --- a/pyrogram/__init__.py +++ b/pyrogram/__init__.py @@ -24,7 +24,7 @@ if sys.version_info[:3] in [(3, 5, 0), (3, 5, 1), (3, 5, 2)]: # Monkey patch the standard "typing" module because Python versions from 3.5.0 to 3.5.2 have a broken one. sys.modules["typing"] = typing -__version__ = "0.13.0-asyncio" +__version__ = "0.14.0-asyncio" __license__ = "GNU Lesser General Public License v3 or later (LGPLv3+)" __copyright__ = "Copyright (C) 2017-2019 Dan " diff --git a/pyrogram/client/methods/decorators/on_callback_query.py b/pyrogram/client/methods/decorators/on_callback_query.py index 5057f59f..1552bae7 100644 --- a/pyrogram/client/methods/decorators/on_callback_query.py +++ b/pyrogram/client/methods/decorators/on_callback_query.py @@ -32,10 +32,11 @@ class OnCallbackQuery(BaseClient): ) -> callable: """Decorator for handling callback queries. - This does the same thing as :meth:`~Client.add_handler` using the :obj:`CallbackQueryHandler`. + This does the same thing as :meth:`~pyrogram.Client.add_handler` using the + :obj:`~pyrogram.CallbackQueryHandler`. Parameters: - filters (:obj:`Filters`): + filters (:obj:`~pyrogram.Filters`, *optional*): Pass one or more filters to allow only a subset of callback queries to be passed in your function. diff --git a/pyrogram/client/methods/decorators/on_deleted_messages.py b/pyrogram/client/methods/decorators/on_deleted_messages.py index 53457b55..0d87ba5a 100644 --- a/pyrogram/client/methods/decorators/on_deleted_messages.py +++ b/pyrogram/client/methods/decorators/on_deleted_messages.py @@ -32,10 +32,11 @@ class OnDeletedMessages(BaseClient): ) -> callable: """Decorator for handling deleted messages. - This does the same thing as :meth:`~Client.add_handler` using the :obj:`DeletedMessagesHandler`. + This does the same thing as :meth:`~pyrogram.Client.add_handler` using the + :obj:`~pyrogram.DeletedMessagesHandler`. Parameters: - filters (:obj:`Filters`): + filters (:obj:`~pyrogram.Filters`, *optional*): Pass one or more filters to allow only a subset of messages to be passed in your function. diff --git a/pyrogram/client/methods/decorators/on_disconnect.py b/pyrogram/client/methods/decorators/on_disconnect.py index b195ac54..4a514a41 100644 --- a/pyrogram/client/methods/decorators/on_disconnect.py +++ b/pyrogram/client/methods/decorators/on_disconnect.py @@ -25,7 +25,7 @@ class OnDisconnect(BaseClient): def on_disconnect(self=None) -> callable: """Decorator for handling disconnections. - This does the same thing as :meth:`~Client.add_handler` using the :obj:`DisconnectHandler`. + This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.DisconnectHandler`. """ def decorator(func: callable) -> Handler: diff --git a/pyrogram/client/methods/decorators/on_inline_query.py b/pyrogram/client/methods/decorators/on_inline_query.py index ee7175eb..adc65d25 100644 --- a/pyrogram/client/methods/decorators/on_inline_query.py +++ b/pyrogram/client/methods/decorators/on_inline_query.py @@ -32,10 +32,10 @@ class OnInlineQuery(BaseClient): ) -> callable: """Decorator for handling inline queries. - This does the same thing as :meth:`~Client.add_handler` using the :obj:`InlineQueryHandler`. + This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.InlineQueryHandler`. Parameters: - filters (:obj:`Filters `): + filters (:obj:`~pyrogram.Filters`, *optional*): Pass one or more filters to allow only a subset of inline queries to be passed in your function. diff --git a/pyrogram/client/methods/decorators/on_message.py b/pyrogram/client/methods/decorators/on_message.py index 0f5c836c..758a6831 100644 --- a/pyrogram/client/methods/decorators/on_message.py +++ b/pyrogram/client/methods/decorators/on_message.py @@ -32,10 +32,10 @@ class OnMessage(BaseClient): ) -> callable: """Decorator for handling messages. - This does the same thing as :meth:`~Client.add_handler` using the :obj:`MessageHandler`. + This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.MessageHandler`. Parameters: - filters (:obj:`Filters`): + filters (:obj:`~pyrogram.Filters`, *optional*): Pass one or more filters to allow only a subset of messages to be passed in your function. diff --git a/pyrogram/client/methods/decorators/on_poll.py b/pyrogram/client/methods/decorators/on_poll.py index 7442858d..0ade42c0 100644 --- a/pyrogram/client/methods/decorators/on_poll.py +++ b/pyrogram/client/methods/decorators/on_poll.py @@ -32,10 +32,10 @@ class OnPoll(BaseClient): ) -> callable: """Decorator for handling poll updates. - This does the same thing as :meth:`~Client.add_handler` using the :obj:`PollHandler`. + This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.PollHandler`. Parameters: - filters (:obj:`Filters`): + filters (:obj:`~pyrogram.Filters`, *optional*): Pass one or more filters to allow only a subset of polls to be passed in your function. diff --git a/pyrogram/client/methods/decorators/on_raw_update.py b/pyrogram/client/methods/decorators/on_raw_update.py index e03402ca..7dff75fa 100644 --- a/pyrogram/client/methods/decorators/on_raw_update.py +++ b/pyrogram/client/methods/decorators/on_raw_update.py @@ -30,7 +30,7 @@ class OnRawUpdate(BaseClient): ) -> callable: """Decorator for handling raw updates. - This does the same thing as :meth:`~Client.add_handler` using the :obj:`RawUpdateHandler`. + This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.RawUpdateHandler`. Parameters: group (``int``, *optional*): diff --git a/pyrogram/client/methods/decorators/on_user_status.py b/pyrogram/client/methods/decorators/on_user_status.py index bcdcf024..09e037f7 100644 --- a/pyrogram/client/methods/decorators/on_user_status.py +++ b/pyrogram/client/methods/decorators/on_user_status.py @@ -31,10 +31,10 @@ class OnUserStatus(BaseClient): group: int = 0 ) -> callable: """Decorator for handling user status updates. - This does the same thing as :meth:`~Client.add_handler` using the :obj:`UserStatusHandler`. + This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.UserStatusHandler`. Parameters: - filters (:obj:`Filters`): + filters (:obj:`~pyrogram.Filters`, *optional*): Pass one or more filters to allow only a subset of UserStatus updated to be passed in your function. group (``int``, *optional*):