You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
While reviewing #2464 I noticed that we're not very consistend on whether we use logger.warning or warnings.warn to issue warnings to users and I think we should try to overhaul that in v14. Here are a few things that came to my mind and that I'd like to discuss & tackle:
We should add a subclass of UserWarning named TelegramUserWarning or similar. That way users can filter for those explicitly, if they want to.
TelegramDeprecationWarning should then become a subclass of that new class
Both should be properly included in the documentation. They exist so that users can use them in filtering, so users should be above to find them in the docs. To this end, they should probably also be easier importable, i.e. via telegram.utils.TGWarning or telegram.deprecation.TGWarning, maybe even telegram.TGWarning (see also Clear up imports policy #2468)
Issue a warning regarding a particular runtime event:
warnings.warn() in library code if the issue is avoidable and the client application should be modified to eliminate the warning
logging.warning() if there is nothing the client application can do about the situation, but the event should still be noted
The way I understand this, this would mean in particular that we should use warnings.warn() whenever
the user passes some non-reasonable value on initialization on classes that are usually set up manually (e.g. Updater and Handlers, in contrast to the TG types)
the way the users tries to use stuff does not correspond to how they set up the bot (thinking of e.g. thisthis)
the users misuses something, the example that I have in mind is equality comparison for objects that have no _id_attrs
We should make a wiki page on logging and warnings. We can then delete the logging section from the readme. the wiki page should also contain some basic info about how to catch warnings in the logger and how to filter warnings/logging entries made by PTB.
edit: for warnings, it would be good to double check that the stacklevel is set appropriately
As changing warnings <-> logs is somewhat breaking at least for people who filter those things, I'm putting this on the v14 milestone.
While reviewing #2464 I noticed that we're not very consistend on whether we use
logger.warningorwarnings.warnto issue warnings to users and I think we should try to overhaul that in v14. Here are a few things that came to my mind and that I'd like to discuss & tackle:We should add a subclass of
UserWarningnamedTelegramUserWarningor similar. That way users can filter for those explicitly, if they want to.TelegramDeprecationWarningshould then become a subclass of that new classBoth should be properly included in the documentation. They exist so that users can use them in filtering, so users should be above to find them in the docs. To this end, they should probably also be easier importable, i.e. via
telegram.utils.TGWarningortelegram.deprecation.TGWarning, maybe eventelegram.TGWarning(see also Clear up imports policy #2468)Regarding when to use what: Citing the python docs on logging:
The way I understand this, this would mean in particular that we should use
warnings.warn()wheneverUpdaterandHandlers, in contrast to the TG types)thisthis)_id_attrsWe should make a wiki page on logging and warnings. We can then delete the logging section from the readme. the wiki page should also contain some basic info about how to catch warnings in the logger and how to filter warnings/logging entries made by PTB.
edit: for warnings, it would be good to double check that the
stacklevelis set appropriatelyAs changing warnings <-> logs is somewhat breaking at least for people who filter those things, I'm putting this on the v14 milestone.