examples 1.0.2

阅读最新文档 - 浏览GitHub代码存储库

eXamples（又称：xamples以SEO）是一个Python3库，它使可交互、自文档化和自验证的示例成为可能。这些示例通过装饰器或通过单独的MODULE_examples.py源文件直接附加到Python函数。

主要特性

• 简单直观的API：为要添加到函数中的每个示例添加@examples.example(*args, **kwargs)装饰器。
• 自动文档化：默认情况下，示例会添加到函数的docstring中，可以在交互式解释器和使用portray或pdocs时查看。
• 签名验证：所有示例都可以通过单个调用（examples.verify_all_signatures()）轻松检查，以确保它们与函数签名（以及类型注释！）匹配。
• 作为测试：示例充当额外的测试用例，可以轻松地使用您最喜欢的测试运行器中的单个测试用例进行验证：（examples.test_all_examples()）。
• 异步兼容性：示例可以像非异步函数一样轻松地附加和测试。

缺少的功能

• 类支持：目前，示例只能附加到单个函数。计划在未来的版本中支持类和方法。

快速入门

以下指南应能帮助您在短时间内使用eXamples。

1. 安装 - TL;DR：在项目的虚拟环境中运行pip3 install examples。

2. 添加示例 - 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
   

3. 验证和测试示例 - TL;DR: 在您的项目测试用例中运行 examples.verify_and_test_examples。

    # test_my_module_with_examples.py
    from examples import verify_and_test_examples
   
    import my_module_with_examples
   
   
    def test_examples_verifying_signature():
        verify_and_test_examples(my_module_with_examples)
   

4. 内省示例 -

    import examples
   
    from my_module_with_examples import add
   
   
    examples.get_examples(add)[0].use() == 2
   

为什么创建示例？

我一直想要一种将示例附加到函数上的方法，以便在文档、测试和API提案中可重复使用。就像将Python参数类型从注释移动到类型注解一样使它们更广泛地有用一样，我希望示例也能为示例调用做到同样的效果。

希望你也觉得 eXamples 很有用！

~Timothy Crosley