Skip to content

Commit 86f35d5

Browse files
sschessche
authored
Merge branch 'pandas-dev:main' into gh52234-nan-not-in-index
2 parents 90e63db + d2664fe commit 86f35d5

File tree

7 files changed

+275
-23
lines changed

7 files changed

+275
-23
lines changed

‎ci/code_checks.sh

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -105,16 +105,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
105105
pandas.errors.UnsupportedFunctionCall \
106106
pandas.test \
107107
pandas.NaT \
108-
pandas.Timestamp.strptime \
109-
pandas.Timestamp.time \
110-
pandas.Timestamp.timetuple \
111-
pandas.Timestamp.timetz \
112-
pandas.Timestamp.to_datetime64 \
113-
pandas.Timestamp.toordinal \
114-
pandas.Timestamp.tzname \
115-
pandas.Timestamp.utcoffset \
116-
pandas.Timestamp.utctimetuple \
117-
pandas.Timestamp.weekday \
118108
pandas.arrays.TimedeltaArray \
119109
pandas.Period.asfreq \
120110
pandas.Period.now \

‎doc/source/whatsnew/v2.1.0.rst

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -358,12 +358,11 @@ Datetimelike
358358
^^^^^^^^^^^^
359359
- :meth:`DatetimeIndex.map` with ``na_action="ignore"`` now works as expected. (:issue:`51644`)
360360
- Bug in :func:`date_range` when ``freq`` was a :class:`DateOffset` with ``nanoseconds`` (:issue:`46877`)
361-
- 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`)
361+
- 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`)
362362
- Bug in :meth:`Timestamp.round` with values close to the implementation bounds returning incorrect results instead of raising ``OutOfBoundsDatetime`` (:issue:`51494`)
363363
- Bug in :meth:`arrays.DatetimeArray.map` and :meth:`DatetimeIndex.map`, where the supplied callable operated array-wise instead of element-wise (:issue:`51977`)
364364
- 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`)
365365
- Bug in parsing datetime strings with weekday but no day e.g. "2023 Sept Thu" incorrectly raising ``AttributeError`` instead of ``ValueError`` (:issue:`52659`)
366-
-
367366

368367
Timedelta
369368
^^^^^^^^^

‎pandas/_libs/tslibs/nattype.pyx

Lines changed: 123 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -256,7 +256,16 @@ cdef class _NaT(datetime):
256256

257257
def to_datetime64(self) -> np.datetime64:
258258
"""
259-
Return a numpy.datetime64 object with 'ns' precision.
259+
Return a numpy.datetime64 object with same precision.
260+
261+
Examples
262+
--------
263+
>>> ts = pd.Timestamp(year=2023, month=1, day=1,
264+
... hour=10, second=15)
265+
>>> ts
266+
Timestamp('2023-01-01 10:00:15')
267+
>>> ts.to_datetime64()
268+
numpy.datetime64('2023-01-01T10:00:15.000000')
260269
"""
261270
return np.datetime64("NaT", "ns")
262271

@@ -429,6 +438,14 @@ class NaTType(_NaT):
429438
Return the day of the week represented by the date.
430439
431440
Monday == 0 ... Sunday == 6.
441+
442+
Examples
443+
--------
444+
>>> ts = pd.Timestamp('2023-01-01')
445+
>>> ts
446+
Timestamp('2023-01-01 00:00:00')
447+
>>> ts.weekday()
448+
6
432449
""",
433450
)
434451
isoweekday = _make_nan_func(
@@ -514,13 +531,6 @@ class NaTType(_NaT):
514531
""",
515532
)
516533
# _nat_methods
517-
utctimetuple = _make_error_func("utctimetuple", datetime)
518-
timetz = _make_error_func("timetz", datetime)
519-
timetuple = _make_error_func("timetuple", datetime)
520-
time = _make_error_func("time", datetime)
521-
toordinal = _make_error_func("toordinal", datetime)
522-
tzname = _make_error_func("tzname", datetime)
523-
utcoffset = _make_error_func("utcoffset", datetime)
524534

525535
# "fromisocalendar" was introduced in 3.8
526536
fromisocalendar = _make_error_func("fromisocalendar", datetime)
@@ -570,7 +580,106 @@ class NaTType(_NaT):
570580
datetime.date(2023, 1, 1)
571581
"""
572582
)
583+
utctimetuple = _make_error_func(
584+
"utctimetuple",
585+
"""
586+
Return UTC time tuple, compatible with time.localtime().
587+
588+
Examples
589+
--------
590+
>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
591+
>>> ts
592+
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
593+
>>> ts.utctimetuple()
594+
time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1, tm_hour=9,
595+
tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=0)
596+
"""
597+
)
598+
utcoffset = _make_error_func(
599+
"utcoffset",
600+
"""
601+
Return utc offset.
602+
603+
Examples
604+
--------
605+
>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
606+
>>> ts
607+
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
608+
>>> ts.utcoffset()
609+
datetime.timedelta(seconds=3600)
610+
"""
611+
)
612+
tzname = _make_error_func(
613+
"tzname",
614+
"""
615+
Return time zone name.
616+
617+
Examples
618+
--------
619+
>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
620+
>>> ts
621+
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
622+
>>> ts.tzname()
623+
'CET'
624+
"""
625+
)
626+
time = _make_error_func(
627+
"time",
628+
"""
629+
Return time object with same time but with tzinfo=None.
630+
631+
Examples
632+
--------
633+
>>> ts = pd.Timestamp('2023-01-01 10:00:00')
634+
>>> ts
635+
Timestamp('2023-01-01 10:00:00')
636+
>>> ts.time()
637+
datetime.time(10, 0)
638+
""",
639+
)
640+
timetuple = _make_error_func(
641+
"timetuple",
642+
"""
643+
Return time tuple, compatible with time.localtime().
644+
645+
Examples
646+
--------
647+
>>> ts = pd.Timestamp('2023-01-01 10:00:00')
648+
>>> ts
649+
Timestamp('2023-01-01 10:00:00')
650+
>>> ts.timetuple()
651+
time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1,
652+
tm_hour=10, tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=-1)
653+
"""
654+
)
655+
timetz = _make_error_func(
656+
"timetz",
657+
"""
658+
Return time object with same time and tzinfo.
659+
660+
Examples
661+
--------
662+
>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
663+
>>> ts
664+
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
665+
>>> ts.timetz()
666+
datetime.time(10, 0, tzinfo=<DstTzInfo 'Europe/Brussels' CET+1:00:00 STD>)
667+
"""
668+
)
669+
toordinal = _make_error_func(
670+
"toordinal",
671+
"""
672+
Return proleptic Gregorian ordinal. January 1 of year 1 is day 1.
573673
674+
Examples
675+
--------
676+
>>> ts = pd.Timestamp('2023-01-01 10:00:50')
677+
>>> ts
678+
Timestamp('2023-01-01 10:00:50')
679+
>>> ts.toordinal()
680+
738521
681+
"""
682+
)
574683
ctime = _make_error_func(
575684
"ctime",
576685
"""
@@ -612,6 +721,12 @@ class NaTType(_NaT):
612721
Timestamp.strptime(string, format)
613722
614723
Function is not implemented. Use pd.to_datetime().
724+
725+
Examples
726+
--------
727+
>>> pd.Timestamp.strptime("2023-01-01", "%d/%m/%y")
728+
Traceback (most recent call last):
729+
NotImplementedError
615730
""",
616731
)
617732

‎pandas/_libs/tslibs/period.pyx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1917,7 +1917,8 @@ cdef class _Period(PeriodMixin):
19171917
Parameters
19181918
----------
19191919
freq : str, BaseOffset
1920-
The desired frequency.
1920+
The desired frequency. If passing a `str`, it needs to be a
1921+
valid :ref:`period alias <timeseries.period_aliases>`.
19211922
how : {'E', 'S', 'end', 'start'}, default 'end'
19221923
Start or end of the timespan.
19231924

‎pandas/_libs/tslibs/timestamps.pyx

Lines changed: 142 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1204,7 +1204,16 @@ cdef class _Timestamp(ABCTimestamp):
12041204

12051205
cpdef to_datetime64(self):
12061206
"""
1207-
Return a numpy.datetime64 object with 'ns' precision.
1207+
Return a numpy.datetime64 object with same precision.
1208+
1209+
Examples
1210+
--------
1211+
>>> ts = pd.Timestamp(year=2023, month=1, day=1,
1212+
... hour=10, second=15)
1213+
>>> ts
1214+
Timestamp('2023-01-01 10:00:15')
1215+
>>> ts.to_datetime64()
1216+
numpy.datetime64('2023-01-01T10:00:15.000000')
12081217
"""
12091218
# TODO: find a way to construct dt64 directly from _reso
12101219
abbrev = npy_unit_to_abbrev(self._creso)
@@ -1591,13 +1600,137 @@ class Timestamp(_Timestamp):
15911600
) from err
15921601
return _dt.isocalendar()
15931602

1603+
def tzname(self):
1604+
"""
1605+
Return time zone name.
1606+
1607+
Examples
1608+
--------
1609+
>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
1610+
>>> ts
1611+
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
1612+
>>> ts.tzname()
1613+
'CET'
1614+
"""
1615+
return super().tzname()
1616+
1617+
def utcoffset(self):
1618+
"""
1619+
Return utc offset.
1620+
1621+
Examples
1622+
--------
1623+
>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
1624+
>>> ts
1625+
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
1626+
>>> ts.utcoffset()
1627+
datetime.timedelta(seconds=3600)
1628+
"""
1629+
return super().utcoffset()
1630+
1631+
def utctimetuple(self):
1632+
"""
1633+
Return UTC time tuple, compatible with time.localtime().
1634+
1635+
Examples
1636+
--------
1637+
>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
1638+
>>> ts
1639+
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
1640+
>>> ts.utctimetuple()
1641+
time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1, tm_hour=9,
1642+
tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=0)
1643+
"""
1644+
return super().utctimetuple()
1645+
1646+
def time(self):
1647+
"""
1648+
Return time object with same time but with tzinfo=None.
1649+
1650+
Examples
1651+
--------
1652+
>>> ts = pd.Timestamp('2023-01-01 10:00:00')
1653+
>>> ts
1654+
Timestamp('2023-01-01 10:00:00')
1655+
>>> ts.time()
1656+
datetime.time(10, 0)
1657+
"""
1658+
return super().time()
1659+
1660+
def timetuple(self):
1661+
"""
1662+
Return time tuple, compatible with time.localtime().
1663+
1664+
Examples
1665+
--------
1666+
>>> ts = pd.Timestamp('2023-01-01 10:00:00')
1667+
>>> ts
1668+
Timestamp('2023-01-01 10:00:00')
1669+
>>> ts.timetuple()
1670+
time.struct_time(tm_year=2023, tm_mon=1, tm_mday=1,
1671+
tm_hour=10, tm_min=0, tm_sec=0, tm_wday=6, tm_yday=1, tm_isdst=-1)
1672+
"""
1673+
try:
1674+
_dt = datetime(self.year, self.month, self.day,
1675+
self.hour, self.minute, self.second,
1676+
self.microsecond, self.tzinfo, fold=self.fold)
1677+
except ValueError as err:
1678+
raise NotImplementedError(
1679+
"timetuple not yet supported on Timestamps which "
1680+
"are outside the range of Python's standard library. "
1681+
) from err
1682+
return _dt.timetuple()
1683+
1684+
def timetz(self):
1685+
"""
1686+
Return time object with same time and tzinfo.
1687+
1688+
Examples
1689+
--------
1690+
>>> ts = pd.Timestamp('2023-01-01 10:00:00', tz='Europe/Brussels')
1691+
>>> ts
1692+
Timestamp('2023-01-01 10:00:00+0100', tz='Europe/Brussels')
1693+
>>> ts.timetz()
1694+
datetime.time(10, 0, tzinfo=<DstTzInfo 'Europe/Brussels' CET+1:00:00 STD>)
1695+
"""
1696+
return super().timetz()
1697+
1698+
def toordinal(self):
1699+
"""
1700+
Return proleptic Gregorian ordinal. January 1 of year 1 is day 1.
1701+
1702+
Examples
1703+
--------
1704+
>>> ts = pd.Timestamp('2023-01-01 10:00:50')
1705+
>>> ts
1706+
Timestamp('2023-01-01 10:00:50')
1707+
>>> ts.toordinal()
1708+
738521
1709+
"""
1710+
try:
1711+
_dt = datetime(self.year, self.month, self.day,
1712+
self.hour, self.minute, self.second,
1713+
self.microsecond, self.tzinfo, fold=self.fold)
1714+
except ValueError as err:
1715+
raise NotImplementedError(
1716+
"toordinal not yet supported on Timestamps which "
1717+
"are outside the range of Python's standard library. "
1718+
) from err
1719+
return _dt.toordinal()
1720+
15941721
# Issue 25016.
15951722
@classmethod
15961723
def strptime(cls, date_string, format):
15971724
"""
15981725
Timestamp.strptime(string, format)
15991726
16001727
Function is not implemented. Use pd.to_datetime().
1728+
1729+
Examples
1730+
--------
1731+
>>> pd.Timestamp.strptime("2023-01-01", "%d/%m/%y")
1732+
Traceback (most recent call last):
1733+
NotImplementedError
16011734
"""
16021735
raise NotImplementedError(
16031736
"Timestamp.strptime() is not implemented. "
@@ -2463,6 +2596,14 @@ default 'raise'
24632596
Return the day of the week represented by the date.
24642597
24652598
Monday == 0 ... Sunday == 6.
2599+
2600+
Examples
2601+
--------
2602+
>>> ts = pd.Timestamp('2023-01-01')
2603+
>>> ts
2604+
Timestamp('2023-01-01 00:00:00')
2605+
>>> ts.weekday()
2606+
6
24662607
"""
24672608
# same as super().weekday(), but that breaks because of how
24682609
# we have overridden year, see note in create_timestamp_from_ts

‎pandas/core/ops/docstrings.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -463,7 +463,7 @@ def make_flex_doc(op_name: str, typ: str) -> str:
463463
Equivalent to ``{equiv}``, but with support to substitute a fill_value
464464
for missing data in one of the inputs. With reverse version, `{reverse}`.
465465
466-
Among flexible wrappers (`add`, `sub`, `mul`, `div`, `mod`, `pow`) to
466+
Among flexible wrappers (`add`, `sub`, `mul`, `div`, `floordiv`, `mod`, `pow`) to
467467
arithmetic operators: `+`, `-`, `*`, `/`, `//`, `%`, `**`.
468468
469469
Parameters

‎pandas/tests/scalar/timestamp/test_timestamp.py

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1142,3 +1142,9 @@ def test_negative_dates():
11421142
func = "^isocalendar"
11431143
with pytest.raises(NotImplementedError, match=func + msg):
11441144
ts.isocalendar()
1145+
func = "^timetuple"
1146+
with pytest.raises(NotImplementedError, match=func + msg):
1147+
ts.timetuple()
1148+
func = "^toordinal"
1149+
with pytest.raises(NotImplementedError, match=func + msg):
1150+
ts.toordinal()

0 commit comments

Comments
 (0)