From 1876e768793359a5ad13a797b7d2f621a8a5bff8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Wed, 21 Jun 2023 15:49:06 +0200 Subject: [PATCH] DOC: Fixing EX01 - Added examples (#53725) * Examples Timestamp.time, timetuple, timetz, to_datetime64, toordinal * Added tests and updated code_checks.sh * Corrected time and timetz * Corrected Timestamp.time and timetz --- ci/code_checks.sh | 5 -- doc/source/whatsnew/v2.1.0.rst | 3 +- pandas/_libs/tslibs/nattype.pyx | 72 ++++++++++++++-- pandas/_libs/tslibs/timestamps.pyx | 86 ++++++++++++++++++- .../tests/scalar/timestamp/test_timestamp.py | 6 ++ 5 files changed, 159 insertions(+), 13 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index ba511e9dc4c55b..693017c6715ae9 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -105,11 +105,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.errors.UnsupportedFunctionCall \ pandas.test \ pandas.NaT \ - pandas.Timestamp.time \ - pandas.Timestamp.timetuple \ - pandas.Timestamp.timetz \ - pandas.Timestamp.to_datetime64 \ - pandas.Timestamp.toordinal \ pandas.arrays.TimedeltaArray \ pandas.Period.asfreq \ pandas.Period.now \ diff --git a/doc/source/whatsnew/v2.1.0.rst b/doc/source/whatsnew/v2.1.0.rst index 44691e4265f5b4..45d3c349ba94e9 100644 --- a/doc/source/whatsnew/v2.1.0.rst +++ b/doc/source/whatsnew/v2.1.0.rst @@ -358,12 +358,11 @@ Datetimelike ^^^^^^^^^^^^ - :meth:`DatetimeIndex.map` with ``na_action="ignore"`` now works as expected. (:issue:`51644`) - Bug in :func:`date_range` when ``freq`` was a :class:`DateOffset` with ``nanoseconds`` (:issue:`46877`) -- Bug in :meth:`Timestamp.date`, :meth:`Timestamp.isocalendar` were returning incorrect results for inputs outside those supported by the Python standard library's datetime module (:issue:`53668`) +- Bug in :meth:`Timestamp.date`, :meth:`Timestamp.isocalendar`, :meth:`Timestamp.timetuple`, and :meth:`Timestamp.toordinal` were returning incorrect results for inputs outside those supported by the Python standard library's datetime module (:issue:`53668`) - Bug in :meth:`Timestamp.round` with values close to the implementation bounds returning incorrect results instead of raising ``OutOfBoundsDatetime`` (:issue:`51494`) - Bug in :meth:`arrays.DatetimeArray.map` and :meth:`DatetimeIndex.map`, where the supplied callable operated array-wise instead of element-wise (:issue:`51977`) - Bug in constructing a :class:`Series` or :class:`DataFrame` from a datetime or timedelta scalar always inferring nanosecond resolution instead of inferring from the input (:issue:`52212`) - Bug in parsing datetime strings with weekday but no day e.g. "2023 Sept Thu" incorrectly raising ``AttributeError`` instead of ``ValueError`` (:issue:`52659`) -- Timedelta ^^^^^^^^^ diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 9878e8861c0e65..09e38e3a979b24 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -256,7 +256,16 @@ cdef class _NaT(datetime): def to_datetime64(self) -> np.datetime64: """ - Return a numpy.datetime64 object with 'ns' precision. + Return a numpy.datetime64 object with same precision. + + Examples + -------- + >>> ts = pd.Timestamp(year=2023, month=1, day=1, + ... hour=10, second=15) + >>> ts + Timestamp('2023-01-01 10:00:15') + >>> ts.to_datetime64() + numpy.datetime64('2023-01-01T10:00:15.000000') """ return np.datetime64("NaT", "ns") @@ -522,10 +531,6 @@ class NaTType(_NaT): """, ) # _nat_methods - timetz = _make_error_func("timetz", datetime) - timetuple = _make_error_func("timetuple", datetime) - time = _make_error_func("time", datetime) - toordinal = _make_error_func("toordinal", datetime) # "fromisocalendar" was introduced in 3.8 fromisocalendar = _make_error_func("fromisocalendar", datetime) @@ -618,6 +623,63 @@ class NaTType(_NaT): 'CET' """ ) + time = _make_error_func( + "time", + """ + Return time object with same time but with tzinfo=None. + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00') + >>> ts + Timestamp('2023-01-01 10:00:00') + >>> ts.time() + datetime.time(10, 0) + """, + ) + timetuple = _make_error_func( + "timetuple", + """ + Return time tuple, compatible with time.localtime(). + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00') + >>> ts + Timestamp('2023-01-01 10:00:00') + >>> ts.timetuple() + time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1, + tm_hour=10, tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=-1) + """ + ) + timetz = _make_error_func( + "timetz", + """ + Return time object with same time and tzinfo. + + 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.timetz() + datetime.time(10, 0, tzinfo=) + """ + ) + toordinal = _make_error_func( + "toordinal", + """ + Return proleptic Gregorian ordinal. January 1 of year 1 is day 1. + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:50') + >>> ts + Timestamp('2023-01-01 10:00:50') + >>> ts.toordinal() + 738521 + """ + ) ctime = _make_error_func( "ctime", """ diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index ca256c3498e7dd..844fc8f0ed187c 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -1204,7 +1204,16 @@ cdef class _Timestamp(ABCTimestamp): cpdef to_datetime64(self): """ - Return a numpy.datetime64 object with 'ns' precision. + Return a numpy.datetime64 object with same precision. + + Examples + -------- + >>> ts = pd.Timestamp(year=2023, month=1, day=1, + ... hour=10, second=15) + >>> ts + Timestamp('2023-01-01 10:00:15') + >>> ts.to_datetime64() + numpy.datetime64('2023-01-01T10:00:15.000000') """ # TODO: find a way to construct dt64 directly from _reso abbrev = npy_unit_to_abbrev(self._creso) @@ -1634,6 +1643,81 @@ class Timestamp(_Timestamp): """ return super().utctimetuple() + def time(self): + """ + Return time object with same time but with tzinfo=None. + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00') + >>> ts + Timestamp('2023-01-01 10:00:00') + >>> ts.time() + datetime.time(10, 0) + """ + return super().time() + + def timetuple(self): + """ + Return time tuple, compatible with time.localtime(). + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:00') + >>> ts + Timestamp('2023-01-01 10:00:00') + >>> ts.timetuple() + time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1, + tm_hour=10, tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=-1) + """ + try: + _dt = datetime(self.year, self.month, self.day, + self.hour, self.minute, self.second, + self.microsecond, self.tzinfo, fold=self.fold) + except ValueError as err: + raise NotImplementedError( + "timetuple not yet supported on Timestamps which " + "are outside the range of Python's standard library. " + ) from err + return _dt.timetuple() + + def timetz(self): + """ + Return time object with same time and tzinfo. + + 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.timetz() + datetime.time(10, 0, tzinfo=) + """ + return super().timetz() + + def toordinal(self): + """ + Return proleptic Gregorian ordinal. January 1 of year 1 is day 1. + + Examples + -------- + >>> ts = pd.Timestamp('2023-01-01 10:00:50') + >>> ts + Timestamp('2023-01-01 10:00:50') + >>> ts.toordinal() + 738521 + """ + try: + _dt = datetime(self.year, self.month, self.day, + self.hour, self.minute, self.second, + self.microsecond, self.tzinfo, fold=self.fold) + except ValueError as err: + raise NotImplementedError( + "toordinal not yet supported on Timestamps which " + "are outside the range of Python's standard library. " + ) from err + return _dt.toordinal() + # Issue 25016. @classmethod def strptime(cls, date_string, format): diff --git a/pandas/tests/scalar/timestamp/test_timestamp.py b/pandas/tests/scalar/timestamp/test_timestamp.py index 2e4b41e06bbd64..aa326f3a43bd51 100644 --- a/pandas/tests/scalar/timestamp/test_timestamp.py +++ b/pandas/tests/scalar/timestamp/test_timestamp.py @@ -1142,3 +1142,9 @@ def test_negative_dates(): func = "^isocalendar" with pytest.raises(NotImplementedError, match=func + msg): ts.isocalendar() + func = "^timetuple" + with pytest.raises(NotImplementedError, match=func + msg): + ts.timetuple() + func = "^toordinal" + with pytest.raises(NotImplementedError, match=func + msg): + ts.toordinal()