flavors_google

Example Google style docstrings.

This module demonstrates documentation as specified by the Google Python Style Guide. Docstrings may extend over multiple lines. Sections are created with a section header and a colon followed by a block of indented text.

Example:

Examples can be given using either the Example or Examples sections. Sections support any reStructuredText formatting, including literal blocks::

$ python example_google.py

Section breaks are created by resuming unindented text. Section breaks are also implicitly created anytime a new section starts.

Attributes:
  • module_level_variable1 (int): Module level variables may be documented in either the Attributes section of the module docstring, or in an inline docstring immediately following the variable.

    Either form is acceptable, but the two should not be mixed. Choose one convention to document module level variables and be consistent with it.

Todo:
  • For module TODOs
  • You have to also use sphinx.ext.todo extension
  1# Examples taken from:
  2#
  3# - The Napoleon documentation at https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
  4#   License: BSD-3
  5# - The Google Style Guide at https://google.github.io/styleguide/pyguide.html
  6#   License: CC BY 3.0
  7#
  8# flake8: noqa
  9# fmt: off
 10"""Example Google style docstrings.
 11
 12This module demonstrates documentation as specified by the `Google Python
 13Style Guide`_. Docstrings may extend over multiple lines. Sections are created
 14with a section header and a colon followed by a block of indented text.
 15
 16Example:
 17    Examples can be given using either the ``Example`` or ``Examples``
 18    sections. Sections support any reStructuredText formatting, including
 19    literal blocks::
 20
 21        $ python example_google.py
 22
 23Section breaks are created by resuming unindented text. Section breaks
 24are also implicitly created anytime a new section starts.
 25
 26Attributes:
 27    module_level_variable1 (int): Module level variables may be documented in
 28        either the ``Attributes`` section of the module docstring, or in an
 29        inline docstring immediately following the variable.
 30
 31        Either form is acceptable, but the two should not be mixed. Choose
 32        one convention to document module level variables and be consistent
 33        with it.
 34
 35Todo:
 36    * For module TODOs
 37    * You have to also use ``sphinx.ext.todo`` extension
 38
 39.. _Google Python Style Guide:
 40   http://google.github.io/styleguide/pyguide.html
 41
 42"""
 43__docformat__ = "google"
 44
 45from typing import Any, Mapping, Sequence, Tuple
 46
 47
 48module_level_variable1 = 12345
 49
 50module_level_variable2 = 98765
 51"""int: Module level variable documented inline.
 52
 53The docstring may span multiple lines. The type may optionally be specified
 54on the first line, separated by a colon.
 55"""
 56
 57
 58def function_with_types_in_docstring(param1, param2):
 59    """Example function with types documented in the docstring.
 60
 61    `PEP 484`_ type annotations are supported. If attribute, parameter, and
 62    return types are annotated according to `PEP 484`_, they do not need to be
 63    included in the docstring:
 64
 65    Args:
 66        param1 (int): The first parameter.
 67        param2 (str): The second parameter.
 68
 69    Returns:
 70        bool: The return value. True for success, False otherwise.
 71
 72    .. _PEP 484:
 73        https://www.python.org/dev/peps/pep-0484/
 74
 75    """
 76
 77
 78def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
 79    """Example function with PEP 484 type annotations.
 80
 81    Args:
 82        param1: The first parameter.
 83        param2: The second parameter.
 84
 85    Returns:
 86        The return value. True for success, False otherwise.
 87
 88    """
 89    raise NotImplementedError
 90
 91
 92def module_level_function(param1, param2=None, *args, **kwargs):
 93    """This is an example of a module level function.
 94
 95    Function parameters should be documented in the ``Args`` section. The name
 96    of each parameter is required. The type and description of each parameter
 97    is optional, but should be included if not obvious.
 98
 99    If *args or **kwargs are accepted,
100    they should be listed as ``*args`` and ``**kwargs``.
101
102    The format for a parameter is::
103
104        name (type): description
105            The description may span multiple lines. Following
106            lines should be indented. The "(type)" is optional.
107
108            Multiple paragraphs are supported in parameter
109            descriptions.
110
111    Args:
112        param1 (int): The first parameter.
113        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
114            Second line of description should be indented.
115        *args: Variable length argument list.
116        **kwargs: Arbitrary keyword arguments.
117
118    Returns:
119        bool: True if successful, False otherwise.
120
121        The return type is optional and may be specified at the beginning of
122        the ``Returns`` section followed by a colon.
123
124        The ``Returns`` section may span multiple lines and paragraphs.
125        Following lines should be indented to match the first line.
126
127        The ``Returns`` section supports any reStructuredText formatting,
128        including literal blocks::
129
130            {
131                'param1': param1,
132                'param2': param2
133            }
134
135    Raises:
136        AttributeError: The ``Raises`` section is a list of all exceptions
137            that are relevant to the interface.
138        ValueError: If `param2` is equal to `param1`.
139
140    """
141    if param1 == param2:
142        raise ValueError('param1 may not be equal to param2')
143    return True
144
145
146def example_generator(n):
147    """Generators have a ``Yields`` section instead of a ``Returns`` section.
148
149    Args:
150        n (int): The upper limit of the range to generate, from 0 to `n` - 1.
151
152    Yields:
153        int: The next number in the range of 0 to `n` - 1.
154
155    Examples:
156        Examples should be written in doctest format, and should illustrate how
157        to use the function.
158
159        >>> print([i for i in example_generator(4)])
160        [0, 1, 2, 3]
161
162    """
163    for i in range(n):
164        yield i
165
166
167class ExampleError(Exception):
168    """Exceptions are documented in the same way as classes.
169
170    The __init__ method may be documented in either the class level
171    docstring, or as a docstring on the __init__ method itself.
172
173    Either form is acceptable, but the two should not be mixed. Choose one
174    convention to document the __init__ method and be consistent with it.
175
176    Note:
177        Do not include the `self` parameter in the ``Args`` section.
178
179    Args:
180        msg (str): Human readable string describing the exception.
181        code (:obj:`int`, optional): Error code.
182
183    Attributes:
184        msg (str): Human readable string describing the exception.
185        code (int): Exception error code.
186
187    """
188
189    def __init__(self, msg, code):
190        self.msg = msg
191        self.code = code
192
193    def add_note(self, note: str):
194        """This method is present on Python 3.11+ and manually added here so that snapshots are consistent."""
195
196
197class ExampleClass(object):
198    """The summary line for a class docstring should fit on one line.
199
200    If the class has public attributes, they may be documented here
201    in an ``Attributes`` section and follow the same formatting as a
202    function's ``Args`` section. Alternatively, attributes may be documented
203    inline with the attribute's declaration (see __init__ method below).
204
205    Properties created with the ``@property`` decorator should be documented
206    in the property's getter method.
207
208    Attributes:
209        attr1 (str): Description of `attr1`.
210        attr2 (:obj:`int`, optional): Description of `attr2`.
211
212    """
213
214    def __init__(self, param1, param2, param3):
215        """Example of docstring on the __init__ method.
216
217        The __init__ method may be documented in either the class level
218        docstring, or as a docstring on the __init__ method itself.
219
220        Either form is acceptable, but the two should not be mixed. Choose one
221        convention to document the __init__ method and be consistent with it.
222
223        Note:
224            Do not include the `self` parameter in the ``Args`` section.
225
226        Args:
227            param1 (str): Description of `param1`.
228            param2 (:obj:`int`, optional): Description of `param2`. Multiple
229                lines are supported.
230            param3 (:obj:`list` of :obj:`str`): Description of `param3`.
231
232        """
233        self.attr1 = param1
234        self.attr2 = param2
235        self.attr3 = param3  #: Doc comment *inline* with attribute
236
237        #: list of str: Doc comment *before* attribute, with type specified
238        self.attr4 = ['attr4']
239
240        self.attr5 = None
241        """str: Docstring *after* attribute, with type specified."""
242
243    @property
244    def readonly_property(self):
245        """str: Properties should be documented in their getter method."""
246        return 'readonly_property'
247
248    @property
249    def readwrite_property(self):
250        """:obj:`list` of :obj:`str`: Properties with both a getter and setter
251        should only be documented in their getter method.
252
253        If the setter method contains notable behavior, it should be
254        mentioned here.
255        """
256        return ['readwrite_property']
257
258    @readwrite_property.setter
259    def readwrite_property(self, value):
260        value
261
262    def example_method(self, param1, param2):
263        """Class methods are similar to regular functions.
264
265        Note:
266            Do not include the `self` parameter in the ``Args`` section.
267
268        Args:
269            param1: The first parameter.
270            param2: The second parameter.
271
272        Returns:
273            True if successful, False otherwise.
274
275        """
276        return True
277
278    def __special__(self):
279        """By default special members with docstrings are not included.
280
281        Special members are any methods or attributes that start with and
282        end with a double underscore. Any special member with a docstring
283        will be included in the output, if
284        ``napoleon_include_special_with_doc`` is set to True.
285
286        This behavior can be enabled by changing the following setting in
287        Sphinx's conf.py::
288
289            napoleon_include_special_with_doc = True
290
291        """
292        pass
293
294    def __special_without_docstring__(self):
295        pass
296
297    def _private(self):
298        """By default private members are not included.
299
300        Private members are any methods or attributes that start with an
301        underscore and are *not* special. By default they are not included
302        in the output.
303
304        This behavior can be changed such that private members *are* included
305        by changing the following setting in Sphinx's conf.py::
306
307            napoleon_include_private_with_doc = True
308
309        """
310        pass
311
312    def _private_without_docstring(self):
313        pass
314
315
316def fetch_smalltable_rows(table_handle: Any,
317                          keys: Sequence[str],
318                          require_all_keys: bool = False,
319) -> Mapping[bytes, Tuple[str]]:
320    """Fetches rows from a Smalltable.
321
322    Retrieves rows pertaining to the given keys from the Table instance
323    represented by table_handle.  String keys will be UTF-8 encoded.
324
325    Args:
326        table_handle: An open smalltable.Table instance.
327        keys: A sequence of strings representing the key of each table
328          row to fetch.  String keys will be UTF-8 encoded.
329        require_all_keys: Optional; If require_all_keys is True only
330          rows with values set for all keys will be returned.
331
332    Returns:
333        A dict mapping keys to the corresponding table row data
334        fetched. Each row is represented as a tuple of strings. For
335        example:
336
337        {b'Serak': ('Rigel VII', 'Preparer'),
338         b'Zim': ('Irk', 'Invader'),
339         b'Lrrr': ('Omicron Persei 8', 'Emperor')}
340
341        Returned keys are always bytes.  If a key from the keys argument is
342        missing from the dictionary, then that row was not found in the
343        table (and require_all_keys must have been False).
344
345    Raises:
346        IOError: An error occurred accessing the smalltable.
347    """
348    raise NotImplementedError
349
350
351def fetch_smalltable_rows2(table_handle: Any,
352                          keys: Sequence[str],
353                          require_all_keys: bool = False,
354) -> Mapping[bytes, Tuple[str]]:
355    """Fetches rows from a Smalltable.
356
357    Retrieves rows pertaining to the given keys from the Table instance
358    represented by table_handle.  String keys will be UTF-8 encoded.
359
360    Args:
361      table_handle:
362        An open smalltable.Table instance.
363      keys:
364        A sequence of strings representing the key of each table row to
365        fetch.  String keys will be UTF-8 encoded.
366      require_all_keys:
367        Optional; If require_all_keys is True only rows with values set
368        for all keys will be returned.
369
370    Returns:
371      A dict mapping keys to the corresponding table row data
372      fetched. Each row is represented as a tuple of strings. For
373      example:
374
375      {b'Serak': ('Rigel VII', 'Preparer'),
376       b'Zim': ('Irk', 'Invader'),
377       b'Lrrr': ('Omicron Persei 8', 'Emperor')}
378
379      Returned keys are always bytes.  If a key from the keys argument is
380      missing from the dictionary, then that row was not found in the
381      table (and require_all_keys must have been False).
382
383    Raises:
384      IOError: An error occurred accessing the smalltable.
385    """
386    raise NotImplementedError
387
388
389class SampleClass:
390    """Summary of class here.
391
392    Longer class information....
393    Longer class information....
394
395    Attributes:
396        likes_spam: A boolean indicating if we like SPAM or not.
397        eggs: An integer count of the eggs we have laid.
398    """
399
400    def __init__(self, likes_spam=False):
401        """Inits SampleClass with blah."""
402        self.likes_spam = likes_spam
403        self.eggs = 0
404
405    def public_method(self):
406        """Performs operation blah."""
407
408
409def invalid_format(test):
410    """
411    In this example, there is no colon after the argument and an empty section.
412
413    Args:
414      test
415        there is a colon missing in the previous line
416    Returns:
417
418    """
419
420
421def example_code():
422    """
423    Test case for https://github.com/mitmproxy/pdoc/issues/264.
424
425    Example:
426
427        ```python
428        tmp = a2()
429
430        tmp2 = a()
431        ```
432    """
433
434
435def newline_after_args(test: str):
436    """
437    Test case for https://github.com/mitmproxy/pdoc/pull/458.
438
439    Args:
440
441      test
442        there is unexpected whitespace before test.
443    """
444
445
446def alternative_section_names(test: str):
447    """
448    In this example, we check whether alternative section names aliased to
449    'Args' are handled properly.
450
451    Parameters:
452        test: the test string
453    """
module_level_variable1 = 12345
module_level_variable2 = 98765

int: Module level variable documented inline.

The docstring may span multiple lines. The type may optionally be specified on the first line, separated by a colon.

def function_with_types_in_docstring(param1, param2):
59def function_with_types_in_docstring(param1, param2):
60    """Example function with types documented in the docstring.
61
62    `PEP 484`_ type annotations are supported. If attribute, parameter, and
63    return types are annotated according to `PEP 484`_, they do not need to be
64    included in the docstring:
65
66    Args:
67        param1 (int): The first parameter.
68        param2 (str): The second parameter.
69
70    Returns:
71        bool: The return value. True for success, False otherwise.
72
73    .. _PEP 484:
74        https://www.python.org/dev/peps/pep-0484/
75
76    """

Example function with types documented in the docstring.

PEP 484 type annotations are supported. If attribute, parameter, and return types are annotated according to PEP 484, they do not need to be included in the docstring:

Arguments:
  • param1 (int): The first parameter.
  • param2 (str): The second parameter.
Returns:

bool: The return value. True for success, False otherwise.

def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
79def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:
80    """Example function with PEP 484 type annotations.
81
82    Args:
83        param1: The first parameter.
84        param2: The second parameter.
85
86    Returns:
87        The return value. True for success, False otherwise.
88
89    """
90    raise NotImplementedError

Example function with PEP 484 type annotations.

Arguments:
  • param1: The first parameter.
  • param2: The second parameter.
Returns:

The return value. True for success, False otherwise.

def module_level_function(param1, param2=None, *args, **kwargs):
 93def module_level_function(param1, param2=None, *args, **kwargs):
 94    """This is an example of a module level function.
 95
 96    Function parameters should be documented in the ``Args`` section. The name
 97    of each parameter is required. The type and description of each parameter
 98    is optional, but should be included if not obvious.
 99
100    If *args or **kwargs are accepted,
101    they should be listed as ``*args`` and ``**kwargs``.
102
103    The format for a parameter is::
104
105        name (type): description
106            The description may span multiple lines. Following
107            lines should be indented. The "(type)" is optional.
108
109            Multiple paragraphs are supported in parameter
110            descriptions.
111
112    Args:
113        param1 (int): The first parameter.
114        param2 (:obj:`str`, optional): The second parameter. Defaults to None.
115            Second line of description should be indented.
116        *args: Variable length argument list.
117        **kwargs: Arbitrary keyword arguments.
118
119    Returns:
120        bool: True if successful, False otherwise.
121
122        The return type is optional and may be specified at the beginning of
123        the ``Returns`` section followed by a colon.
124
125        The ``Returns`` section may span multiple lines and paragraphs.
126        Following lines should be indented to match the first line.
127
128        The ``Returns`` section supports any reStructuredText formatting,
129        including literal blocks::
130
131            {
132                'param1': param1,
133                'param2': param2
134            }
135
136    Raises:
137        AttributeError: The ``Raises`` section is a list of all exceptions
138            that are relevant to the interface.
139        ValueError: If `param2` is equal to `param1`.
140
141    """
142    if param1 == param2:
143        raise ValueError('param1 may not be equal to param2')
144    return True

This is an example of a module level function.

Function parameters should be documented in the Args section. The name of each parameter is required. The type and description of each parameter is optional, but should be included if not obvious.

If args or *kwargs are accepted, they should be listed as *args and **kwargs.

The format for a parameter is::

name (type): description
    The description may span multiple lines. Following
    lines should be indented. The "(type)" is optional.

    Multiple paragraphs are supported in parameter
    descriptions.
Arguments:
  • param1 (int): The first parameter.
  • param2 (str, optional): The second parameter. Defaults to None. Second line of description should be indented.
  • *args: Variable length argument list.
  • **kwargs: Arbitrary keyword arguments.
Returns:

bool: True if successful, False otherwise.

The return type is optional and may be specified at the beginning of the Returns section followed by a colon.

The Returns section may span multiple lines and paragraphs. Following lines should be indented to match the first line.

The Returns section supports any reStructuredText formatting, including literal blocks::

{
    'param1': param1,
    'param2': param2
}
Raises:
  • AttributeError: The Raises section is a list of all exceptions that are relevant to the interface.
  • ValueError: If param2 is equal to param1.
def example_generator(n):
147def example_generator(n):
148    """Generators have a ``Yields`` section instead of a ``Returns`` section.
149
150    Args:
151        n (int): The upper limit of the range to generate, from 0 to `n` - 1.
152
153    Yields:
154        int: The next number in the range of 0 to `n` - 1.
155
156    Examples:
157        Examples should be written in doctest format, and should illustrate how
158        to use the function.
159
160        >>> print([i for i in example_generator(4)])
161        [0, 1, 2, 3]
162
163    """
164    for i in range(n):
165        yield i

Generators have a Yields section instead of a Returns section.

Arguments:
  • n (int): The upper limit of the range to generate, from 0 to n - 1.
Yields:

int: The next number in the range of 0 to n - 1.

Examples:

Examples should be written in doctest format, and should illustrate how to use the function.

>>> print([i for i in example_generator(4)])
[0, 1, 2, 3]
class ExampleError(builtins.Exception):
168class ExampleError(Exception):
169    """Exceptions are documented in the same way as classes.
170
171    The __init__ method may be documented in either the class level
172    docstring, or as a docstring on the __init__ method itself.
173
174    Either form is acceptable, but the two should not be mixed. Choose one
175    convention to document the __init__ method and be consistent with it.
176
177    Note:
178        Do not include the `self` parameter in the ``Args`` section.
179
180    Args:
181        msg (str): Human readable string describing the exception.
182        code (:obj:`int`, optional): Error code.
183
184    Attributes:
185        msg (str): Human readable string describing the exception.
186        code (int): Exception error code.
187
188    """
189
190    def __init__(self, msg, code):
191        self.msg = msg
192        self.code = code
193
194    def add_note(self, note: str):
195        """This method is present on Python 3.11+ and manually added here so that snapshots are consistent."""

Exceptions are documented in the same way as classes.

The __init__ method may be documented in either the class level docstring, or as a docstring on the __init__ method itself.

Either form is acceptable, but the two should not be mixed. Choose one convention to document the __init__ method and be consistent with it.

Note:

Do not include the self parameter in the Args section.

Arguments:
  • msg (str): Human readable string describing the exception.
  • code (int, optional): Error code.
Attributes:
  • msg (str): Human readable string describing the exception.
  • code (int): Exception error code.
ExampleError(msg, code)
190    def __init__(self, msg, code):
191        self.msg = msg
192        self.code = code
msg
code
def add_note(self, note: str):
194    def add_note(self, note: str):
195        """This method is present on Python 3.11+ and manually added here so that snapshots are consistent."""

This method is present on Python 3.11+ and manually added here so that snapshots are consistent.

Inherited Members
builtins.BaseException
with_traceback
args
class ExampleClass:
198class ExampleClass(object):
199    """The summary line for a class docstring should fit on one line.
200
201    If the class has public attributes, they may be documented here
202    in an ``Attributes`` section and follow the same formatting as a
203    function's ``Args`` section. Alternatively, attributes may be documented
204    inline with the attribute's declaration (see __init__ method below).
205
206    Properties created with the ``@property`` decorator should be documented
207    in the property's getter method.
208
209    Attributes:
210        attr1 (str): Description of `attr1`.
211        attr2 (:obj:`int`, optional): Description of `attr2`.
212
213    """
214
215    def __init__(self, param1, param2, param3):
216        """Example of docstring on the __init__ method.
217
218        The __init__ method may be documented in either the class level
219        docstring, or as a docstring on the __init__ method itself.
220
221        Either form is acceptable, but the two should not be mixed. Choose one
222        convention to document the __init__ method and be consistent with it.
223
224        Note:
225            Do not include the `self` parameter in the ``Args`` section.
226
227        Args:
228            param1 (str): Description of `param1`.
229            param2 (:obj:`int`, optional): Description of `param2`. Multiple
230                lines are supported.
231            param3 (:obj:`list` of :obj:`str`): Description of `param3`.
232
233        """
234        self.attr1 = param1
235        self.attr2 = param2
236        self.attr3 = param3  #: Doc comment *inline* with attribute
237
238        #: list of str: Doc comment *before* attribute, with type specified
239        self.attr4 = ['attr4']
240
241        self.attr5 = None
242        """str: Docstring *after* attribute, with type specified."""
243
244    @property
245    def readonly_property(self):
246        """str: Properties should be documented in their getter method."""
247        return 'readonly_property'
248
249    @property
250    def readwrite_property(self):
251        """:obj:`list` of :obj:`str`: Properties with both a getter and setter
252        should only be documented in their getter method.
253
254        If the setter method contains notable behavior, it should be
255        mentioned here.
256        """
257        return ['readwrite_property']
258
259    @readwrite_property.setter
260    def readwrite_property(self, value):
261        value
262
263    def example_method(self, param1, param2):
264        """Class methods are similar to regular functions.
265
266        Note:
267            Do not include the `self` parameter in the ``Args`` section.
268
269        Args:
270            param1: The first parameter.
271            param2: The second parameter.
272
273        Returns:
274            True if successful, False otherwise.
275
276        """
277        return True
278
279    def __special__(self):
280        """By default special members with docstrings are not included.
281
282        Special members are any methods or attributes that start with and
283        end with a double underscore. Any special member with a docstring
284        will be included in the output, if
285        ``napoleon_include_special_with_doc`` is set to True.
286
287        This behavior can be enabled by changing the following setting in
288        Sphinx's conf.py::
289
290            napoleon_include_special_with_doc = True
291
292        """
293        pass
294
295    def __special_without_docstring__(self):
296        pass
297
298    def _private(self):
299        """By default private members are not included.
300
301        Private members are any methods or attributes that start with an
302        underscore and are *not* special. By default they are not included
303        in the output.
304
305        This behavior can be changed such that private members *are* included
306        by changing the following setting in Sphinx's conf.py::
307
308            napoleon_include_private_with_doc = True
309
310        """
311        pass
312
313    def _private_without_docstring(self):
314        pass

The summary line for a class docstring should fit on one line.

If the class has public attributes, they may be documented here in an Attributes section and follow the same formatting as a function's Args section. Alternatively, attributes may be documented inline with the attribute's declaration (see __init__ method below).

Properties created with the @property decorator should be documented in the property's getter method.

Attributes:
  • attr1 (str): Description of attr1.
  • attr2 (int, optional): Description of attr2.
ExampleClass(param1, param2, param3)
215    def __init__(self, param1, param2, param3):
216        """Example of docstring on the __init__ method.
217
218        The __init__ method may be documented in either the class level
219        docstring, or as a docstring on the __init__ method itself.
220
221        Either form is acceptable, but the two should not be mixed. Choose one
222        convention to document the __init__ method and be consistent with it.
223
224        Note:
225            Do not include the `self` parameter in the ``Args`` section.
226
227        Args:
228            param1 (str): Description of `param1`.
229            param2 (:obj:`int`, optional): Description of `param2`. Multiple
230                lines are supported.
231            param3 (:obj:`list` of :obj:`str`): Description of `param3`.
232
233        """
234        self.attr1 = param1
235        self.attr2 = param2
236        self.attr3 = param3  #: Doc comment *inline* with attribute
237
238        #: list of str: Doc comment *before* attribute, with type specified
239        self.attr4 = ['attr4']
240
241        self.attr5 = None
242        """str: Docstring *after* attribute, with type specified."""

Example of docstring on the __init__ method.

The __init__ method may be documented in either the class level docstring, or as a docstring on the __init__ method itself.

Either form is acceptable, but the two should not be mixed. Choose one convention to document the __init__ method and be consistent with it.

Note:

Do not include the self parameter in the Args section.

Arguments:
  • param1 (str): Description of param1.
  • param2 (int, optional): Description of param2. Multiple lines are supported.
  • param3 (list of str): Description of param3.
attr1
attr2
attr3
attr4
attr5

str: Docstring after attribute, with type specified.

readonly_property
244    @property
245    def readonly_property(self):
246        """str: Properties should be documented in their getter method."""
247        return 'readonly_property'

str: Properties should be documented in their getter method.

readwrite_property
249    @property
250    def readwrite_property(self):
251        """:obj:`list` of :obj:`str`: Properties with both a getter and setter
252        should only be documented in their getter method.
253
254        If the setter method contains notable behavior, it should be
255        mentioned here.
256        """
257        return ['readwrite_property']

list of str: Properties with both a getter and setter should only be documented in their getter method.

If the setter method contains notable behavior, it should be mentioned here.

def example_method(self, param1, param2):
263    def example_method(self, param1, param2):
264        """Class methods are similar to regular functions.
265
266        Note:
267            Do not include the `self` parameter in the ``Args`` section.
268
269        Args:
270            param1: The first parameter.
271            param2: The second parameter.
272
273        Returns:
274            True if successful, False otherwise.
275
276        """
277        return True

Class methods are similar to regular functions.

Note:

Do not include the self parameter in the Args section.

Arguments:
  • param1: The first parameter.
  • param2: The second parameter.
Returns:

True if successful, False otherwise.

def fetch_smalltable_rows( table_handle: Any, keys: Sequence[str], require_all_keys: bool = False) -> Mapping[bytes, Tuple[str]]:
317def fetch_smalltable_rows(table_handle: Any,
318                          keys: Sequence[str],
319                          require_all_keys: bool = False,
320) -> Mapping[bytes, Tuple[str]]:
321    """Fetches rows from a Smalltable.
322
323    Retrieves rows pertaining to the given keys from the Table instance
324    represented by table_handle.  String keys will be UTF-8 encoded.
325
326    Args:
327        table_handle: An open smalltable.Table instance.
328        keys: A sequence of strings representing the key of each table
329          row to fetch.  String keys will be UTF-8 encoded.
330        require_all_keys: Optional; If require_all_keys is True only
331          rows with values set for all keys will be returned.
332
333    Returns:
334        A dict mapping keys to the corresponding table row data
335        fetched. Each row is represented as a tuple of strings. For
336        example:
337
338        {b'Serak': ('Rigel VII', 'Preparer'),
339         b'Zim': ('Irk', 'Invader'),
340         b'Lrrr': ('Omicron Persei 8', 'Emperor')}
341
342        Returned keys are always bytes.  If a key from the keys argument is
343        missing from the dictionary, then that row was not found in the
344        table (and require_all_keys must have been False).
345
346    Raises:
347        IOError: An error occurred accessing the smalltable.
348    """
349    raise NotImplementedError

Fetches rows from a Smalltable.

Retrieves rows pertaining to the given keys from the Table instance represented by table_handle. String keys will be UTF-8 encoded.

Arguments:
  • table_handle: An open smalltable.Table instance.
  • keys: A sequence of strings representing the key of each table row to fetch. String keys will be UTF-8 encoded.
  • require_all_keys: Optional; If require_all_keys is True only rows with values set for all keys will be returned.
Returns:

A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example:

{b'Serak': ('Rigel VII', 'Preparer'), b'Zim': ('Irk', 'Invader'), b'Lrrr': ('Omicron Persei 8', 'Emperor')}

Returned keys are always bytes. If a key from the keys argument is missing from the dictionary, then that row was not found in the table (and require_all_keys must have been False).

Raises:
  • IOError: An error occurred accessing the smalltable.
def fetch_smalltable_rows2( table_handle: Any, keys: Sequence[str], require_all_keys: bool = False) -> Mapping[bytes, Tuple[str]]:
352def fetch_smalltable_rows2(table_handle: Any,
353                          keys: Sequence[str],
354                          require_all_keys: bool = False,
355) -> Mapping[bytes, Tuple[str]]:
356    """Fetches rows from a Smalltable.
357
358    Retrieves rows pertaining to the given keys from the Table instance
359    represented by table_handle.  String keys will be UTF-8 encoded.
360
361    Args:
362      table_handle:
363        An open smalltable.Table instance.
364      keys:
365        A sequence of strings representing the key of each table row to
366        fetch.  String keys will be UTF-8 encoded.
367      require_all_keys:
368        Optional; If require_all_keys is True only rows with values set
369        for all keys will be returned.
370
371    Returns:
372      A dict mapping keys to the corresponding table row data
373      fetched. Each row is represented as a tuple of strings. For
374      example:
375
376      {b'Serak': ('Rigel VII', 'Preparer'),
377       b'Zim': ('Irk', 'Invader'),
378       b'Lrrr': ('Omicron Persei 8', 'Emperor')}
379
380      Returned keys are always bytes.  If a key from the keys argument is
381      missing from the dictionary, then that row was not found in the
382      table (and require_all_keys must have been False).
383
384    Raises:
385      IOError: An error occurred accessing the smalltable.
386    """
387    raise NotImplementedError

Fetches rows from a Smalltable.

Retrieves rows pertaining to the given keys from the Table instance represented by table_handle. String keys will be UTF-8 encoded.

Arguments:
  • table_handle: An open smalltable.Table instance.
  • keys: A sequence of strings representing the key of each table row to fetch. String keys will be UTF-8 encoded.
  • require_all_keys: Optional; If require_all_keys is True only rows with values set for all keys will be returned.
Returns:

A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example:

{b'Serak': ('Rigel VII', 'Preparer'), b'Zim': ('Irk', 'Invader'), b'Lrrr': ('Omicron Persei 8', 'Emperor')}

Returned keys are always bytes. If a key from the keys argument is missing from the dictionary, then that row was not found in the table (and require_all_keys must have been False).

Raises:
  • IOError: An error occurred accessing the smalltable.
class SampleClass:
390class SampleClass:
391    """Summary of class here.
392
393    Longer class information....
394    Longer class information....
395
396    Attributes:
397        likes_spam: A boolean indicating if we like SPAM or not.
398        eggs: An integer count of the eggs we have laid.
399    """
400
401    def __init__(self, likes_spam=False):
402        """Inits SampleClass with blah."""
403        self.likes_spam = likes_spam
404        self.eggs = 0
405
406    def public_method(self):
407        """Performs operation blah."""

Summary of class here.

Longer class information.... Longer class information....

Attributes:
  • likes_spam: A boolean indicating if we like SPAM or not.
  • eggs: An integer count of the eggs we have laid.
SampleClass(likes_spam=False)
401    def __init__(self, likes_spam=False):
402        """Inits SampleClass with blah."""
403        self.likes_spam = likes_spam
404        self.eggs = 0

Inits SampleClass with blah.

likes_spam
eggs
def public_method(self):
406    def public_method(self):
407        """Performs operation blah."""

Performs operation blah.

def invalid_format(test):
410def invalid_format(test):
411    """
412    In this example, there is no colon after the argument and an empty section.
413
414    Args:
415      test
416        there is a colon missing in the previous line
417    Returns:
418
419    """

In this example, there is no colon after the argument and an empty section.

Arguments:
  • test there is a colon missing in the previous line

Returns:

def example_code():
422def example_code():
423    """
424    Test case for https://github.com/mitmproxy/pdoc/issues/264.
425
426    Example:
427
428        ```python
429        tmp = a2()
430
431        tmp2 = a()
432        ```
433    """

Test case for https://github.com/mitmproxy/pdoc/issues/264.

Example:
tmp = a2()

tmp2 = a()
def newline_after_args(test: str):
436def newline_after_args(test: str):
437    """
438    Test case for https://github.com/mitmproxy/pdoc/pull/458.
439
440    Args:
441
442      test
443        there is unexpected whitespace before test.
444    """

Test case for https://github.com/mitmproxy/pdoc/pull/458.

Arguments:
  • test there is unexpected whitespace before test.
def alternative_section_names(test: str):
447def alternative_section_names(test: str):
448    """
449    In this example, we check whether alternative section names aliased to
450    'Args' are handled properly.
451
452    Parameters:
453        test: the test string
454    """

In this example, we check whether alternative section names aliased to 'Args' are handled properly.

Arguments:
  • test: the test string