Skip to content

Commit 2efdd87

Browse files
committed
Update 22_static_type_checking.md to include advantages of static type checking and support for positional/keyword parameter types
Signed-off-by: Jos Verlinde <Jos_Verlinde@hotmail.com>
1 parent 224ad7f commit 2efdd87

File tree

1 file changed

+32
-1
lines changed

1 file changed

+32
-1
lines changed

docs/22_static_type_checking.md

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,6 @@ When MicroPython code is compiled to .mpy or frozen into a firmware, the microco
1414
- Refactoring: Static type checking helps identify type-related issues during refactoring, making code changes safer and more predictable.
1515
- API Documentation: Type hints serve as documentation for function signatures, making it easier to understand how to use them¹.
1616

17-
1817
### Disadvantages:
1918
- Verbose Syntax: Adding type hints can make code more verbose, especially for complex data structures.
2019
- Learning Curve: Developers need to learn type hinting syntax and conventions.
@@ -63,3 +62,35 @@ def get_register_name(register: int) -> Optional[str]:
6362
```
6463

6564
In this example, the `TYPE_CHECKING` constant is set to `False` by default. When performing static type checking, you can set `TYPE_CHECKING` to `True` to include the type hints and imports. This allows you to use type hints and perform static type checking without requiring the `typing` module at runtime.
65+
66+
67+
## Positional and keyword parameter types
68+
69+
Based on [PEP-570](https://peps.python.org/pep-0570/)
70+
71+
72+
While MicroPython does not support the full range of Python's function parameter types at runtime ,
73+
it does make sense to support some of them in static type checking.
74+
75+
In type stubs the following function signature is used to indicate the types of parameters:
76+
77+
```python
78+
79+
def name(positional_only_parameters, /, positional_or_keyword_parameters,
80+
*, keyword_only_parameters):
81+
...
82+
83+
```
84+
85+
The following would apply:
86+
87+
- All parameters left of the `/` are treated as positional-only.
88+
- If `/` is not specified in the function definition, that function does not accept any positional-only arguments.
89+
- The logic around optional values for positional-only parameters remains the same as for positional-or-keyword parameters.
90+
- Once a positional-only parameter is specified with a default, the following positional-only and positional-or-keyword parameters need to have defaults as well.
91+
- Positional-only parameters which do not have default values are required positional-only parameters.
92+
93+
As guidance:
94+
95+
Use positional-only if names do not matter or have no meaning, and there are only a few arguments which will always be passed in the same order.
96+
Use keyword-only when names have meaning and the function definition is more understandable by being explicit with names.

0 commit comments

Comments
 (0)