加载模块时,Python文档字符串和注释是否存储在内存中？
我想知道这是否属实,因为我通常会很好地记录我的代码; 这可能会影响内存使用吗？
通常每个Python对象都有一个__doc__方法.这些文档字符串是从文件中读取还是以其他方式处理？
我在论坛,谷歌和邮件列表中进行了搜索,但我没有找到任何相关信息.
你知道的更好吗？
我使用Sphinx和autodocs功能来确保我们的项目中有很好的文档.
但是,在为方法或函数编写docstring时,我发现在文本中引用它们的参数很有用.但似乎没有一种结构化的方式来做到这一点.
我们可以说例如
Use ``name`` to set the username
但是没有结构,要求你记住你用过的样式,如果你改变了样式,你必须追捕并杀死所有不正确的样式.
:param:在信息字段列表之外不起作用,所以你不能写
Use :param:`name` to set the username
我已经看到一些项目使用:parm:但是没有记录,似乎没有用.所以他们必须有一些定制
所以我希望我错过了一些令人眼花缭乱的事情.
如果一个参数传递给函数有望得到一定(或同等学历)的结构,使用python的内置list,tuple以及dict,如何和在那里它应该被记录？
示例文档:
def foo(bar):
"""
Args:
bar: 2-tuple, ([(<mapping>,<number>), ...], <string>)
"""
pass
有点麻烦; 一些问题:
编辑:该示例不是为了尝试强制执行类型,而是尝试记录结构.对于这一点,duck typing是OK.
我在Python的类型中有很多函数:
def foobar(one, two):
"""
My function.
:param int one: My one argument.
:param int two: My two argument.
:rtype: Something nice.
"""
return 100 + one + two
我需要解析docstring以获得类似的字典:
{
'sdesc' : 'My function.',
'params' : [('one', 'My one argument.'), ('two', 'My two argument.')],
'rtype' : 'Something nice.'
}
我可以使用sphinx.util.docstrings.prepare_docstring如下:
>>> prepare_docstring(foobar.__doc__)
['My function.', ':param int one: My one argument.', ':param int two: My two argument.', ':rtype: Something nice.', '']
我可以创建我自己的解析器,可能使用正则表达式用于params和rtype,以及东西.
但有没有更好的方法来做到这一点或更好的方法？怎么样sphinx.ext.autodoc？关于如何解析这种文档字符串的任何其他建议？
:rtype:指定这是返回对象的类型
因此,当我obj在下面的代码片段中创建对象时,我收到来自IDE的警告cls is not callable,因为IDE期望,这cls是object类型的SomeAbstractClass,我想要SomeAbstractClass自己
IDE是对的,因为这是默认行为.但是我如何指定,我正在返回课程,而不是课程的实例？
指定type而不是SomeAbstractClass帮助,但不是解决方案,因为没有进一步的内省可用.
def class_selector(data):
"""
:rtype: SomeAbstractClass
:return: Return some class based on given parameters
"""
return get_from.get(data.name)
cls = class_selector(data)
obj = cls(data.more_data)
同时我通过""":type: SomeAbstractClass"""在创建对象后添加来解决这个问题 ,但是这并没有取消警告并且它是脏的解决方案.
顺便说一句,谈论python 2.x.
考虑一下filterNot(基本上与之相反filter)的实现:
def filterNot(f, sequence):
return filter(lambda x: not f(x), sequence)
参数f可以是"函数"或"方法"或lambda- 甚至是类定义的对象__call__.
现在考虑一下这个参数的docstring行:
:param ??? f: Should return True for each element to be abandoned
现在,应该取代什么？- 如何在docstring中引用参数类型f.callable是显而易见的选择(如果我发号施令,我会指示:P)但是有没有既定的惯例？
如果我使用三引号将方法字符串添加到方法中,只要在三引号后面键入一个空格,PyCharm就会使用方法所采用的参数填充docstring,并返回一个返回值,如下所示:
def fill_blank(self, direction):
"""
:param direction:
:return:
"""
我已经搜索了PyCharm首选项中的"docstring"和"stub"并关闭了显示的所有内容,即使它似乎与这种特定行为无关; 我用谷歌搜索高低,但无法弄清楚如何让它停止.有谁知道怎么样？(这是在PyCharm CE 3.4中)
当我用参数创建一个函数时,PyCharm让我用:param param_name:字段创建docstring ,这非常好.但我还需要添加:type param_name:.
那样:
def foo(bar, xyz):
return bar + xyz
使用生成docstring选项我有(即使使用文档存根启用的插入'类型'和'rtype'):
def foo(bar, xyz):
"""
:param bar:
:param xyz:
"""
return bar + xyz
而我想的是:
def foo(bar, xyz):
"""
:param bar:
:type bar:
:param xyz:
:type xyz:
"""
return bar + xyz
似乎某些转义字符在docstring中仍然很重要.例如,如果我们运行python foo.py(Python 2.7.10),它将发出错误,如ValueError: invalid \x escape.
def f():
"""
do not deal with '\x0'
"""
pass
实际上,似乎正确的docsting应该是:
"""
do not deal with '\\\\x0'
"""
另外它也会影响import.
对于Python 3.4.3+,错误消息是:
File "foo.py", line 4
"""
SyntaxError: (unicode error) 'unicodeescape' codec can't decode bytes in position 24-25: truncated \xXX escape
我觉得有点奇怪,因为我认为它只会对__doc__模块本身产生影响并且没有任何副作用.
为什么设计如此？它是Python中的缺陷/错误吗？
我知道"""和原始文字的含义,但我认为python解释器应该能够特别处理docstring,至少在理论上.
我总是在函数定义中使用类型提示，例如：
def foo(a: int, b: str) -> bool:
pass
当我使用 PyCharm 自动文档字符串生成器在我的代码中生成文档字符串时，我得到了这个：
def foo(a: int, b: str) -> bool:
"""
:param a:
:type a:
:param b:
:type b:
"""
pass
如您所见，我在函数本身中定义的类型值没有被 PyCharm 识别，我应该再次将它们写在 docstring 中。我如何让 PyCharm 为我自动生成这样的东西（从第一行读取类型值并将它们插入到文档字符串中）：
def foo(a: int, b: str) -> bool:
"""
:param a:
:type a: int
:param b:
:type b: str
:rtype: bool
"""
pass