diff --git a/.github/workflows/example_notifier.yml b/.github/workflows/example_notifier.yml deleted file mode 100644 index 6521b32a8..000000000 --- a/.github/workflows/example_notifier.yml +++ /dev/null @@ -1,16 +0,0 @@ -name: Warning maintainers -on: - pull_request_target: - paths: examples/** -permissions: - pull-requests: write -jobs: - job: - runs-on: ubuntu-latest - name: about example change - steps: - - name: running the check - uses: Poolitzer/notifier-action@master - with: - notify-message: Hey there. Relax, I am just a little warning for the maintainers to release directly after merging your PR, otherwise we have broken examples and people might get confused :) - repo-token: ${{ secrets.GITHUB_TOKEN }} diff --git a/examples/README.md b/examples/README.md index b69280ce6..d3d0f7d6a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,4 +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://python-telegram-bot.readthedocs.io/en/latest/telegram.ext.html) submodule. @@ -6,10 +7,10 @@ All examples are licensed under the [CC0 License](https://github.com/python-tele 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`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/echobot.py) +### [`echobot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/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`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py) +### [`timerbot.py`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/timerbot.py) This bot uses the [`JobQueue`](https://python-telegram-bot.readthedocs.io/en/latest/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`](https://github.com/python-telegram-bot/python-telegram-bot/blob/master/examples/conversationbot.py) diff --git a/examples/arbitrarycallbackdatabot.py b/examples/arbitrarycallbackdatabot.py index 92a2e4ef7..5c2dbc2c4 100644 --- a/examples/arbitrarycallbackdatabot.py +++ b/examples/arbitrarycallbackdatabot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """This example showcases how PTBs "arbitrary callback data" feature can be used. @@ -10,6 +10,19 @@ https://github.com/python-telegram-bot/python-telegram-bot/wiki/Arbitrary-callba import logging from typing import List, Tuple, cast +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update from telegram.ext import ( Application, diff --git a/examples/chatmemberbot.py b/examples/chatmemberbot.py index 1081057db..315632750 100644 --- a/examples/chatmemberbot.py +++ b/examples/chatmemberbot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -14,6 +14,19 @@ bot. import logging from typing import Optional, Tuple +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import Chat, ChatMember, ChatMemberUpdated, Update from telegram.constants import ParseMode from telegram.ext import Application, ChatMemberHandler, CommandHandler, ContextTypes diff --git a/examples/contexttypesbot.py b/examples/contexttypesbot.py index fc228c69e..a25c3185c 100644 --- a/examples/contexttypesbot.py +++ b/examples/contexttypesbot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -14,6 +14,19 @@ import logging from collections import defaultdict from typing import DefaultDict, Optional, Set +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update from telegram.constants import ParseMode from telegram.ext import ( diff --git a/examples/conversationbot.py b/examples/conversationbot.py index fccf0b037..e74d7ce7c 100644 --- a/examples/conversationbot.py +++ b/examples/conversationbot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -16,6 +16,19 @@ bot. import logging +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update from telegram.ext import ( Application, diff --git a/examples/conversationbot2.py b/examples/conversationbot2.py index 696f104a6..fcbcdcca3 100644 --- a/examples/conversationbot2.py +++ b/examples/conversationbot2.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -17,6 +17,19 @@ bot. import logging from typing import Dict +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update from telegram.ext import ( Application, diff --git a/examples/deeplinking.py b/examples/deeplinking.py index a5d1c35a9..0dd0f66aa 100644 --- a/examples/deeplinking.py +++ b/examples/deeplinking.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """Bot that explains Telegram's "Deep Linking Parameters" functionality. @@ -20,6 +20,19 @@ bot. import logging +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update, helpers from telegram.constants import ParseMode from telegram.ext import Application, CallbackQueryHandler, CommandHandler, ContextTypes, filters diff --git a/examples/echobot.py b/examples/echobot.py index 59fcbe373..c2b8a2a3d 100644 --- a/examples/echobot.py +++ b/examples/echobot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -17,6 +17,19 @@ bot. import logging +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) 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 6f34c718d..e369a6765 100644 --- a/examples/errorhandlerbot.py +++ b/examples/errorhandlerbot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """This is a very simple example on how one could implement a custom error handler.""" @@ -8,6 +8,19 @@ import json import logging import traceback +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import Update from telegram.constants import ParseMode from telegram.ext import Application, CommandHandler, ContextTypes diff --git a/examples/inlinebot.py b/examples/inlinebot.py index 3c36b5dbe..1b11fe948 100644 --- a/examples/inlinebot.py +++ b/examples/inlinebot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -16,6 +16,19 @@ import logging from html import escape from uuid import uuid4 +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import InlineQueryResultArticle, InputTextMessageContent, Update from telegram.constants import ParseMode from telegram.ext import Application, CommandHandler, ContextTypes, InlineQueryHandler diff --git a/examples/inlinekeyboard.py b/examples/inlinekeyboard.py index 49a745620..5189e773f 100644 --- a/examples/inlinekeyboard.py +++ b/examples/inlinekeyboard.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -8,6 +8,19 @@ Basic example for a bot that uses inline keyboards. For an in-depth explanation, """ import logging +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) 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 dfb5294ea..78486c5cb 100644 --- a/examples/inlinekeyboard2.py +++ b/examples/inlinekeyboard2.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """Simple inline keyboard bot with multiple CallbackQueryHandlers. @@ -16,6 +16,19 @@ Press Ctrl-C on the command line to stop the bot. """ import logging +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update from telegram.ext import ( Application, diff --git a/examples/nestedconversationbot.py b/examples/nestedconversationbot.py index a960b7ec5..ec27717a8 100644 --- a/examples/nestedconversationbot.py +++ b/examples/nestedconversationbot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -17,6 +17,19 @@ bot. import logging from typing import Any, Dict, Tuple +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import InlineKeyboardButton, InlineKeyboardMarkup, Update from telegram.ext import ( Application, diff --git a/examples/passportbot.py b/examples/passportbot.py index 76f97ce89..f6cd24942 100644 --- a/examples/passportbot.py +++ b/examples/passportbot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -14,6 +14,19 @@ See https://github.com/python-telegram-bot/python-telegram-bot/wiki/Telegram-Pas import logging from pathlib import Path +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import Update from telegram.ext import Application, ContextTypes, MessageHandler, filters diff --git a/examples/paymentbot.py b/examples/paymentbot.py index db6b54898..09afa7c3e 100644 --- a/examples/paymentbot.py +++ b/examples/paymentbot.py @@ -1,11 +1,24 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """Basic example for a bot that can receive payment from user.""" import logging +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import LabeledPrice, ShippingOption, Update from telegram.ext import ( Application, diff --git a/examples/persistentconversationbot.py b/examples/persistentconversationbot.py index 7e606a2e6..1814835db 100644 --- a/examples/persistentconversationbot.py +++ b/examples/persistentconversationbot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -17,6 +17,19 @@ bot. import logging from typing import Dict +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import ReplyKeyboardMarkup, ReplyKeyboardRemove, Update from telegram.ext import ( Application, diff --git a/examples/pollbot.py b/examples/pollbot.py index 91f28d7fd..19fd2c6db 100644 --- a/examples/pollbot.py +++ b/examples/pollbot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -9,6 +9,19 @@ one the user sends the bot """ import logging +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import ( KeyboardButton, KeyboardButtonPollType, diff --git a/examples/rawapibot.py b/examples/rawapibot.py index b4dd928df..b2911ed0d 100644 --- a/examples/rawapibot.py +++ b/examples/rawapibot.py @@ -1,4 +1,5 @@ #!/usr/bin/env python +# pylint: disable=wrong-import-position """Simple Bot to reply to Telegram messages. This is built on the API wrapper, see echobot.py to see the same example built @@ -9,6 +10,19 @@ import asyncio import logging from typing import NoReturn +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] # type: ignore[assignment] + +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" + ) from telegram import Bot from telegram.error import Forbidden, NetworkError diff --git a/examples/timerbot.py b/examples/timerbot.py index 81488dd88..d468dbe14 100644 --- a/examples/timerbot.py +++ b/examples/timerbot.py @@ -1,5 +1,5 @@ #!/usr/bin/env python -# pylint: disable=unused-argument +# pylint: disable=unused-argument, wrong-import-position # This program is dedicated to the public domain under the CC0 license. """ @@ -20,6 +20,19 @@ bot. import logging +from telegram import __version__ as TG_VER + +try: + from telegram import __version_info__ +except ImportError: + __version_info__ = (0, 0, 0, 0, 0) # type: ignore[assignment] + +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" + ) from telegram import Update from telegram.ext import Application, CommandHandler, ContextTypes diff --git a/telegram/_bot.py b/telegram/_bot.py index 9c32b0863..41d7ff888 100644 --- a/telegram/_bot.py +++ b/telegram/_bot.py @@ -2292,9 +2292,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): "Either venue or latitude, longitude, address and title must be " "passed as arguments." ) - if not ( - bool(venue) ^ any([latitude, longitude, address, title]) - ): # pylint: disable=superfluous-parens + if not bool(venue) ^ any([latitude, longitude, address, title]): raise ValueError( "Either venue or latitude, longitude, address and title must be " "passed as arguments. Not both." @@ -2421,9 +2419,7 @@ class Bot(TelegramObject, AbstractAsyncContextManager): raise ValueError( "Either contact or phone_number and first_name must be passed as arguments." ) - if not ( - bool(contact) ^ any([phone_number, first_name]) - ): # pylint: disable=superfluous-parens + if not bool(contact) ^ any([phone_number, first_name]): raise ValueError( "Either contact or phone_number and first_name must be passed as arguments. " "Not both."