从Python源代码中的Sphinx注释中提取类型注解
项目描述
是什么？
从使用Sphinx兼容文档字符串记录的Python源代码中提取类型注解。
为什么？
现有的工具，如PyAnnotate，需要您编写一个驱动程序来测试您的应用程序，而一个特殊的钩子收集类型信息并将其转换为注解。这确实很好，但需要编写一个覆盖您整个应用程序的综合驱动程序，这需要大量的努力。
如果您的应用程序的文档字符串中已经有了类型信息，那么直接将此信息转换为注解可能更简单。库图佐夫将帮助您完成这项工作。
如何？
库图佐夫是这样做的
扫描包和子模块中的文档字符串
解析文档字符串，提取每个参数的类型信息
写入与PyAnnotate兼容的JSON文件
剩下需要您做的
运行PyAnnotate并消费生成的JSON文件
手动调整结果
盈利
您需要调整的量可能会有所不同。这很大程度上取决于您的文档字符串的质量和准确性。
示例
我们将为example.py文件添加注解。您需要pyannotate（pip install pyannotate）才能继续。
$ python -m kutuzov example.py > type_info.json
$ cat type_info.json
[
{
"func_name": "Dog.__init__",
"line": 2,
"path": "example.py",
"samples": 1,
"type_comments": [
"(str) -> None"
]
},
{
"func_name": "Dog.bark",
"line": 16,
"path": "example.py",
"samples": 1,
"type_comments": [
"(str) -> str"
]
}
]
$ pyannotate example.py --py3
Refactored example.py
--- example.py (original)
+++ example.py (refactored)
@@ -1,5 +1,5 @@
class Dog:
- def __init__(self, name):
+ def __init__(self, name: str) -> None:
"""
:param str name: The name of this dog.
"""
@@ -13,7 +13,7 @@
"""
return self._name
- def bark(self, language='en'):
+ def bark(self, language: str = 'en') -> str:
"""
Make some noise!
Files that need to be modified:
example.py
NOTE: this was a dry run; use -w to write files您可能已经注意到，[example.py](example.py) 中已经包含了 PyAnnotate 驱动程序。
$ cat type_info.json
[
{
"path": "example.py",
"line": 2,
"func_name": "Dog.__init__",
"type_comments": [
"(str) -> None"
],
"samples": 1
},
{
"path": "example.py",
"line": 8,
"func_name": "name",
"type_comments": [
"() -> str"
],
"samples": 1
},
{
"path": "example.py",
"line": 16,
"func_name": "Dog.bark",
"type_comments": [
"(str) -> str"
],
"samples": 1
}
]如果您将其与之前生成的 JSON 进行比较，会发现它们大部分是相似的。最大的不同是 Kutuzov 丢失了 name 属性 - 它还不知道如何处理这些。
名字有什么含义？
米哈伊尔·库图佐夫 是 拿破仑·波拿巴 的同时代人。一幅 特定的画作 描绘了拿破仑在斯芬克斯雕像前。而 斯芬克斯 当然是我们所有人喜爱的用于 Python 文档的项目。
这个项目部分受到了 sphinx.ext.napoleon 的启发，它做的是类似的事情，但针对的是不同的 docstring 格式。
关闭
kutuzov-0.1.0.tar.gz 的哈希值
| 算法 | 哈希摘要 | |
|---|---|---|
| SHA256 | a948cec2f70427a5b33532e67f867a6bef1f09836497a8b5157258030d44b19d |
|
| MD5 | 3e66805f0f2e31a2a263487e6a9b24ab |
|
| BLAKE2b-256 | c3516ddc2a0c7040b59268e29dec5a1736003b588e590f01482f976ba4084cdf |