From 64b2588eb85d2f88a804acb85aab27673580d8a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Mon, 31 Jul 2023 11:09:37 +0200 Subject: [PATCH 1/3] Examples for UnsupportedFunctionCall ... --- ci/code_checks.sh | 4 ---- pandas/core/dtypes/base.py | 16 ++++++++++------ pandas/errors/__init__.py | 11 +++++++++++ pandas/io/stata.py | 13 +++++++++++++ scripts/validate_docstrings.py | 1 + 5 files changed, 35 insertions(+), 10 deletions(-) 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..44a989e465690 100644 --- a/pandas/core/dtypes/base.py +++ b/pandas/core/dtypes/base.py @@ -82,17 +82,21 @@ 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: - ... + >>> import pyarrow # doctest: +SKIP + >>> from pd.api.extensions import ExtensionArray # doctest: +SKIP + >>> class ExtensionDtype: # doctest: +SKIP + ... def __from_arrow__(self, array: pyarrow.Union[pyarrow.Array, + ... pyarrow.ChunkedArray] + ... ) -> ExtensionArray: # doctest: +SKIP + ... ... 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..e03591e283f0e 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" + >>> 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 = { From 3c69badaba2520589534b90c127ece321d117d17 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Mon, 31 Jul 2023 12:09:35 +0200 Subject: [PATCH 2/3] Changed ExtensionDtype example, & file's name on StataREader.data_label --- pandas/core/dtypes/base.py | 13 +++++++------ pandas/io/stata.py | 2 +- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/pandas/core/dtypes/base.py b/pandas/core/dtypes/base.py index 44a989e465690..6f7886c3f1131 100644 --- a/pandas/core/dtypes/base.py +++ b/pandas/core/dtypes/base.py @@ -90,12 +90,13 @@ class property**. as only argument and is expected to return the appropriate pandas ExtensionArray for this dtype and the passed values:: - >>> import pyarrow # doctest: +SKIP - >>> from pd.api.extensions import ExtensionArray # doctest: +SKIP - >>> class ExtensionDtype: # doctest: +SKIP - ... def __from_arrow__(self, array: pyarrow.Union[pyarrow.Array, - ... pyarrow.ChunkedArray] - ... ) -> ExtensionArray: # doctest: +SKIP + >>> 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. diff --git a/pandas/io/stata.py b/pandas/io/stata.py index e03591e283f0e..449e404869d56 100644 --- a/pandas/io/stata.py +++ b/pandas/io/stata.py @@ -2037,7 +2037,7 @@ def data_label(self) -> str: >>> 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" + >>> 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 From ef806587d0da051b3025b2e3445b96be5c331435 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Mon, 31 Jul 2023 14:31:24 +0200 Subject: [PATCH 3/3] removed colon --- pandas/core/dtypes/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/dtypes/base.py b/pandas/core/dtypes/base.py index 6f7886c3f1131..c6c162001d147 100644 --- a/pandas/core/dtypes/base.py +++ b/pandas/core/dtypes/base.py @@ -88,7 +88,7 @@ class property**. 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:: + ExtensionArray for this dtype and the passed values: >>> import pyarrow >>> from pandas.api.extensions import ExtensionArray