flavors_google API documentation

# 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

View Source

      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): View Source

    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: View Source

    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): View Source

     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): View Source

    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): View Source

    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) View Source

    190    def __init__(self, msg, code):
    191        self.msg = msg
    192        self.code = code

msg
code
def add_note(self, note: str): View Source

    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, /): View Source

    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: View Source

    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) View Source

    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 View Source

    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 View Source

    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): View Source

    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]]: View Source

    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]]: View Source

    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: View Source

    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) View Source

    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): View Source

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

Performs operation blah.

def invalid_format(test): View Source

    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(): View Source

    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): View Source

    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): View Source

    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