<!– Check that we have byexample installed first $ hash byexample # byexample: +fail-fast
–>
byexample
byexample is a literate programming engine where you mix ordinary text and snippets of code in the same file and then you execute them as regression tests.
Do not <i>write</i> tests: write what you want, what do you expect, make examples of them. Let byexample <b>turn them</b> in your tests.
You can always be <b>sure</b> that the examples are correct and your documentation is up to date!
Usage
You write your documentation with examples in a Markdown or other text file.
Then, you run byexample from the command line selecting which language or languages you want to run: Python, Ruby, Shell and C/C++ to mention a few.
And yes, you can write examples in different languages in the same file. Combine them to combine their strengths and make your life easier.
That’s all. byexample will compare the output of the examples with the expected ones and it will show any difference.
How do I get started?
First, you need to install it:
$ pip install byexample # install it # byexample: +skip
Or if you prefer, you can install it inside a virtual env.
If you don’t have pip or python installed, check the download page.
That’s it! Now, write a tutorial, a blog or a how-to and put some examples in between (like this README.md that you are reading); All the snippets and examples will be collected, executed and checked.
$ byexample -l python,ruby,shell README.md # run it # byexample: +skip [PASS] Pass: <...> Fail: <...> Skip: <...>
Several languages are supported like Python, Ruby and C++ along with others.
Take at look at the official web page: https://byexamples.github.io
Some quick links:
Languages supported
Currently we support:
More languages will be supported in the future. Stay tuned.
Currently unsupported:
Help is needed!
Platforms supported
Linux is the preferable choice as it is very well tested.
Since 9.2.1 macOS is also supported for the testing is more limited and it is expected to have little variations from Linux.
You can even run byexample in Windows** using Windows Subsystem for Linux but keep in mind that the testing is even more limited; a native execution in Windows (outside of WSL) is currently not supported.
Contributing
First off, thanks for using and considering contributing to byexample.
We love to receive contributions from our community. There are tons of ways you can contribute
add support to new languages (Javascript, Julia, just listen to you heart). Check this how to.
misspelling? Improve to the documentation is more than welcome.
add more examples. How do you use byexample? Give us your feedback!
is byexample producing a hard-to-debug diff or you found a bug? Create an issue in github.
But don’t be limited to those options. We keep our mind open to other useful contributions: write a tutorial or a blog, feature requests, social media…
Check out our CONTRIBUTING guidelines and welcome!
Extend byexample
It is possible to extend byexample adding new ways to find examples in a document and/or to parse and run/interpret a new language or adding hooks to be called regardless of the language/interpreter.
Check out how to support new finders and languages and how to hook to events with concerns for a quick tutorials that shows exactly how to do that.
You could also share your work and contribute to byexample with your extensions.
Versioning
We use semantic version for the core or engine.
For each module we have the following categorization:
experimental: non backward compatibility changes are possible or even removal between versions (even patch versions).
provisional: low impact non backward compatibility changes may occur between versions; but in general a change like that will happen only between major versions.
stable: non backward compatibility changes, if happen, they will between major versions.
deprecated: it will disappear in a future version.
unsupported: it may work but currently it is not possible to offer any guarantees. Contributions from the community are needed!
See the latest releases and tags and the changelog
Current version:
$ byexample -V
byexample 11.0.0 (Python <...>) - GNU GPLv3
<...>
Copyright (C) Di Paola Martin - https://byexamples.github.io
<...>License
This project is licensed under GPLv3
$ head -n 2 LICENSE # byexample: +norm-ws
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007See LICENSE for more details.
1 maintainer
Release files for byexample 11.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| byexample-11.0.0.tar.gz | 142.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| byexample-11.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 319.8 kB
Release files / byexample-11.0.0.tar.gz
| Download URL | byexample-11.0.0.tar.gz |
|---|---|
| Size | 142.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a89a82d7ea652a4a848e6c38229daa2de726f4e9731908986821a34d1737310a
|
|
BLAKE2b-256 checksum How to use checksums |
ab19999a8d4f8ad6e4b00965f49caee34b617a756bc2d3c5dbb5167f6cb0ae90
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.0.1 CPython/3.11.11
|
Release files / byexample-11.0.0-py3-none-any.whl
| Download URL | byexample-11.0.0-py3-none-any.whl |
|---|---|
| Size | 177.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6518c5f10bbf477017973005ea6dfaa8d96ba5d55a2ff996b4a50991e8c895b8
|
|
BLAKE2b-256 checksum How to use checksums |
d4250c59c7be26c0e7e89eddabcbc9872661514c928a0a3de40426bc4adac705
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.0.1 CPython/3.11.11
|
