Skip to content

Commit 4c2b9e3

Browse files
committed
docs: add two warning about no-types mode
Fixes #1161
1 parent 363ccf4 commit 4c2b9e3

File tree

2 files changed

+32
-1
lines changed

2 files changed

+32
-1
lines changed

docs/examples.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,26 @@ False
4343

4444
As shown, the generated `__init__` method allows for both positional and keyword arguments.
4545

46+
---
47+
48+
Unlike Data Classes, *attrs* doesn't force you to use type annotations.
49+
So, the previous example could also have been written as:
50+
51+
```{doctest}
52+
>>> @define
53+
... class Coordinates:
54+
... x = field()
55+
... y = field()
56+
>>> Coordinates(1, 2)
57+
Coordinates(x=1, y=2)
58+
```
59+
60+
:::{caution}
61+
If a class body contains a field that is defined using {func}`attrs.field` (or {func}`attr.ib`), but **lacks a type annotation**, *attrs* switches to a no-typing mode and ignores fields that have type annotations but are not defined using {func}`attrs.field` (or {func}`attr.ib`).
62+
:::
63+
64+
---
65+
4666
For private attributes, *attrs* will strip the leading underscores for keyword arguments:
4767

4868
```{doctest}

docs/types.md

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,18 @@ SomeClass(a_number=1, list_of_numbers=[1, 2, 3])
1919

2020
You can choose freely between the approaches, but please remember that if you choose to use type annotations, you **must** annotate **all** attributes!
2121

22-
---
22+
:::{caution}
23+
If you define a class with a {func}`attrs.field` that **lacks** a type annotation, *attrs* will **ignore** other fields that have a type annotation, but are not defined using {func}`attrs.field`:
24+
25+
```{doctest}
26+
>>> @define
27+
... class SomeClass:
28+
... a_number = field(default=42)
29+
... another_number: int = 23
30+
>>> SomeClass()
31+
SomeClass(a_number=42)
32+
```
33+
:::
2334

2435
Even when going all-in on type annotations, you will need {func}`attrs.field` for some advanced features though.
2536

0 commit comments

Comments
 (0)