Voir
Voir lets you wrap your scripts to display certain values or metrics and/or analyze their behavior. To use Voir:
- Add a file named
voirfile.pyin the current directory. - Define one or more instruments in
voirfile.py. - Run
voir script.pyinstead ofpython script.py.
Here are a few things you can do:
- Patch functions and libraries prior to running a script
- Log CPU or GPU usage
- Manipulate or log streams of data coming from the script
- Show a nifty dashboard
Functioning
An instrument is a function defined in voirfile.py that begins with instrument_, or a value in the __instruments__ dictionary of the same file. It takes one argument, the overseer, and its purpose is to do things at various points during execution. In order to do so, it is implemented as a generator function: all it has is to yield one of the overseer's phases, and the overseer will return to the instrument after that phase is finished. The overseer defines the order, so you only need to yield the phases you want to wait for.
def instrument_show_phases(ov):
yield ov.phases.init
# Voir has initialized itself. You can add command-line arguments here.
yield ov.phases.parse_args
# The command-line arguments have been parsed.
yield ov.phases.load_script
# The script has been loaded: its imports have been done, its functions defined,
# but the top level statements have not been executed. You can perform some
# manipulations prior to the script running.
yield ov.phases.run_script
# The script has finished.
yield ov.phases.finalize
Voir also logs events in the 3rd file descriptor if it is open, or to the $DATA_FD descriptor. Consequently, if you run voir script.py 3>&1 you should be able to see the list of phases.
Example
This instrument adds a --time command-line argument to Voir. When given, it will calculate the time the script took to load and import its dependencies, and then the time it took to run, and it will print out these times.
def instrument_time(ov):
yield ov.phases.init
ov.argparser.add_argument("--time", action="store_true")
yield ov.phases.parse_args
if ov.options.time:
t0 = time.time()
yield ov.phases.load_script
t1 = time.time()
print(f"Load time: {(t1 - t0) * 1000}ms")
yield ov.phases.run_script
t2 = time.time()
print(f"Run time: {(t2 - t1) * 1000}ms")
The --time argument goes BEFORE the script, so you would invoke it like this:
voir --time script.py SCRIPT_ARGUMENTS ...
1 maintainer
Metadata
1 maintainer
Release files for voir 0.2.24
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| voir-0.2.24.tar.gz | 102.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| voir-0.2.24-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 147.0 kB
Release files / voir-0.2.24.tar.gz
| Download URL | voir-0.2.24.tar.gz |
|---|---|
| Size | 102.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
36ccf92a2e969cee4c5148d139a93e2712c64b7ed487578cce3895f15ec873dd
|
|
BLAKE2b-256 checksum How to use checksums |
fb59f74bd206413de70001db37cac3979d06631166787447b6f6b43f50984904
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.
Transparency logRelease files / voir-0.2.24-py3-none-any.whl
| Download URL | voir-0.2.24-py3-none-any.whl |
|---|---|
| Size | 44.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0a6cfd0e109437e0cb05503378fb70f83f8255acc17911f89ec91ee9364ceb90
|
|
BLAKE2b-256 checksum How to use checksums |
1f95576c3133016e3b003791d3d28f2187519bb55532da7eb010b39611613218
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 2, 2026.
Transparency log
