python - 我有更好的 Python 文档吗？更有条理？

Question

我想这个问题已经有人问过了，但我没有找到。

我过去使用过 Java 和 PHP，我相信他们的语言文档结构更好。至少他们的 API。

如果您查看 Java 的 API，它会很棒。结构良好且可预测。它还可以让您找到您不知道的新东西。我正在考虑这个https://docs.oracle.com/javase/7/docs/api/ .

PHP 的结构不是很好，但它工作得很好。我在说这个:https://www.php.net/manual/en/ .

现在，如果您看到 Python 的等效内容(至少是我发现的 https://docs.python.org/3/index.html )，您会觉得它是一个非常长的教程。在我看来，搜索东西很困难，而且没有真正的等级组织。当您阅读有关函数的内容时，当我真正在寻找摘要时，还会有很多描述内容的文本。以https://docs.python.org/3/library/string.html为例，请参阅有关“格式字符串语法”的部分，感觉它应该放在专门针对该主题的其他地方。

所以我的问题是:Python API 的结构是否与 JAVA 中的功能相似？

Answer 1

Python 在标准库中有一个几乎等同于 Javadoc 的文件，称为 pydoc。

您可以使用命令将其作为 Web 服务器启动

$ python -m pydoc -b

(或者 -p 80 如果随机端口给你带来麻烦，那么转到 http://localhost)

这应该会打开一个 Web 浏览器，让您可以浏览标准库以及您碰巧安装的任何其他包。

---

请注意，您还可以使用 help() 实用程序从 Python 的交互式 shell/REPL 获取所有这些信息。

>>> help()

let's say you wanted to find functions to do stuff on strings, as an example let's say strip(). How would you find this function using either method?

$ python -m pydoc str

或

>>> help(str)

将显示 str 类型的帮助，包括它的所有方法。

如果你不知道一个字符串是 str 类型，你可以创建一个并询问它的类型:

>>> type("foo")
<class 'str'>
>>> help(type("foo"))

要查看对象属性的更紧凑目录，您可以使用

>>> dir(str)
['__add__', '__class__', '__contains__', '__delattr__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__', '__getnewargs__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__iter__', '__le__', '__len__', '__lt__', '__mod__', '__mul__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__rmod__', '__rmul__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', 'capitalize', 'casefold', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', 'format', 'format_map', 'index', 'isalnum', 'isalpha', 'isascii', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', 'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']

但由于您已经知道名称是 strip()，因此您可以就该对象寻求帮助。

>>> help(str.strip)

这将显示方法签名和文档字符串(如果有)。

使用 Pydoc 的 Web 服务器，您单击起始页上“内置模块”中的 builtins 链接，然后单击 str 链接以查看完全相同的信息，因为 help() 也由 pydoc 提供服务。

还有一个“搜索”和一个“获取”栏。在“获取”栏中输入 str.strip 即可直接访问它，就像使用 help(str.strip) 一样。

This is great info. Thanks. Is there somewhere where this is posted online? So you don't have to start a server locally?

据我所知没有。而且似乎没有太多意义 https://docs.python.org .本地服务器的优点是它会根据您启动它的解释器准确记录系统上安装的内容，即使您安装了多个 Python 版本(或者正在使用安装了不同包的 virtualenvs)。甚至标准库也可能因操作系统或发行版以及(从源代码编译时)编译时可用的 C 库而异。