Merge branch 'main' into to_timestamp

Author: saldanhad

.github/workflows/package-checks.yml

@@ -67,7 +67,7 @@ jobs:
           fetch-depth: 0
 
       - name: Set up Python
-        uses: mamba-org/setup-micromamba@v1
+        uses: mamba-org/setup-micromamba@v2
         with:
           environment-name: recipe-test
           create-args: >-

.github/workflows/wheels.yml

@@ -165,7 +165,7 @@ jobs:
           CIBW_PLATFORM: ${{ matrix.buildplat[1] == 'pyodide_wasm32' && 'pyodide' || 'auto' }}
 
       - name: Set up Python
-        uses: mamba-org/setup-micromamba@v1
+        uses: mamba-org/setup-micromamba@v2
         with:
           environment-name: wheel-env
           # Use a fixed Python, since we might have an unreleased Python not

ci/code_checks.sh

@@ -154,12 +154,10 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.errors.ValueLabelTypeMismatch SA01" \
         -i "pandas.infer_freq SA01" \
         -i "pandas.io.json.build_table_schema PR07,RT03,SA01" \
-        -i "pandas.io.stata.StataReader.value_labels RT03,SA01" \
         -i "pandas.io.stata.StataReader.variable_labels RT03,SA01" \
         -i "pandas.io.stata.StataWriter.write_file SA01" \
         -i "pandas.json_normalize RT03,SA01" \
         -i "pandas.plotting.andrews_curves RT03,SA01" \
-        -i "pandas.plotting.lag_plot RT03,SA01" \
         -i "pandas.plotting.scatter_matrix PR07,SA01" \
         -i "pandas.set_eng_float_format RT03,SA01" \
         -i "pandas.tseries.offsets.BDay PR02,SA01" \

pandas/_libs/tslibs/nattype.pyi

@@ -9,6 +9,7 @@ from typing import (
     Literal,
     NoReturn,
     TypeAlias,
+    overload,
 )
 
 import numpy as np
@@ -159,15 +160,31 @@ class NaTType:
     # inject Period properties
     @property
     def qyear(self) -> float: ...
+    # comparisons
     def __eq__(self, other: object) -> bool: ...
     def __ne__(self, other: object) -> bool: ...
     __lt__: _NatComparison
     __le__: _NatComparison
     __gt__: _NatComparison
     __ge__: _NatComparison
+    # unary operators
+    def __pos__(self) -> Self: ...
+    def __neg__(self) -> Self: ...
+    # binary operators
     def __sub__(self, other: Self | timedelta | datetime) -> Self: ...
     def __rsub__(self, other: Self | timedelta | datetime) -> Self: ...
     def __add__(self, other: Self | timedelta | datetime) -> Self: ...
     def __radd__(self, other: Self | timedelta | datetime) -> Self: ...
+    def __mul__(self, other: float) -> Self: ...  # analogous to timedelta
+    def __rmul__(self, other: float) -> Self: ...
+    @overload  # analogous to timedelta
+    def __truediv__(self, other: Self | timedelta) -> float: ...  # Literal[NaN]
+    @overload
+    def __truediv__(self, other: float) -> Self: ...
+    @overload  # analogous to timedelta
+    def __floordiv__(self, other: Self | timedelta) -> float: ...  # Literal[NaN]
+    @overload
+    def __floordiv__(self, other: float) -> Self: ...
+    # other
     def __hash__(self) -> int: ...
     def as_unit(self, unit: str, round_ok: bool = ...) -> NaTType: ...

pandas/io/stata.py

@@ -2076,9 +2076,19 @@ def value_labels(self) -> dict[str, dict[int, str]]:
         """
         Return a nested dict associating each variable name to its value and label.
 
+        This method retrieves the value labels from a Stata file. Value labels are
+        mappings between the coded values and their corresponding descriptive labels
+        in a Stata dataset.
+
         Returns
         -------
         dict
+            A python dictionary.
+
+        See Also
+        --------
+        read_stata : Read Stata file into DataFrame.
+        DataFrame.to_stata : Export DataFrame object to Stata dta format.
 
         Examples
         --------

pandas/plotting/_misc.py

@@ -39,7 +39,7 @@ def table(ax: Axes, data: DataFrame | Series, **kwargs) -> Table:
     **kwargs
         Keyword arguments to be passed to matplotlib.table.table.
         If `rowLabels` or `colLabels` is not specified, data index or column
-        name will be used.
+        names will be used.
 
     Returns
     -------
@@ -59,11 +59,11 @@ def table(ax: Axes, data: DataFrame | Series, **kwargs) -> Table:
 
             >>> import matplotlib.pyplot as plt
             >>> df = pd.DataFrame({"A": [1, 2], "B": [3, 4]})
-            >>> fix, ax = plt.subplots()
+            >>> fig, ax = plt.subplots()
             >>> ax.axis("off")
             (0.0, 1.0, 0.0, 1.0)
             >>> table = pd.plotting.table(
-            ...     ax, df, loc="center", cellLoc="center", colWidths=list([0.2, 0.2])
+            ...     ax, df, loc="center", cellLoc="center", colWidths=[0.2, 0.2]
             ... )
     """
     plot_backend = _get_plot_backend("matplotlib")
@@ -549,6 +549,10 @@ def lag_plot(series: Series, lag: int = 1, ax: Axes | None = None, **kwds) -> Ax
     """
     Lag plot for time series.
 
+    A lag plot is a scatter plot of a time series against a lag of itself. It helps
+    in visualizing the temporal dependence between observations by plotting the values
+    at time `t` on the x-axis and the values at time `t + lag` on the y-axis.
+
     Parameters
     ----------
     series : Series
@@ -563,6 +567,13 @@ def lag_plot(series: Series, lag: int = 1, ax: Axes | None = None, **kwds) -> Ax
     Returns
     -------
     matplotlib.axes.Axes
+        The matplotlib Axes object containing the lag plot.
+
+    See Also
+    --------
+    plotting.autocorrelation_plot : Autocorrelation plot for time series.
+    matplotlib.pyplot.scatter : A scatter plot of y vs. x with varying marker size
+        and/or color in Matplotlib.
 
     Examples
     --------