MNT: Add type hints to Mouse methods

[welli7ngton]

• Added explicit return types to various DesktopBot methods.
• Introduced Literal for button parameters to restrict values:
  • I realized that the Button type is an Enum, from now on the bot only accepts the literal values of left, right and middle because I didn't find a better way to represent this enum, what do you guys think.
• Ensured consistent type annotations across mouse-related functions.

[joao-voltarelli]

Hi @welli7ngton, great work!

I think using Literal could work well for this scenario. There's just one small problem, if I'm not mistaken, the 'Literal' type is available from Python >= 3.8. Since the framework supports Python 3.7, some older projects that still use Python 3.7 may be incompatible with future versions.

I was taking a better look at the _mouse_click method, and it has an internal check to verify the value that was passed to the 'button' parameter, so if the user passes an incorrect value, the method itself will throw an exception indicating the problem.

So, I believe that leaving the parameter type as 'str' for now won't be a big problem since the method checks the content that was passed. What do you think?

Here's a reference: https://github.com/botcity-dev/botcity-framework-core-python/blob/815196110f09b028b9546c0af8bc523cf1ecc8d8/botcity/core/input_utils.py#L77#L80

[welli7ngton]

Hello @joao-voltarelli

You're right, Literal is only avaible from Python 3.8 onwards, i found a way to use Literal type in older versions of python, i havents tried yet, but heres the example that i found on stackoverflow: ImportError: cannot import name 'Literal' from 'typing'

Let me know what do you think

[joao-voltarelli]

Hey @welli7ngton!

Yesterday, I was reading about the typing_extensions package, and it seemed like an interesting alternative, but I got a bit confused when reading the oficial documentation.

Apparently, although it seems to work for older versions of Python, the official documentation mentions that it currently supports version 3.8 or higher and will stop supporting older versions in the future: https://typing-extensions.readthedocs.io/en/latest/#python-version-support

So I'm not really sure how it works. If you can, could you please look into it and take a deeper look into how it works?

[welli7ngton]

@joao-voltarelli Sure, I'll dive into it. If I don't get confident that everything will work smoothly without issues, I'll proceed with your last proposed solution.

[welli7ngton]

Hi @joao-voltarelli, that doc sounds kinda confuse for me, im gonna proceed with your solution :))

[welli7ngton]

Hey @joao-voltarelli, i had to solve a conflict in my branches.

I didn't understand the reason for the conflict when trying to push my branch, apparently it was resolved, but if you find it interesting that I redo the branch to avoid any problems, I understand and make the changes from the most recent version of the main branch.

Best regards, welli7ngton.

[joao-voltarelli]

Hi @joao-voltarelli, that doc sounds kinda confuse for me, im gonna proceed with your solution :))

No problem following this way! Since the method already has an internal check of the content that is passed, there is no problem if we leave the type as "str" ​​for now.

[joao-voltarelli]

@welli7ngton I think we'll just need to make a small adjustment.

In the click(), click_relative(), mouse_down() and mouse_up() methods we can remove this treatment:

• mouse_button = mouse_map.get(button, "left")

I say this because the _mouse_click() method that is invoked expects the parameter to be of type 'str'. This treatment means the mouse_button variable can be an Enum (if it exists in the mouse_map dictionary).

With this, the internal check that is done within the _mouse_click() method would cause the ValueError exception to be thrown: https://github.com/botcity-dev/botcity-framework-core-python/blob/815196110f09b028b9546c0af8bc523cf1ecc8d8/botcity/core/input_utils.py#L77#L80

Since this parameter value check is already done in _mouse_click(), I think we can leave it out of the methods in bot.py. What do you think?

[welli7ngton]

Hi @joao-voltarelli, i see now, it also ensure consistency in handling mouse button inputs. I agree, ill solve this soon, thanks for the feedback

[joao-voltarelli]

Hi @welli7ngton, now everything likes to work fine!

Just one detail, I gave you incorrect information about the mouse_down() and mouse_up() methods.
In these two specific methods, we need to use this treatment to get the correct button:
mouse_button = mouse_map.get(button, None), since the pyinput press and release methods do not accept strings.

Sorry about that! I've already made a commit to fix this point, thanks for the contribution!