You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guide/users/checking.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -25,8 +25,8 @@ If you want to also specify the *base* reference to use (instead of the current
25
25
```console
26
26
$ griffe check mypackage -b HEAD -a 2.0.0
27
27
$ griffe check mypackage -b 2.0.0 -a 1.0.0
28
-
$ griffe check mypackage -b fix-issue-90 -a 1.2.3
29
-
$ griffe check mypackage -b 8afcfd6e
28
+
$ griffe check mypackage -b fix-issue-90 -a 1.2.3
29
+
$ griffe check mypackage -b 8afcfd6e
30
30
```
31
31
32
32
TIP: **Important:** Remember that the base is the most recent reference, and the one we compare it against is the oldest one.
@@ -160,7 +160,7 @@ greet("hello", "world")
160
160
161
161
NOTE: Moving required parameters around is not really an API breakage, depending on our definition of API, since this won't raise immediate errors like `TypeError`. The function expects a number of arguments, and the developer passes it this same number of arguments: the contract is fulfilled. But parameters very often have specific meaning, and changing their order will *silently lead* (no immediate error) to incorrect behavior, potentially making it difficult to detect, understand and fix the issue. That is why it is important to warn developers about such changes.
162
162
163
-
> TIP: **Hint**
163
+
> TIP: **Hint**
164
164
> If you often add, move or remove parameters, consider making them keyword-only, so that their order doesn't matter.
165
165
>
166
166
> ```python title="before"
@@ -205,7 +205,7 @@ greet("hello", "world")
205
205
greet(prefix="hello", name="world")
206
206
```
207
207
208
-
> TIP: **Hint**
208
+
> TIP: **Hint**
209
209
> Allow a deprecation period for the removed parameter by swallowing it in a variadic positional parameter, a variadic keyword parameter, or both.
210
210
>
211
211
> === "positional-only"
@@ -326,7 +326,7 @@ greet(name="tim")
326
326
greet2("tim")
327
327
```
328
328
329
-
> TIP: **Hint**
329
+
> TIP: **Hint**
330
330
> Although it actually is a breaking change, changing your positional or keyword parameters' kind to keyword-only makes your public function more robust to future changes (forward-compatibility).
331
331
>
332
332
> For functions with lots of optional parameters, and a few (one or two) required parameters, it can be a good idea to accept the required parameters as positional or keyword, while accepting the optional parameters as keyword-only parameters:
@@ -391,7 +391,7 @@ if isinstance(compute_something(7), float):
391
391
392
392
NOTE: Changing default value of parameters is not really an API breakage, depending on our definition of API, since this won't raise immediate errors like `TypeError`. Not using the parameter still provides the argument with a default value: the contract is fulfilled. But default values very often have specific meaning, and changing them will *silently lead* (no immediate error) to incorrect behavior, potentially making it difficult to detect, understand and fix the issue. That is why it is important to warn developers about such changes.
393
393
394
-
> TIP: **Hint**
394
+
> TIP: **Hint**
395
395
> Allow a deprecation period for the old default value by using a sentinel value to detect when the parameter wasn't used by the user:
396
396
>
397
397
> ```python title="in the coming release"
@@ -445,7 +445,7 @@ def greet(name, prefix):
445
445
greet("tiff")
446
446
```
447
447
448
-
> TIP: **Hint**
448
+
> TIP: **Hint**
449
449
> Allow a deprecation period for the default value by using a sentinel value to detect when the parameter wasn't used by the user:
450
450
>
451
451
> ```python title="in the coming release"
@@ -489,7 +489,7 @@ def greet(name, prefix):
489
489
greet("tiff")
490
490
```
491
491
492
-
> TIP: **Hint**
492
+
> TIP: **Hint**
493
493
> You can delay (or avoid) and inform your users about the upcoming breakage by temporarily (or permanently) providing a default value for the new parameter:
494
494
>
495
495
> ```python title="in the coming release"
@@ -530,7 +530,7 @@ from your import module
530
530
print(module.special_thing)
531
531
```
532
532
533
-
>TIP: **Hint**
533
+
>TIP: **Hint**
534
534
> Allow a deprecation period by declaring a module-level `__getattr__` function that returns the given objectwhile warning about its deprecation:
535
535
>
536
536
>```python
@@ -606,7 +606,7 @@ if PY_VERSION is None:
606
606
607
607
NOTE: Changing the value of an attribute isnot really an API breakage, depending on our definition of API, since this won't raise immediate errors like `TypeError`. The attribute is still here and accessed: the contract is fulfilled. But developers heavily rely on the value of public attributes, so changing it will lead to incorrect behavior, potentially making it difficult to detect, understand and fix the issue. That is why it is important to warn developers about such changes.
608
608
609
-
TIP: **Hint**
609
+
TIP: **Hint**
610
610
Make sure to document the change of value of the attribute in your changelog, particularly the previous and new range of values it can take.
0 commit comments