Merge branch 'pandas-dev:main' into test_issue

Author: loicdiridollou

README.md

@@ -101,7 +101,7 @@ pip install pandas-stubs
 
 ## Installation from sources
 
-- Make sure you have `python >= 3.9` installed.
+- Make sure you have `python >= 3.10` installed.
 - Install poetry
 
 ```sh

conftest.py

@@ -0,0 +1,36 @@
+import gc
+
+import pytest
+
+
+@pytest.fixture
+def mpl_cleanup():
+    """
+    Ensure Matplotlib is cleaned up around a test.
+
+    Before a test is run:
+
+    1) Set the backend to "template" to avoid requiring a GUI.
+
+    After a test is run:
+
+    1) Reset units registry
+    2) Reset rc_context
+    3) Close all figures
+
+    See matplotlib/testing/decorators.py#L24.
+    """
+    mpl = pytest.importorskip("matplotlib")
+    mpl_units = pytest.importorskip("matplotlib.units")
+    plt = pytest.importorskip("matplotlib.pyplot")
+    orig_units_registry = mpl_units.registry.copy()
+    try:
+        with mpl.rc_context():
+            mpl.use("template")
+            yield
+    finally:
+        mpl_units.registry.clear()
+        mpl_units.registry.update(orig_units_registry)
+        plt.close("all")
+        # https://matplotlib.org/stable/users/prev_whats_new/whats_new_3.6.0.html#garbage-collection-is-no-longer-run-on-figure-close
+        gc.collect(1)

docs/release_procedure.md

@@ -7,13 +7,12 @@
 
 ```shell
 rm dist/*
-poetry publish --build  # you will get prompted for your pypi username/password
+poetry build
+twine upload dist/*  # Requires having the pypi API token allowing uploads
 git commit -a -m "Version a.b.c.yymmdd"
 git push upstream main
 git tag va.b.c.yymmdd
 git push upstream --tags
 ```
 
 The conda bots will recognize that a new version has been uploaded to pypi, and generate a pull request sent to the maintainers to approve it.
-
-Note - Changes will need to be made to use pypi API tokens in the near future.

docs/setup.md

@@ -1,7 +1,8 @@
 ## Set Up Environment
 
-- Make sure you have `python >= 3.9` installed.
-- Install poetry: `pip install 'poetry>=1.2'`
+- Make sure you have `python >= 3.10` installed.
+- If using macOS, you may need to install `hdf5` (e.g., via `brew install hdf5`).
+- Install poetry: `pip install 'poetry>=1.8'`
 - Install the project dependencies: `poetry update`
 - Enter the virtual environment: `poetry shell`
 - Run all tests: `poe test_all`

docs/tests.md

@@ -5,7 +5,7 @@
 Here are the most important options. Fore more details, please use `poe --help`.
 
 - Run all tests (against both source and installed stubs): `poe test_all`
-- Run tests against the source code: `poe test` 
+- Run tests against the source code: `poe test`
   - Run only mypy: `poe mypy`
   - Run only pyright: `poe pyright`
   - Run only pytest: `poe pytest`
@@ -20,3 +20,9 @@ The following tests are **optional**. Some of them are run by the CI but it is o
 - Use mypy nightly to validate the annotations: `poe mypy --mypy_nightly`
 - Use pyright in full strict mode: `poe pyright_strict`
 - Run stubtest to compare the installed pandas-stubs against pandas (this will fail): `poe stubtest`. If you have created an allowlist to ignore certain errors: `poe stubtest path_to_the_allow_list`
+
+Among the tests above, the following can be run directly during a PR by commenting in the discussion.
+
+- Run pytest against pandas nightly by commenting `/pandas_nightly`
+- Use mypy nightly to validate the annotations by commenting `/mypy_nightly`
+- Use pyright in full strict mode by commenting `/pyright_strict`

pandas-stubs/_libs/interval.pyi

@@ -201,15 +201,15 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __eq__(self, other: Interval[_OrderableT]) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __eq__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...  # type: ignore[overload-overlap]
+    def __eq__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...
     @overload
     def __eq__(self, other: Series[_OrderableT]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __eq__(self, other: object) -> Literal[False]: ...
     @overload
     def __ne__(self, other: Interval[_OrderableT]) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __ne__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...  # type: ignore[overload-overlap]
+    def __ne__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...
     @overload
     def __ne__(self, other: Series[_OrderableT]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload

pandas-stubs/_libs/tslibs/dtypes.pyi

@@ -1,4 +1,5 @@
 from enum import Enum
+from typing import cast
 
 from .offsets import BaseOffset
 
@@ -29,16 +30,16 @@ class FreqGroup:
     def get_freq_group(code: int) -> int: ...
 
 class Resolution(Enum):
-    RESO_NS: int
-    RESO_US: int
-    RESO_MS: int
-    RESO_SEC: int
-    RESO_MIN: int
-    RESO_HR: int
-    RESO_DAY: int
-    RESO_MTH: int
-    RESO_QTR: int
-    RESO_YR: int
+    RESO_NS = cast(int, ...)
+    RESO_US = cast(int, ...)
+    RESO_MS = cast(int, ...)
+    RESO_SEC = cast(int, ...)
+    RESO_MIN = cast(int, ...)
+    RESO_HR = cast(int, ...)
+    RESO_DAY = cast(int, ...)
+    RESO_MTH = cast(int, ...)
+    RESO_QTR = cast(int, ...)
+    RESO_YR = cast(int, ...)
 
     def __lt__(self, other) -> bool: ...
     def __ge__(self, other) -> bool: ...

pandas-stubs/_libs/tslibs/offsets.pyi

@@ -12,7 +12,9 @@ from typing import (
     overload,
 )
 
+from dateutil.relativedelta import weekday as WeekdayClass
 import numpy as np
+from pandas import Timestamp
 from pandas.core.indexes.datetimes import DatetimeIndex
 from typing_extensions import Self
 
@@ -21,7 +23,7 @@ from pandas._typing import npt
 
 from pandas.tseries.holiday import AbstractHolidayCalendar
 
-_DatetimeT = TypeVar("_DatetimeT", bound=date)
+_DatetimeT = TypeVar("_DatetimeT", bound=datetime)
 _TimedeltaT = TypeVar("_TimedeltaT", bound=timedelta)
 
 prefix_mapping: dict[str, type]
@@ -41,26 +43,32 @@ class BaseOffset:
     @overload
     def __add__(self, other: npt.NDArray[np.object_]) -> npt.NDArray[np.object_]: ...
     @overload
-    def __add__(self, other: BaseOffset) -> Self: ...
+    def __add__(self, other: _DatetimeT) -> _DatetimeT: ...  # type: ignore[overload-overlap]  # pyright: ignore[reportOverlappingOverload]
+    @overload
+    def __add__(self, other: date) -> Timestamp: ...
     @overload
-    def __add__(self, other: _DatetimeT) -> _DatetimeT: ...
+    def __add__(self, other: BaseOffset) -> Self: ...
     @overload
     def __add__(self, other: _TimedeltaT) -> _TimedeltaT: ...
     @overload
     def __radd__(self, other: npt.NDArray[np.object_]) -> npt.NDArray[np.object_]: ...
     @overload
-    def __radd__(self, other: BaseOffset) -> Self: ...
+    def __radd__(self, other: _DatetimeT) -> _DatetimeT: ...  # type: ignore[overload-overlap]  # pyright: ignore[reportOverlappingOverload]
+    @overload
+    def __radd__(self, other: date) -> Timestamp: ...
     @overload
-    def __radd__(self, other: _DatetimeT) -> _DatetimeT: ...
+    def __radd__(self, other: BaseOffset) -> Self: ...
     @overload
     def __radd__(self, other: _TimedeltaT) -> _TimedeltaT: ...
     def __sub__(self, other: BaseOffset) -> Self: ...
     @overload
     def __rsub__(self, other: npt.NDArray[np.object_]) -> npt.NDArray[np.object_]: ...
     @overload
-    def __rsub__(self, other: BaseOffset) -> Self: ...
+    def __rsub__(self, other: _DatetimeT) -> _DatetimeT: ...  # type: ignore[overload-overlap]  # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __rsub__(self, other: _DatetimeT) -> _DatetimeT: ...
+    def __rsub__(self, other: date) -> Timestamp: ...
+    @overload
+    def __rsub__(self, other: BaseOffset) -> Self: ...
     @overload
     def __rsub__(self, other: _TimedeltaT) -> _TimedeltaT: ...
     def __call__(self, other): ...
@@ -257,7 +265,7 @@ class DateOffset(RelativeDeltaOffset):
         year: int = ...,
         month: int = ...,
         day: int = ...,
-        weekday: int = ...,
+        weekday: int | WeekdayClass = ...,
         hour: int = ...,
         minute: int = ...,
         second: int = ...,

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -102,7 +102,7 @@ class Timedelta(timedelta):
     value: int
     def __new__(
         cls,
-        value: str | int | Timedelta | timedelta | np.timedelta64 = ...,
+        value: str | float | Timedelta | timedelta | np.timedelta64 = ...,
         unit: TimeDeltaUnitChoices = ...,
         *,
         days: float | np.integer | np.floating = ...,
@@ -248,7 +248,7 @@ class Timedelta(timedelta):
     def __rmul__(self, other: Series[float]) -> TimedeltaSeries: ...
     # maybe related to https://github.com/python/mypy/issues/10755
     @overload
-    def __rmul__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...  # type: ignore[misc]
+    def __rmul__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
     # Override due to more types supported than dt.timedelta
     # error: Signature of "__floordiv__" incompatible with supertype "timedelta"
     @overload  # type: ignore[override]

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -59,21 +59,18 @@ class Timestamp(datetime):
     def __new__(
         cls,
         ts_input: np.integer | float | str | _date | datetime | np.datetime64 = ...,
-        # Freq is deprecated but is left in to allow code like Timestamp(2000,1,1)
-        # Removing it would make the other arguments position only
-        freq: int | str | BaseOffset | None = ...,
-        tz: str | _tzinfo | int | None = ...,
-        unit: str | int | None = ...,
         year: int | None = ...,
         month: int | None = ...,
         day: int | None = ...,
         hour: int | None = ...,
         minute: int | None = ...,
         second: int | None = ...,
         microsecond: int | None = ...,
-        nanosecond: int | None = ...,
         tzinfo: _tzinfo | None = ...,
         *,
+        nanosecond: int | None = ...,
+        tz: str | _tzinfo | int | None = ...,
+        unit: str | int | None = ...,
         fold: Literal[0, 1] | None = ...,
     ) -> Self: ...
     # GH 46171
@@ -119,8 +116,6 @@ class Timestamp(datetime):
     def fromordinal(
         cls,
         ordinal: int,
-        # freq produces a FutureWarning about being deprecated in a future version
-        freq: None = ...,
         tz: _tzinfo | str | None = ...,
     ) -> Self: ...
     @classmethod