DOC: Fixing EX01 - Added examples (#54318)

* Examples for UnsupportedFunctionCall ...

* Changed ExtensionDtype example,  & file's name on StataREader.data_label

* removed colon

Author: DeaMariaLeon

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"

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

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
     """
 
 

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

scripts/validate_docstrings.py

@@ -54,6 +54,7 @@
     "errors.NoBufferPresent",
     "errors.IncompatibilityWarning",
     "errors.PyperclipException",
+    "errors.PyperclipWindowsException",
 }
 PRIVATE_CLASSES = ["NDFrame", "IndexOpsMixin"]
 ERROR_MSGS = {