Skip to content

Commit d2664fe

Browse files
DeaMariaLeonDeaMariaLeon
authored
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
1 parent f64a0e3 commit d2664fe

File tree

5 files changed

+159
-13
lines changed

5 files changed

+159
-13
lines changed

Diff for: ‎ci/code_checks.sh

-5
Original file line numberDiff line numberDiff line change
@@ -105,11 +105,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
105105
pandas.errors.UnsupportedFunctionCall \
106106
pandas.test \
107107
pandas.NaT \
108-
pandas.Timestamp.time \
109-
pandas.Timestamp.timetuple \
110-
pandas.Timestamp.timetz \
111-
pandas.Timestamp.to_datetime64 \
112-
pandas.Timestamp.toordinal \
113108
pandas.arrays.TimedeltaArray \
114109
pandas.Period.asfreq \
115110
pandas.Period.now \

Diff for: ‎doc/source/whatsnew/v2.1.0.rst

+1-2
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
^^^^^^^^^

Diff for: ‎pandas/_libs/tslibs/nattype.pyx

+67-5
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

@@ -522,10 +531,6 @@ class NaTType(_NaT):
522531
""",
523532
)
524533
# _nat_methods
525-
timetz = _make_error_func("timetz", datetime)
526-
timetuple = _make_error_func("timetuple", datetime)
527-
time = _make_error_func("time", datetime)
528-
toordinal = _make_error_func("toordinal", datetime)
529534

530535
# "fromisocalendar" was introduced in 3.8
531536
fromisocalendar = _make_error_func("fromisocalendar", datetime)
@@ -618,6 +623,63 @@ class NaTType(_NaT):
618623
'CET'
619624
"""
620625
)
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.
673+
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+
)
621683
ctime = _make_error_func(
622684
"ctime",
623685
"""

Diff for: ‎pandas/_libs/tslibs/timestamps.pyx

+85-1
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)
@@ -1634,6 +1643,81 @@ class Timestamp(_Timestamp):
16341643
"""
16351644
return super().utctimetuple()
16361645

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+
16371721
# Issue 25016.
16381722
@classmethod
16391723
def strptime(cls, date_string, format):

Diff for: ‎pandas/tests/scalar/timestamp/test_timestamp.py

+6
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)