docstring

来源： https://stackoverflow.com/questions/33262919/should-the-docstring-only-contain-the-exceptions-that-are-explicitly-raised-by-a

问题 I have seen the following statement in a number of docstrings when help() ing a class: "See help(type(self)) for accurate signature." Notably, it is in the help() for scipy.stats.binom.__init__ and for stockfish.Stockfish.__init__ at the very least. I assume, therefore, that it is some sort of stock message. In any case, I can't figure out what the heck it means. Is this useful information? Note that, being "outside" of the class, so to speak, I never have access to self . Furthermore, it is

问题 I'm learning how to use Sphinx to create a documentation for my code. After I saw some examples like this: def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real -- the real part (default 0.0) imag -- the imaginary part (default 0.0) """ if imag == 0.0 and real == 0.0: return complex_zero ... What is the language used in comments to make Sphinx understand and catch them? Without this syntax and logic, Sphinx doesn't see the comments in my code and when I generate

问题 I'm learning how to use Sphinx to create a documentation for my code. After I saw some examples like this: def complex(real=0.0, imag=0.0): """Form a complex number. Keyword arguments: real -- the real part (default 0.0) imag -- the imaginary part (default 0.0) """ if imag == 0.0 and real == 0.0: return complex_zero ... What is the language used in comments to make Sphinx understand and catch them? Without this syntax and logic, Sphinx doesn't see the comments in my code and when I generate

问题 Is there a way to specify expected integer outcomes in a docstring in hex notation? def identity(val): """ >>> identity(243) 243 >>> identity(243) 0xf3 """ return val if __name__ == "__main__": import doctest doctest.testmod() Doctest doesn't interpret the hex notation, resulting in a failure: ********************************************************************** File "hextest.py", line 5, in __main__.identity Failed example: identity(243) Expected: 0xf3 Got: 243 *****************************

问题 Suppose I have a function with a docstring where I declare the return type as a tuple with two strings: def foo(): """ Returns: Tuple[str, str]: Tuple of first name and last name """ Am I supposed to import Tuple from typing if I don't use it anywhere except for in docstrings? 回答1: PyCharm's docstring support for type hints does not actually use typing . You do not need to import the module. The typing module is only there to support the fact that annotations are executed at runtime; for a

问题 It seems that some escape chars still matter in docstring. For example, if we run python foo.py ( Python 2.7.10 ), it will emit error like ValueError: invalid \x escape . def f(): """ do not deal with '\x0' """ pass And in effect, it seem the correct docsting should be: """ do not deal with '\\\\x0' """ Additionally it also affects import . For Python 3.4.3+ , the error message is: File "foo.py", line 4 """ SyntaxError: (unicode error) 'unicodeescape' codec can't decode bytes in position 24

问题 It seems that some escape chars still matter in docstring. For example, if we run python foo.py ( Python 2.7.10 ), it will emit error like ValueError: invalid \x escape . def f(): """ do not deal with '\x0' """ pass And in effect, it seem the correct docsting should be: """ do not deal with '\\\\x0' """ Additionally it also affects import . For Python 3.4.3+ , the error message is: File "foo.py", line 4 """ SyntaxError: (unicode error) 'unicodeescape' codec can't decode bytes in position 24

问题 It seems that some escape chars still matter in docstring. For example, if we run python foo.py ( Python 2.7.10 ), it will emit error like ValueError: invalid \x escape . def f(): """ do not deal with '\x0' """ pass And in effect, it seem the correct docsting should be: """ do not deal with '\\\\x0' """ Additionally it also affects import . For Python 3.4.3+ , the error message is: File "foo.py", line 4 """ SyntaxError: (unicode error) 'unicodeescape' codec can't decode bytes in position 24

问题 I have some existing Python 3.6 code that I'd like to move to Python 3.7 dataclasses. I have __init__ methods with nice docstring documentation, specifying the attributes the constructors take and their types. However, if I change these classes to use the new Python dataclasses in 3.7, the constructor is implicit. How do I provide constructor documentation in this case? I like the idea of dataclasses, but not if I have to forego clear documentation to use them. edited to clarify I'm using