Added dedicated page about using types with pytest #12842 #12963
Conversation
psf-chronographer
bot
added
the
bot:chronographer:provided
|
(Also you amended an unrelated commit :) ) |
|
Thank you for the feedback! I’m still a beginner with pytest and open-source contributions, and I’m eager to learn more. I appreciate your guidance. I’d be happy to focus on pytest-specific examples for typing if that would be more relevant. Would you like me to demonstrate typing with pytest’s fixtures, parameterized tests, or any specific areas you think would be most beneficial for the documentation? Thanks again for your help! |
mwychung
force-pushed
the
feature/doc-typing-12842
branch
from
09e6ee2 to
1d944c4
Compare
There was a problem hiding this comment.
@Pierre-Sassoulas actually this has been discussed in the past, and seems like the overall consensus is that having a page dedicated how to type tests would be welcome, as those topics are often brought up and unclear for many people.
However I think the docs as presented are a bit verbose, IMHO.
I think a "typing tests with pytest" page should already consider that readers know about Python typing (how to add types, what are the benefits/drawbacks, etc, perhaps only pointing to the external docs for readers that are not familiar yet), and focus mainly on the topics that pertain to pytest/tests: tests, fixtures, parametrized tests, etc.
The main benefits of add typing to tests should also be highlighted:
- Refactoring: the type checker can easily point out the necessary changes in both code and tests, without needing to run the full test suite.
- Readability: the types make the test code easier to read.
For production code, there are other benefits (such as preventing errors), but for tests, those are the main two reasons to add typing to tests IMHO.
doc/en/how-to/types.rst
Outdated
| This guide explains how to apply typing in pytest to improve code readability and prevent type-related errors. | ||
|
|
||
|
|
||
| 1. Introduction to Typing |
There was a problem hiding this comment.
I would replace this entire section with a paragraph like "this page assumes the reader already knows how typing in Python works, its benefits, etc, for more information see PAGE".
There was a problem hiding this comment.
I would add a section like "Why type tests", explaining the motivation to add types to tests (which are slightly different than the reasons to add typing to production code).
There was a problem hiding this comment.
Thanks for the feedback! I added "Why Type tests" to focus on the specific benefits of typing in tests, like improved refactoring and readability. Let me know if further changes are needed!
doc/en/how-to/types.rst
Outdated
| 2. Typing Test Functions | ||
| ----------------- |
There was a problem hiding this comment.
Sections need to use the same number of characters as the title, here for example:
| 2. Typing Test Functions | |
| ----------------- | |
| 2. Typing Test Functions | |
| ------------------------ |
There was a problem hiding this comment.
Thank you so much for your helpful guidance. I matched all the section titles with same number of characters.
doc/en/how-to/types.rst
Outdated
|
|
||
| 2. Typing Test Functions | ||
| ----------------- | ||
| Test functions in pytest check whether the code runs correctly. |
There was a problem hiding this comment.
As I mentioned, the reason for a test is different: it is better to run the test in order to see if the code is correct -- but we add typing to help with refactoring and readability. 👍
doc/en/how-to/types.rst
Outdated
| In this function: | ||
| `test_add` is typed as `-> None` because it does not return anything. | ||
| The assertion `assert result == 5` checks if the result is correct. | ||
|
|
||
| Example result: | ||
| If the input data type is incorrect, like passing `add("2", 3)`, a `TypeError` will occur. |
There was a problem hiding this comment.
These are not needed, as we assume readers already know about Python typing.
doc/en/how-to/types.rst
Outdated
| * Typing Fixtures with Lists and Dictionaries: | ||
| Here are the examples showing how to use List and Dict types in pytest. | ||
| When you want to use complex data structures like lists or dictionaries, import `List` and `Dict` from Python's `typing` module to specify the types. | ||
| Note: From Python 3.5 or later, typing module is built-in module in Python. |
There was a problem hiding this comment.
We can drop this too, again we can assume the reader knows about typing and the particulars about list/List, etc.
doc/en/how-to/types.rst
Outdated
| In this function: | ||
| `test_add` is typed as `-> None` because it does not return anything. |
There was a problem hiding this comment.
We can instead mention that while at first marking a function as returning -> None might seem useless, having at least a type annotation means most type checkers will now type check the function, so it is useful because of that.
mwychung
force-pushed
the
feature/doc-typing-12842
branch
from
310b7d5 to
b938e70
Compare
|
Thank you so much for all the helpful feedback and guidance! I’ve removed the unnecessary sections as suggested and have added a few more focused areas specific to pytest, such as typing with monkeypatch, parametrize, and tmp_path. I believe these changes better align with the needs of the readers and improve the relevance of the documentation. If any further adjustments are needed, please feel free to let me know—I’m happy to make additional updates. I truly appreciate your insights throughout this process, and I’m excited to continue learning and contributing! |
Fix (#12842 )
doc/en/how-to/types.rst.This guide explains how to apply typing in pytest, covering typing test functions, fixtures, and parameterized tests to improve code readability and prevent type-related errors.
AUTHORS.