Is there some obvious reason why `api.typing` is not present in the `api` interface stub?

[Dr-Irv]

Is there some obvious reason why api.typing is not present in the api interface stub?
https://github.com/pandas-dev/pandas-stubs/blob/86073150f5e1b607c37a536ec99204ed21bad0cb/pandas-stubs/api/__init__.pyi
Was it missed in #1058?
I see types there but not typing, both are public interfaces according to docs.

I just wanted to use pandas.api.typing.NaTType in my code but my static type checker complained that typing is not part of pandas.api.

Originally posted by @Molkree in #1220

[Dr-Irv]

@loicdiridollou need to add typing to pandas-stubs\api\__init__.pyi

[loicdiridollou]

Ill add typing to the api init. Furthermore the NaTType was exposed in the pandas repo after we added it to the stubs repo so even if we were correct in pandas.api.__init__ it’d still be an issue. I’ll add it, fix it all and make sure we are not missing anything else. Thanks for raising it!

…

On Mon, May 19, 2025 at 8:32 AM Irv Lustig ***@***.***> wrote: Assigned #1221 <#1221> to @loicdiridollou <https://github.com/loicdiridollou>. — Reply to this email directly, view it on GitHub <#1221 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AMQNSQB5P4MRXX7AWQUTCY327HFNPAVCNFSM6AAAAAB5NTWFTSVHI2DSMVQWIX3LMV45UABCJFZXG5LFIV3GK3TUJZXXI2LGNFRWC5DJN5XDWMJXG4YTIMJWGU3DOMY> . You are receiving this because you were assigned.Message ID: ***@***.***>

[Molkree]

I just stumbled on a similar problem with pandas.io module. __init__.pyi is completely empty here, so none of the underlying modules are visible to type checkers.
This goes on deeper as well, because pandas.io.formats.__init__.pyi is also empty
I was interested in pandas.io.formats.style.Styler.
Would you like me to file a separate issue(s)?

[loicdiridollou]

Good catch, the question to @Dr-Irv is should we realign all those __init__ and when we are in the case like pandas.io where all imports are under the TYPE_CHECKING if statement, does it mean that we need it in pandas-stubs?
I will take care of it if we agree on direction.

[Molkree]

when we are in the case like pandas.io where all imports are under the TYPE_CHECKING if statement, does it mean that we need it in pandas-stubs

Hm, I didn't notice this at first, do you know the rationale behind this?

I wanted to write something like this:

def foo(df: pd.DataFrame) -> pandas.io.formats.style.Styler:

but it fails with AttributeError: module 'pandas.io.formats' has no attribute 'style' so I have to wrap import and enable future annotations:

from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from pandas.io.formats.style import Styler

def colour_platform_column(df: pd.DataFrame) -> Styler:

This is a bit cumbersome, maybe I'm missing something here? Docs don't mention the fact that you have to do such hacks.

[Dr-Irv]

Good catch, the question to @Dr-Irv is should we realign all those __init__ and when we are in the case like pandas.io where all imports are under the TYPE_CHECKING if statement, does it mean that we need it in pandas-stubs?

My take on this is that if the pandas source has an __init__.py in some sub-package that imports other sub-packages/modules, then the stubs should do the same in the corresponding __init__.pyi, but without the if TYPE_CHECKING line.

I think they would all need to be of the from from sub_package import xyz as xyz for it to work in the stubs.