diff --git a/ci/code_checks.sh b/ci/code_checks.sh index f6ed36b735cf4..9ef8a7395d30e 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -63,16 +63,12 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then MSG='Partially validate docstrings (EX01)' ; echo $MSG $BASE_DIR/scripts/validate_docstrings.py --format=actions --errors=EX01 --ignore_functions \ - pandas.errors.PyperclipWindowsException \ - pandas.errors.UnsupportedFunctionCall \ pandas.NaT \ - pandas.io.stata.StataReader.data_label \ pandas.io.stata.StataReader.value_labels \ pandas.io.stata.StataReader.variable_labels \ pandas.io.stata.StataWriter.write_file \ pandas.plotting.deregister_matplotlib_converters \ pandas.plotting.register_matplotlib_converters \ - pandas.api.extensions.ExtensionDtype \ pandas.api.extensions.ExtensionArray \ pandas.arrays.NumpyExtensionArray \ RET=$(($RET + $?)) ; echo $MSG "DONE" diff --git a/pandas/core/dtypes/base.py b/pandas/core/dtypes/base.py index 83656ba1ca14a..c6c162001d147 100644 --- a/pandas/core/dtypes/base.py +++ b/pandas/core/dtypes/base.py @@ -82,17 +82,22 @@ class property**. ``__eq__`` or ``__hash__``, the default implementations here will not work. + Examples + -------- + For interaction with Apache Arrow (pyarrow), a ``__from_arrow__`` method can be implemented: this method receives a pyarrow Array or ChunkedArray as only argument and is expected to return the appropriate pandas - ExtensionArray for this dtype and the passed values:: - - class ExtensionDtype: - - def __from_arrow__( - self, array: Union[pyarrow.Array, pyarrow.ChunkedArray] - ) -> ExtensionArray: - ... + ExtensionArray for this dtype and the passed values: + + >>> import pyarrow + >>> from pandas.api.extensions import ExtensionArray + >>> class ExtensionDtype: + ... def __from_arrow__( + ... self, + ... array: pyarrow.Array | pyarrow.ChunkedArray + ... ) -> ExtensionArray: + ... ... This class does not inherit from 'abc.ABCMeta' for performance reasons. Methods and properties required by the interface raise diff --git a/pandas/errors/__init__.py b/pandas/errors/__init__.py index 0a9d9390e7c37..09a612eca0529 100644 --- a/pandas/errors/__init__.py +++ b/pandas/errors/__init__.py @@ -74,6 +74,17 @@ class UnsupportedFunctionCall(ValueError): Exception raised when attempting to call a unsupported numpy function. For example, ``np.cumsum(groupby_object)``. + + Examples + -------- + >>> df = pd.DataFrame({"A": [0, 0, 1, 1], + ... "B": ["x", "x", "z", "y"], + ... "C": [1, 2, 3, 4]} + ... ) + >>> np.cumsum(df.groupby(["A"])) + Traceback (most recent call last): + UnsupportedFunctionCall: numpy operations are not valid with groupby. + Use .groupby(...).cumsum() instead """ diff --git a/pandas/io/stata.py b/pandas/io/stata.py index 633f67cac4643..449e404869d56 100644 --- a/pandas/io/stata.py +++ b/pandas/io/stata.py @@ -2031,6 +2031,19 @@ def _do_convert_categoricals( def data_label(self) -> str: """ Return data label of Stata file. + + Examples + -------- + >>> df = pd.DataFrame([(1,)], columns=["variable"]) + >>> time_stamp = pd.Timestamp(2000, 2, 29, 14, 21) + >>> data_label = "This is a data file." + >>> path = "/My_path/filename.dta" + >>> df.to_stata(path, time_stamp=time_stamp, # doctest: +SKIP + ... data_label=data_label, # doctest: +SKIP + ... version=None) # doctest: +SKIP + >>> with pd.io.stata.StataReader(path) as reader: # doctest: +SKIP + ... print(reader.data_label) # doctest: +SKIP + This is a data file. """ self._ensure_open() return self._data_label diff --git a/scripts/validate_docstrings.py b/scripts/validate_docstrings.py index 43cca70d92077..b1b63b469ec3b 100755 --- a/scripts/validate_docstrings.py +++ b/scripts/validate_docstrings.py @@ -54,6 +54,7 @@ "errors.NoBufferPresent", "errors.IncompatibilityWarning", "errors.PyperclipException", + "errors.PyperclipWindowsException", } PRIVATE_CLASSES = ["NDFrame", "IndexOpsMixin"] ERROR_MSGS = {