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 = {