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    def with_traceback(self, object, /):
197        """This method has a changed docstring in Python 3.13+ and is manually added here so that snapshots are consistent."""
198
199class ExampleClass(object):
200    """The summary line for a class docstring should fit on one line.
201
202    If the class has public attributes, they may be documented here
203    in an ``Attributes`` section and follow the same formatting as a
204    function's ``Args`` section. Alternatively, attributes may be documented
205    inline with the attribute's declaration (see __init__ method below).
206
207    Properties created with the ``@property`` decorator should be documented
208    in the property's getter method.
209
210    Attributes:
211        attr1 (str): Description of `attr1`.
212        attr2 (:obj:`int`, optional): Description of `attr2`.
213
214    """
215
216    def __init__(self, param1, param2, param3):
217        """Example of docstring on the __init__ method.
218
219        The __init__ method may be documented in either the class level
220        docstring, or as a docstring on the __init__ method itself.
221
222        Either form is acceptable, but the two should not be mixed. Choose one
223        convention to document the __init__ method and be consistent with it.
224
225        Note:
226            Do not include the `self` parameter in the ``Args`` section.
227
228        Args:
229            param1 (str): Description of `param1`.
230            param2 (:obj:`int`, optional): Description of `param2`. Multiple
231                lines are supported.
232            param3 (:obj:`list` of :obj:`str`): Description of `param3`.
233
234        """
235        self.attr1 = param1
236        self.attr2 = param2
237        self.attr3 = param3  #: Doc comment *inline* with attribute
238
239        #: list of str: Doc comment *before* attribute, with type specified
240        self.attr4 = ['attr4']
241
242        self.attr5 = None
243        """str: Docstring *after* attribute, with type specified."""
244
245    @property
246    def readonly_property(self):
247        """str: Properties should be documented in their getter method."""
248        return 'readonly_property'
249
250    @property
251    def readwrite_property(self):
252        """:obj:`list` of :obj:`str`: Properties with both a getter and setter
253        should only be documented in their getter method.
254
255        If the setter method contains notable behavior, it should be
256        mentioned here.
257        """
258        return ['readwrite_property']
259
260    @readwrite_property.setter
261    def readwrite_property(self, value):
262        value
263
264    def example_method(self, param1, param2):
265        """Class methods are similar to regular functions.
266
267        Note:
268            Do not include the `self` parameter in the ``Args`` section.
269
270        Args:
271            param1: The first parameter.
272            param2: The second parameter.
273
274        Returns:
275            True if successful, False otherwise.
276
277        """
278        return True
279
280    def __special__(self):
281        """By default special members with docstrings are not included.
282
283        Special members are any methods or attributes that start with and
284        end with a double underscore. Any special member with a docstring
285        will be included in the output, if
286        ``napoleon_include_special_with_doc`` is set to True.
287
288        This behavior can be enabled by changing the following setting in
289        Sphinx's conf.py::
290
291            napoleon_include_special_with_doc = True
292
293        """
294        pass
295
296    def __special_without_docstring__(self):
297        pass
298
299    def _private(self):
300        """By default private members are not included.
301
302        Private members are any methods or attributes that start with an
303        underscore and are *not* special. By default they are not included
304        in the output.
305
306        This behavior can be changed such that private members *are* included
307        by changing the following setting in Sphinx's conf.py::
308
309            napoleon_include_private_with_doc = True
310
311        """
312        pass
313
314    def _private_without_docstring(self):
315        pass
316
317
318def fetch_smalltable_rows(table_handle: Any,
319                          keys: Sequence[str],
320                          require_all_keys: bool = False,
321) -> Mapping[bytes, Tuple[str]]:
322    """Fetches rows from a Smalltable.
323
324    Retrieves rows pertaining to the given keys from the Table instance
325    represented by table_handle.  String keys will be UTF-8 encoded.
326
327    Args:
328        table_handle: An open smalltable.Table instance.
329        keys: A sequence of strings representing the key of each table
330          row to fetch.  String keys will be UTF-8 encoded.
331        require_all_keys: Optional; If require_all_keys is True only
332          rows with values set for all keys will be returned.
333
334    Returns:
335        A dict mapping keys to the corresponding table row data
336        fetched. Each row is represented as a tuple of strings. For
337        example:
338
339        {b'Serak': ('Rigel VII', 'Preparer'),
340         b'Zim': ('Irk', 'Invader'),
341         b'Lrrr': ('Omicron Persei 8', 'Emperor')}
342
343        Returned keys are always bytes.  If a key from the keys argument is
344        missing from the dictionary, then that row was not found in the
345        table (and require_all_keys must have been False).
346
347    Raises:
348        IOError: An error occurred accessing the smalltable.
349    """
350    raise NotImplementedError
351
352
353def fetch_smalltable_rows2(table_handle: Any,
354                          keys: Sequence[str],
355                          require_all_keys: bool = False,
356) -> Mapping[bytes, Tuple[str]]:
357    """Fetches rows from a Smalltable.
358
359    Retrieves rows pertaining to the given keys from the Table instance
360    represented by table_handle.  String keys will be UTF-8 encoded.
361
362    Args:
363      table_handle:
364        An open smalltable.Table instance.
365      keys:
366        A sequence of strings representing the key of each table row to
367        fetch.  String keys will be UTF-8 encoded.
368      require_all_keys:
369        Optional; If require_all_keys is True only rows with values set
370        for all keys will be returned.
371
372    Returns:
373      A dict mapping keys to the corresponding table row data
374      fetched. Each row is represented as a tuple of strings. For
375      example:
376
377      {b'Serak': ('Rigel VII', 'Preparer'),
378       b'Zim': ('Irk', 'Invader'),
379       b'Lrrr': ('Omicron Persei 8', 'Emperor')}
380
381      Returned keys are always bytes.  If a key from the keys argument is
382      missing from the dictionary, then that row was not found in the
383      table (and require_all_keys must have been False).
384
385    Raises:
386      IOError: An error occurred accessing the smalltable.
387    """
388    raise NotImplementedError
389
390
391class SampleClass:
392    """Summary of class here.
393
394    Longer class information....
395    Longer class information....
396
397    Attributes:
398        likes_spam: A boolean indicating if we like SPAM or not.
399        eggs: An integer count of the eggs we have laid.
400    """
401
402    def __init__(self, likes_spam=False):
403        """Inits SampleClass with blah."""
404        self.likes_spam = likes_spam
405        self.eggs = 0
406
407    def public_method(self):
408        """Performs operation blah."""
409
410
411def invalid_format(test):
412    """
413    In this example, there is no colon after the argument and an empty section.
414
415    Args:
416      test
417        there is a colon missing in the previous line
418    Returns:
419
420    """
421
422
423def example_code():
424    """
425    Test case for https://github.com/mitmproxy/pdoc/issues/264.
426
427    Example:
428
429        ```python
430        tmp = a2()
431
432        tmp2 = a()
433        ```
434    """
435
436
437def newline_after_args(test: str):
438    """
439    Test case for https://github.com/mitmproxy/pdoc/pull/458.
440
441    Args:
442
443      test
444        there is unexpected whitespace before test.
445    """
446
447
448def alternative_section_names(test: str):
449    """
450    In this example, we check whether alternative section names aliased to
451    'Args' are handled properly.
452
453    Parameters:
454        test: the test string
455    """
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."""
196
197    def with_traceback(self, object, /):
198        """This method has a changed docstring in Python 3.13+ and is 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.

def with_traceback(self, object, /):
197    def with_traceback(self, object, /):
198        """This method has a changed docstring in Python 3.13+ and is manually added here so that snapshots are consistent."""

This method has a changed docstring in Python 3.13+ and is manually added here so that snapshots are consistent.

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

str: Properties should be documented in their getter method.

readwrite_property
251    @property
252    def readwrite_property(self):
253        """:obj:`list` of :obj:`str`: Properties with both a getter and setter
254        should only be documented in their getter method.
255
256        If the setter method contains notable behavior, it should be
257        mentioned here.
258        """
259        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):
265    def example_method(self, param1, param2):
266        """Class methods are similar to regular functions.
267
268        Note:
269            Do not include the `self` parameter in the ``Args`` section.
270
271        Args:
272            param1: The first parameter.
273            param2: The second parameter.
274
275        Returns:
276            True if successful, False otherwise.
277
278        """
279        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]]:
319def fetch_smalltable_rows(table_handle: Any,
320                          keys: Sequence[str],
321                          require_all_keys: bool = False,
322) -> Mapping[bytes, Tuple[str]]:
323    """Fetches rows from a Smalltable.
324
325    Retrieves rows pertaining to the given keys from the Table instance
326    represented by table_handle.  String keys will be UTF-8 encoded.
327
328    Args:
329        table_handle: An open smalltable.Table instance.
330        keys: A sequence of strings representing the key of each table
331          row to fetch.  String keys will be UTF-8 encoded.
332        require_all_keys: Optional; If require_all_keys is True only
333          rows with values set for all keys will be returned.
334
335    Returns:
336        A dict mapping keys to the corresponding table row data
337        fetched. Each row is represented as a tuple of strings. For
338        example:
339
340        {b'Serak': ('Rigel VII', 'Preparer'),
341         b'Zim': ('Irk', 'Invader'),
342         b'Lrrr': ('Omicron Persei 8', 'Emperor')}
343
344        Returned keys are always bytes.  If a key from the keys argument is
345        missing from the dictionary, then that row was not found in the
346        table (and require_all_keys must have been False).
347
348    Raises:
349        IOError: An error occurred accessing the smalltable.
350    """
351    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]]:
354def fetch_smalltable_rows2(table_handle: Any,
355                          keys: Sequence[str],
356                          require_all_keys: bool = False,
357) -> Mapping[bytes, Tuple[str]]:
358    """Fetches rows from a Smalltable.
359
360    Retrieves rows pertaining to the given keys from the Table instance
361    represented by table_handle.  String keys will be UTF-8 encoded.
362
363    Args:
364      table_handle:
365        An open smalltable.Table instance.
366      keys:
367        A sequence of strings representing the key of each table row to
368        fetch.  String keys will be UTF-8 encoded.
369      require_all_keys:
370        Optional; If require_all_keys is True only rows with values set
371        for all keys will be returned.
372
373    Returns:
374      A dict mapping keys to the corresponding table row data
375      fetched. Each row is represented as a tuple of strings. For
376      example:
377
378      {b'Serak': ('Rigel VII', 'Preparer'),
379       b'Zim': ('Irk', 'Invader'),
380       b'Lrrr': ('Omicron Persei 8', 'Emperor')}
381
382      Returned keys are always bytes.  If a key from the keys argument is
383      missing from the dictionary, then that row was not found in the
384      table (and require_all_keys must have been False).
385
386    Raises:
387      IOError: An error occurred accessing the smalltable.
388    """
389    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:
392class SampleClass:
393    """Summary of class here.
394
395    Longer class information....
396    Longer class information....
397
398    Attributes:
399        likes_spam: A boolean indicating if we like SPAM or not.
400        eggs: An integer count of the eggs we have laid.
401    """
402
403    def __init__(self, likes_spam=False):
404        """Inits SampleClass with blah."""
405        self.likes_spam = likes_spam
406        self.eggs = 0
407
408    def public_method(self):
409        """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)
403    def __init__(self, likes_spam=False):
404        """Inits SampleClass with blah."""
405        self.likes_spam = likes_spam
406        self.eggs = 0

Inits SampleClass with blah.

likes_spam
eggs
def public_method(self):
408    def public_method(self):
409        """Performs operation blah."""

Performs operation blah.

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

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():
424def example_code():
425    """
426    Test case for https://github.com/mitmproxy/pdoc/issues/264.
427
428    Example:
429
430        ```python
431        tmp = a2()
432
433        tmp2 = a()
434        ```
435    """

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

Example:
tmp = a2()

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

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

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

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

Arguments:
  • test: the test string