Skip to content

Commit 4bc73dd

Browse files
augustelalandeaugustelalande
authored
[pydoclint] Implement docstring-missing-exception and docstring-extraneous-exception (DOC501, DOC502) (#11471)
## Summary These are the first rules implemented as part of #458, but I plan to implement more. Specifically, this implements `docstring-missing-exception` which checks for raised exceptions not documented in the docstring, and `docstring-extraneous-exception` which checks for exceptions in the docstring not present in the body. ## Test Plan Test fixtures added for both google and numpy style.
1 parent 53b84ab commit 4bc73dd

21 files changed

+1161
-67
lines changed

‎LICENSE

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1371,3 +1371,28 @@ are:
13711371
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
13721372
SOFTWARE.
13731373
"""
1374+
1375+
- pydoclint, licensed as follows:
1376+
"""
1377+
MIT License
1378+
1379+
Copyright (c) 2023 jsh9
1380+
1381+
Permission is hereby granted, free of charge, to any person obtaining a copy
1382+
of this software and associated documentation files (the "Software"), to deal
1383+
in the Software without restriction, including without limitation the rights
1384+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
1385+
copies of the Software, and to permit persons to whom the Software is
1386+
furnished to do so, subject to the following conditions:
1387+
1388+
The above copyright notice and this permission notice shall be included in all
1389+
copies or substantial portions of the Software.
1390+
1391+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1392+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1393+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
1394+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1395+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
1396+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1397+
SOFTWARE.
1398+
"""

‎crates/ruff_linter/resources/test/fixtures/pydoclint/DOC501_google.py

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
import something
2+
from somewhere import AnotherError
3+
4+
5+
class FasterThanLightError(Exception):
6+
...
7+
8+
9+
_some_error = Exception
10+
11+
12+
# OK
13+
def calculate_speed(distance: float, time: float) -> float:
14+
"""Calculate speed as distance divided by time.
15+
16+
Args:
17+
distance: Distance traveled.
18+
time: Time spent traveling.
19+
20+
Returns:
21+
Speed as distance divided by time.
22+
23+
Raises:
24+
FasterThanLightError: If speed is greater than the speed of light.
25+
"""
26+
try:
27+
return distance / time
28+
except ZeroDivisionError as exc:
29+
raise FasterThanLightError from exc
30+
31+
32+
# DOC501
33+
def calculate_speed(distance: float, time: float) -> float:
34+
"""Calculate speed as distance divided by time.
35+
36+
Args:
37+
distance: Distance traveled.
38+
time: Time spent traveling.
39+
40+
Returns:
41+
Speed as distance divided by time.
42+
"""
43+
try:
44+
return distance / time
45+
except ZeroDivisionError as exc:
46+
raise FasterThanLightError from exc
47+
48+
49+
# DOC501
50+
def calculate_speed(distance: float, time: float) -> float:
51+
"""Calculate speed as distance divided by time.
52+
53+
Args:
54+
distance: Distance traveled.
55+
time: Time spent traveling.
56+
57+
Returns:
58+
Speed as distance divided by time.
59+
"""
60+
try:
61+
return distance / time
62+
except ZeroDivisionError as exc:
63+
raise FasterThanLightError from exc
64+
except:
65+
raise ValueError
66+
67+
68+
# DOC501
69+
def calculate_speed(distance: float, time: float) -> float:
70+
"""Calculate speed as distance divided by time.
71+
72+
Args:
73+
distance: Distance traveled.
74+
time: Time spent traveling.
75+
76+
Returns:
77+
Speed as distance divided by time.
78+
"""
79+
try:
80+
return distance / time
81+
except ZeroDivisionError as exc:
82+
print('oops')
83+
raise exc
84+
85+
86+
# DOC501
87+
def calculate_speed(distance: float, time: float) -> float:
88+
"""Calculate speed as distance divided by time.
89+
90+
Args:
91+
distance: Distance traveled.
92+
time: Time spent traveling.
93+
94+
Returns:
95+
Speed as distance divided by time.
96+
"""
97+
try:
98+
return distance / time
99+
except (ZeroDivisionError, ValueError) as exc:
100+
print('oops')
101+
raise exc
102+
103+
104+
# DOC501
105+
def calculate_speed(distance: float, time: float) -> float:
106+
"""Calculate speed as distance divided by time.
107+
108+
Args:
109+
distance: Distance traveled.
110+
time: Time spent traveling.
111+
112+
Returns:
113+
Speed as distance divided by time.
114+
"""
115+
raise AnotherError
116+
117+
118+
# DOC501
119+
def calculate_speed(distance: float, time: float) -> float:
120+
"""Calculate speed as distance divided by time.
121+
122+
Args:
123+
distance: Distance traveled.
124+
time: Time spent traveling.
125+
126+
Returns:
127+
Speed as distance divided by time.
128+
"""
129+
raise AnotherError()
130+
131+
132+
# DOC501
133+
def foo(bar: int):
134+
"""Foo.
135+
136+
Args:
137+
bar: Bar.
138+
"""
139+
raise something.SomeError
140+
141+
142+
# DOC501, but can't resolve the error
143+
def calculate_speed(distance: float, time: float) -> float:
144+
"""Calculate speed as distance divided by time.
145+
146+
Args:
147+
distance: Distance traveled.
148+
time: Time spent traveling.
149+
150+
Returns:
151+
Speed as distance divided by time.
152+
"""
153+
raise _some_error
154+
155+
156+
# OK
157+
def calculate_speed(distance: float, time: float) -> float:
158+
try:
159+
return distance / time
160+
except ZeroDivisionError as exc:
161+
raise FasterThanLightError from exc
162+
163+
164+
# OK
165+
def calculate_speed(distance: float, time: float) -> float:
166+
raise NotImplementedError
167+
168+
169+
# OK
170+
def foo(bar: int):
171+
"""Foo.
172+
173+
Args:
174+
bar: Bar.
175+
176+
Raises:
177+
SomeError: Wow.
178+
"""
179+
raise something.SomeError
180+
181+
182+
# OK
183+
def foo(bar: int):
184+
"""Foo.
185+
186+
Args:
187+
bar: Bar.
188+
189+
Raises:
190+
something.SomeError: Wow.
191+
"""
192+
raise something.SomeError

‎crates/ruff_linter/resources/test/fixtures/pydoclint/DOC501_numpy.py

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
class FasterThanLightError(Exception):
2+
...
3+
4+
5+
# OK
6+
def calculate_speed(distance: float, time: float) -> float:
7+
"""
8+
Calculate speed as distance divided by time.
9+
10+
Parameters
11+
----------
12+
distance : float
13+
Distance traveled.
14+
time : float
15+
Time spent traveling.
16+
17+
Returns
18+
-------
19+
float
20+
Speed as distance divided by time.
21+
22+
Raises
23+
------
24+
FasterThanLightError
25+
If speed is greater than the speed of light.
26+
"""
27+
try:
28+
return distance / time
29+
except ZeroDivisionError as exc:
30+
raise FasterThanLightError from exc
31+
32+
33+
# DOC501
34+
def calculate_speed(distance: float, time: float) -> float:
35+
"""
36+
Calculate speed as distance divided by time.
37+
38+
Parameters
39+
----------
40+
distance : float
41+
Distance traveled.
42+
time : float
43+
Time spent traveling.
44+
45+
Returns
46+
-------
47+
float
48+
Speed as distance divided by time.
49+
"""
50+
try:
51+
return distance / time
52+
except ZeroDivisionError as exc:
53+
raise FasterThanLightError from exc
54+
55+
56+
# DOC501
57+
def calculate_speed(distance: float, time: float) -> float:
58+
"""
59+
Calculate speed as distance divided by time.
60+
61+
Parameters
62+
----------
63+
distance : float
64+
Distance traveled.
65+
time : float
66+
Time spent traveling.
67+
68+
Returns
69+
-------
70+
float
71+
Speed as distance divided by time.
72+
"""
73+
try:
74+
return distance / time
75+
except ZeroDivisionError as exc:
76+
raise FasterThanLightError from exc
77+
except:
78+
raise ValueError

‎crates/ruff_linter/resources/test/fixtures/pydoclint/DOC502_google.py

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
class FasterThanLightError(Exception):
2+
...
3+
4+
5+
# DOC502
6+
def calculate_speed(distance: float, time: float) -> float:
7+
"""Calculate speed as distance divided by time.
8+
9+
Args:
10+
distance: Distance traveled.
11+
time: Time spent traveling.
12+
13+
Returns:
14+
Speed as distance divided by time.
15+
16+
Raises:
17+
FasterThanLightError: If speed is greater than the speed of light.
18+
"""
19+
return distance / time
20+
21+
22+
# DOC502
23+
def calculate_speed(distance: float, time: float) -> float:
24+
"""Calculate speed as distance divided by time.
25+
26+
Args:
27+
distance: Distance traveled.
28+
time: Time spent traveling.
29+
30+
Returns:
31+
Speed as distance divided by time.
32+
33+
Raises:
34+
FasterThanLightError: If speed is greater than the speed of light.
35+
DivisionByZero: Divide by zero.
36+
"""
37+
return distance / time
38+
39+
40+
# DOC502
41+
def calculate_speed(distance: float, time: float) -> float:
42+
"""Calculate speed as distance divided by time.
43+
44+
Args:
45+
distance: Distance traveled.
46+
time: Time spent traveling.
47+
48+
Returns:
49+
Speed as distance divided by time.
50+
51+
Raises:
52+
FasterThanLightError: If speed is greater than the speed of light.
53+
DivisionByZero: Divide by zero.
54+
"""
55+
try:
56+
return distance / time
57+
except ZeroDivisionError as exc:
58+
raise FasterThanLightError from exc

0 commit comments

Comments
 (0)