\nflavors_google
\n\nExample Google style docstrings.
\n\nThis module demonstrates documentation as specified by the Google Python\nStyle Guide. Docstrings may extend over multiple lines. Sections are created\nwith a section header and a colon followed by a block of indented text.
\n\nExample:
\n\n\n\n\nExamples can be given using either the
\n\nExampleorExamples\n sections. Sections support any reStructuredText formatting, including\n literal blocks::\n$ python example_google.py\n
Section breaks are created by resuming unindented text. Section breaks\nare also implicitly created anytime a new section starts.
\n\nAttributes:
\n\n- \n
module_level_variable1 (int): Module level variables may be documented in\neither the
\n\nAttributessection of the module docstring, or in an\ninline docstring immediately following the variable.Either form is acceptable, but the two should not be mixed. Choose\none convention to document module level variables and be consistent\nwith it.
\n
Todo:
\n\n\n\n\n
\n- For module TODOs
\n- You have to also use
\nsphinx.ext.todoextension
1# Examples taken from:\n 2#\n 3# - The Napoleon documentation at https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html\n 4# License: BSD-3\n 5# - The Google Style Guide at https://google.github.io/styleguide/pyguide.html\n 6# License: CC BY 3.0\n 7#\n 8# flake8: noqa\n 9# fmt: off\n 10"""Example Google style docstrings.\n 11\n 12This module demonstrates documentation as specified by the `Google Python\n 13Style Guide`_. Docstrings may extend over multiple lines. Sections are created\n 14with a section header and a colon followed by a block of indented text.\n 15\n 16Example:\n 17 Examples can be given using either the ``Example`` or ``Examples``\n 18 sections. Sections support any reStructuredText formatting, including\n 19 literal blocks::\n 20\n 21 $ python example_google.py\n 22\n 23Section breaks are created by resuming unindented text. Section breaks\n 24are also implicitly created anytime a new section starts.\n 25\n 26Attributes:\n 27 module_level_variable1 (int): Module level variables may be documented in\n 28 either the ``Attributes`` section of the module docstring, or in an\n 29 inline docstring immediately following the variable.\n 30\n 31 Either form is acceptable, but the two should not be mixed. Choose\n 32 one convention to document module level variables and be consistent\n 33 with it.\n 34\n 35Todo:\n 36 * For module TODOs\n 37 * You have to also use ``sphinx.ext.todo`` extension\n 38\n 39.. _Google Python Style Guide:\n 40 http://google.github.io/styleguide/pyguide.html\n 41\n 42"""\n 43__docformat__ = "google"\n 44\n 45from typing import Any, Mapping, Sequence, Tuple\n 46\n 47\n 48module_level_variable1 = 12345\n 49\n 50module_level_variable2 = 98765\n 51"""int: Module level variable documented inline.\n 52\n 53The docstring may span multiple lines. The type may optionally be specified\n 54on the first line, separated by a colon.\n 55"""\n 56\n 57\n 58def function_with_types_in_docstring(param1, param2):\n 59 """Example function with types documented in the docstring.\n 60\n 61 `PEP 484`_ type annotations are supported. If attribute, parameter, and\n 62 return types are annotated according to `PEP 484`_, they do not need to be\n 63 included in the docstring:\n 64\n 65 Args:\n 66 param1 (int): The first parameter.\n 67 param2 (str): The second parameter.\n 68\n 69 Returns:\n 70 bool: The return value. True for success, False otherwise.\n 71\n 72 .. _PEP 484:\n 73 https://www.python.org/dev/peps/pep-0484/\n 74\n 75 """\n 76\n 77\n 78def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:\n 79 """Example function with PEP 484 type annotations.\n 80\n 81 Args:\n 82 param1: The first parameter.\n 83 param2: The second parameter.\n 84\n 85 Returns:\n 86 The return value. True for success, False otherwise.\n 87\n 88 """\n 89 raise NotImplementedError\n 90\n 91\n 92def module_level_function(param1, param2=None, *args, **kwargs):\n 93 """This is an example of a module level function.\n 94\n 95 Function parameters should be documented in the ``Args`` section. The name\n 96 of each parameter is required. The type and description of each parameter\n 97 is optional, but should be included if not obvious.\n 98\n 99 If *args or **kwargs are accepted,\n100 they should be listed as ``*args`` and ``**kwargs``.\n101\n102 The format for a parameter is::\n103\n104 name (type): description\n105 The description may span multiple lines. Following\n106 lines should be indented. The "(type)" is optional.\n107\n108 Multiple paragraphs are supported in parameter\n109 descriptions.\n110\n111 Args:\n112 param1 (int): The first parameter.\n113 param2 (:obj:`str`, optional): The second parameter. Defaults to None.\n114 Second line of description should be indented.\n115 *args: Variable length argument list.\n116 **kwargs: Arbitrary keyword arguments.\n117\n118 Returns:\n119 bool: True if successful, False otherwise.\n120\n121 The return type is optional and may be specified at the beginning of\n122 the ``Returns`` section followed by a colon.\n123\n124 The ``Returns`` section may span multiple lines and paragraphs.\n125 Following lines should be indented to match the first line.\n126\n127 The ``Returns`` section supports any reStructuredText formatting,\n128 including literal blocks::\n129\n130 {\n131 'param1': param1,\n132 'param2': param2\n133 }\n134\n135 Raises:\n136 AttributeError: The ``Raises`` section is a list of all exceptions\n137 that are relevant to the interface.\n138 ValueError: If `param2` is equal to `param1`.\n139\n140 """\n141 if param1 == param2:\n142 raise ValueError('param1 may not be equal to param2')\n143 return True\n144\n145\n146def example_generator(n):\n147 """Generators have a ``Yields`` section instead of a ``Returns`` section.\n148\n149 Args:\n150 n (int): The upper limit of the range to generate, from 0 to `n` - 1.\n151\n152 Yields:\n153 int: The next number in the range of 0 to `n` - 1.\n154\n155 Examples:\n156 Examples should be written in doctest format, and should illustrate how\n157 to use the function.\n158\n159 >>> print([i for i in example_generator(4)])\n160 [0, 1, 2, 3]\n161\n162 """\n163 for i in range(n):\n164 yield i\n165\n166\n167class ExampleError(Exception):\n168 """Exceptions are documented in the same way as classes.\n169\n170 The __init__ method may be documented in either the class level\n171 docstring, or as a docstring on the __init__ method itself.\n172\n173 Either form is acceptable, but the two should not be mixed. Choose one\n174 convention to document the __init__ method and be consistent with it.\n175\n176 Note:\n177 Do not include the `self` parameter in the ``Args`` section.\n178\n179 Args:\n180 msg (str): Human readable string describing the exception.\n181 code (:obj:`int`, optional): Error code.\n182\n183 Attributes:\n184 msg (str): Human readable string describing the exception.\n185 code (int): Exception error code.\n186\n187 """\n188\n189 def __init__(self, msg, code):\n190 self.msg = msg\n191 self.code = code\n192\n193 def add_note(self, note: str):\n194 """This method is present on Python 3.11+ and manually added here so that snapshots are consistent."""\n195\n196 def with_traceback(self, object, /):\n197 """This method has a changed docstring in Python 3.13+ and is manually added here so that snapshots are consistent."""\n198\n199class ExampleClass(object):\n200 """The summary line for a class docstring should fit on one line.\n201\n202 If the class has public attributes, they may be documented here\n203 in an ``Attributes`` section and follow the same formatting as a\n204 function's ``Args`` section. Alternatively, attributes may be documented\n205 inline with the attribute's declaration (see __init__ method below).\n206\n207 Properties created with the ``@property`` decorator should be documented\n208 in the property's getter method.\n209\n210 Attributes:\n211 attr1 (str): Description of `attr1`.\n212 attr2 (:obj:`int`, optional): Description of `attr2`.\n213\n214 """\n215\n216 def __init__(self, param1, param2, param3):\n217 """Example of docstring on the __init__ method.\n218\n219 The __init__ method may be documented in either the class level\n220 docstring, or as a docstring on the __init__ method itself.\n221\n222 Either form is acceptable, but the two should not be mixed. Choose one\n223 convention to document the __init__ method and be consistent with it.\n224\n225 Note:\n226 Do not include the `self` parameter in the ``Args`` section.\n227\n228 Args:\n229 param1 (str): Description of `param1`.\n230 param2 (:obj:`int`, optional): Description of `param2`. Multiple\n231 lines are supported.\n232 param3 (:obj:`list` of :obj:`str`): Description of `param3`.\n233\n234 """\n235 self.attr1 = param1\n236 self.attr2 = param2\n237 self.attr3 = param3 #: Doc comment *inline* with attribute\n238\n239 #: list of str: Doc comment *before* attribute, with type specified\n240 self.attr4 = ['attr4']\n241\n242 self.attr5 = None\n243 """str: Docstring *after* attribute, with type specified."""\n244\n245 @property\n246 def readonly_property(self):\n247 """str: Properties should be documented in their getter method."""\n248 return 'readonly_property'\n249\n250 @property\n251 def readwrite_property(self):\n252 """:obj:`list` of :obj:`str`: Properties with both a getter and setter\n253 should only be documented in their getter method.\n254\n255 If the setter method contains notable behavior, it should be\n256 mentioned here.\n257 """\n258 return ['readwrite_property']\n259\n260 @readwrite_property.setter\n261 def readwrite_property(self, value):\n262 value\n263\n264 def example_method(self, param1, param2):\n265 """Class methods are similar to regular functions.\n266\n267 Note:\n268 Do not include the `self` parameter in the ``Args`` section.\n269\n270 Args:\n271 param1: The first parameter.\n272 param2: The second parameter.\n273\n274 Returns:\n275 True if successful, False otherwise.\n276\n277 """\n278 return True\n279\n280 def __special__(self):\n281 """By default special members with docstrings are not included.\n282\n283 Special members are any methods or attributes that start with and\n284 end with a double underscore. Any special member with a docstring\n285 will be included in the output, if\n286 ``napoleon_include_special_with_doc`` is set to True.\n287\n288 This behavior can be enabled by changing the following setting in\n289 Sphinx's conf.py::\n290\n291 napoleon_include_special_with_doc = True\n292\n293 """\n294 pass\n295\n296 def __special_without_docstring__(self):\n297 pass\n298\n299 def _private(self):\n300 """By default private members are not included.\n301\n302 Private members are any methods or attributes that start with an\n303 underscore and are *not* special. By default they are not included\n304 in the output.\n305\n306 This behavior can be changed such that private members *are* included\n307 by changing the following setting in Sphinx's conf.py::\n308\n309 napoleon_include_private_with_doc = True\n310\n311 """\n312 pass\n313\n314 def _private_without_docstring(self):\n315 pass\n316\n317\n318def fetch_smalltable_rows(table_handle: Any,\n319 keys: Sequence[str],\n320 require_all_keys: bool = False,\n321) -> Mapping[bytes, Tuple[str]]:\n322 """Fetches rows from a Smalltable.\n323\n324 Retrieves rows pertaining to the given keys from the Table instance\n325 represented by table_handle. String keys will be UTF-8 encoded.\n326\n327 Args:\n328 table_handle: An open smalltable.Table instance.\n329 keys: A sequence of strings representing the key of each table\n330 row to fetch. String keys will be UTF-8 encoded.\n331 require_all_keys: Optional; If require_all_keys is True only\n332 rows with values set for all keys will be returned.\n333\n334 Returns:\n335 A dict mapping keys to the corresponding table row data\n336 fetched. Each row is represented as a tuple of strings. For\n337 example:\n338\n339 {b'Serak': ('Rigel VII', 'Preparer'),\n340 b'Zim': ('Irk', 'Invader'),\n341 b'Lrrr': ('Omicron Persei 8', 'Emperor')}\n342\n343 Returned keys are always bytes. If a key from the keys argument is\n344 missing from the dictionary, then that row was not found in the\n345 table (and require_all_keys must have been False).\n346\n347 Raises:\n348 IOError: An error occurred accessing the smalltable.\n349 """\n350 raise NotImplementedError\n351\n352\n353def fetch_smalltable_rows2(table_handle: Any,\n354 keys: Sequence[str],\n355 require_all_keys: bool = False,\n356) -> Mapping[bytes, Tuple[str]]:\n357 """Fetches rows from a Smalltable.\n358\n359 Retrieves rows pertaining to the given keys from the Table instance\n360 represented by table_handle. String keys will be UTF-8 encoded.\n361\n362 Args:\n363 table_handle:\n364 An open smalltable.Table instance.\n365 keys:\n366 A sequence of strings representing the key of each table row to\n367 fetch. String keys will be UTF-8 encoded.\n368 require_all_keys:\n369 Optional; If require_all_keys is True only rows with values set\n370 for all keys will be returned.\n371\n372 Returns:\n373 A dict mapping keys to the corresponding table row data\n374 fetched. Each row is represented as a tuple of strings. For\n375 example:\n376\n377 {b'Serak': ('Rigel VII', 'Preparer'),\n378 b'Zim': ('Irk', 'Invader'),\n379 b'Lrrr': ('Omicron Persei 8', 'Emperor')}\n380\n381 Returned keys are always bytes. If a key from the keys argument is\n382 missing from the dictionary, then that row was not found in the\n383 table (and require_all_keys must have been False).\n384\n385 Raises:\n386 IOError: An error occurred accessing the smalltable.\n387 """\n388 raise NotImplementedError\n389\n390\n391class SampleClass:\n392 """Summary of class here.\n393\n394 Longer class information....\n395 Longer class information....\n396\n397 Attributes:\n398 likes_spam: A boolean indicating if we like SPAM or not.\n399 eggs: An integer count of the eggs we have laid.\n400 """\n401\n402 def __init__(self, likes_spam=False):\n403 """Inits SampleClass with blah."""\n404 self.likes_spam = likes_spam\n405 self.eggs = 0\n406\n407 def public_method(self):\n408 """Performs operation blah."""\n409\n410\n411def invalid_format(test):\n412 """\n413 In this example, there is no colon after the argument and an empty section.\n414\n415 Args:\n416 test\n417 there is a colon missing in the previous line\n418 Returns:\n419\n420 """\n421\n422\n423def example_code():\n424 """\n425 Test case for https://github.com/mitmproxy/pdoc/issues/264.\n426\n427 Example:\n428\n429 ```python\n430 tmp = a2()\n431\n432 tmp2 = a()\n433 ```\n434 """\n435\n436\n437def newline_after_args(test: str):\n438 """\n439 Test case for https://github.com/mitmproxy/pdoc/pull/458.\n440\n441 Args:\n442\n443 test\n444 there is unexpected whitespace before test.\n445 """\n446\n447\n448def alternative_section_names(test: str):\n449 """\n450 In this example, we check whether alternative section names aliased to\n451 'Args' are handled properly.\n452\n453 Parameters:\n454 test: the test string\n455 """\n456\n457def keyword_arguments(**kwargs):\n458 """\n459 This an example for a function with keyword arguments documented in the docstring.\n460\n461 Args:\n462 **kwargs: A dictionary containing user info.\n463\n464 Keyword Arguments:\n465 str_arg (str): First string argument.\n466 int_arg (int): Second integer argument.\n467 """\n
\n module_level_variable1 =\n12345\n\n \n
\n \n \n \n\n \n module_level_variable2 =\n98765\n\n \n
\n \n \n int: Module level variable documented inline.
\n\nThe docstring may span multiple lines. The type may optionally be specified\non the first line, separated by a colon.
\n\n \n def\n function_with_types_in_docstring(param1, param2):\n\n \n\n
\n \n 59def function_with_types_in_docstring(param1, param2):\n60 """Example function with types documented in the docstring.\n61\n62 `PEP 484`_ type annotations are supported. If attribute, parameter, and\n63 return types are annotated according to `PEP 484`_, they do not need to be\n64 included in the docstring:\n65\n66 Args:\n67 param1 (int): The first parameter.\n68 param2 (str): The second parameter.\n69\n70 Returns:\n71 bool: The return value. True for success, False otherwise.\n72\n73 .. _PEP 484:\n74 https://www.python.org/dev/peps/pep-0484/\n75\n76 """\n
Example function with types documented in the docstring.
\n\nPEP 484 type annotations are supported. If attribute, parameter, and\nreturn types are annotated according to PEP 484, they do not need to be\nincluded in the docstring:
\n\nArguments:
\n\n- \n
- param1 (int): The first parameter. \n
- param2 (str): The second parameter. \n
Returns:
\n\n\n\nbool: The return value. True for success, False otherwise.
\n
\n \n def\n function_with_pep484_type_annotations(param1: int, param2: str) -> bool:\n\n \n\n
\n \n 79def function_with_pep484_type_annotations(param1: int, param2: str) -> bool:\n80 """Example function with PEP 484 type annotations.\n81\n82 Args:\n83 param1: The first parameter.\n84 param2: The second parameter.\n85\n86 Returns:\n87 The return value. True for success, False otherwise.\n88\n89 """\n90 raise NotImplementedError\n
Example function with PEP 484 type annotations.
\n\nArguments:
\n\n- \n
- param1: The first parameter. \n
- param2: The second parameter. \n
Returns:
\n\n\n\nThe return value. True for success, False otherwise.
\n
\n \n def\n module_level_function(param1, param2=None, *args, **kwargs):\n\n \n\n
\n \n 93def module_level_function(param1, param2=None, *args, **kwargs):\n 94 """This is an example of a module level function.\n 95\n 96 Function parameters should be documented in the ``Args`` section. The name\n 97 of each parameter is required. The type and description of each parameter\n 98 is optional, but should be included if not obvious.\n 99\n100 If *args or **kwargs are accepted,\n101 they should be listed as ``*args`` and ``**kwargs``.\n102\n103 The format for a parameter is::\n104\n105 name (type): description\n106 The description may span multiple lines. Following\n107 lines should be indented. The "(type)" is optional.\n108\n109 Multiple paragraphs are supported in parameter\n110 descriptions.\n111\n112 Args:\n113 param1 (int): The first parameter.\n114 param2 (:obj:`str`, optional): The second parameter. Defaults to None.\n115 Second line of description should be indented.\n116 *args: Variable length argument list.\n117 **kwargs: Arbitrary keyword arguments.\n118\n119 Returns:\n120 bool: True if successful, False otherwise.\n121\n122 The return type is optional and may be specified at the beginning of\n123 the ``Returns`` section followed by a colon.\n124\n125 The ``Returns`` section may span multiple lines and paragraphs.\n126 Following lines should be indented to match the first line.\n127\n128 The ``Returns`` section supports any reStructuredText formatting,\n129 including literal blocks::\n130\n131 {\n132 'param1': param1,\n133 'param2': param2\n134 }\n135\n136 Raises:\n137 AttributeError: The ``Raises`` section is a list of all exceptions\n138 that are relevant to the interface.\n139 ValueError: If `param2` is equal to `param1`.\n140\n141 """\n142 if param1 == param2:\n143 raise ValueError('param1 may not be equal to param2')\n144 return True\n
This is an example of a module level function.
\n\nFunction parameters should be documented in the Args section. The name\nof each parameter is required. The type and description of each parameter\nis optional, but should be included if not obvious.
If *args or **kwargs are accepted,\nthey should be listed as *args and **kwargs.
The format for a parameter is::
\n\nname (type): description\n The description may span multiple lines. Following\n lines should be indented. The "(type)" is optional.\n\n Multiple paragraphs are supported in parameter\n descriptions.\nArguments:
\n\n- \n
- param1 (int): The first parameter. \n
- param2 (
str, optional): The second parameter. Defaults to None.\nSecond line of description should be indented. \n - *args: Variable length argument list. \n
- **kwargs: Arbitrary keyword arguments. \n
Returns:
\n\n\n\n\nbool: True if successful, False otherwise.
\n \nThe return type is optional and may be specified at the beginning of\n the
\n \nReturnssection followed by a colon.The
\n \nReturnssection may span multiple lines and paragraphs.\n Following lines should be indented to match the first line.The
\n\nReturnssection supports any reStructuredText formatting,\n including literal blocks::\n{\n \'param1\': param1,\n \'param2\': param2\n}\n
Raises:
\n\n- \n
- AttributeError: The
Raisessection is a list of all exceptions\nthat are relevant to the interface. \n - ValueError: If
param2is equal toparam1. \n
\n \n def\n example_generator(n):\n\n \n\n
\n \n 147def example_generator(n):\n148 """Generators have a ``Yields`` section instead of a ``Returns`` section.\n149\n150 Args:\n151 n (int): The upper limit of the range to generate, from 0 to `n` - 1.\n152\n153 Yields:\n154 int: The next number in the range of 0 to `n` - 1.\n155\n156 Examples:\n157 Examples should be written in doctest format, and should illustrate how\n158 to use the function.\n159\n160 >>> print([i for i in example_generator(4)])\n161 [0, 1, 2, 3]\n162\n163 """\n164 for i in range(n):\n165 yield i\n
Generators have a Yields section instead of a Returns section.
Arguments:
\n\n- \n
- n (int): The upper limit of the range to generate, from 0 to
n- 1. \n
Yields:
\n\n\n\n\nint: The next number in the range of 0 to
\nn- 1.
Examples:
\n\n\n\nExamples should be written in doctest format, and should illustrate how\n to use the function.
\n \n\n\n\n>>> print([i for i in example_generator(4)])\n[0, 1, 2, 3]\n
\n \n class\n ExampleError(builtins.Exception):\n\n \n\n
\n \n 168class ExampleError(Exception):\n169 """Exceptions are documented in the same way as classes.\n170\n171 The __init__ method may be documented in either the class level\n172 docstring, or as a docstring on the __init__ method itself.\n173\n174 Either form is acceptable, but the two should not be mixed. Choose one\n175 convention to document the __init__ method and be consistent with it.\n176\n177 Note:\n178 Do not include the `self` parameter in the ``Args`` section.\n179\n180 Args:\n181 msg (str): Human readable string describing the exception.\n182 code (:obj:`int`, optional): Error code.\n183\n184 Attributes:\n185 msg (str): Human readable string describing the exception.\n186 code (int): Exception error code.\n187\n188 """\n189\n190 def __init__(self, msg, code):\n191 self.msg = msg\n192 self.code = code\n193\n194 def add_note(self, note: str):\n195 """This method is present on Python 3.11+ and manually added here so that snapshots are consistent."""\n196\n197 def with_traceback(self, object, /):\n198 """This method has a changed docstring in Python 3.13+ and is manually added here so that snapshots are consistent."""\n
Exceptions are documented in the same way as classes.
\n\nThe __init__ method may be documented in either the class level\ndocstring, or as a docstring on the __init__ method itself.
\n\nEither form is acceptable, but the two should not be mixed. Choose one\nconvention to document the __init__ method and be consistent with it.
\n\nNote:
\n\n\n\n\nDo not include the
\nselfparameter in theArgssection.
Arguments:
\n\n- \n
- msg (str): Human readable string describing the exception. \n
- code (
int, optional): Error code. \n
Attributes:
\n\n- \n
- msg (str): Human readable string describing the exception. \n
- code (int): Exception error code. \n
\n \n\n\n\n \n\n\n
\n \n \n def\n add_note(self, note: str):\n\n \n\n
\n \n 194 def add_note(self, note: str):\n195 """This method is present on Python 3.11+ and manually added here so that snapshots are consistent."""\n
This method is present on Python 3.11+ and manually added here so that snapshots are consistent.
\n\n \n\n\n\n \n\n\n
\n \n \n def\n with_traceback(self, object, /):\n\n \n\n
\n \n 197 def with_traceback(self, object, /):\n198 """This method has a changed docstring in Python 3.13+ and is manually added here so that snapshots are consistent."""\n
This method has a changed docstring in Python 3.13+ and is manually added here so that snapshots are consistent.
\n\n \n class\n ExampleClass:\n\n \n\n
\n \n 200class ExampleClass(object):\n201 """The summary line for a class docstring should fit on one line.\n202\n203 If the class has public attributes, they may be documented here\n204 in an ``Attributes`` section and follow the same formatting as a\n205 function's ``Args`` section. Alternatively, attributes may be documented\n206 inline with the attribute's declaration (see __init__ method below).\n207\n208 Properties created with the ``@property`` decorator should be documented\n209 in the property's getter method.\n210\n211 Attributes:\n212 attr1 (str): Description of `attr1`.\n213 attr2 (:obj:`int`, optional): Description of `attr2`.\n214\n215 """\n216\n217 def __init__(self, param1, param2, param3):\n218 """Example of docstring on the __init__ method.\n219\n220 The __init__ method may be documented in either the class level\n221 docstring, or as a docstring on the __init__ method itself.\n222\n223 Either form is acceptable, but the two should not be mixed. Choose one\n224 convention to document the __init__ method and be consistent with it.\n225\n226 Note:\n227 Do not include the `self` parameter in the ``Args`` section.\n228\n229 Args:\n230 param1 (str): Description of `param1`.\n231 param2 (:obj:`int`, optional): Description of `param2`. Multiple\n232 lines are supported.\n233 param3 (:obj:`list` of :obj:`str`): Description of `param3`.\n234\n235 """\n236 self.attr1 = param1\n237 self.attr2 = param2\n238 self.attr3 = param3 #: Doc comment *inline* with attribute\n239\n240 #: list of str: Doc comment *before* attribute, with type specified\n241 self.attr4 = ['attr4']\n242\n243 self.attr5 = None\n244 """str: Docstring *after* attribute, with type specified."""\n245\n246 @property\n247 def readonly_property(self):\n248 """str: Properties should be documented in their getter method."""\n249 return 'readonly_property'\n250\n251 @property\n252 def readwrite_property(self):\n253 """:obj:`list` of :obj:`str`: Properties with both a getter and setter\n254 should only be documented in their getter method.\n255\n256 If the setter method contains notable behavior, it should be\n257 mentioned here.\n258 """\n259 return ['readwrite_property']\n260\n261 @readwrite_property.setter\n262 def readwrite_property(self, value):\n263 value\n264\n265 def example_method(self, param1, param2):\n266 """Class methods are similar to regular functions.\n267\n268 Note:\n269 Do not include the `self` parameter in the ``Args`` section.\n270\n271 Args:\n272 param1: The first parameter.\n273 param2: The second parameter.\n274\n275 Returns:\n276 True if successful, False otherwise.\n277\n278 """\n279 return True\n280\n281 def __special__(self):\n282 """By default special members with docstrings are not included.\n283\n284 Special members are any methods or attributes that start with and\n285 end with a double underscore. Any special member with a docstring\n286 will be included in the output, if\n287 ``napoleon_include_special_with_doc`` is set to True.\n288\n289 This behavior can be enabled by changing the following setting in\n290 Sphinx's conf.py::\n291\n292 napoleon_include_special_with_doc = True\n293\n294 """\n295 pass\n296\n297 def __special_without_docstring__(self):\n298 pass\n299\n300 def _private(self):\n301 """By default private members are not included.\n302\n303 Private members are any methods or attributes that start with an\n304 underscore and are *not* special. By default they are not included\n305 in the output.\n306\n307 This behavior can be changed such that private members *are* included\n308 by changing the following setting in Sphinx's conf.py::\n309\n310 napoleon_include_private_with_doc = True\n311\n312 """\n313 pass\n314\n315 def _private_without_docstring(self):\n316 pass\n
The summary line for a class docstring should fit on one line.
\n\nIf the class has public attributes, they may be documented here\nin an Attributes section and follow the same formatting as a\nfunction\'s Args section. Alternatively, attributes may be documented\ninline with the attribute\'s declaration (see __init__ method below).
Properties created with the @property decorator should be documented\nin the property\'s getter method.
Attributes:
\n\n\n\n \n\n\n\n \n\n\n
\n \n \n \n \n \n \n \n ExampleClass(param1, param2, param3)\n\n \n\n
\n \n 217 def __init__(self, param1, param2, param3):\n218 """Example of docstring on the __init__ method.\n219\n220 The __init__ method may be documented in either the class level\n221 docstring, or as a docstring on the __init__ method itself.\n222\n223 Either form is acceptable, but the two should not be mixed. Choose one\n224 convention to document the __init__ method and be consistent with it.\n225\n226 Note:\n227 Do not include the `self` parameter in the ``Args`` section.\n228\n229 Args:\n230 param1 (str): Description of `param1`.\n231 param2 (:obj:`int`, optional): Description of `param2`. Multiple\n232 lines are supported.\n233 param3 (:obj:`list` of :obj:`str`): Description of `param3`.\n234\n235 """\n236 self.attr1 = param1\n237 self.attr2 = param2\n238 self.attr3 = param3 #: Doc comment *inline* with attribute\n239\n240 #: list of str: Doc comment *before* attribute, with type specified\n241 self.attr4 = ['attr4']\n242\n243 self.attr5 = None\n244 """str: Docstring *after* attribute, with type specified."""\n
Example of docstring on the __init__ method.
\n\nThe __init__ method may be documented in either the class level\ndocstring, or as a docstring on the __init__ method itself.
\n\nEither form is acceptable, but the two should not be mixed. Choose one\nconvention to document the __init__ method and be consistent with it.
\n\nNote:
\n\n\n\n\nDo not include the
\nselfparameter in theArgssection.
Arguments:
\n\n- \n
- param1 (str): Description of
param1. \n - param2 (
int, optional): Description ofparam2. Multiple\nlines are supported. \n - param3 (
listofstr): Description ofparam3. \n
\n \n\n\n\n \n\n\n
\n \n readonly_property\n\n \n\n
\n \n 246 @property\n247 def readonly_property(self):\n248 """str: Properties should be documented in their getter method."""\n249 return 'readonly_property'\n
str: Properties should be documented in their getter method.
\n\n \n\n\n\n \n\n\n
\n \n readwrite_property\n\n \n\n
\n \n 251 @property\n252 def readwrite_property(self):\n253 """:obj:`list` of :obj:`str`: Properties with both a getter and setter\n254 should only be documented in their getter method.\n255\n256 If the setter method contains notable behavior, it should be\n257 mentioned here.\n258 """\n259 return ['readwrite_property']\n
list of str: Properties with both a getter and setter\nshould only be documented in their getter method.
If the setter method contains notable behavior, it should be\nmentioned here.
\n\n \n\n\n\n \n\n\n
\n \n \n def\n example_method(self, param1, param2):\n\n \n\n
\n \n 265 def example_method(self, param1, param2):\n266 """Class methods are similar to regular functions.\n267\n268 Note:\n269 Do not include the `self` parameter in the ``Args`` section.\n270\n271 Args:\n272 param1: The first parameter.\n273 param2: The second parameter.\n274\n275 Returns:\n276 True if successful, False otherwise.\n277\n278 """\n279 return True\n
Class methods are similar to regular functions.
\n\nNote:
\n\n\n\n\nDo not include the
\nselfparameter in theArgssection.
Arguments:
\n\n- \n
- param1: The first parameter. \n
- param2: The second parameter. \n
Returns:
\n\n\n\nTrue if successful, False otherwise.
\n
\n \n def\n fetch_smalltable_rows(\ttable_handle: Any,\tkeys: Sequence[str],\trequire_all_keys: bool = False) -> Mapping[bytes, Tuple[str]]:\n\n \n\n
\n \n 319def fetch_smalltable_rows(table_handle: Any,\n320 keys: Sequence[str],\n321 require_all_keys: bool = False,\n322) -> Mapping[bytes, Tuple[str]]:\n323 """Fetches rows from a Smalltable.\n324\n325 Retrieves rows pertaining to the given keys from the Table instance\n326 represented by table_handle. String keys will be UTF-8 encoded.\n327\n328 Args:\n329 table_handle: An open smalltable.Table instance.\n330 keys: A sequence of strings representing the key of each table\n331 row to fetch. String keys will be UTF-8 encoded.\n332 require_all_keys: Optional; If require_all_keys is True only\n333 rows with values set for all keys will be returned.\n334\n335 Returns:\n336 A dict mapping keys to the corresponding table row data\n337 fetched. Each row is represented as a tuple of strings. For\n338 example:\n339\n340 {b'Serak': ('Rigel VII', 'Preparer'),\n341 b'Zim': ('Irk', 'Invader'),\n342 b'Lrrr': ('Omicron Persei 8', 'Emperor')}\n343\n344 Returned keys are always bytes. If a key from the keys argument is\n345 missing from the dictionary, then that row was not found in the\n346 table (and require_all_keys must have been False).\n347\n348 Raises:\n349 IOError: An error occurred accessing the smalltable.\n350 """\n351 raise NotImplementedError\n
Fetches rows from a Smalltable.
\n\nRetrieves rows pertaining to the given keys from the Table instance\nrepresented by table_handle. String keys will be UTF-8 encoded.
\n\nArguments:
\n\n- \n
- table_handle: An open smalltable.Table instance. \n
- keys: A sequence of strings representing the key of each table\nrow to fetch. String keys will be UTF-8 encoded. \n
- require_all_keys: Optional; If require_all_keys is True only\nrows with values set for all keys will be returned. \n
Returns:
\n\n\n\n\nA dict mapping keys to the corresponding table row data\n fetched. Each row is represented as a tuple of strings. For\n example:
\n \n{b\'Serak\': (\'Rigel VII\', \'Preparer\'),\n b\'Zim\': (\'Irk\', \'Invader\'),\n b\'Lrrr\': (\'Omicron Persei 8\', \'Emperor\')}
\n \nReturned keys are always bytes. If a key from the keys argument is\n missing from the dictionary, then that row was not found in the\n table (and require_all_keys must have been False).
\n
Raises:
\n\n- \n
- IOError: An error occurred accessing the smalltable. \n
\n \n def\n fetch_smalltable_rows2(\ttable_handle: Any,\tkeys: Sequence[str],\trequire_all_keys: bool = False) -> Mapping[bytes, Tuple[str]]:\n\n \n\n
\n \n 354def fetch_smalltable_rows2(table_handle: Any,\n355 keys: Sequence[str],\n356 require_all_keys: bool = False,\n357) -> Mapping[bytes, Tuple[str]]:\n358 """Fetches rows from a Smalltable.\n359\n360 Retrieves rows pertaining to the given keys from the Table instance\n361 represented by table_handle. String keys will be UTF-8 encoded.\n362\n363 Args:\n364 table_handle:\n365 An open smalltable.Table instance.\n366 keys:\n367 A sequence of strings representing the key of each table row to\n368 fetch. String keys will be UTF-8 encoded.\n369 require_all_keys:\n370 Optional; If require_all_keys is True only rows with values set\n371 for all keys will be returned.\n372\n373 Returns:\n374 A dict mapping keys to the corresponding table row data\n375 fetched. Each row is represented as a tuple of strings. For\n376 example:\n377\n378 {b'Serak': ('Rigel VII', 'Preparer'),\n379 b'Zim': ('Irk', 'Invader'),\n380 b'Lrrr': ('Omicron Persei 8', 'Emperor')}\n381\n382 Returned keys are always bytes. If a key from the keys argument is\n383 missing from the dictionary, then that row was not found in the\n384 table (and require_all_keys must have been False).\n385\n386 Raises:\n387 IOError: An error occurred accessing the smalltable.\n388 """\n389 raise NotImplementedError\n
Fetches rows from a Smalltable.
\n\nRetrieves rows pertaining to the given keys from the Table instance\nrepresented by table_handle. String keys will be UTF-8 encoded.
\n\nArguments:
\n\n- \n
- table_handle: An open smalltable.Table instance. \n
- keys: A sequence of strings representing the key of each table row to\nfetch. String keys will be UTF-8 encoded. \n
- require_all_keys: Optional; If require_all_keys is True only rows with values set\nfor all keys will be returned. \n
Returns:
\n\n\n\n\nA dict mapping keys to the corresponding table row data\n fetched. Each row is represented as a tuple of strings. For\n example:
\n \n{b\'Serak\': (\'Rigel VII\', \'Preparer\'),\n b\'Zim\': (\'Irk\', \'Invader\'),\n b\'Lrrr\': (\'Omicron Persei 8\', \'Emperor\')}
\n \nReturned keys are always bytes. If a key from the keys argument is\n missing from the dictionary, then that row was not found in the\n table (and require_all_keys must have been False).
\n
Raises:
\n\n- \n
- IOError: An error occurred accessing the smalltable. \n
\n \n class\n SampleClass:\n\n \n\n
\n \n 392class SampleClass:\n393 """Summary of class here.\n394\n395 Longer class information....\n396 Longer class information....\n397\n398 Attributes:\n399 likes_spam: A boolean indicating if we like SPAM or not.\n400 eggs: An integer count of the eggs we have laid.\n401 """\n402\n403 def __init__(self, likes_spam=False):\n404 """Inits SampleClass with blah."""\n405 self.likes_spam = likes_spam\n406 self.eggs = 0\n407\n408 def public_method(self):\n409 """Performs operation blah."""\n
Summary of class here.
\n\nLonger class information....\nLonger class information....
\n\nAttributes:
\n\n- \n
- likes_spam: A boolean indicating if we like SPAM or not. \n
- eggs: An integer count of the eggs we have laid. \n
\n \n def\n invalid_format(test):\n\n \n\n
\n \n 412def invalid_format(test):\n413 """\n414 In this example, there is no colon after the argument and an empty section.\n415\n416 Args:\n417 test\n418 there is a colon missing in the previous line\n419 Returns:\n420\n421 """\n
In this example, there is no colon after the argument and an empty section.
\n\nArguments:
\n\n- \n
- test\nthere is a colon missing in the previous line \n
Returns:
\n\n \n def\n example_code():\n\n \n\n
\n \n 424def example_code():\n425 """\n426 Test case for https://github.com/mitmproxy/pdoc/issues/264.\n427\n428 Example:\n429\n430 ```python\n431 tmp = a2()\n432\n433 tmp2 = a()\n434 ```\n435 """\n
Test case for https://github.com/mitmproxy/pdoc/issues/264.
\n\nExample:
\n\n\n\n\n\n\ntmp = a2()\n\ntmp2 = a()\n
\n \n def\n newline_after_args(test: str):\n\n \n\n
\n \n 438def newline_after_args(test: str):\n439 """\n440 Test case for https://github.com/mitmproxy/pdoc/pull/458.\n441\n442 Args:\n443\n444 test\n445 there is unexpected whitespace before test.\n446 """\n
Test case for https://github.com/mitmproxy/pdoc/pull/458.
\n\nArguments:
\n\n- \n
- test\nthere is unexpected whitespace before test. \n
\n \n def\n alternative_section_names(test: str):\n\n \n\n
\n \n 449def alternative_section_names(test: str):\n450 """\n451 In this example, we check whether alternative section names aliased to\n452 'Args' are handled properly.\n453\n454 Parameters:\n455 test: the test string\n456 """\n
In this example, we check whether alternative section names aliased to\n\'Args\' are handled properly.
\n\nArguments:
\n\n- \n
- test: the test string \n
\n \n def\n keyword_arguments(**kwargs):\n\n \n\n
\n \n 458def keyword_arguments(**kwargs):\n459 """\n460 This an example for a function with keyword arguments documented in the docstring.\n461\n462 Args:\n463 **kwargs: A dictionary containing user info.\n464\n465 Keyword Arguments:\n466 str_arg (str): First string argument.\n467 int_arg (int): Second integer argument.\n468 """\n
This an example for a function with keyword arguments documented in the docstring.
\n\nArguments:
\n\n- \n
- **kwargs: A dictionary containing user info. \n
Keyword Args:
\n\n- \n
- str_arg (str): First string argument. \n
- int_arg (int): Second integer argument. \n