Use TypeAlias in code where types are declared

[Dr-Irv]

After introducing TypeAlias in _typing.py, goal of this PR is to use it in any other source files that are creating types in this way. Also, make all of those types private.

I believe that I caught them all via some searching, but may have missed a few. Couldn't find a rule that enforces use of TypeAlias. Note that in 3.12, the recommendation is to do a type declaration, which is probably why there isn't such a rule.

[mroeschke]

Is this idea of making these lead with a starting _ is to they are marked as "private"? Should they instead just be moved to _typing.py with other defined "private" annotations?

[Dr-Irv]

Is this idea of making these lead with a starting _ is to they are marked as "private"? Should they instead just be moved to _typing.py with other defined "private" annotations?

The difference with the annotations in _typing.py is that many (but not all) are used in more than one pandas module. For the ones that are marked private in this PR, they are only used locally within that module.

I'm also going to be doing an MR to make more of the ones in _typing.py public.

[rhshadrach]

We were planning on moving core to _core, but ran into some bikeshedding issues. I think we should still operate under the assumption we will eventually do that (I believe there is consensus that we really want to do it). Assuming that is done, what will we want to do about private variables like this? I think we should strive for consistency, either all with a leading underscore or none.

[Dr-Irv]

I still like the idea of having a TypeAlias being private within a module. If someone is making a change to pandas and then wants to use that alias in another module, they then have to think about moving it to _typing.py, which is where it belongs.

Let's say that we had already changed core to _core. If you're down deep in the pandas code, e.g., in pandas/_core/arrays/datetimelike.py, you shouldn't have to remember that your are 2 levels down from _core. IMHO, anything within that file should be private unless it is meant to be imported from somewhere else.

[rhshadrach]

IMHO, anything within that file should be private unless it is meant to be imported from somewhere else.

This seems to me to be a very large change. I count 2432 functions (not merely callables) at the top level of modules across pandas that do not start with an _. Now some are undoubtedly public, but many are not. On the other hand, there are 438 functions at the top level of a module that do start with an _.

Edit: I misread your comment on the first pass. This means that as soon as you want to import something you need to remove the _ from the name? That will mean constantly changing top-level functions in modules. I'm strongly opposed to this.

[rhshadrach]

this PR is just keeping along with that inconsistency.

This PR is changing the names of identifiers to mark them as private when they already reside in modules that are documented as private. This is code churn with no benefit.

[Dr-Irv]

This PR is changing the names of identifiers to mark them as private when they already reside in modules that are documented as private. This is code churn with no benefit.

Disagree. Right now, someone can do from pandas.core.apply import ResType, which is "valid" from a code perspective, invalid from a documentation perspective. If we make the change as I suggested, then whenever pyright implements their "disallow private imports" or this ruff rule https://docs.astral.sh/ruff/rules/import-private-name/ comes out of preview, then from pandas.core.apply import _ResType would get flagged.

[rhshadrach]

I think the sustainable change to accomplish what you want is from pandas._core.apply. Not changing the hundreds of symbols from across pandas.core.

[Dr-Irv]

OK - then I'll change this to just add TypeAlias and keep the symbol names the same.

[Dr-Irv]

@rhshadrach @mroeschke I've kept all the type aliases with the same names as before - now this just introduces TypeAlias and removes any unused aliases.