标签: docstring

我理解在Python中,字符串只是一个表达式,并且在将控制权返回给代码的调用者时,字符串本身就会被垃圾收集,但......

1. 代码中的大类/方法doc字符串:它们是否通过构建字符串对象来浪费内存？
2. 模块级doc字符串:它们是由解释器无限存储的吗？

这甚至重要吗？我唯一关心的问题是,如果我使用像Django这样的大型框架,或者使用多个大型开源库,那么它们往往会被很好地记录下来,可能有多兆字节的文本.在这些情况下,文档字符串是否已加载到内存中以供沿途使用的代码,然后保存在那里,或者是否像普通字符串一样立即收集？

我正在尝试从 Windows dll 创建一堆 python 函数，并且希望将文档字符串附加到每个新函数。

我当前的代码：

import ctypes

lib=ctypes.WinDLL('example.dll')

VCS_OpenDevice=lib['VCS_OpenDevice']
VCS_OpenDevice.restype=ctypes.c_double

当我在解释器中运行此脚本并尝试使用该函数时，我收到“无文档字符串”消息。

不知道在那里添加什么东西。任何帮助表示赞赏。

在IRB或其他交互式解释器(如pry)中,如何获取有关对象和方法的内联文档？例如,我可以做到这一点:

[1] pry(main)> x = 'hello world'
=> "hello world"
[2] pry(main)> x.st
x.start_with?  x.strip        x.strip!   
[2] pry(main)> x.st

但现在我想读取用法/接口/ rdoc对这些方法及其接口的说法.顺便说一句,那条中间线是制表完成的.

我正在寻找类似于ipython的东西,?可以将其附加到属性名称以查看docstring,甚至??可以查看源代码:

In [1]: x = 'potato'

In [2]: x.st
x.startswith  x.strip       

In [2]: x.strip?
Type:       builtin_function_or_method
String Form:<built-in method strip of str object at 0x15e1b10>
Docstring:
S.strip([chars]) -> string or unicode

Return a copy of the string S with leading and trailing
whitespace removed.
If chars is given and not None, remove characters in chars …

在Clojure中创建库时,最好在每个函数中包含docstrings和其他元数据,例如:

(defn ^Boolean foo
  "Returns whether x is bar."
  {:added "1.5"}
  [x]
  (bar? x))

有时(使用高阶函数时)最终使用def (something-that-returns-a-fn)这样的函数更容易定义函数:

(defn wrapper [f]
  "Some HOF, let's say it just prints 'WHARRGARBL' and then returns the fn."
  (println "WHARRGARBL")
  f)

(def foo
  "Prints 'WHARRGARBL' and then returns whether x is bar."
  (wrapper (fn [x] (bar? x))))

如果我没有弄错的话,以这种方式定义函数会消除使用的优点defn- 即,文档字符串以一种很好的方式打印,而不是包括函数支持的arities,以及在函数定义中简洁地包含属性映射的能力.我是对的,还是有其他简洁的方法来记录通过HOF创建的功能？我可以这样做:

(defn foo
  "Prints 'WHARRGARBL' and then returns whether x is bar."
  {:added "1.5"}
  [x]
  ((wrapper (fn [y] (bar? y))) x))

但这似乎有点多余而且不必要地复杂,因为我将x的函数定义为y的函数,应用于x.有没有更好的办法？

就在最近,我遇到了一个非常奇怪的问题,我发现没有决心.例如,如果我在解释器中运行以下代码

>>> def test():
...     'docstring'
...     ...
... 
>>> print(test.__doc__)

我得到了'docstring',这并不奇怪.现在如果我在*.py文件中运行它,我会得到None.

我尝试了多个具有相同结果的文件; 但为什么解释器返回文档字符串而不是任何文件？任何帮助肯定会受到赞赏.

注意:我已经尝试过三重引号,双重和单引号,以及我可以集合的任何其他变体,没有运气.

已解决:不确定具体如何,但我使用的命令在该shell实例中被"破坏"了.现在工作正常

我正在编写一个简单的 Python 包（目前）只有一个模块。

我应该把文档字符串和__author__元属性放在哪里？他们是__init__.py在每个模块中还是在每个模块中？

是否有与此相关的 PEP？我只能找到通用文档字符串，它不能回答这个问题。

我们有一个 Flask api，我正在为这些类编写文档字符串。每个 get 方法都有 url/?key=value 形式的 url 参数，例如 /?format=csv，在编写文档字符串时，记录它们的最佳/推荐方式是什么？我的第一个想法是将它们放入方法文档字符串中，但 pycharm 和 pylint 抱怨，因为它们不是方法的实际参数。

谢谢

我在Python文档字符串的末尾看到了一条尾随的白线(比如在Numpy文档字符串和Google风格的文档字符串中,我记得在某处读到了这是建议的.

这就是说,它们似乎在文档字符串转换器,如被忽略在Napolean与在常规实例中的PEP-257文档.

在Python文档字符串中添加尾部白线的目的是什么？它纯粹是为了易读吗？

我正在按照 numpy 文档字符串指南编写文档字符串。然后我使用 sphinx 的 autodoc 生成我的文档。在一些文档字符串中，我使用 LaTeX 公式（sphinx.ext.mathjax）。似乎这\r意味着一些特殊的事情，比如一条新线。如果我有以下命令：

"""
This :math:`\langle a, b\rangle` denotes the dot product of a and b
"""

它无法正确渲染。它将类似角度放入新行并给我一个错误：内联解释文本或短语引用起始字符串没有结束字符串 如果我用 \langle 替换 \rangle 一切正常。我怎样才能解决这个问题？

我在 VSCode 上使用 pygame 模块，但遇到了 pygame 没有 init 成员的问题。我按照此链接的解决方案进行操作。我编辑了用户设置并添加了

    "python.linting.pylintArgs": [
        "--extension-pkg-whitelist=pygame",
        "--unsafe-load-any-extension=y"
    ]

到json文件的末尾

pygame 问题已解决。但是，当我使用import random. 我收到此警告：

缺少模块文档字符串pylint（缺少模块文档字符串）

我该如何让它消失？另外，有没有更好的方法来解决pygame的init问题？

谢谢！