From b2134194de1750903614370001360e1998d7dc91 Mon Sep 17 00:00:00 2001 From: Elliot Ford Date: Wed, 5 Apr 2023 12:38:36 +0100 Subject: [PATCH 1/5] typo fix: 'too' -> 'to' --- docs/philosophy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/philosophy.md b/docs/philosophy.md index 9204ec599..8b08ba3bd 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -81,7 +81,7 @@ 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 +A consideration in creating stubs is to 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 From 962dd6a25ebfb543bee8c188e88392b62a622b75 Mon Sep 17 00:00:00 2001 From: Elliot Ford Date: Wed, 5 Apr 2023 12:54:01 +0100 Subject: [PATCH 2/5] standardise spaces after '.' within paragraph All other ends of sentences (period/full stop, '.') are followed by two spaces - these are followed by one. Making these match. Note this has no impact on rendering, Markdown only creates a single rendered space after a '.' in either case. --- docs/philosophy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/philosophy.md b/docs/philosophy.md index 8b08ba3bd..a6984f13c 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -87,9 +87,9 @@ not too narrow and not too wide. A type annotation to an argument to a function 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 +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 +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. From 8d3645e8aab71431fd855768d63b50458a886de7 Mon Sep 17 00:00:00 2001 From: Elliot Ford Date: Wed, 5 Apr 2023 12:55:33 +0100 Subject: [PATCH 3/5] remove trailing whitespace in paragraph All other lines in this paragraph have no trailing whitespace, remove this single trailing whitespace to match. Note that this has no impact on the rendering of the Markdown. --- docs/philosophy.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/philosophy.md b/docs/philosophy.md index a6984f13c..8ae752c5e 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -89,7 +89,7 @@ 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 +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. From a49f1c28d28c042270410255b38c1c5b7017365a Mon Sep 17 00:00:00 2001 From: Elliot Ford Date: Wed, 5 Apr 2023 12:54:01 +0100 Subject: [PATCH 4/5] standardise spaces after '.' for whole philsophy doc As with previous commit, but for the whole document. Found using the regex "\. ([^ ])" and replacing with ". $1". All other ends of sentences (period/full stop, '.') are followed by two spaces - these are followed by one. Making these match. Note this has no impact on rendering, Markdown only creates a single rendered space after a '.' in either case. --- docs/philosophy.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/philosophy.md b/docs/philosophy.md index 8ae752c5e..3f619f89c 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -1,7 +1,7 @@ # 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 +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. @@ -27,12 +27,12 @@ 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 +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 +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 @@ -74,9 +74,9 @@ interval of `Timestamp`s. 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()`, +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 +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 @@ -108,9 +108,9 @@ Here is an example that illustrates this concept, from `tests/test_interval.py`: 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_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 +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. From c6bf262897271d3ff141e9963b6a43de71eddff4 Mon Sep 17 00:00:00 2001 From: Elliot Ford Date: Wed, 5 Apr 2023 12:55:33 +0100 Subject: [PATCH 5/5] remove trailing whitespace for whole philosophy doc As with previous commit, but for the whole document. Found using the regex "\s$". All other lines have no trailing whitespace, remove these single trailing whitespaces to match. Note that this has no impact on the rendering of the Markdown. --- docs/philosophy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/philosophy.md b/docs/philosophy.md index 3f619f89c..bc9106317 100644 --- a/docs/philosophy.md +++ b/docs/philosophy.md @@ -1,12 +1,12 @@ # 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 +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 +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.