Home

Read Latest Documentation - Browse GitHub Code Repository

eXamples (AKA: xamples for SEO) is a Python3 library enabling interactable, self-documenting, and self-verifying examples. These examples are attached directly to Python functions using decorators or via separate MODULE_examples.py source files.

Key Features:

Simple and Obvious API : Add @examples.example(*args, **kwargs) decorators for each example you want to add to a function.

: Add 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 portray or pdocs.

: Examples, by default, get added to your functions docstring viewable both in interactive interpreters and when using portray 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() ).

: All examples can easily be checked to ensure they match the function signature (and type annotations!) with a single call ( ). 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() ).

: Examples act as additional test cases, that can easily be verified using a single test case in your favorite test runner: ( ). Async Compatibility: Examples can be attached and tested as easily against async functions as non-async ones.

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 using eXamples in no time.

Installation - TL;DR: Run pip3 install examples within your projects virtual environment. Adding Examples - TL;DR: Add example decorators that represent each of your examples: # 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: run examples.verify_and_test_examples within your projects test cases. # 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 ) Introspect Examples - import examples from my_module_with_examples import add examples . get_examples ( 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 type annotations has made them more broadly useful, I hope examples can do the same for example calls.

I hope you too find eXamples useful!

~Timothy Crosley