feat/fix: improve typehinting of wait_fors

[AstreaTSS]

Pull Request Type

• Feature addition
• Bugfix
• Documentation update
• Code refactor
• Tests improvement
• CI/CD pipeline enhancement
• Other: [Replace with a description]

Description

This PR improves typehintings for the wait_for functions, largely by using plenty of overloads. It also fixes some incorrect typehints along the way.

Changes

• For wait_for, make event: Union[str, "BaseEvent"] > event: Union[str, "type[BaseEvent]"].
• Add overloads for wait_for to let the typehinter return the type of event passed in if an event type is passed at any point.
• Add overloads for wait_for_component to enforce either passing messages or components.

Related Issues

Test Scenarios

Python Compatibility

• I've ensured my code works on Python 3.10.x
• I've ensured my code works on Python 3.11.x

Checklist

• I've run the pre-commit code linter over all edited files (I'm facing issues with this check running in certain contexts, I'll let the bot take care of it)
• I've tested my changes on supported Python versions
• I've added tests for my code, if applicable
• I've updated / added documentation, where applicable