diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 965a5ae5cbd50..ba511e9dc4c55 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -105,16 +105,11 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.errors.UnsupportedFunctionCall \ pandas.test \ pandas.NaT \ - pandas.Timestamp.strptime \ pandas.Timestamp.time \ pandas.Timestamp.timetuple \ pandas.Timestamp.timetz \ pandas.Timestamp.to_datetime64 \ pandas.Timestamp.toordinal \ - pandas.Timestamp.tzname \ - pandas.Timestamp.utcoffset \ - pandas.Timestamp.utctimetuple \ - pandas.Timestamp.weekday \ pandas.arrays.TimedeltaArray \ pandas.Period.asfreq \ pandas.Period.now \ diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index a179aa225f845..9878e8861c0e6 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -429,6 +429,14 @@ class NaTType(_NaT): Return the day of the week represented by the date. Monday == 0 ... Sunday == 6. + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01') + >>> ts + Timestamp('2023-01-01 00:00:00') + >>> ts.weekday() + 6 """, ) isoweekday = _make_nan_func( @@ -514,13 +522,10 @@ class NaTType(_NaT): """, ) # _nat_methods - utctimetuple = _make_error_func("utctimetuple", datetime) timetz = _make_error_func("timetz", datetime) timetuple = _make_error_func("timetuple", datetime) time = _make_error_func("time", datetime) toordinal = _make_error_func("toordinal", datetime) - tzname = _make_error_func("tzname", datetime) - utcoffset = _make_error_func("utcoffset", datetime) # "fromisocalendar" was introduced in 3.8 fromisocalendar = _make_error_func("fromisocalendar", datetime) @@ -570,7 +575,49 @@ class NaTType(_NaT): datetime.date(2023, 1, 1) """ ) + utctimetuple = _make_error_func( + "utctimetuple", + """ + Return UTC time tuple, compatible with time.localtime(). + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels') + >>> ts + Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels') + >>> ts.utctimetuple() + time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1, tm_hour=9, + tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=0) + """ + ) + utcoffset = _make_error_func( + "utcoffset", + """ + Return utc offset. + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels') + >>> ts + Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels') + >>> ts.utcoffset() + datetime.timedelta(seconds=3600) + """ + ) + tzname = _make_error_func( + "tzname", + """ + Return time zone name. + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels') + >>> ts + Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels') + >>> ts.tzname() + 'CET' + """ + ) ctime = _make_error_func( "ctime", """ @@ -612,6 +659,12 @@ class NaTType(_NaT): Timestamp.strptime(string, format) Function is not implemented. Use pd.to_datetime(). + + Examples + -------- + >>> pd.Timestamp.strptime("2023-01-01", "%d/%m/%y") + Traceback (most recent call last): + NotImplementedError """, ) diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 54f0dac459990..ca256c3498e7d 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -1591,6 +1591,49 @@ class Timestamp(_Timestamp): ) from err return _dt.isocalendar() + def tzname(self): + """ + Return time zone name. + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels') + >>> ts + Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels') + >>> ts.tzname() + 'CET' + """ + return super().tzname() + + def utcoffset(self): + """ + Return utc offset. + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels') + >>> ts + Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels') + >>> ts.utcoffset() + datetime.timedelta(seconds=3600) + """ + return super().utcoffset() + + def utctimetuple(self): + """ + Return UTC time tuple, compatible with time.localtime(). + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels') + >>> ts + Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels') + >>> ts.utctimetuple() + time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1, tm_hour=9, + tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=0) + """ + return super().utctimetuple() + # Issue 25016. @classmethod def strptime(cls, date_string, format): @@ -1598,6 +1641,12 @@ class Timestamp(_Timestamp): Timestamp.strptime(string, format) Function is not implemented. Use pd.to_datetime(). + + Examples + -------- + >>> pd.Timestamp.strptime("2023-01-01", "%d/%m/%y") + Traceback (most recent call last): + NotImplementedError """ raise NotImplementedError( "Timestamp.strptime() is not implemented. " @@ -2463,6 +2512,14 @@ default 'raise' Return the day of the week represented by the date. Monday == 0 ... Sunday == 6. + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01') + >>> ts + Timestamp('2023-01-01 00:00:00') + >>> ts.weekday() + 6 """ # same as super().weekday(), but that breaks because of how # we have overridden year, see note in create_timestamp_from_ts