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
orExamples
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 """
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.
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.
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.
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 toparam1
.
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]
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 theArgs
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.
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.
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.
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:
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 theArgs
section.
Arguments:
- param1 (str): Description of
param1
. - param2 (
int
, optional): Description ofparam2
. Multiple lines are supported. - param3 (
list
ofstr
): Description ofparam3
.
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.
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.
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 theArgs
section.
Arguments:
- param1: The first parameter.
- param2: The second parameter.
Returns:
True if successful, False otherwise.
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.
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.
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.
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:
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.
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