DOC: Fixing EX01 - Added examples

ci/code_checks.sh

@@ -105,10 +105,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         pandas.errors.UnsupportedFunctionCall \
         pandas.test \
         pandas.NaT \
-        pandas.Timestamp.date \
-        pandas.Timestamp.dst \
-        pandas.Timestamp.isocalendar \
-        pandas.Timestamp.isoweekday \
         pandas.Timestamp.strptime \
         pandas.Timestamp.time \
         pandas.Timestamp.timetuple \

pandas/_libs/tslibs/nattype.pyx

@@ -437,6 +437,14 @@ class NaTType(_NaT):
         Return the day of the week represented by the date.
 
         Monday == 1 ... Sunday == 7.
+
+        Examples
+        --------
+        >>> ts = pd.Timestamp('2023-01-01 10:00:00')
+        >>> ts
+        Timestamp('2023-01-01 10:00:00')
+        >>> ts.isoweekday()
+        7
         """,
     )
     total_seconds = _make_nan_func(
@@ -506,13 +514,9 @@ class NaTType(_NaT):
         """,
     )
     # _nat_methods
-    date = _make_nat_func("date", datetime.date.__doc__)
-
     utctimetuple = _make_error_func("utctimetuple", datetime)
     timetz = _make_error_func("timetz", datetime)
     timetuple = _make_error_func("timetuple", datetime)
-    isocalendar = _make_error_func("isocalendar", datetime)
-    dst = _make_error_func("dst", datetime)
     time = _make_error_func("time", datetime)
     toordinal = _make_error_func("toordinal", datetime)
     tzname = _make_error_func("tzname", datetime)
@@ -524,6 +528,47 @@ class NaTType(_NaT):
     # ----------------------------------------------------------------------
     # The remaining methods have docstrings copy/pasted from the analogous
     # Timestamp methods.
+    isocalendar = _make_error_func(
+        "isocalendar",
+        """
+        Return a named tuple containing ISO year, week number, and weekday.
+
+        Examples
+        --------
+        >>> ts = pd.Timestamp('2023-01-01 10:00:00')
+        >>> ts
+        Timestamp('2023-01-01 10:00:00')
+        >>> ts.isocalendar()
+        datetime.IsoCalendarDate(year=2022, week=52, weekday=7)
+        """
+        )
+    dst = _make_error_func(
+        "dst",
+        """
+        Return self.tzinfo.dst(self).
+
+        Examples
+        --------
+        >>> ts = pd.Timestamp('2000-06-01 00:00:00',
+        ...                   tz='Europe/Brussels').dst()
+        >>> ts
+        datetime.timedelta(seconds=3600)
+        """
+        )
+    date = _make_nat_func(
+        "date",
+        """
+        Return date object with same year, month and day.
+
+        Examples
+        --------
+        >>> ts = pd.Timestamp('2023-01-01 10:00:00.00')
+        >>> ts
+        Timestamp('2023-01-01 10:00:00')
+        >>> ts.date()
+        datetime.date(2023, 1, 1)
+        """
+        )
 
     ctime = _make_error_func(
         "ctime",

pandas/_libs/tslibs/timestamps.pyx

@@ -1531,6 +1531,70 @@ class Timestamp(_Timestamp):
             ) from err
         return _dt.ctime()
 
+    def date(self):
+        """
+        Return date object with same year, month and day.
+
+        Examples
+        --------
+        >>> ts = pd.Timestamp('2023-01-01 10:00:00.00')
+        >>> ts
+        Timestamp('2023-01-01 10:00:00')
+        >>> ts.date()
+        datetime.date(2023, 1, 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(
+                "date not yet supported on Timestamps which "
+                "are outside the range of Python's standard library. "
+                "For now, please call the components you need (such as `.year` "
+                "and `.month`) and construct your string from there."
+            ) from err
+        return _dt.date()
+
+    def dst(self):
+        """
+        Return self.tzinfo.dst(self).
+
+        Examples
+        --------
+        >>> ts = pd.Timestamp('2000-06-01 00:00:00',
+        ...                   tz='Europe/Brussels').dst()
+        >>> ts
+        datetime.timedelta(seconds=3600)
+        """
+        _dt = datetime(self.year, self.month, self.day,
+                       self.hour, self.minute, self.second,
+                       self.microsecond, self.tzinfo, fold=self.fold)
+        return _dt.dst()
+
+    def isocalendar(self):
+        """
+        Return a named tuple containing ISO year, week number, and weekday.
+
+        Examples
+        --------
+        >>> ts = pd.Timestamp('2023-01-01 10:00:00')
+        >>> ts
+        Timestamp('2023-01-01 10:00:00')
+        >>> ts.isocalendar()
+        datetime.IsoCalendarDate(year=2022, week=52, weekday=7)
+        """
+        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(
+                "isocalendar not yet supported on Timestamps which "
+                "are outside the range of Python's standard library. "
+            ) from err
+        return _dt.isocalendar()
+
     # Issue 25016.
     @classmethod
     def strptime(cls, date_string, format):
@@ -2384,10 +2448,27 @@ default 'raise'
         Return the day of the week represented by the date.
 
         Monday == 1 ... Sunday == 7.
+
+        Examples
+        --------
+        >>> ts = pd.Timestamp('2023-01-01 10:00:00')
+        >>> ts
+        Timestamp('2023-01-01 10:00:00')
+        >>> ts.isoweekday()
+        7
         """
         # same as super().isoweekday(), but that breaks because of how
         #  we have overridden year, see note in create_timestamp_from_ts
-        return self.weekday() + 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(
+                "isocalendar not yet supported on Timestamps which "
+                "are outside the range of Python's standard library. "
+            ) from err
+        return _dt.weekday() + 1
 
     def weekday(self):
         """

pandas/tests/scalar/timestamp/test_timestamp.py

@@ -1124,9 +1124,25 @@ def test_negative_dates():
     # https://github.com/pandas-dev/pandas/issues/50787
     ts = Timestamp("-2000-01-01")
     msg = (
-        "^strftime not yet supported on Timestamps which are outside the range of "
+        " not yet supported on Timestamps which are outside the range of "
         "Python's standard library. For now, please call the components you need "
         r"\(such as `.year` and `.month`\) and construct your string from there.$"
     )
-    with pytest.raises(NotImplementedError, match=msg):
+    func = "^strftime"
+    with pytest.raises(NotImplementedError, match=func + msg):
         ts.strftime("%Y")
+    func = "^date"
+    with pytest.raises(NotImplementedError, match=func + msg):
+        ts.date()
+
+    msg = (
+        "isocalendar not yet supported on Timestamps which "
+        "are outside the range of Python's standard library. "
+    )
+    with pytest.raises(NotImplementedError, match=msg):
+        ts.isocalendar()
+    with pytest.raises(NotImplementedError, match=msg):
+        ts.isoweekday()
+
+    with pytest.raises(pytz.NonExistentTimeError, match="-2000-01-01 00:00:00"):
+        Timestamp("-2000", tz="Europe/Brussels").dst()