diff --git a/ci/code_checks.sh b/ci/code_checks.sh index bb2dacd2ead61..0d28dcd046a7b 100755 --- a/ci/code_checks.sh +++ b/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 \ diff --git a/pandas/_libs/tslibs/np_datetime.pyx b/pandas/_libs/tslibs/np_datetime.pyx index 990f862c3d105..7b2ee68c73ad2 100644 --- a/pandas/_libs/tslibs/np_datetime.pyx +++ b/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 diff --git a/pandas/errors/__init__.py b/pandas/errors/__init__.py index a4597551acc71..ba2723fe66744 100644 --- a/pandas/errors/__init__.py +++ b/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'] """