我制作了一个将docstring提供给Python存根文件的库 |
您所在的位置：网站首页 › python文件为什么保存不了 › 我制作了一个将docstring提供给Python存根文件的库 |
|
最近，有些情况下使用Python存根文件进行工作。但是，mypy的存根文件生成命令不会将docstring添加到存根文件中，因此我创建了一个库来自己添加它，因此我将对此进行介绍。 什么是存根文件？ 这是一个扩展名为.pyi的文件，它描述Python类型信息并省略逻辑部分。 使用存根文件具有以下优点。 由于修饰器的便利性和第三方库的便利性，可以启用完成并检查运行不正常的模块。 可以通过将单独的存根文件添加到没有类型注释的第三方库中来添加类型信息(也启用了检查功能)。 对于运行许多类型推断时具有高负载的大型模块，使用省略安装部分的最小存根文件可以减少负载并减少诸如完成和检查之类的延迟。相反，缺点是 由于类型信息等的定义在原始模块的存根文件中被覆盖，因此，在项目代码等频繁更新的情况下，由于它偏离了模块的内容(当在模块中使用它时)，这是不可取的。尽可能多的项目)拥有一种实时更新存根文件的机制会很好。 *基本上，如果是库代码，则不会经常更新，因此可以很好地减少编辑器的负担。有一个类似 的地方。 有关如何创建存根文件的信息，请参阅如何创建包含符合PEP 561的类型提示的程序包。 您为什么开始使用存根文件？ 在 项目中，某些代码不再完成或在VS Code上进行了类型检查(由于装饰器等)。尽管它曾经工作过，但不知道是由于更新还是因为VS Code上使用的库，但是即使等待一会儿也不能方便地保留它，因此有些"仅项目"模块具有存根文件实时添加(我尝试了其他各种措施，但最后，部分存根文件支持似乎快速而平静)。 *我在Github上看到了一个尚待解决的问题，因此似乎有可能很快得到改善。 我不想手动创建存根文件，因此我使用了mypy的存根文件生成命令，但是文档字符串消失了 可以决定在项目中使用存根文件，但如果您需要手动更新存根文件，则只会增加工时，因此不建议使用。我希望您在尽可能自动化的同时实时更新存根文件。 关于自动生成存根文件，mypy提供了一个名为stubgen的命令功能，因此我正在使用它。 自动存根生成(存根) 避免了手动生成存根文件，从而大大减轻了负担。但是，文档字符串会消失在使用此存根生成的存根文件中。 例如，如果您具有以下模块代码，则 12345678910111213141516171819202122232425262728293031323334353637383940414243from random import randint sample_int: int = 100 def sample_func(a: int, b: str) -> bool: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit, ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Parameters ---------- a : int Lorem ipsum dolor sit amet, consectetur adipiscing elit. b : str ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Returns ------- c : bool Ut enim ad minim veniam, quis nostrud exercitation. """ return True class SampleClass: def __init__(self) -> None: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit. """ @property def sample_property(self) -> int: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Returns ------- d : int ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. """ return randint(0, 100)如果使用stubgen命令生成包含此模块内容的存根文件，则其外观如下所示。 12345678sample_int: int def sample_func(a: int, b: str) -> bool: ... class SampleClass: def __init__(self) -> None: ... @property def sample_property(self) -> int: ...您可以看到 类型信息仍然存在，但是文档字符串已消失。在VS Code上使用的每个扩展名(Pylance等)中，如果存根文件与模块位于同一目录中，则存根文件似乎具有优先权，在这种情况下，文档字符串的内容将显示在编辑器中。不可以。 这就是为什么我自己制作并将其注册为PyPI(pip)的原因 使用 ，我编写了一个库，该库将原始模块的文档字符串提供给存根文件，并将其注册到PyPI(pip)(MIT许可证)中。 可以在工作中编写它，但是我觉得它可以私下使用，因此我以OSS私有形式编写它(以便它可以用于其他私有项目等)。 stubdoc --Github 我在很短的时间内完成了它(我还有很多其他想做的事情)，所以请原谅我的粗加工(因为如果坚持下去，几天之内就不会完成了？ ？)。我想我会很快开始在工作中使用它，因此，如果我发现那里不起作用，我将不定期对其进行更新。 可以使用pip命令完成安装。 1$ pip install stubdoc如何使用-m自变量(或--module_path)是存根文件的原始模块文件的路径(因为导入是通过内部将此路径称为模块来完成的，因此在上层结构中是../指定类似根目录的/路径无效。)，指定要将文档字符串添加到-s自变量(或--stub_path)的存根文件的路径。 命令示例： 1$ stubdoc -m samples/sample.py -s out/samples/sample.pyi也可以在 或Python上处理。 12345from stubdoc import add_docstring_to_stubfile add_docstring_to_stubfile( original_module_path='sample/path.py', stub_file_path='sample/path.pyi')结果，上面示例中给出的存根文件的内容将被替换为带有docstring的内容，如下所示。 1234567891011121314151617181920212223242526272829303132333435sample_int: int def sample_func(a: int, b: str) -> bool: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit, ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Parameters ---------- a : int Lorem ipsum dolor sit amet, consectetur adipiscing elit. b : str ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Returns ------- c : bool Ut enim ad minim veniam, quis nostrud exercitation. """ class SampleClass: def __init__(self) -> None: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit. """ @property def sample_property(self) -> int: """ Lorem ipsum dolor sit amet, consectetur adipiscing elit. Returns ------- d : int ed do eiusmod tempor incididunt ut labore et dolore magna aliqua. """局限性 仅当描述 省略号实例(...)和pass关键字且函数冒号后没有换行符时才有效(该格式与mypy stubgen命令的输出结果相同)。例如，它不支持在Ellipsis实例之前具有换行符的存根文件(例如，当手动生成存根文件时)，如下所示。 123456789def sample_func(a: int, b: str) -> bool: ... class SampleClass: def __init__(self) -> None: ... @property def sample_property(self) -> int: pass另外，不支持嵌套函数等。仅针对在顶层定义的函数或类的方法。例如，未选中嵌套如下所示的函数。 12def sample_func_1(a: int, b: str) -> bool: def sample_func_2(c: list) -> None: ...参考？参考站点摘要 如何使用符合PEP 561的类型提示制作软件包 自动存根生成(存根) |
今日新闻 |
推荐新闻 |
| CopyRight 2018-2019 办公设备维修网 版权所有 豫ICP备15022753号-3 |