DOC: Fixing EX01 - Added examples

ci/code_checks.sh

@@ -65,16 +65,9 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
     $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX01 --ignore_functions \
         pandas.errors.IncompatibilityWarning \
         pandas.errors.InvalidComparison \
-        pandas.errors.IntCastingNaNError \
         pandas.errors.LossySetitemError \
-        pandas.errors.MergeError \
         pandas.errors.NoBufferPresent \
-        pandas.errors.NullFrequencyError \
-        pandas.errors.NumbaUtilError \
         pandas.errors.OptionError \
-        pandas.errors.OutOfBoundsDatetime \
-        pandas.errors.OutOfBoundsTimedelta \
-        pandas.errors.ParserError \
         pandas.errors.PerformanceWarning \
         pandas.errors.PyperclipException \
         pandas.errors.PyperclipWindowsException \

pandas/_libs/tslibs/np_datetime.pyx

@@ -158,6 +158,13 @@ cdef bint cmp_scalar(int64_t lhs, int64_t rhs, int op) except -1:
 class OutOfBoundsDatetime(ValueError):
     """
     Raised when the datetime is outside the range that can be represented.
+
+    Examples
+    --------
+    >>> pd.to_datetime("08335394550")
+    Traceback (most recent call last):
+    OutOfBoundsDatetime: Parsing "08335394550" to datetime overflows,
+    at position 0
     """
     pass
 
@@ -167,6 +174,13 @@ class OutOfBoundsTimedelta(ValueError):
     Raised when encountering a timedelta value that cannot be represented.
 
     Representation should be within a timedelta64[ns].
+
+    Examples
+    --------
+    >>> pd.date_range(start="1/1/1700", freq="B", periods=100000)
+    Traceback (most recent call last):
+    OutOfBoundsTimedelta: Cannot cast 139999 days 00:00:00
+    to unit='ns' without overflow.
     """
     # Timedelta analogue to OutOfBoundsDatetime
     pass

pandas/errors/__init__.py

@@ -18,6 +18,12 @@
 class IntCastingNaNError(ValueError):
     """
     Exception raised when converting (``astype``) an array with NaN to an integer type.
+
+    Examples
+    --------
+    >>> pd.DataFrame(np.array([[1, np.nan], [2, 3]]), dtype="i8")
+    Traceback (most recent call last):
+    IntCastingNaNError: Cannot convert non-finite values (NA or inf) to integer
     """
 
 
@@ -27,6 +33,13 @@ class NullFrequencyError(ValueError):
 
     Particularly ``DatetimeIndex.shift``, ``TimedeltaIndex.shift``,
     ``PeriodIndex.shift``.
+
+    Examples
+    --------
+    >>> df = pd.DatetimeIndex(["2011-01-01 10:00", "2011-01-01"], freq=None)
+    >>> df.shift(2)
+    Traceback (most recent call last):
+    NullFrequencyError: Cannot shift with no freq
     """
 
 
@@ -63,6 +76,17 @@ class ParserError(ValueError):
     --------
     read_csv : Read CSV (comma-separated) file into a DataFrame.
     read_html : Read HTML table into a DataFrame.
+
+    Examples
+    --------
+    >>> data = '''a,b,c
+    ... cat,foo,bar
+    ... dog,foo,"baz'''
+    >>> from io import StringIO
+    >>> pd.read_csv(StringIO(data), skipfooter=1, engine='python')
+    Traceback (most recent call last):
+    ParserError: ',' expected after '"'. Error could possibly be due
+    to parsing errors in the skipped footer rows
     """
 
 
@@ -181,6 +205,18 @@ class MergeError(ValueError):
     Exception raised when merging data.
 
     Subclass of ``ValueError``.
+
+    Examples
+    --------
+    >>> left = pd.DataFrame({"a": ["a", "b", "b", "d"],
+    ...                     "b": ["cat", "dog", "weasel", "horse"]},
+    ...                     index=range(4))
+    >>> right = pd.DataFrame({"a": ["a", "b", "c", "d"],
+    ...                      "c": ["meow", "bark", "chirp", "nay"]},
+    ...                      index=range(4)).set_index("a")
+    >>> left.join(right, on="a", validate="one_to_one",)
+    Traceback (most recent call last):
+    MergeError: Merge keys are not unique in left dataset; not a one-to-one merge
     """
 
 
@@ -225,6 +261,17 @@ def __str__(self) -> str:
 class NumbaUtilError(Exception):
     """
     Error raised for unsupported Numba engine routines.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"key": ["a", "a", "b", "b"], "data": [1, 2, 3, 4]},
+    ...                   columns=["key", "data"])
+    >>> def incorrect_function(x):
+    ...     return sum(x) * 2.7
+    >>> df.groupby("key").agg(incorrect_function, engine="numba")
+    Traceback (most recent call last):
+    NumbaUtilError: The first 2 arguments to incorrect_function
+    must be ['values', 'index']
     """