Annotate API-exposed Items from pandas.core.api

Question

Annotate API-exposed Items from pandas.core.api

WillAyd opened this issue 5 years ago · comments

We currently expose all of the following items from pandas.core.api via the API:

from pandas.core.api import (
    # dtype
    Int8Dtype, Int16Dtype, Int32Dtype, Int64Dtype, UInt8Dtype,
    UInt16Dtype, UInt32Dtype, UInt64Dtype, CategoricalDtype,
    PeriodDtype, IntervalDtype, DatetimeTZDtype,

    # missing
    isna, isnull, notna, notnull,

    # indexes
    Index, CategoricalIndex, Int64Index, UInt64Index, RangeIndex,
    Float64Index, MultiIndex, IntervalIndex, TimedeltaIndex,
    DatetimeIndex, PeriodIndex, IndexSlice,

    # tseries
    NaT, Period, period_range, Timedelta, timedelta_range,
    Timestamp, date_range, bdate_range, Interval, interval_range,
    DateOffset,

    # conversion
    to_numeric, to_datetime, to_timedelta,

    # misc
    np, Grouper, factorize, unique, value_counts, NamedAgg,
    array, Categorical, set_eng_float_format, Series, DataFrame,
    Panel)

A pseudo-prioritized list of annotations I think we need out of this would be the below. Open to suggestions on how to prioritize and obviously community PRs are very welcome!

...

These don't necessarily need to be completed in order. Will continue to expand checklist as we tackle more items so if you see something you'd like to tackle feel free to call it out

William Ayd · Answer 1 · Mon Jun 10 2019 21:35:15 GMT+0800 (China Standard Time)

@vaibhavhrt @gwrome

Vaibhav Vishal · Answer 2 · Mon Jun 10 2019 22:13:29 GMT+0800 (China Standard Time)

@WillAyd I am not sure what exactly needs to be done. Do we need to annotate every attribute/method of class DataFrame, Index, etc.? Can you provide some example(mypy docs or SO link maybe)

William Ayd · Answer 3 · Tue Jun 11 2019 02:52:08 GMT+0800 (China Standard Time)

Yes that's correct - would want to add annotations to the methods for these objects (and attributes where inference may not work)

Vaibhav Vishal · Answer 4 · Tue Jun 11 2019 11:57:53 GMT+0800 (China Standard Time)

Alright, I will start with DataFrame, since it's one of the few things in pandas I use in my projects. I will open a new issue for it.

…

On Tue, 11 Jun 2019, 12:23 am William Ayd, ***@***.***> wrote: Yes that's correct - would want to add annotations to the methods for these objects (and attributes where inference may not work) — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#26766?email_source=notifications&email_token=AFMJMLEF6TVCQMNDJMFMZDTPZ2PJDA5CNFSM4HWTSJS2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODXK3MQQ#issuecomment-500545090>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AFMJMLG2ABH4VDJNDYY4JVTPZ2PJDANCNFSM4HWTSJSQ> .

Tom Augspurger · Answer 5 · Tue Feb 11 2020 23:05:23 GMT+0800 (China Standard Time)

I'm unpinning this to make room for #31879. Will re-pin tomorrow.

finete · Answer 6 · Sun Nov 08 2020 17:21:11 GMT+0800 (China Standard Time)

@WillAyd I am not quite sure that I understand the meaning of this issue.
Is it about creating something like this?

class MyDataFrame(pandas.DataFrame):
    col_foo: datetime.datetime

def func(df: MyDataFrame):
    df['col_foo'].dt

func(MyDataFrame())  # mypy passes
func(pd.Dataframe(columns=['col_foo'] , dtype=np.datetime64))  # mypy passes?
func(pd.Dataframe(columns=['col_foo']))  # mypy raises error?

I was looking for something that imitates the dataclass\ NamedTuple usage api

William Ayd · Answer 7 · Wed Nov 11 2020 01:43:46 GMT+0800 (China Standard Time)

We can close this issue; I haven't tracked it in quite some time

finete · Answer 8 · Wed Nov 11 2020 01:52:04 GMT+0800 (China Standard Time)

@WillAyd which issue tracks development of something similar to the type annotations I have mentioned above?

karlicoss · Answer 9 · Wed Nov 11 2020 02:11:56 GMT+0800 (China Standard Time)

I'd be interested in something like this, obviously it would be very hard to type everything properly and conveniently (considering how dynamic pandas can be), but for simple usecases, having some helpers which exploit Literal and TypedDict could cover many cases where typing is desirable.

William Ayd · Answer 10 · Wed Nov 11 2020 02:17:51 GMT+0800 (China Standard Time)

Sounds good. Feel free to submit PRs to improve annotations - they are always welcome

jbrockmendel · Answer 11 · Sun Feb 12 2023 09:46:26 GMT+0800 (China Standard Time)

I think this has served its purpose. Closing.