add docs/philosphy.md (#41)

* update readme, rename docs that have development instructions

* add link to dev docs

* remove duplicate link to docs

* add philsophy docs and example to help those docs.  Bump version

Author: Dr-Irv

README.md

@@ -22,6 +22,55 @@ The stubs are likely incomplete in terms of covering the published API of pandas
 The stubs are tested with [mypy](http://mypy-lang.org/) and [pyright](https://github.com/microsoft/pyright#readme) and are currently shipped with the Visual Studio Code extension
 [pylance](https://github.com/microsoft/pylance-release#readme).
 
+## Usage
+
+Let’s take this example piece of code in file `round.py`
+
+```python
+import pandas as pd
+
+decimals = pd.DataFrame({'TSLA': 2, 'AMZN': 1})
+prices = pd.DataFrame(data={'date': ['2021-08-13', '2021-08-07', '2021-08-21'],
+                            'TSLA': [720.13, 716.22, 731.22], 'AMZN': [3316.50, 3200.50, 3100.23]})
+rounded_prices = prices.round(decimals=decimals)
+```
+
+Mypy won't see any issues with that, but after installing pandas-stubs and running it again:
+
+```sh
+mypy round.py
+```
+
+we get the following error message:
+
+```text
+round.py:6: error: Argument "decimals" to "round" of "DataFrame" has incompatible type "DataFrame"; expected "Union[int, Dict[Any, Any], Series[Any]]"  [arg-type]
+Found 1 error in 1 file (checked 1 source file)
+```
+
+And, if you use pyright:
+
+```sh
+pyright round.py
+```
+
+you get the following error message:
+
+```text
+ round.py:6:40 - error: Argument of type "DataFrame" cannot be assigned to parameter "decimals" of type "int | Dict[Unknown, Unknown] | Series[Unknown]" in function "round"
+    Type "DataFrame" cannot be assigned to type "int | Dict[Unknown, Unknown] | Series[Unknown]"
+      "DataFrame" is incompatible with "int"
+      "DataFrame" is incompatible with "Dict[Unknown, Unknown]"
+      "DataFrame" is incompatible with "Series[Unknown]" (reportGeneralTypeIssues)
+```
+
+And after confirming with the [docs](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.round.html)
+we can fix the code:
+
+```python
+decimals = pd.Series({'TSLA': 2, 'AMZN': 1})
+```
+
 ## Version Numbering Convention
 
 The version number x.y.z.yymmdd corresponds to a test done with pandas version x.y.z, with the stubs released on the date mm/yy/dd.

docs/README.md

@@ -3,6 +3,9 @@
 For any update to the stubs, we require an associated test case that should fail without
 a proposed change, and works with a proposed change.  See <https://github.com/pandas-dev/pandas-stubs/tree/main/tests/> for examples.
 
+The stubs are developed with a certain [philosophy](philosophy.md) that should be 
+understood by developers proposing changes to the stubs.
+
 Instructions for working with the code are found here:
 
 - [How to set up the environment](setup.md)

docs/philosophy.md

@@ -0,0 +1,113 @@
+# pandas-stubs Type Checking Philosophy
+
+The goal of the pandas-stubs project is to provide type stubs for the public API
+that represent the recommended ways of using pandas. This is opposed to the 
+philosophy within the pandas source, as described [here](https://pandas.pydata.org/docs/development/contributing_codebase.html?highlight=typing#type-hints), which
+is to assist with the development of the pandas source code to ensure type safety within
+that source.
+
+Due to the methodology used by Microsoft to develop the original stubs, there are internal 
+classes, methods and functions that are annotated within the pandas-stubs project
+that are incorrect with respect to the pandas source, but that have no effect on type
+checking user code that calls the public API.
+
+## Use of Generic Types
+
+There are other differences that are extensions of the pandas API to assist in type
+checking.  Two key examples are that `Series` and `Interval` are typed as generic types.
+
+### Series are Generic
+
+`Series` is declared as `Series[S1]` where `S1` is a `TypeVar` consisting of types normally
+used within series, if that type can be inferred.  Consider the following example
+that compares the values in a `Series` to an integer.
+
+```python
+s = pd.Series([1, 2, 3])
+lt = s < 3
+```
+
+In the pandas source, `lt` is a `Series` with a `dtype` of `bool`. In the pandas-stubs,
+the type of `lt` is `Series[bool]`. This allows further type checking to occur in other
+pandas methods.  Note that in the above example, `s` is typed as `Series[Any]` because
+its type cannot be statically inferred.
+
+This also allows type checking for operations on series that contain date/time data. Consider
+the following example that creates two series of datetimes with corresponding arithmetic.
+
+```python
+s1 = pd.Series(pd.to_datetime(["2022-05-01", "2022-06-01"]))
+reveal_type(s1)
+s2 = pd.Series(pd.to_datetime(["2022-05-15", "2022-06-15"]))
+reveal_type(s2)
+td = s1 - s2
+reveal_type(td)
+ssum = s1 + s2
+reveal_type(ssum)
+```
+
+The above code (without the `reveal_type()` statements) will raise an `Exception` on the computation of `ssum` because it is
+inappropriate to add two series containing `Timestamp` values.  The types will be
+revealed as follows:
+
+```text
+ttest.py:4: note: Revealed type is "pandas.core.series.TimestampSeries"
+ttest.py:6: note: Revealed type is "pandas.core.series.TimestampSeries"
+ttest.py:8: note: Revealed type is "pandas.core.series.TimedeltaSeries"
+ttest.py:10: note: Revealed type is "builtins.Exception"
+```
+
+The type `TimestampSeries` is the result of creating a series from `pd.to_datetime()`, while
+the type `TimedeltaSeries` is the result of subtracting two `TimestampSeries` as well as
+the result of `pd.to_timedelta()`.
+
+### Interval is Generic
+
+A pandas `Interval` can be a time interval, an interval of integers, or an interval of
+time, represented as having endpoints with the `Timestamp` class.  pandas-stubs tracks
+the type of an `Interval`, based on the arguments passed to the `Interval` constructor.
+This allows detecting inappropriate operations, such as adding an integer to an
+interval of `Timestamp`s.
+
+## Testing the Type Stubs
+
+A set of (most likely incomplete) tests for testing the type stubs is in the pandas-stubs
+repository in the `tests` directory.  The tests are used with `mypy` and `pyright` to
+validate correct typing, and also with `pytest` to validate that the provided code
+actually executes. The recent decision for Python 3.11 to include `assert_type()`,
+which is supported by `typing_extensions` version 4.2 and beyond makes it easier
+to test to validate the return types of functions and methods. Future work
+is intended to expand the use of `assert_type()` in the test code.
+
+## Narrow vs. Wide Arguments
+
+A consideration in creating stubs is too make the set of type annotations for
+function arguments "just right", i.e.,
+not too narrow and not too wide.  A type annotation to an argument to a function or
+method is too narrow if it disallows valid arguments.  A type annotation to
+an argument to a function or method is too wide if
+it allows invalid arguments.  Testing for type annotations that are too narrow is rather
+straightforward. It is easy to create an example for which the type checker indicates
+the argument is incorrect, and add it to the set of tests in the pandas-stubs
+repository after fixing the appropriate stub. However, testing for when type annotations 
+are too wide is a bit more complicated.
+In this case, the test will fail when using `pytest`, but it is also desirable to
+have type checkers report errors for code that is expected to fail type checking.
+
+Here is an example that illustrates this concept, from `tests/test_interval.py`:
+
+```python
+    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
+
+```
+
+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.

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pandas-stubs"
-version = "1.4.2.220622"
+version = "1.4.2.220626"
 description = "Type annotations for pandas"
 authors = ["The Pandas Development Team <[email protected]>"]
 license = "BSD-3-Clause"

tests/test_timefuncs.py

@@ -47,16 +47,17 @@ def test_types_comparison() -> None:
 
 
 def test_types_timestamp_series_comparisons() -> None:
-    #GH 27
-    df =  pd.DataFrame(['2020-01-01','2019-01-01'])
-    tss = pd.to_datetime(df[0], format = '%Y-%m-%d')
-    ts = pd.to_datetime('2019-02-01', format = '%Y-%m-%d')
+    # GH 27
+    df = pd.DataFrame(["2020-01-01", "2019-01-01"])
+    tss = pd.to_datetime(df[0], format="%Y-%m-%d")
+    ts = pd.to_datetime("2019-02-01", format="%Y-%m-%d")
     tssr = tss <= ts
     tssr2 = tss >= ts
     tssr3 = tss == ts
-    assert_type(tssr,'pd.Series[bool]')
-    assert_type(tssr2,'pd.Series[bool]')
-    assert_type(tssr3,'pd.Series[bool]')
+    assert_type(tssr, "pd.Series[bool]")
+    assert_type(tssr2, "pd.Series[bool]")
+    assert_type(tssr3, "pd.Series[bool]")
+
 
 def test_types_pydatetime() -> None:
     ts: pd.Timestamp = pd.Timestamp("2021-03-01T12")
@@ -166,3 +167,12 @@ def test_iso_calendar() -> None:
     # GH 31
     dates = pd.date_range(start="2012-01-01", end="2019-12-31", freq="W-MON")
     dates.isocalendar()
+
+
+def fail_on_adding_two_timestamps() -> None:
+    s1 = pd.Series(pd.to_datetime(["2022-05-01", "2022-06-01"]))
+    s2 = pd.Series(pd.to_datetime(["2022-05-15", "2022-06-15"]))
+    if TYPE_CHECKING:
+        ssum: pd.Series = s1 + s2  # type: ignore
+        ts = pd.Timestamp("2022-06-30")
+        tsum: pd.Series = s1 + ts  # type: ignore