From 67e7468366098f79cd2aa4f88b40e6e47d93ae5a Mon Sep 17 00:00:00 2001 From: Bibo-Joshi <22366557+Bibo-Joshi@users.noreply.github.com> Date: Thu, 9 Jun 2022 17:22:32 +0200 Subject: [PATCH] Move Examples To Documentation (#3089) --- README.rst | 2 +- README_RAW.rst | 2 +- .../examples.arbitrarycallbackdatabot.rst | 7 + docs/source/examples.chatmemberbot.rst | 7 + docs/source/examples.contexttypesbot.rst | 7 + docs/source/examples.conversationbot.rst | 14 ++ docs/source/examples.conversationbot2.rst | 14 ++ docs/source/examples.customwebhookbot.rst | 7 + docs/source/examples.deeplinking.rst | 7 + docs/source/examples.echobot.rst | 7 + docs/source/examples.errorhandlerbot.rst | 7 + docs/source/examples.inlinebot.rst | 7 + docs/source/examples.inlinekeyboard.rst | 7 + docs/source/examples.inlinekeyboard2.rst | 7 + .../source/examples.nestedconversationbot.rst | 14 ++ docs/source/examples.passportbot.rst | 16 ++ docs/source/examples.paymentbot.rst | 7 + .../examples.persistentconversationbot.rst | 7 + docs/source/examples.pollbot.rst | 7 + docs/source/examples.rawapibot.rst | 11 + docs/source/examples.rst | 194 ++++++++++++++++++ docs/source/examples.timerbot.rst | 7 + docs/source/examples.webappbot.rst | 16 ++ docs/source/index.rst | 9 +- examples/README.md | 70 +------ examples/arbitrarycallbackdatabot.py | 2 +- examples/chatmemberbot.py | 2 +- examples/contexttypesbot.py | 2 +- examples/conversationbot.py | 2 +- examples/conversationbot2.py | 2 +- examples/customwebhookbot.py | 2 +- examples/deeplinking.py | 2 +- examples/echobot.py | 2 +- examples/errorhandlerbot.py | 2 +- examples/inlinebot.py | 2 +- examples/inlinekeyboard.py | 2 +- examples/inlinekeyboard2.py | 2 +- examples/nestedconversationbot.py | 2 +- examples/passportbot.py | 2 +- examples/paymentbot.py | 2 +- examples/persistentconversationbot.py | 2 +- examples/pollbot.py | 2 +- examples/rawapibot.py | 2 +- examples/timerbot.py | 2 +- examples/webappbot.py | 2 +- telegram/ext/_applicationbuilder.py | 15 +- telegram/ext/_conversationhandler.py | 6 +- 47 files changed, 416 insertions(+), 105 deletions(-) create mode 100644 docs/source/examples.arbitrarycallbackdatabot.rst create mode 100644 docs/source/examples.chatmemberbot.rst create mode 100644 docs/source/examples.contexttypesbot.rst create mode 100644 docs/source/examples.conversationbot.rst create mode 100644 docs/source/examples.conversationbot2.rst create mode 100644 docs/source/examples.customwebhookbot.rst create mode 100644 docs/source/examples.deeplinking.rst create mode 100644 docs/source/examples.echobot.rst create mode 100644 docs/source/examples.errorhandlerbot.rst create mode 100644 docs/source/examples.inlinebot.rst create mode 100644 docs/source/examples.inlinekeyboard.rst create mode 100644 docs/source/examples.inlinekeyboard2.rst create mode 100644 docs/source/examples.nestedconversationbot.rst create mode 100644 docs/source/examples.passportbot.rst create mode 100644 docs/source/examples.paymentbot.rst create mode 100644 docs/source/examples.persistentconversationbot.rst create mode 100644 docs/source/examples.pollbot.rst create mode 100644 docs/source/examples.rawapibot.rst create mode 100644 docs/source/examples.rst create mode 100644 docs/source/examples.timerbot.rst create mode 100644 docs/source/examples.webappbot.rst diff --git a/README.rst b/README.rst index e64417519..abca55dba 100644 --- a/README.rst +++ b/README.rst @@ -151,7 +151,7 @@ Resources - The `package documentation `_ is the technical reference for ``python-telegram-bot``. It contains descriptions of all available classes, modules, methods and arguments. - The `wiki `_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation. -- Our `examples directory `_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. +- Our `examples section `_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. Even if it is not your approach for learning, please take a look at ``echobot.py``. It is the de facto base for most of the bots out there. The code for these examples is released to the public domain, so you can start by grabbing the code and building on top of it. - The `official Telegram Bot API documentation `_ is of course always worth a read. diff --git a/README_RAW.rst b/README_RAW.rst index dd22b96c9..882ffd470 100644 --- a/README_RAW.rst +++ b/README_RAW.rst @@ -148,7 +148,7 @@ Resources - The `package documentation `_ is the technical reference for ``python-telegram-bot``. It contains descriptions of all available classes, modules, methods and arguments. - The `wiki `_ is home to number of more elaborate introductions of the different features of ``python-telegram-bot`` and other useful resources that go beyond the technical documentation. -- Our `examples directory `_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. +- Our `examples section `_ contains several examples that showcase the different features of both the Bot API and ``python-telegram-bot``. Even if it is not your approach for learning, please take a look at ``echobot.py``. It is the de facto base for most of the bots out there. The code for these examples is released to the public domain, so you can start by grabbing the code and building on top of it. - The `official Telegram Bot API documentation `_ is of course always worth a read. diff --git a/docs/source/examples.arbitrarycallbackdatabot.rst b/docs/source/examples.arbitrarycallbackdatabot.rst new file mode 100644 index 000000000..17eb22426 --- /dev/null +++ b/docs/source/examples.arbitrarycallbackdatabot.rst @@ -0,0 +1,7 @@ +``arbitrarycallbackdatabot.py`` +=============================== + +.. literalinclude:: ../../examples/arbitrarycallbackdatabot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.chatmemberbot.rst b/docs/source/examples.chatmemberbot.rst new file mode 100644 index 000000000..a913d3400 --- /dev/null +++ b/docs/source/examples.chatmemberbot.rst @@ -0,0 +1,7 @@ +``chatmemberbot.py`` +==================== + +.. literalinclude:: ../../examples/chatmemberbot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.contexttypesbot.rst b/docs/source/examples.contexttypesbot.rst new file mode 100644 index 000000000..62438ebc5 --- /dev/null +++ b/docs/source/examples.contexttypesbot.rst @@ -0,0 +1,7 @@ +``contexttypesbot.py`` +====================== + +.. literalinclude:: ../../examples/contexttypesbot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.conversationbot.rst b/docs/source/examples.conversationbot.rst new file mode 100644 index 000000000..ebd129ff2 --- /dev/null +++ b/docs/source/examples.conversationbot.rst @@ -0,0 +1,14 @@ +``conversationbot.py`` +====================== + +.. literalinclude:: ../../examples/conversationbot.py + :language: python + :linenos: + +.. _conversationbot-diagram: + +State Diagram +------------- + +.. image:: ../../examples/conversationbot.png + \ No newline at end of file diff --git a/docs/source/examples.conversationbot2.rst b/docs/source/examples.conversationbot2.rst new file mode 100644 index 000000000..b032cfc75 --- /dev/null +++ b/docs/source/examples.conversationbot2.rst @@ -0,0 +1,14 @@ +``conversationbot2.py`` +======================= + +.. literalinclude:: ../../examples/conversationbot2.py + :language: python + :linenos: + +.. _conversationbot2-diagram: + +State Diagram +------------- + +.. image:: ../../examples/conversationbot2.png + \ No newline at end of file diff --git a/docs/source/examples.customwebhookbot.rst b/docs/source/examples.customwebhookbot.rst new file mode 100644 index 000000000..95a5a70e5 --- /dev/null +++ b/docs/source/examples.customwebhookbot.rst @@ -0,0 +1,7 @@ +``customwebhookbot.py`` +======================= + +.. literalinclude:: ../../examples/customwebhookbot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.deeplinking.rst b/docs/source/examples.deeplinking.rst new file mode 100644 index 000000000..64960d5e5 --- /dev/null +++ b/docs/source/examples.deeplinking.rst @@ -0,0 +1,7 @@ +``deeplinking.py`` +================== + +.. literalinclude:: ../../examples/deeplinking.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.echobot.rst b/docs/source/examples.echobot.rst new file mode 100644 index 000000000..a4e2401d3 --- /dev/null +++ b/docs/source/examples.echobot.rst @@ -0,0 +1,7 @@ +``echobot.py`` +============== + +.. literalinclude:: ../../examples/echobot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.errorhandlerbot.rst b/docs/source/examples.errorhandlerbot.rst new file mode 100644 index 000000000..3df821033 --- /dev/null +++ b/docs/source/examples.errorhandlerbot.rst @@ -0,0 +1,7 @@ +``errorhandlerbot.py`` +====================== + +.. literalinclude:: ../../examples/errorhandlerbot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.inlinebot.rst b/docs/source/examples.inlinebot.rst new file mode 100644 index 000000000..dcf5df3fd --- /dev/null +++ b/docs/source/examples.inlinebot.rst @@ -0,0 +1,7 @@ +``inlinebot.py`` +================ + +.. literalinclude:: ../../examples/inlinebot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.inlinekeyboard.rst b/docs/source/examples.inlinekeyboard.rst new file mode 100644 index 000000000..16290cde3 --- /dev/null +++ b/docs/source/examples.inlinekeyboard.rst @@ -0,0 +1,7 @@ +``inlinekeyboard.py`` +===================== + +.. literalinclude:: ../../examples/inlinekeyboard.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.inlinekeyboard2.rst b/docs/source/examples.inlinekeyboard2.rst new file mode 100644 index 000000000..936b4dab2 --- /dev/null +++ b/docs/source/examples.inlinekeyboard2.rst @@ -0,0 +1,7 @@ +``inlinekeyboard2.py`` +====================== + +.. literalinclude:: ../../examples/inlinekeyboard2.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.nestedconversationbot.rst b/docs/source/examples.nestedconversationbot.rst new file mode 100644 index 000000000..48536591d --- /dev/null +++ b/docs/source/examples.nestedconversationbot.rst @@ -0,0 +1,14 @@ +``nestedconversationbot.py`` +============================ + +.. literalinclude:: ../../examples/nestedconversationbot.py + :language: python + :linenos: + +.. _nestedconversationbot-diagram: + +State Diagram +------------- + +.. image:: ../../examples/nestedconversationbot.png + \ No newline at end of file diff --git a/docs/source/examples.passportbot.rst b/docs/source/examples.passportbot.rst new file mode 100644 index 000000000..74c3306c8 --- /dev/null +++ b/docs/source/examples.passportbot.rst @@ -0,0 +1,16 @@ +``passportbot.py`` +================== + +.. literalinclude:: ../../examples/passportbot.py + :language: python + :linenos: + +.. _passportbot-html: + +HTML Page +--------- + +.. literalinclude:: ../../examples/passportbot.html + :language: html + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.paymentbot.rst b/docs/source/examples.paymentbot.rst new file mode 100644 index 000000000..dd6c158f2 --- /dev/null +++ b/docs/source/examples.paymentbot.rst @@ -0,0 +1,7 @@ +``paymentbot.py`` +================= + +.. literalinclude:: ../../examples/paymentbot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.persistentconversationbot.rst b/docs/source/examples.persistentconversationbot.rst new file mode 100644 index 000000000..07203fbe8 --- /dev/null +++ b/docs/source/examples.persistentconversationbot.rst @@ -0,0 +1,7 @@ +``persistentconversationbot.py`` +================================ + +.. literalinclude:: ../../examples/persistentconversationbot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.pollbot.rst b/docs/source/examples.pollbot.rst new file mode 100644 index 000000000..9fed7231a --- /dev/null +++ b/docs/source/examples.pollbot.rst @@ -0,0 +1,7 @@ +``pollbot.py`` +============== + +.. literalinclude:: ../../examples/pollbot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.rawapibot.rst b/docs/source/examples.rawapibot.rst new file mode 100644 index 000000000..61e66a6e2 --- /dev/null +++ b/docs/source/examples.rawapibot.rst @@ -0,0 +1,11 @@ +`rawapibot.py` +============== + +This example uses only the pure, "bare-metal" API wrapper. + + + +.. literalinclude:: ../../examples/rawapibot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 000000000..42a138199 --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,194 @@ +Examples +======== + +In this section we display small examples to show what a bot written with +``python-telegram-bot`` looks like. +Some bots focus on one specific +aspect of the Telegram Bot API while others focus on one of the +mechanics of this library. Except for the +:any:`examples.rawapibot` example, they all use the high-level +framework this library provides with the +:any:`telegram.ext ` submodule. + +All examples are licensed under the `CC0 +License `__ +and are therefore fully dedicated to the public domain. You can use them +as the base for your own bots without worrying about copyrights. + +Do note that we ignore one pythonic convention. Best practice would +dictate, in many handler callbacks function signatures, to replace the +argument ``context`` with an underscore, since ``context`` is an unused +local variable in those callbacks. However, since these are examples and +not having a name for that argument confuses beginners, we decided to +have it present. + +:any:`examples.echobot` +----------------------- + +This is probably the base for most of the bots made with +``python-telegram-bot``. It simply replies to each text message with a +message that contains the same text. + +:any:`examples.timerbot` +------------------------ + +This bot uses the +:class:`telegram.ext.JobQueue` +class to send timed messages. The user sets a timer by using ``/set`` +command with a specific time, for example ``/set 30``. The bot then sets +up a job to send a message to that user after 30 seconds. The user can +also cancel the timer by sending ``/unset``. To learn more about the +``JobQueue``, read `this wiki +article `__. + +:any:`examples.conversationbot` +------------------------------- + +A common task for a bot is to ask information from the user. In v5.0 of +this library, we introduced the +:class:`telegram.ext.ConversationHandler` +for that exact purpose. This example uses it to retrieve +user-information in a conversation-like style. To get a better +understanding, take a look at the :ref:`state diagrem `. + +:any:`examples.conversationbot2` +-------------------------------- + +A more complex example of a bot that uses the ``ConversationHandler``. +It is also more confusing. Good thing there is a :ref:`fancy state diagram `. +for this one, too! + +:any:`examples.nestedconversationbot` +------------------------------------- + +A even more complex example of a bot that uses the nested +``ConversationHandler``\ s. While it’s certainly not that complex that +you couldn’t built it without nested ``ConversationHanldler``\ s, it +gives a good impression on how to work with them. Of course, there is a +:ref:`fancy state diagram ` +for this example, too! + +:any:`examples.persistentconversationbot` +----------------------------------------- + +A basic example of a bot store conversation state and user_data over +multiple restarts. + +:any:`examples.inlinekeyboard` +------------------------------ + +This example sheds some light on inline keyboards, callback queries and +message editing. A wiki site explaining this examples lives +`here `__. + +:any:`examples.inlinekeyboard2` +------------------------------- + +A more complex example about inline keyboards, callback queries and +message editing. This example showcases how an interactive menu could be +build using inline keyboards. + +:any:`examples.deeplinking` +--------------------------- + +A basic example on how to use deeplinking with inline keyboards. + +:any:`examples.inlinebot` +------------------------- + +A basic example of an `inline +bot `__. Don’t forget to enable +inline mode with `@BotFather `_. + +:any:`examples.pollbot` +----------------------- + +This example sheds some light on polls, poll answers and the +corresponding handlers. + +:any:`examples.passportbot` +--------------------------- + +A basic example of a bot that can accept passports. Use in combination +with the :ref:`HTML page `. +Don’t forget to enable and configure payments with +`@BotFather `_. Check out this +`guide `__ +on Telegram passports in PTB. + +:any:`examples.paymentbot` +-------------------------- + +A basic example of a bot that can accept payments. Don’t forget to +enable and configure payments with +`@BotFather `_. + +:any:`examples.errorhandlerbot` +------------------------------- + +A basic example on how to set up a custom error handler. + +:any:`examples.chatmemberbot` +----------------------------- + +A basic example on how ``(my_)chat_member`` updates can be used. + +:any:`examples.webappbot` +------------------------- + +A basic example of how `Telegram +WebApps `__ can be used. Use in +combination with the :ref:`HTML page `. +For your convenience, this file is hosted by the PTB team such that you +don’t need to host it yourself. Uses the +`iro.js `__ JavaScript library to showcase a +user interface that is hard to achieve with native Telegram +functionality. + +:any:`examples.contexttypesbot` +------------------------------- + +This example showcases how ``telegram.ext.ContextTypes`` can be used to +customize the ``context`` argument of handler and job callbacks. + +:any:`examples.customwebhookbot` +-------------------------------- + +This example showcases how a custom webhook setup can be used in +combination with ``telegram.ext.Application``. + +:any:`examples.arbitrarycallbackdatabot` +---------------------------------------- + +This example showcases how PTBs “arbitrary callback data” feature can be +used. + +Pure API +-------- + +The :any:`examples.rawapibot` example example uses only the pure, “bare-metal” API wrapper. + +.. toctree:: + :hidden: + + examples.arbitrarycallbackdatabot + examples.chatmemberbot + examples.contexttypesbot + examples.conversationbot + examples.conversationbot2 + examples.customwebhookbot + examples.deeplinking + examples.echobot + examples.errorhandlerbot + examples.inlinebot + examples.inlinekeyboard + examples.inlinekeyboard2 + examples.nestedconversationbot + examples.passportbot + examples.paymentbot + examples.persistentconversationbot + examples.pollbot + examples.rawapibot + examples.timerbot + examples.webappbot + diff --git a/docs/source/examples.timerbot.rst b/docs/source/examples.timerbot.rst new file mode 100644 index 000000000..89f29fb09 --- /dev/null +++ b/docs/source/examples.timerbot.rst @@ -0,0 +1,7 @@ +``timerbot.py`` +=============== + +.. literalinclude:: ../../examples/timerbot.py + :language: python + :linenos: + \ No newline at end of file diff --git a/docs/source/examples.webappbot.rst b/docs/source/examples.webappbot.rst new file mode 100644 index 000000000..55a814130 --- /dev/null +++ b/docs/source/examples.webappbot.rst @@ -0,0 +1,16 @@ +``webappbot.py`` +================ + +.. literalinclude:: ../../examples/webappbot.py + :language: python + :linenos: + +.. _webappbot-html: + +HTML Page +--------- + +.. literalinclude:: ../../examples/webappbot.html + :language: html + :linenos: + \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index d3b743c2b..c9e356dc7 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,7 +5,7 @@ .. include:: ../../README.rst -.. The toctrees are hidden such that they don't reander on the start page but still include the contents into the documentation. +.. The toctrees are hidden such that they don't render on the start page but still include the contents into the documentation. .. toctree:: :hidden: @@ -16,6 +16,13 @@ telegram_auxil Telegrams Bot API Docs +.. toctree:: + :hidden: + :caption: Resources + + examples + Wiki + .. toctree:: :hidden: :caption: Project diff --git a/examples/README.md b/examples/README.md index 1afaeec4d..78c907eaf 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,71 +1,5 @@ # Examples -## ⚠️ The examples in this directory are subject to changes and may not work on the PTB version that you are using. You can find the examples compatible with a specific version at https://github.com/python-telegram-bot/python-telegram-bot/tree/v/examples -In this folder are small examples to show what a bot written with `python-telegram-bot` looks like. Some bots focus on one specific aspect of the Telegram Bot API while others focus on one of the mechanics of this library. Except for the [`rawapibot.py`](#pure-api) example, they all use the high-level framework this library provides with the [`telegram.ext`](https://docs.python-telegram-bot.org/telegram.ext.html) submodule. +A description of the examples in this directory can be found in the [documentation](https://docs.python-telegram-bot.org/examples.html). -All examples are licensed under the [CC0 License](LICENSE.txt) and are therefore fully dedicated to the public domain. You can use them as the base for your own bots without worrying about copyrights. - -Do note that we ignore one pythonic convention. Best practice would dictate, in many handler callbacks function signatures, to replace the argument `context` with an underscore, since `context` is an unused local variable in those callbacks. However, since these are examples and not having a name for that argument confuses beginners, we decided to have it present. - -### [`echobot.py`](echobot.py) -This is probably the base for most of the bots made with `python-telegram-bot`. It simply replies to each text message with a message that contains the same text. - -### [`timerbot.py`](timerbot.py) -This bot uses the [`JobQueue`](https://docs.python-telegram-bot.org/telegram.ext.jobqueue.html) class to send timed messages. The user sets a timer by using `/set` command with a specific time, for example `/set 30`. The bot then sets up a job to send a message to that user after 30 seconds. The user can also cancel the timer by sending `/unset`. To learn more about the `JobQueue`, read [this wiki article](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Extensions-%E2%80%93-JobQueue). - -### [`conversationbot.py`](conversationbot.py) -A common task for a bot is to ask information from the user. In v5.0 of this library, we introduced the [`ConversationHandler`](https://docs.python-telegram-bot.org/telegram.ext.conversationhandler.html) for that exact purpose. This example uses it to retrieve user-information in a conversation-like style. To get a better understanding, take a look at the [state diagram](conversationbot.png). - -### [`conversationbot2.py`](conversationbot2.py) -A more complex example of a bot that uses the `ConversationHandler`. It is also more confusing. Good thing there is a [fancy state diagram](conversationbot2.png) for this one, too! - -### [`nestedconversationbot.py`](nestedconversationbot.py) -A even more complex example of a bot that uses the nested `ConversationHandler`s. While it's certainly not that complex that you couldn't built it without nested `ConversationHanldler`s, it gives a good impression on how to work with them. Of course, there is a [fancy state diagram](nestedconversationbot.png) for this example, too! - -### [`persistentconversationbot.py`](persistentconversationbot.py) -A basic example of a bot store conversation state and user_data over multiple restarts. - -### [`inlinekeyboard.py`](inlinekeyboard.py) -This example sheds some light on inline keyboards, callback queries and message editing. A wiki site explaining this examples lives [here](https://github.com/python-telegram-bot/python-telegram-bot/wiki/InlineKeyboard-Example). - -### [`inlinekeyboard2.py`](inlinekeyboard2.py) -A more complex example about inline keyboards, callback queries and message editing. This example showcases how an interactive menu could be build using inline keyboards. - -### [`deeplinking.py`](deeplinking.py) -A basic example on how to use deeplinking with inline keyboards. - -### [`inlinebot.py`](inlinebot.py) -A basic example of an [inline bot](https://core.telegram.org/bots/inline). Don't forget to enable inline mode with [@BotFather](https://t.me/BotFather). - -### [`pollbot.py`](pollbot.py) -This example sheds some light on polls, poll answers and the corresponding handlers. - -### [`passportbot.py`](passportbot.py) -A basic example of a bot that can accept passports. Use in combination with [`passportbot.html`](passportbot.html). Don't forget to enable and configure payments with [@BotFather](https://t.me/BotFather). Check out this [guide](https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Passport) on Telegram passports in PTB. - -### [`paymentbot.py`](paymentbot.py) -A basic example of a bot that can accept payments. Don't forget to enable and configure payments with [@BotFather](https://t.me/BotFather). - -### [`errorhandlerbot.py`](errorhandlerbot.py) -A basic example on how to set up a custom error handler. - -### [`chatmemberbot.py`](chatmemberbot.py) -A basic example on how `(my_)chat_member` updates can be used. - -### [`webappbot.py`](webappbot.py) -A basic example of how [Telegram WebApps](https://core.telegram.org/bots/webapps) can be used. -Use in combination with [`webappbot.html`](webappbot.html). -For your convenience, this file is hosted by the PTB team such that you don't need to host it yourself. -Uses the [`iro.js`](https://iro.js.org) JavaScript library to showcase a user interface that is hard to achieve with native Telegram functionality. - -### [`contexttypesbot.py`](contexttypesbot.py) -This example showcases how `telegram.ext.ContextTypes` can be used to customize the `context` argument of handler and job callbacks. - -### [`customwebhookbot.py`](customwebhookbot.py) -This example showcases how a custom webhook setup can be used in combination with `telegram.ext.Application`. - -### [`arbitrarycallbackdatabot.py`](arbitrarycallbackdatabot.py) -This example showcases how PTBs "arbitrary callback data" feature can be used. - -## Pure API -The [`rawapibot.py`](rawapibot.py) example uses only the pure, "bare-metal" API wrapper. +All examples are licensed under the [CC0 License](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/LICENSE.txt) and are therefore fully dedicated to the public domain. You can use them as the base for your own bots without worrying about copyrights. \ No newline at end of file diff --git a/examples/arbitrarycallbackdatabot.py b/examples/arbitrarycallbackdatabot.py index 5c2dbc2c4..0b0ffa1d7 100644 --- a/examples/arbitrarycallbackdatabot.py +++ b/examples/arbitrarycallbackdatabot.py @@ -21,7 +21,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update from telegram.ext import ( diff --git a/examples/chatmemberbot.py b/examples/chatmemberbot.py index 315632750..952145754 100644 --- a/examples/chatmemberbot.py +++ b/examples/chatmemberbot.py @@ -25,7 +25,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import Chat, ChatMember, ChatMemberUpdated, Update from telegram.constants import ParseMode diff --git a/examples/contexttypesbot.py b/examples/contexttypesbot.py index ee28fad1e..75c541bd8 100644 --- a/examples/contexttypesbot.py +++ b/examples/contexttypesbot.py @@ -25,7 +25,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update from telegram.constants import ParseMode diff --git a/examples/conversationbot.py b/examples/conversationbot.py index e74d7ce7c..a323ab8c1 100644 --- a/examples/conversationbot.py +++ b/examples/conversationbot.py @@ -27,7 +27,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update from telegram.ext import ( diff --git a/examples/conversationbot2.py b/examples/conversationbot2.py index fcbcdcca3..14491bf5e 100644 --- a/examples/conversationbot2.py +++ b/examples/conversationbot2.py @@ -28,7 +28,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update from telegram.ext import ( diff --git a/examples/customwebhookbot.py b/examples/customwebhookbot.py index bc7538301..c129e41eb 100644 --- a/examples/customwebhookbot.py +++ b/examples/customwebhookbot.py @@ -36,7 +36,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import Update diff --git a/examples/deeplinking.py b/examples/deeplinking.py index 0dd0f66aa..990bd5995 100644 --- a/examples/deeplinking.py +++ b/examples/deeplinking.py @@ -31,7 +31,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update, helpers from telegram.constants import ParseMode diff --git a/examples/echobot.py b/examples/echobot.py index c2b8a2a3d..6aa369cae 100644 --- a/examples/echobot.py +++ b/examples/echobot.py @@ -28,7 +28,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import ForceReply, Update from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters diff --git a/examples/errorhandlerbot.py b/examples/errorhandlerbot.py index e369a6765..404000e5f 100644 --- a/examples/errorhandlerbot.py +++ b/examples/errorhandlerbot.py @@ -19,7 +19,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import Update from telegram.constants import ParseMode diff --git a/examples/inlinebot.py b/examples/inlinebot.py index 901b69e09..4f07abcaa 100644 --- a/examples/inlinebot.py +++ b/examples/inlinebot.py @@ -29,7 +29,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import InlineQueryResultArticle, InputTextMessageContent, Update from telegram.constants import ParseMode diff --git a/examples/inlinekeyboard.py b/examples/inlinekeyboard.py index 5189e773f..517f810b4 100644 --- a/examples/inlinekeyboard.py +++ b/examples/inlinekeyboard.py @@ -19,7 +19,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update from telegram.ext import Application, CallbackQueryHandler, CommandHandler, ContextTypes diff --git a/examples/inlinekeyboard2.py b/examples/inlinekeyboard2.py index 78486c5cb..d40381588 100644 --- a/examples/inlinekeyboard2.py +++ b/examples/inlinekeyboard2.py @@ -27,7 +27,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update from telegram.ext import ( diff --git a/examples/nestedconversationbot.py b/examples/nestedconversationbot.py index ec27717a8..684ee157a 100644 --- a/examples/nestedconversationbot.py +++ b/examples/nestedconversationbot.py @@ -28,7 +28,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update from telegram.ext import ( diff --git a/examples/passportbot.py b/examples/passportbot.py index f6cd24942..ab466f669 100644 --- a/examples/passportbot.py +++ b/examples/passportbot.py @@ -25,7 +25,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import Update from telegram.ext import Application, ContextTypes, MessageHandler, filters diff --git a/examples/paymentbot.py b/examples/paymentbot.py index 09afa7c3e..d2206b7be 100644 --- a/examples/paymentbot.py +++ b/examples/paymentbot.py @@ -17,7 +17,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import LabeledPrice, ShippingOption, Update from telegram.ext import ( diff --git a/examples/persistentconversationbot.py b/examples/persistentconversationbot.py index 1814835db..cd62cf7c6 100644 --- a/examples/persistentconversationbot.py +++ b/examples/persistentconversationbot.py @@ -28,7 +28,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update from telegram.ext import ( diff --git a/examples/pollbot.py b/examples/pollbot.py index 19fd2c6db..4ced581b6 100644 --- a/examples/pollbot.py +++ b/examples/pollbot.py @@ -20,7 +20,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import ( KeyboardButton, diff --git a/examples/rawapibot.py b/examples/rawapibot.py index b2911ed0d..19c136e3f 100644 --- a/examples/rawapibot.py +++ b/examples/rawapibot.py @@ -21,7 +21,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import Bot from telegram.error import Forbidden, NetworkError diff --git a/examples/timerbot.py b/examples/timerbot.py index d468dbe14..02d2af7fe 100644 --- a/examples/timerbot.py +++ b/examples/timerbot.py @@ -31,7 +31,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import Update from telegram.ext import Application, CommandHandler, ContextTypes diff --git a/examples/webappbot.py b/examples/webappbot.py index e2d47cc38..011d9dae6 100644 --- a/examples/webappbot.py +++ b/examples/webappbot.py @@ -22,7 +22,7 @@ if __version_info__ < (20, 0, 0, "alpha", 1): raise RuntimeError( f"This example is not compatible with your current PTB version {TG_VER}. To view the " f"{TG_VER} version of this example, " - f"visit https://github.com/python-telegram-bot/python-telegram-bot/tree/v{TG_VER}/examples" + f"visit https://docs.python-telegram-bot.org/en/v{TG_VER}/examples.html" ) from telegram import KeyboardButton, ReplyKeyboardMarkup, ReplyKeyboardRemove, Update, WebAppInfo from telegram.ext import Application, CommandHandler, ContextTypes, MessageHandler, filters diff --git a/telegram/ext/_applicationbuilder.py b/telegram/ext/_applicationbuilder.py index b0f054013..aa110910b 100644 --- a/telegram/ext/_applicationbuilder.py +++ b/telegram/ext/_applicationbuilder.py @@ -644,8 +644,7 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]): """Sets the private key and corresponding password for decryption of telegram passport data for :attr:`telegram.ext.Application.bot`. - .. seealso:: `passportbot.py `_, `Telegram Passports + .. seealso:: :any:`examples.passportbot`, `Telegram Passports `_ Args: @@ -704,8 +703,7 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]): .. seealso:: `Arbitrary callback_data `_, - `arbitrarycallbackdatabot.py `_ + :any:`examples.arbitrarycallbackdatabot` Args: arbitrary_callback_data (:obj:`bool` | :obj:`int`): If :obj:`True` is passed, the @@ -794,8 +792,7 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]): instantiated. .. seealso:: `JobQueue `_, `timerbot.py `_ + /Extensions-%E2%80%93-JobQueue>`_, :any:`examples.timerbot` Note: * :meth:`telegram.ext.JobQueue.set_application` will be called automatically by @@ -832,8 +829,7 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]): .. seealso:: `Making your bot persistent `_, - `persistentconversationbot.py `_ + :any:`examples.persistentconversationbot` Warning: If a :class:`telegram.ext.ContextTypes` instance is set via :meth:`context_types`, @@ -855,8 +851,7 @@ class ApplicationBuilder(Generic[BT, CCT, UD, CD, BD, JQ]): """Sets a :class:`telegram.ext.ContextTypes` instance for :attr:`telegram.ext.Application.context_types`. - .. seealso:: `contexttypesbot.py `_ + .. seealso:: :any:`examples.contexttypesbot` Args: context_types (:class:`telegram.ext.ContextTypes`): The context types. diff --git a/telegram/ext/_conversationhandler.py b/telegram/ext/_conversationhandler.py index ebb7e13df..4cd3f06ee 100644 --- a/telegram/ext/_conversationhandler.py +++ b/telegram/ext/_conversationhandler.py @@ -183,10 +183,8 @@ class ConversationHandler(BaseHandler[Update, CCT]): attribute or else the latter will be ignored. You may map :attr:`END` to one of the parents states to continue the parent conversation after the child conversation has ended or even map a state to :attr:`END` to end the *parent* conversation from within the child - conversation. For an example on nested :class:`ConversationHandler` s, see our `examples`_. - - .. _`examples`: https://github.com/python-telegram-bot/python-telegram-bot/tree/master\ - /examples#examples + conversation. For an example on nested :class:`ConversationHandler` s, see + :any:`examples.conversationbot`. Args: entry_points (List[:class:`telegram.ext.BaseHandler`]): A list of :obj:`BaseHandler`