mirror of
https://github.com/python-telegram-bot/python-telegram-bot.git
synced 2024-10-23 17:36:26 +02:00
More transition guiding
Hinrich Mahler
parent
963aac86ce
commit
f21bf0d1b7
7 changed files with 106 additions and 28 deletions
|
|
@ -50,7 +50,7 @@ Again, please try to be precise and include all relevant information. This means
|
|||
* What kind of handler did you set up to handle this? What is it supposed to do?
|
||||
2. What is actually happening?
|
||||
* If you're encountering an exception, please provide the full [traceback](https://realpython.com/python-traceback/)
|
||||
* Make sure that you activate [logging](https://github.com/python-telegram-bot/python-telegram-bot/#logging) or an [[error handler|Exception-Handling]] so that you can actually see the traceback!
|
||||
* Make sure that you activate [logging](https://github.com/python-telegram-bot/python-telegram-bot/#logging) or an [[error handler|Exceptions,-Warnings-and-Logging]] so that you can actually see the traceback!
|
||||
3. Where exactly are things going south? If you can locate the line/s of code that are misbehaving, please include them in your question.
|
||||
|
||||
If you have a hard time laying your finger on where exactly things go south, it might be helpful to provide a [minimal working example](https://telegra.ph/Minimal-Working-Example-for-PTB-07-18).
|
||||
|
|
|
|||
|
|
@ -1,11 +1 @@
|
|||
In `python-telegram-bot`, all Telegram-related errors are encapsulated in the `TelegramError` exception class and its subclasses, located in [`telegram.error`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.error.html) module.
|
||||
|
||||
Any error, including `TelegramError`, that is raised in one of your handlers (or while calling `get_updates` in the `Updater`), is forwarded to all registered error handlers, so you can react to them. You can register an error handler by calling `Dispatcher.add_error_handler(callback)`, where `callback` is a function that takes the `update` and `context`. `update` will be the update that caused the error (or `None` if the error wasn't caused by an update, e.g. for [[Jobs|Extensions-–-JobQueue]]) and `context.error` the error that was raised.
|
||||
|
||||
**Example:** You're trying to send a message, but the user blocked the bot. An `Unauthorized` exception, a subclass of `TelegramError`, will be raised and delivered to your error handler, so you can delete it from your conversation list, if you keep one.
|
||||
|
||||
**Note:** The error handler might be only your last resort - of course you can also handle Exceptions as they occur. Only uncaught exceptions are forwarded to the error handler.
|
||||
|
||||
## Example
|
||||
|
||||
For an example on how an error handler might look like, please head over to the [examples directory](https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples).
|
||||
This page is now over at [[Exceptions, Warnings and Logging|Exceptions,-Warnings-and-Logging]]
|
||||
56
Exceptions,-Warnings-and-Logging.md
Normal file
56
Exceptions,-Warnings-and-Logging.md
Normal file
|
|
@ -0,0 +1,56 @@
|
|||
While you program your bot and while the bot is running there can be several things that can go wrong. This page gives an overview on how you can handle those situations.
|
||||
|
||||
# Exceptions
|
||||
|
||||
In `python-telegram-bot`, all Telegram-related errors are encapsulated in the `TelegramError` exception class and its subclasses, located in [`telegram.error`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.error.html) module.
|
||||
|
||||
Any error, including `TelegramError`, that is raised in one of your handlers (or while calling `get_updates` in the `Updater`), is forwarded to all registered error handlers, so you can react to them. You can register an error handler by calling `Dispatcher.add_error_handler(callback)`, where `callback` is a function that takes the `update` and `context`. `update` will be the update that caused the error (or `None` if the error wasn't caused by an update, e.g. for [[Jobs|Extensions-–-JobQueue]]) and `context.error` the error that was raised.
|
||||
|
||||
**Example:** You're trying to send a message, but the user blocked the bot. An `Unauthorized` exception, a subclass of `TelegramError`, will be raised and delivered to your error handler, so you can delete it from your conversation list, if you keep one.
|
||||
|
||||
**Note:** The error handler might be only your last resort - of course you can also handle Exceptions as they occur. Only uncaught exceptions are forwarded to the error handler.
|
||||
|
||||
## Example
|
||||
|
||||
For an example on how an error handler might look like, please head over to the [examples directory](https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples).
|
||||
|
||||
# Logging
|
||||
|
||||
In case you don't have an error handler registered, PTB will *log* any unhandled exception.
|
||||
For logging, PTB uses Pythons [`logging` module](https://docs.python.org/3/library/logging.html).
|
||||
To set up logging to standard output, you can write
|
||||
```python
|
||||
import logging
|
||||
logging.basicConfig(
|
||||
level=logging.INFO,
|
||||
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
|
||||
)
|
||||
```
|
||||
at the beginning of your script. If you want debug logs instead:
|
||||
```python
|
||||
logger.setLevel(logging.DEBUG)
|
||||
```
|
||||
`python-telegram-bot` makes some more verbose log entries on the `logging.DEBUG` level that might be helpful when you're trying to debug your bot.
|
||||
|
||||
Note that also some 3rd party libraries that `python-telegram-bot` uses, make log entries in the same manner. For example, if you don't want to see the logs of the `APScheduler` library about your `JobQueue` jobs being scheduled, you can specify the logging level of `APScheduler` as follows:
|
||||
|
||||
```python
|
||||
import logging
|
||||
|
||||
aps_logger = logging.getLogger('apscheduler')
|
||||
aps_logger.setLevel(logging.WARNING)
|
||||
```
|
||||
|
||||
# Warnings
|
||||
|
||||
In contrast to exceptions, warnings usually don't indicate that something already did go wrong, but rather that something *could* go wrong or at least could be improved.
|
||||
Warnings issued by `python-telegram-bot` are encapsulated in `PTBUserWarnang` or one of the subclasses, located in the [`telegram.warnings` module](https://python-telegram-bot.readthedocs.io/en/stable/telegram.warnings.html).
|
||||
This allows you to easily handle the warnings using Pythons [`warnings` library](https://docs.python.org/3/library/warnings.html).
|
||||
For example, if you don't want to miss any deprecation warning during development, you can tell Python to turn every such warning issued by PTB into an exception via
|
||||
|
||||
```python
|
||||
import warnings
|
||||
from telegram.error import PTBUserWarning
|
||||
|
||||
warnings.filterwarnings("error", category=PTBDeprecationWarning)
|
||||
```
|
||||
|
|
@ -39,7 +39,7 @@ logging.basicConfig(format='%(asctime)s - %(name)s - %(levelname)s - %(message)s
|
|||
level=logging.INFO)
|
||||
```
|
||||
|
||||
**Note:** Read the article on [[Exception Handling|Exception-Handling]] if you want to learn more.
|
||||
**Note:** Read the article on [[Exceptions, Warnings and Logging|Exceptions,-Warnings-and-Logging]] if you want to learn more.
|
||||
|
||||
Now, you can define a function that should process a specific type of update:
|
||||
|
||||
|
|
@ -149,6 +149,6 @@ updater.stop()
|
|||
#### What to read next?
|
||||
Have a look at the ready-to-run [examples](https://github.com/python-telegram-bot/python-telegram-bot/tree/master/examples).
|
||||
|
||||
Learn about the library exceptions and best practices in [[Exception Handling|Exception-Handling]].
|
||||
Learn about the library exceptions and best practices in [[Exceptions, Warnings and Logging|Exceptions,-Warnings-and-Logging]].
|
||||
|
||||
You want *more features*? Check out [[Extensions – JobQueue|Extensions-–-JobQueue]]!
|
||||
|
|
@ -15,8 +15,6 @@
|
|||
- [What do the `per_*` settings in `ConversationHandler` do?](#what-do-the-per_-settings-in-conversationhandler-do)
|
||||
- [Can I check, if a `ConversationHandler` is currently active for a user?](#can-i-check-if-a-conversationhandler-is-currently-active-for-a-user)
|
||||
- [How can I list all messages of a particular chat or search through them based on a search query?](#how-can-i-list-all-messages-of-a-particular-chat-or-search-through-them-based-on-a-search-query)
|
||||
- [How can I disable logging for the `APScheduler` module?](#how-can-i-disable-logging-for-the-apscheduler-module)
|
||||
- [How do I enforce users joining a specific channel before using my bot?](#how-do-i-enforce-users-joining-a-specific-channel-before-using-my-bot)
|
||||
- [Why am I getting an error `The following arguments have not been supplied`?](#why-am-i-getting-an-error-the-following-arguments-have-not-been-supplied)
|
||||
- [How can I check the version of PTB I am using?](#how-can-i-check-the-version-of-ptb-i-am-using)
|
||||
- [Is there a limit on the number of buttons in an inline keyboard?](#is-there-a-limit-on-the-number-of-buttons-in-an-inline-keyboard)
|
||||
|
|
@ -132,17 +130,6 @@ There is no API method for that (see [here](#can-you-add-feature-to-ptb-can-i-do
|
|||
2. Messages may be edited (in which case your bot will receive a corresponding update)
|
||||
3. Messages may be deleted (and there are no updates for "message deleted"!)
|
||||
|
||||
### How can I disable logging for the `APScheduler` module?
|
||||
|
||||
You can specify the logging level of `APScheduler` as follows:
|
||||
|
||||
```python
|
||||
import logging
|
||||
|
||||
aps_logger = logging.getLogger('apscheduler')
|
||||
aps_logger.setLevel(logging.WARNING)
|
||||
```
|
||||
|
||||
### How do I enforce users joining a specific channel before using my bot?
|
||||
|
||||
After sending an (invite) link to the channel to the user, you can use [`Bot.get_chat_member`](https://python-telegram-bot.readthedocs.io/en/stable/telegram.bot.html#telegram.Bot.get_chat_member) to check if the user is an that channel.
|
||||
|
|
|
|||
|
|
@ -2,6 +2,12 @@
|
|||
|
||||
Add this in the end …
|
||||
|
||||
# New functionality
|
||||
|
||||
Apart from all the refactorings & deprecations explained below, v14 also contains some new functionality. Notable are
|
||||
|
||||
* `Filters.update.edited` provides a shortcut for `(Filters.update.edited_message | Filters.update.edited_channel_post)`
|
||||
|
||||
# Structural changes & Deprecations
|
||||
|
||||
## Removed features
|
||||
|
|
@ -19,6 +25,19 @@ We've made an effort to make it more clear which parts of `python-telegram-bot`
|
|||
|
||||
We introduced the usage of `__slots__` in v13.6, which can reduce memory usage and improve performance. In v14 we removed the ability to set custom attributes on all objects except for `ext.CallbackContext`. To store data, we recommend to use PTBs built-in mechanism for [storing data](Storing-bot,-user-and-chat-related-data) instead. If you want to add additional functionality to some class, we suggest to subclass it.
|
||||
|
||||
## Instantiation of `Updater` and `Dispatcher`
|
||||
|
||||
`Updater` and `Dispatcher` had a large number of arguments many of which were mutually exclusive, and it was not always clear which argument was e.g. intended for the `Updater` and which was passed along to the `Dispatcher` or even the `Bot`.
|
||||
In an effort to make the instantiation of `Updater` and `Dispatcher` more clear, we adopted the so-called [builder pattern](https://en.wikipedia.org/wiki/Builder_pattern).
|
||||
This means that instead of passing arguments directly to `Updater`/`Dispatcher`, one now creates a builder via `Updater/Dispatcher.builder()` and then specifies all required arguments via that builder.
|
||||
Finally, the `Updater/Dispatcher` is created by calling `builder.build()`. A simple example is
|
||||
```python
|
||||
from telegram.ext import Updater
|
||||
updater = Updater.builder().token('TOKEN').build()
|
||||
```
|
||||
|
||||
We hope that this change makes it easier for you to understand what goes where and also simplifies setups of customized solutions, e.g. if you want to use a custom webhook.
|
||||
|
||||
# Changes for specific modules, classes & functions
|
||||
|
||||
## `telegram`
|
||||
|
|
@ -35,10 +54,19 @@ Previously some parts of `telegram.{error, constants}` where available directly
|
|||
|
||||
The argument `hash` is now the second positional argument as specified by the Bot API.
|
||||
|
||||
### `telegram.File`
|
||||
|
||||
* The `custom_path` parameter now also accepts `pathlib.Path` objects.
|
||||
* Instead of returning the file path as string, it's now returned as `pathlib.Path` object.
|
||||
|
||||
### `telegram.ForceReply`
|
||||
|
||||
The argument `force_reply` was removed, since it *always* must be `True` anyway.
|
||||
|
||||
### `telegram.InlineQuery.answer`
|
||||
|
||||
If both parameters `current_offset` and `auto_pagination` are supplied, the method now raises a `ValueError` rather than a `TypeError`.
|
||||
|
||||
### `telegram.PassportFile`
|
||||
|
||||
The argument `file_size` is now optional as specified by the Bot API.
|
||||
|
|
@ -61,6 +89,23 @@ There parameters & attributes `store_{user,chat,bot}_data` were removed. Instead
|
|||
|
||||
Note that `callback_data` is now persisted by default.
|
||||
|
||||
### `CallbackContext`
|
||||
|
||||
* `CallbackContext.from_error` has a new optional argument `job`. When an exception happens inside a `ext.Job` callback, this parameter will be passed.
|
||||
* Accordingly, the attribute `CallbackContext.job` will now also be present in error handlers if the error was caused by a `ext.Job`.
|
||||
|
||||
### `JobQueue.run_monthly`
|
||||
|
||||
Unfortunately, the `day_is_strict` argument was not working correctly (see [#2627](../issues/2627)) and was therefore removed. Instead, you cann now pass `day='last'` to make the job run on the last day of the month.
|
||||
|
||||
### `PicklePersistence`
|
||||
|
||||
* The argument `filename` was renamed to `filepath` and now also accepts a `pathlib.Path` object
|
||||
* [Changes to `BasePersistence`](#basepersistence) also affect this class.
|
||||
|
||||
### `Updater`
|
||||
|
||||
In addition to the changes described [above](#instantiation-of-updater-and-dispatcher)
|
||||
|
||||
* the attribute `user_sig_handler` was renamed to `user_signal_handler`
|
||||
* the attributes `job_queue` and `persistence` were removed. Instead, you can access them via `updater.dispatcher.{job_queue, persistence}`.
|
||||
|
|
|
|||
|
|
@ -11,7 +11,7 @@
|
|||
3. [[Storing data|Storing-bot,-user-and-chat-related-data]]
|
||||
4. [[Making your bot persistent|Making-your-bot-persistent]]
|
||||
5. [[Adding Defaults|Adding-defaults-to-your-bot]]
|
||||
6. [[Exception Handling|Exception-Handling]]
|
||||
6. [[Exceptions, Warnings and Logging|Exceptions, Warnings and Logging]]
|
||||
7. [[Job Queue|Extensions-–-JobQueue]]
|
||||
8. [Arbitrary `callback_data`](Arbitrary-callback_data)
|
||||
9. [[Avoiding flood limits|Avoiding-flood-limits]]
|
||||
|
|
|
|||
Loading…
Reference in a new issue