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