通过示例完成的测试和文档。
examples的Python项目详细描述
Read Latest Documentation-Browse GitHub Code Repository
eXamples(AKA:eXamples for SEO)是一个Python3库,支持可交互、自记录和自我验证的示例。这些示例使用decorator或通过单独的MODULE_examples.py
源文件直接附加到Python函数。在
主要特点:
- ^{str1}$简单而明显的API:为每个要添加到函数的示例添加
@examples.example(*args, **kwargs)
装饰器。在 - Auto Documenting:默认情况下,示例被添加到函数docstring中,无论是在交互式解释程序中还是在使用portray或pdocs时都可以查看。在
- Signature Validating:可以轻松检查所有示例,以确保它们与函数签名(和类型注释)匹配一次呼叫(
examples.verify_all_signatures()
)。在 - 作为测试:示例充当附加测试用例,可以使用您最喜欢的测试运行程序中的单个测试用例轻松验证这些测试用例:(
examples.test_all_examples()
)。在 - Async Compatibility:与非异步函数一样,可以附加示例并针对异步函数进行测试。在
缺少什么:
- Class Support:当前示例只能附加到单个函数。类和方法支持计划在将来的版本中使用。在
快速入门
下面的指南将帮助您尽快开始使用示例。在
- 在
Installation-TL;DR:在项目虚拟环境中运行
在pip3 install examples
。在 - 在
Adding Examples- TL;DR:添加表示每个示例的示例装饰器:
在# my_module_with_examples.py from examples import example @example(1, number_2=1, _example_returns=2) def add(number_1: int, number_2: int) -> int: return number_1 + number_2
- 在
Verify and Test Examples- TL;DR:在项目测试用例中运行
^{pr2}$ 在examples.verify_and_test_examples
。在 - 在
反省的例子-
在import examples from my_module_with_examples import add examples.get_examples(add)[0].use() == 2
为什么要创建示例?在
我一直希望有一种方法可以将示例附加到函数中,使其能够在文档、测试和API建议中重用。 就像将Python参数类型从注释移动到类型注释使它们更广泛地有用一样,我希望示例也能在示例调用中实现同样的效果。在
我希望你也发现eXamples
有用!在
~蒂莫西·克罗斯利
- 项目
标签: