“Docstring处理工具”遵循PEP 257？ [英] "Docstring processing tools" following PEP 257?

问题描述

PEP 257 说：

Docstring处理工具将从docstring的第二行和另外一行删除一致的缩进量，等于所有非空白的最小缩进线后第一行。 docstring的第一行中的任何缩进（即直到第一个换行）都是微不足道的，并被删除。保留了docstring中后续行的相对缩进。空白行应该从文本字符串的开头和结尾移除。

一个函数 trim b b
$ b

HREF = https://stackoverflow.com/questions/2504411/proper-indentation-for-python-multiline-strings>此）。我还会看到一些有关工具的信息，以确保您的文档按照PEP 257（例如，此）。我找不到的是任何Python库，实际上是一个docstring处理工具，它以PEP 257中定义的方式处理文本输入，或至少我找不到工具这使得这个docstring处理功能直接可用。

有没有可以使用PEP中显示的函数 trim 257？显然，我可以将该函数自己粘贴到一个文件中，但是我更愿意知道可以快速抓取和安装的公开库的名称（例如，通过 pip 或 easy_install ），如果我正在使用其他计算机，我想要这个功能，而不是总是从PEP复制和粘贴。鉴于该功能是由BDFL合作的PEP，我认为会有一些官方或半官方图书馆这样做。

编辑：原因我想要这样写一个装饰器，它对类/函数的docstrings进行一些Python内部重新格式化。我不想生成HTML或其他任何东西;我只想改变实际对象的实际文档。我想采用Python对象的纯文本 __ doc __ 属性，并将其重新格式化为将用作纯文本 __ doc __ 属性。我知道如何分配到 __ doc __ ，但是我想知道什么是库，我称之为$ code> some_func .__ doc__ = library.reformatDocstr（some_func .__ doc__ ），并获取图书馆做任何包装等，它做的很好？

解决方案

寻找一个相关问题的答案，我设法找到了这个答案。 trim 算法在 inspect.cleandoc ，所有地方。

PEP 257 says:

Docstring processing tools will strip a uniform amount of indentation from the second and further lines of the docstring, equal to the minimum indentation of all non-blank lines after the first line. Any indentation in the first line of the docstring (i.e., up to the first newline) is insignificant and removed. Relative indentation of later lines in the docstring is retained. Blank lines should be removed from the beginning and end of the docstring.

A function trim implementing this algorithm is then shown in the PEP.

I can find questions where people ask how to format docstrings and are referred to PEP 257 (e.g., this). I also see some info about tools that try to ensure your docstrings follow PEP 257 (e.g., this). What I can't find is any Python library that actually is a "docstring processing tool" that handles docstrings in the way defined in PEP 257 --- or at least, I can't find a tool that makes this docstring processing functionality directly available.

Is there a library that makes available the function trim shown in PEP 257? Obviously I can paste the function into a file myself, but I'd prefer to know the name of a publically available library that I can quickly grab and install (e.g., via pip or easy_install) if I'm using some other computer where I want this functionality, instead of always copying and pasting from the PEP. Given that the function is in a PEP coauthored by the BDFL, I would have thought there would be some official or semi-official library that does this.

Edit: The reason I want this is to write a decorator that does some Python-internal reformatting of the docstrings of classes/functions. I don't want to generate HTML or anything else; I just want to change the actual docstrings of the actual objects. I want to take the plain-text __doc__ attribute of a Python object and reformat it into something that will serve as the plain-text __doc__ attribute of a Python object. I know how to assign to __doc__, but I want to know what is the library where I call some_func.__doc__ = library.reformatDocstr(some_func.__doc__) and get the library to do whatever wrapping etc. it is good at doing?

解决方案

In looking for an answer to a related question, I managed to find the answer to this one. The trim algorithm is implemented in inspect.cleandoc, of all places.

这篇关于“Docstring处理工具”遵循PEP 257？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！