DOC: Fixing EX01 - Added examples (#54242)

Examples interchange

Author: DeaMariaLeon

ci/code_checks.sh

@@ -83,8 +83,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         pandas.util.hash_array \
         pandas.util.hash_pandas_object \
         pandas_object \
-        pandas.api.interchange.from_dataframe \
-        pandas.DatetimeIndex.snap \
         pandas.api.indexers.BaseIndexer \
         pandas.api.indexers.VariableOffsetWindowIndexer \
         pandas.api.extensions.ExtensionDtype \
@@ -100,7 +98,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         pandas.api.extensions.ExtensionArray._values_for_factorize \
         pandas.api.extensions.ExtensionArray.interpolate \
         pandas.api.extensions.ExtensionArray.ravel \
-        pandas.DataFrame.__dataframe__
     RET=$(($RET + $?)) ; echo $MSG "DONE"
 
 fi

pandas/core/frame.py

@@ -912,6 +912,22 @@ def __dataframe__(
 
         `nan_as_null` currently has no effect; once support for nullable extension
         dtypes is added, this value should be propagated to columns.
+
+        Examples
+        --------
+        >>> df_not_necessarily_pandas = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
+        >>> interchange_object = df_not_necessarily_pandas.__dataframe__()
+        >>> interchange_object.column_names()
+        Index(['A', 'B'], dtype='object')
+        >>> df_pandas = (pd.api.interchange.from_dataframe
+        ...              (interchange_object.select_columns_by_name(['A'])))
+        >>> df_pandas
+             A
+        0    1
+        1    2
+
+        These methods (``column_names``, ``select_columns_by_name``) should work
+        for any dataframe library which implements the interchange protocol.
         """
 
         from pandas.core.interchange.dataframe import PandasDataFrameXchg

pandas/core/indexes/datetimes.py

@@ -487,6 +487,17 @@ def snap(self, freq: Frequency = "S") -> DatetimeIndex:
         Returns
         -------
         DatetimeIndex
+
+        Examples
+        --------
+        >>> idx = pd.DatetimeIndex(['2023-01-01', '2023-01-02',
+        ...                        '2023-02-01', '2023-02-02'])
+        >>> idx
+        DatetimeIndex(['2023-01-01', '2023-01-02', '2023-02-01', '2023-02-02'],
+        dtype='datetime64[ns]', freq=None)
+        >>> idx.snap('MS')
+        DatetimeIndex(['2023-01-01', '2023-01-01', '2023-02-01', '2023-02-01'],
+        dtype='datetime64[ns]', freq=None)
         """
         # Superdumb, punting on any optimizing
         freq = to_offset(freq)

pandas/core/interchange/from_dataframe.py

@@ -44,6 +44,22 @@ def from_dataframe(df, allow_copy: bool = True) -> pd.DataFrame:
     Returns
     -------
     pd.DataFrame
+
+    Examples
+    --------
+    >>> df_not_necessarily_pandas = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
+    >>> interchange_object = df_not_necessarily_pandas.__dataframe__()
+    >>> interchange_object.column_names()
+    Index(['A', 'B'], dtype='object')
+    >>> df_pandas = (pd.api.interchange.from_dataframe
+    ...              (interchange_object.select_columns_by_name(['A'])))
+    >>> df_pandas
+         A
+    0    1
+    1    2
+
+    These methods (``column_names``, ``select_columns_by_name``) should work
+    for any dataframe library which implements the interchange protocol.
     """
     if isinstance(df, pd.DataFrame):
         return df