[REFACTOR]: Enum constants

[Bibo-Joshi]

Hey. I'm aware that we didn't discuss this, but it felt like reasonable change. If you disagree, we can close :D
Key points of this PR:

• group the constants in tg.constants into enums. This has the advantage of
  • better name space (ParseMode.HTML instead of PARSEMODE_HTML)
  • the enums are still instances of int/str, so no change there
  • the enums are iterable which may come in handy in some situations (see below)
  • we can control the representation of the enums (see below)
• Some constants didn't really fit into groups, so I left them as standalone constants
• For string enums, I made sure that the string representation reads something like <ParseMode.HTML>, rather than the default behavior of <ParseMode.HTML: 'html'>. This is because the actual value is of little interest and IMO it also encourages users to use the constants rather than plain strings.
• tg.{ChatAction, ParseMode} were removed in favor of tg.constants.{ChatAction, ParseMode}.

Some more changes that could be made but that I didn't make yet because I wasn't sure if we want that:

• For now I kept the constants like Update.ALL_TYPES. However, if you agree, I think we can remove them, as now one can just do list(constants.UpdateType).
• In fact, one could think of dropping these constants alltogether and replacing e.g. Chat.{PRIVATE, CHANNEL, …} by Chat.TYPES = tg.constants.ChatType.

things that should be done in any case:

• Update references to telegram.ParseMode if Input media subclasses init handling refactor #2573 #2717 is merged before this
• Add an enum for the InputMedia* types
• Add enums for Message/attachment types

Checklist for PRs

• Added .. versionadded:: version, .. versionchanged:: version or .. deprecated:: version to the docstrings for user facing changes (for methods/class descriptions, arguments and attributes)
• Created new or adapted existing unit tests

Breaking changes:

• Constants in the module constants are now enums

[github-actions]

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 :)

[harshil21]

Nice change. I thought of Enums too few months back, but dropped it for some reason.

Some changes to be made:

• The ChatAction and ParseMode .rst files should be deleted, and from telegram.rst (sphinx raises warnings),
• There's still telegram.ChatAction all over the docs, should be updated.

[Bibo-Joshi]

@harshil21 what do you think about the two points that I mentioned under "Some more changes that could be made but …"?

[harshil21]

what do you think about the two points that I mentioned under "Some more changes that could be made but …"?

I think we should keep both of them the way it is. Makes it slightly easier for the user. It's not immediately obvious that list(constants.UpdateType) is Update.ALL_TYPES

[Poolitzer]

I like the organisation and improved import. I dont like the docs. Is there a way to get sphinx to insert the value of the constants we link to? I would combine this: Either inline link to the constant but write the value there. Or write the import phrase and insert the value in brakets.

I understand that we want to push people to use our constants, but if they dont want to for whatever reason, we take away the quick look up.

[Bibo-Joshi]

Valid point @Poolitzer 👍 . A straightforward way would be to do :role:`title <target>`, which links to <target> but shows title. I'll try and check if we can somehow get sphinx to automatically infere the title from the <target> - we might need a custom :role: for that or something like this …

[harshil21]

tiny fix

[Bibo-Joshi]

This was actually a bit easier than I thought :) I addded a new role :tg-const: and hooked into the sphinx build process so that :tg-const: links have the acutal value as title. see the changes in docs/source/conf.py for details. I also built the docs at RTD https://python-telegram-bot.readthedocs.io/en/enum-constants/ for easier viewing. The naming of :tg-const: is not fixed - I'm open to alternatives.

One thing that come to think of while doing this is that we also could change the type hints of the parameters where you should pass constants. e.g. parse_mode: constants.ParseMode = None tells your type checker that it's probably a bad idea to pass a plain string. But I wanted to hear your opinion on that and IMO that can also be done in a follow-up PR …

[harshil21]

another tiny unrelated change

[harshil21]

parse_mode: constants.ParseMode = None tells your type checker that it's probably a bad idea to pass a plain string. But I wanted to hear your opinion on that

imo it should be as it is, because ultimately the value is actually a string, the user might think that ParseMode is some class they have to know how to initialize etc. Also whenever there's a new API update, and the user wants to use the new value, they'll have to switch back to a string anyway (until PTB updates).

Also skimming through that RTD I saw that we should add an Enum for location, see for e.g.:
https://python-telegram-bot.readthedocs.io/en/enum-constants/telegram.bot.html#telegram.Bot.edit_message_live_location

[Poolitzer]

Code changes look good!