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)

• Regarding when to use what: Citing the python docs on logging:

  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. this this)
  • 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.