typing to wb.sheets

[Jeroendevr]

related to #2201

Because I am hesitant to make a big PR with typing options because I have some questions. The main.py module of xlwings was ordered based on hierarchy understandably. However to reference a class as a type it has to be declarated before it is used. Therefore I moved Sheet class up.
If typing would be added it could lead to reorganization of the module. Another option would be to spilt te module as an imported module would be declared first.

Using mypy as a type checker

pointed to

# Optional imports
try:
    import matplotlib as mpl
    from matplotlib.backends.backend_agg import FigureCanvas
except ImportError:
    mpl = None
    FigureCanvas = None

But matplotlib is not used within main, could it be removed or has it a function.

Non english excel

Some tests are failing due to localization differences so I don't have 100% tests passed. What would be a wise decision? Adding skipif if locale is not english will lead to a lot of ugly code and decreases readability.

Excuse me for the overlapping non related questions 🤗

[fzumstein]

It would probably be wise to take this as a trigger to split up main.py and put every class into a separate module. But that alone will be quite some work.

[Jeroendevr]

Sounds good, is this PR acceptable? Next I would separate Sheet in a separate PR.

[fzumstein]

Hm no, I think it should be done by introducing a types module, something like here:
https://github.com/encode/starlette/blob/master/starlette/types.py

Then the types can be imported from there. This saves us from refactoring everything and splitting up main.py just for the sake of adding types.

Also, def sheets(self) -> List(sheet) isn't right, it should return Sheets, not a List

[Jeroendevr]

Ah yes you are right about the Sheets.
Can you explain a little bit what you mean? I don't understand how you would use the types.py in the sheet context? Something along the lines of?

# main.py
from types import SheetType

# types.py
import typing

if typing.TYPE_CHECKING:
    from xlwings.main import Sheet

SheetType = typing.callable[["Sheet"],Sheet] 

[fzumstein]

Looks like from __future__ import annotations fixes the issue of not being able to use classes that are defined later. I made an example here: https://github.com/xlwings/xlwings/compare/typing?expand=1

There's going to be a few challenges, e.g., annotating the Collection base class so that I can do xw.sheets[0]. or xw.sheets[0].shapes[0]. and still get the correct methods/properties.

[Jeroendevr]

I have some difficulty understanding how the impl is created (see also #2201 )
But would it be correct that in the case of App

class App:
    self.impl: base_classes.App

Is valid?
And this pattern could then be repeated for every class?

[fzumstein]

impl is the platform-specific implementation, e.g., xlwings._xlwindows.App, so most likely would have to be annotated as typing.Union[xlwings._xlwindows.App, xlwings._xlmac.App, ...]. However, if you do this manually, you shouldn't bother about anything that isn't public API for this first iteration of adding types, so you can ignore impl.

It would be different if you want to do this semi-automatically with MonkeyTyping, see #2201

[Jeroendevr]

Good idea to make it a Union instead of a super class. I understand your idea of not bothering to much with the non public API. However I wanted to understand what is happening and thought that if some of the impl methods are annotated this automatically finds it's way to the public API.
Ok, I'll give another shot next week!

[Jeroendevr]

Hi Felix, it proves more difficult for me than previously thought. You where right that correctly typing the Collection object is quite a challenge.
I tried the MonkeyType but no luck. It did not had a big improvement when adding my own adjustments to the stub file. Because it collects types during runtime only types of the _xlmac where incorporated. Adding the stub file to work with xlwindows takes a lot of effort.
So here is some basic annotations in this PR as a small start.

[fzumstein]

thanks!

[fzumstein]

One remark: | was introduced in Python 3.10 but xlwings will support 3.9 until 2025-10 (according to Python EOL).

[Jeroendevr]

Ah does it matter for users? As type annotations are for Typecheckers.
I'll change it!

[Jeroendevr]

Ok changed the usage to Union and Optional and squashed the commits.

[Jeroendevr]

Hi Felix, As a rule to prevent to much OSS contrib I only have one PR per project. I know it is not feature complete but if it is suitable to merge will you merge it. As it allows me to make further contributions not typing related.
If there is anything I can do to make this PR get merged let me know.

[fzumstein]

Apologies, but it will take a while before I get to this. I need to learn more about type hints first and there's just too many other higher prios right now. Ideally, I'd like to have the whole public API fully type hinted before merging.

[Jeroendevr]

I understand as using loose PR's can confuse the history a bit. On the other side if it is an improvement, you could merge it.
As one of my life mottos is "perfect kills better". Don't wait for it to be perfect if it can be better (which in my opinion it is). But as I said I understand if you want the merging history to be clear or get a better grasp about what is the case with Typing.