DOC: ignore comments (#490)

* DOC: ignore comments

* re-write docs

* add codespell

* update wording

* typo

* adjust wide-narrow example

* TYPE_CHECKING_INVALID_USAGE

Author: twoertwein

.pre-commit-config.yaml

@@ -34,3 +34,8 @@ repos:
           # TypeVars in private files are already private
           --per-file-ignores=_*.pyi:Y001
         ]
+-   repo: https://github.com/codespell-project/codespell
+    rev: v2.2.2
+    hooks:
+    - id: codespell
+      additional_dependencies: [ tomli ]

docs/philosophy.md

@@ -100,14 +100,36 @@ Here is an example that illustrates this concept, from `tests/test_interval.py`:
     i1 = pd.Interval(
         pd.Timestamp("2000-01-01"), pd.Timestamp("2000-01-03"), closed="both"
     )
-    if TYPE_CHECKING:
-        i1 + pd.Timestamp("2000-03-03")  # type: ignore
+    if TYPE_CHECKING_INVALID_USAGE:
+        i1 + pd.Timestamp("2000-03-03")  # type: ignore[operator] # pyright: ignore[reportGeneralTypeIssues]
 
 ```
 
 In this particular example, the stubs consider that `i1` will have the type
 `pd.Interval[pd.Timestamp]`.  It is incorrect code to add a `Timestamp` to a
-time-based interval.  Without the `if TYPE_CHECKING` construct, the code would fail.
-However, it is also desirable to have the type checker pick up this failure, and by
-placing the `# type: ignore` on the line, an indication is made to the type checker
-that we expect this line to not pass the type checker.
+time-based interval.  Without the `if TYPE_CHECKING_INVALID_USAGE` construct, the
+code would fail at runtime. Further, type checkers should report an error for this
+incorrect code. By placing the `# type: ignore[operator] # pyright: ignore[reportGeneralTypeIssues]`
+on the line, type checkers are told to ignore the type error. To ensure that the
+pandas-stubs annotations are not too wide (allow adding a `Timestamp` to a
+time-based interval), mypy and pyright are configured to report unused ignore
+statements.
+
+## Using ignore comments
+
+Type checkers report errors
+
+- when writing negative tests to reject invalid behavior (inside a
+  `TYPE_CHECKING_INVALID_USAGE` block),
+- when writing `overload`s that return incompatible return values, or
+- when type checkers have bugs themselves.
+
+Since mypy and pyright behave slightly differently, we use separate ignore comments
+for them.
+
+- If mypy reports an error, please use `# type: ignore[<error code>]`
+- If pyright reports an error, please use `# pyright: ignore[<error code>]`
+
+If mypy and pyright report errors, for example, inside a `TYPE_CHECKING_INVALID_USAGE`
+block, please ensure that the comment for mypy comes first:
+`# type: ignore[<error code>] # pyright: ignore[<error code>]`.

docs/release_procedure.md

@@ -7,7 +7,7 @@
 
 ```shell
 rm dist/*
-poetry pubish --build  # you will get prompted for your pypi username/password
+poetry publish --build  # you will get prompted for your pypi username/password
 git commit -a -m "Version a.b.c.yymmdd"
 git push upstream main
 git tag va.b.c.yymmdd

pandas-stubs/core/groupby/groupby.pyi

@@ -96,7 +96,7 @@ class GroupBy(BaseGroupBy[NDFrameT]):
     ) -> DataFrame | Series: ...
     def head(self, n: int = ...) -> DataFrame | Series: ...
     def tail(self, n: int = ...) -> DataFrame | Series: ...
-    # Surplus methodss from original pylance stubs; should they go away?
+    # Surplus methods from original pylance stubs; should they go away?
     def first(self, **kwargs) -> DataFrame | Series: ...
     def last(self, **kwargs) -> DataFrame | Series: ...
     def max(self, **kwargs) -> DataFrame | Series: ...

pyproject.toml

@@ -194,3 +194,6 @@ reportUnusedVariable = false
 reportPrivateUsage = false
 # enable optional checks
 reportMissingModuleSource = true
+
+[tool.codespell]
+ignore-words-list = "indext, mose, sav, ser"

tests/test_pandas.py

@@ -973,7 +973,7 @@ def test_merge() -> None:
         ),
         pd.DataFrame,
     )
-    # TOOD: When cross don't need on??
+    # TODO: When cross don't need on??
     check(assert_type(pd.merge(ls, rs, how="cross"), pd.DataFrame), pd.DataFrame)
     check(
         assert_type(

tests/test_series.py

@@ -262,7 +262,7 @@ def test_types_shift() -> None:
 def test_types_rank() -> None:
     s = pd.Series([1, 1, 2, 5, 6, np.nan])
     if PD_LTE_15:
-        s[6] = "milion"
+        s[6] = "million"
     with pytest_warns_bounded(
         FutureWarning,
         match="Dropping of nuisance columns",