Overhaul of Filters

[harshil21]

Breaking changes:

• Closes Refactor Filters #2178

Also fixes #2281 (the problem was that we had duplicate docs in filters.)

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) How do we want to document this breaking change? Just a .. versionchanged:: on top of the filters module?
• Created new or adapted existing unit tests

Notable changes:

• Converted __new__ in BaseFilter to __init__ see: Overhaul of Filters #2759 (comment)

• Made _UpdateType public, so users can now do: filters.UpdateType.MESSAGES.

• deleted ChatType's filter() as discussed offline (reasoning was that Filters.chat_type was always True) .

• All _ChatUserBaseFilter subclasses have a CAPS shortcut with allow_empty=True, we can discuss to remove this / keep it default (False). This allows a user to do something like filters.SENDER_CHAT work for both Channels and Supergroups.

  Edit: It was decided that those shortcuts won't inherit from _CUBF and instead be their own, see
  https://t.me/pythontelegrambotdev/261 for discussion.

• Use a functools.partial() in DICE filter to simplify it for the user. See the examples section in Dice docs.
  Reverted. See: Overhaul of Filters #2759 (comment)

Minor changes:

• remove the name argument in _Dice (to reduce repetition, it is now built from the emoji itself)
• changed import of User, Chat in filters to TG{User, Chat} to avoid namespace conflicts.
• The filters docs are now arranged according to how it appears in source.
• Converted Optional[str] -> str in MimeType and Category (it was just plain wrong).
• Rearrange filters in the source (right now they're all over the place). Should be done after a approving review since the diff is already messy.

[harshil21]

Something I recently noticed: A side effect of #2345 was that the filters docs stopped showing class signatures. See for e.g before -> after.
This was because we added a __new__ in BaseFilter, and sphinx seems to be picking the signature of that instead of the actual class.

So we can:

1. Try to fix by changing something sphinx related
2. Try to remove __new__ (which I was unsuccessful at since the same class variable / property / instance variable was being used causing lots of issues with slots)
3. Don't fix since we document everything well enough anyway.

[Bibo-Joshi]

Mh, this comes from the fact that Sphinx uses inspect.signature, which favor __new__ over __init__ (which makes sense …). We have the same for TelegraObject and BasePersistence.

I think for this PR we can leave it as is and rather convert this in another spin-off issue to think about __new__ in general. Some thoughts:

1. For TelegramObject and BaseFilter we can drop the need for __new__ by just accepting that we need to call super().__init__. Sure, not having to do it nicer, but we'll survive. For TelegramObject we can even get away even easier with [DISCUSSION] Dataclasses #2698: if TelegramObject is a dataclass as well, the auto-generated init will automatically call super
2. For BasePersistence we could move everything that currently happens in __new__ to __init__ that exists anyway. Alternatively, want to make the insert/replace_bot mechanism more explicit anyway in [FEATURE/DISCUSSION]: Allow fine tuning of persistence setup #2524 so we could switch to another approach for replacing/inserting - see e.g. [BUG] Persistence of Bots #1992

[Bibo-Joshi]

nice updates! I left a number of more comments though I'd classify most of them as nitpicking by now 😃

[Bibo-Joshi]

One detail, otherwise I'm happy :)
IIRC you'll sort the contents of filters.py now, right?

I'll force-push v14 to include the master changes later tonight.
If you want to, this could be a good chance to get to know rebasing :D basically, you (pull v14 and) run git rebase v14 and follow the comments in the command line. I guess there should be few to none merge conflicts :)
Alternatively, just merging v14 into this branch is fine as well ofc :)

PS: this article helped me quite well when working with rebase the first time