0
# Docstring Parsing
1
2
The numpydoc docstring parsing module provides comprehensive functionality for parsing, processing, and manipulating NumPy-style docstrings. It offers a dictionary-like interface for accessing docstring sections and supports both standalone parsing and Sphinx integration.
3
4
## Core Parsing Classes
5
6
### Base Parser
7
8
```python { .api }
9
class NumpyDocString(Mapping):
10
"""
11
Base docstring parser with dictionary-like interface.
12
13
Parses NumPy-style docstrings into structured sections like Parameters,
14
Returns, Examples, etc. Provides dictionary-like access to sections.
15
16
Parameters
17
----------
18
docstring : str
19
Raw docstring to parse
20
config : dict, optional
21
Configuration options for parsing behavior
22
23
Attributes
24
----------
25
sections : dict
26
Dictionary mapping section names to parsed content
27
"""
28
29
def __getitem__(self, key: str) -> List[str]:
30
"""
31
Access docstring sections by name.
32
33
Parameters
34
----------
35
key : str
36
Section name ('Parameters', 'Returns', 'Examples', etc.)
37
38
Returns
39
-------
40
list of str
41
Lines comprising the requested section
42
"""
43
44
def __setitem__(self, key: str, val):
45
"""
46
Set docstring section content.
47
48
Parameters
49
----------
50
key : str
51
Section name ('Parameters', 'Returns', 'Examples', etc.)
52
val
53
Section content to set
54
"""
55
56
def __contains__(self, key: str) -> bool:
57
"""Check if section exists in docstring."""
58
59
def __iter__(self):
60
"""Iterate over section names."""
61
62
def __len__(self) -> int:
63
"""Number of sections in docstring."""
64
65
def keys(self):
66
"""Return section names."""
67
68
def values(self):
69
"""Return section contents."""
70
71
def items(self):
72
"""Return (section_name, section_content) pairs."""
73
```
74
75
### Specialized Parsers
76
77
```python { .api }
78
class FunctionDoc(NumpyDocString):
79
"""
80
Function-specific docstring parser.
81
82
Extends NumpyDocString with function-specific parsing logic,
83
handling Parameters, Returns, Yields, and Raises sections with
84
proper type annotation support.
85
86
Parameters
87
----------
88
func : callable
89
Function object to parse docstring from
90
role : str, optional
91
Sphinx role for cross-references ('func', 'meth', etc.)
92
doc : str, optional
93
Override docstring (uses func.__doc__ if None)
94
config : dict, optional
95
Configuration options
96
"""
97
98
class ClassDoc(NumpyDocString):
99
"""
100
Class-specific docstring parser.
101
102
Handles class docstrings with support for Attributes sections
103
and proper inheritance of docstring sections from parent classes.
104
105
Parameters
106
----------
107
cls : type
108
Class object to parse docstring from
109
doc : str, optional
110
Override docstring (uses cls.__doc__ if None)
111
modulename : str, optional
112
Module name for cross-references
113
config : dict, optional
114
Configuration options
115
"""
116
117
class ObjDoc(NumpyDocString):
118
"""
119
Generic object docstring parser.
120
121
Fallback parser for objects that don't fit function or class
122
categories. Handles basic docstring structure without specialized
123
section processing.
124
125
Parameters
126
----------
127
obj : object
128
Python object to parse docstring from
129
doc : str, optional
130
Override docstring (uses obj.__doc__ if None)
131
config : dict, optional
132
Configuration options
133
"""
134
```
135
136
## Factory Function
137
138
```python { .api }
139
def get_doc_object(obj, what=None, doc=None, config=None, **kwargs):
140
"""
141
Factory function for creating appropriate docstring parsers.
142
143
Automatically selects the appropriate parser class based on the
144
object type and creates a configured parser instance.
145
146
Parameters
147
----------
148
obj : object
149
Python object to create parser for
150
what : str, optional
151
Type hint ('function', 'class', 'method', 'module', etc.)
152
If None, type is inferred from obj
153
doc : str, optional
154
Override docstring (uses obj.__doc__ if None)
155
config : dict, optional
156
Configuration options to pass to parser
157
**kwargs
158
Additional arguments passed to parser constructor
159
160
Returns
161
-------
162
NumpyDocString
163
Appropriate parser instance (FunctionDoc, ClassDoc, or ObjDoc)
164
165
Examples
166
--------
167
>>> import numpy as np
168
>>> doc = get_doc_object(np.array)
169
>>> 'Parameters' in doc
170
True
171
>>> doc['Summary']
172
['Create an array.']
173
"""
174
```
175
176
## String Processing Utilities
177
178
### Line Reader
179
180
```python { .api }
181
class Reader:
182
"""
183
Line-based string reader for docstring parsing.
184
185
Provides file-like interface for reading docstring content
186
line by line with support for peeking, seeking, and position tracking.
187
188
Parameters
189
----------
190
data : str or list of str
191
Input data as string or list of lines
192
193
Attributes
194
----------
195
_l : list of str
196
Internal list of lines
197
_i : int
198
Current position index
199
"""
200
201
def __init__(self, data):
202
"""Initialize reader with string or line data."""
203
204
def __getitem__(self, n: int) -> str:
205
"""Get line at position n."""
206
207
def reset(self):
208
"""Reset reader position to beginning."""
209
210
def read(self) -> str:
211
"""
212
Read and return next line.
213
214
Returns
215
-------
216
str
217
Next line or empty string if at end
218
"""
219
220
def seek_next_non_empty_line(self):
221
"""Advance position to next non-empty line."""
222
223
def eof(self) -> bool:
224
"""Check if at end of input."""
225
226
def read_to_condition(self, condition_func):
227
"""
228
Read lines until condition function returns True.
229
230
Parameters
231
----------
232
condition_func : callable
233
Function that takes a line and returns boolean
234
235
Returns
236
-------
237
list of str
238
Lines read before condition was met
239
"""
240
241
def read_to_next_empty_line(self) -> List[str]:
242
"""Read lines until next empty line."""
243
244
def read_to_next_unindented_line(self) -> List[str]:
245
"""Read lines until next unindented line."""
246
```
247
248
### Utility Functions
249
250
```python { .api }
251
def strip_blank_lines(l: List[str]) -> List[str]:
252
"""
253
Remove blank lines from beginning and end of list.
254
255
Parameters
256
----------
257
l : list of str
258
Input list of lines
259
260
Returns
261
-------
262
list of str
263
List with leading/trailing blank lines removed
264
"""
265
266
def dedent_lines(lines: List[str]) -> List[str]:
267
"""
268
Remove common indentation from all lines.
269
270
Similar to textwrap.dedent but operates on list of lines
271
and preserves relative indentation.
272
273
Parameters
274
----------
275
lines : list of str
276
Input lines with potentially common indentation
277
278
Returns
279
-------
280
list of str
281
Lines with common indentation removed
282
"""
283
```
284
285
## Sphinx Integration
286
287
### Sphinx-Specific Parsers
288
289
```python { .api }
290
class SphinxDocString(NumpyDocString):
291
"""
292
Sphinx-specific docstring parser.
293
294
Extends base parser with Sphinx-specific functionality including
295
cross-reference generation, plot directive processing, and
296
integration with Sphinx's documentation build system.
297
298
Parameters
299
----------
300
docstring : str
301
Raw docstring to parse
302
config : dict, optional
303
Sphinx configuration options
304
app : sphinx.application.Sphinx, optional
305
Sphinx application instance
306
what : str, optional
307
Object type for Sphinx autodoc
308
name : str, optional
309
Fully qualified object name
310
obj : object, optional
311
The actual Python object
312
options : dict, optional
313
Sphinx autodoc options
314
"""
315
316
class SphinxFunctionDoc(SphinxDocString, FunctionDoc):
317
"""
318
Sphinx function parser combining Sphinx and function-specific features.
319
320
Provides complete function docstring parsing with Sphinx integration
321
for cross-references, type linking, and documentation generation.
322
"""
323
324
class SphinxClassDoc(SphinxDocString, ClassDoc):
325
"""
326
Sphinx class parser combining Sphinx and class-specific features.
327
328
Handles class docstrings with Sphinx integration including
329
member documentation, inheritance handling, and cross-references.
330
"""
331
332
class SphinxObjDoc(SphinxDocString, ObjDoc):
333
"""
334
Sphinx generic object parser with Sphinx integration features.
335
336
Fallback parser for objects with Sphinx-specific functionality
337
like cross-reference generation and documentation formatting.
338
"""
339
```
340
341
### Sphinx Factory Function
342
343
```python { .api }
344
def get_doc_object(obj, what=None, doc=None, config=None, builder=None):
345
"""
346
Sphinx-specific factory for creating docstring parsers.
347
348
Similar to docscrape.get_doc_object but with Sphinx integration
349
and builder-specific configuration handling.
350
351
Parameters
352
----------
353
obj : object
354
Python object to create parser for
355
what : str, optional
356
Object type hint for Sphinx autodoc
357
doc : str, optional
358
Override docstring
359
config : dict, optional
360
Sphinx configuration
361
builder : sphinx.builders.Builder, optional
362
Sphinx builder instance
363
364
Returns
365
-------
366
SphinxDocString
367
Appropriate Sphinx parser instance
368
"""
369
```
370
371
## Constants and Patterns
372
373
```python { .api }
374
IMPORT_MATPLOTLIB_RE: Pattern[str]
375
"""Regular expression for detecting matplotlib import statements in examples."""
376
```
377
378
## Exception Classes
379
380
```python { .api }
381
class ParseError(Exception):
382
"""
383
Exception raised when docstring parsing fails.
384
385
Indicates malformed docstring structure or content that
386
cannot be properly parsed according to NumPy format rules.
387
388
Parameters
389
----------
390
msg : str
391
Error message describing the parsing failure
392
"""
393
```
394
395
## Usage Examples
396
397
### Basic Parsing
398
399
```python
400
from numpydoc.docscrape import NumpyDocString, get_doc_object
401
402
# Parse docstring directly
403
docstring = '''
404
Summary line.
405
406
Parameters
407
----------
408
x : array_like
409
Input array
410
y : float
411
Scale factor
412
413
Returns
414
-------
415
ndarray
416
Scaled array
417
'''
418
419
doc = NumpyDocString(docstring)
420
print(doc['Summary']) # ['Summary line.']
421
print('Parameters' in doc) # True
422
```
423
424
### Object Parsing
425
426
```python
427
import numpy as np
428
from numpydoc.docscrape import get_doc_object
429
430
# Parse function docstring
431
doc = get_doc_object(np.array)
432
print(doc['Parameters']) # Parsed parameter information
433
print(doc['Returns']) # Return value documentation
434
435
# Parse class docstring
436
doc = get_doc_object(np.ndarray)
437
print(doc['Attributes']) # Class attribute documentation
438
```
439
440
### Sphinx Integration
441
442
```python
443
from numpydoc.docscrape_sphinx import get_doc_object
444
445
# Create Sphinx-aware parser
446
config = {'numpydoc_use_plots': True}
447
doc = get_doc_object(np.fft.fft, config=config)
448
449
# Access processed sections ready for Sphinx
450
sections = doc['Examples'] # Processed with plot directives
451
```
452
453
### Reader Usage
454
455
```python
456
from numpydoc.docscrape import Reader
457
458
content = '''
459
Line 1
460
Line 2
461
462
Line 4
463
'''
464
465
reader = Reader(content)
466
while not reader.eof():
467
line = reader.read()
468
print(f"Read: {line}")
469
470
# Seek operations
471
reader.reset()
472
reader.seek_next_non_empty_line()
473
remaining = reader.read_to_next_empty_line()
474
```