examples 0.1.1

Read Latest Documentation - Browse GitHub Code Repository

eXamples (AKA: xamples for SEO purposes) is a Python3 library enabling interactable, self-documentating, and self-verifying examples to be attached to Python functions using decorators.

Key Features:

• Simple and Obvious API: Simply add @examples.example(*args, **kwargs) decorators for each example you want to add to a function.
• Auto Documenting: Examples, by default, get added to your functions docstring viewable both in interactive interpreters and when using examples or pdocs.
• Signature Validating: All examples can easily be checked to ensure they match the function signature (and type annotations!) with a single call (examples.verify_all_signatures()).
• Act as Tests: Examples act as additional test cases, that can easily be verified using a single test case in your favorite test runner: (examples.test_all_examples()).

What's Missing:

• Class Support: Currently examples can only be attached to individual functions. Class and method support is planned for a future release.

Quick Start

The following guides should get you up and running with a documentation website in no time.

1. Install: pip3 install examples

2. Add Examples:

    from examples import example
   
    @example(1, 1, _example_returns=2)
    def add(number_1: int, number_2: int) -> int:
        return number_1 + number_2
   

3. Verify and test examples

    import examples
   
    examples.verify_and_test_all_examples()
   

4. Introspect examples

    import examples
   
    examples.get(add)[0].use() == 2
   

Why Create Examples?

I've always wanted a way to attach examples to functions in a way that would be re-useable for documentation, testing, and API proposes. Just like moving Python parameter types from comments into prorammatically specified and easily introspectable entities has made them more braodly useful, I hope examples can do the same for example parameters.

I hope you too find eXamples useful!

~Timothy Crosley