2019-10-28 07:53:10 +00:00
# Eth2 Executable Python Spec (PySpec)
2019-03-27 16:28:20 +00:00
2019-10-28 07:53:10 +00:00
The executable Python spec is built from the Eth2 specification,
2019-03-27 16:43:56 +00:00
complemented with the necessary helper functions for hashing, BLS, and more.
With this executable spec,
test-generators can easily create test-vectors for client implementations,
2019-05-06 15:30:32 +00:00
and the spec itself can be verified to be consistent and coherent through sanity tests implemented with pytest.
2019-03-27 16:43:56 +00:00
2019-03-28 16:51:49 +00:00
## Building
2020-01-25 21:10:03 +00:00
To build the pyspec: `python setup.py build`
2020-01-25 00:26:10 +00:00
(or `pip install .` , but beware that ignored files will still be copied over to a temporary dir, due to pip issue 2195).
This outputs the build files to the `./build/lib/eth2spec/...` dir, and can't be used for local test running. Instead, use the dev-install as described below.
2019-03-28 16:51:49 +00:00
2020-01-25 00:26:10 +00:00
## Dev Install
2019-03-28 16:51:49 +00:00
2020-01-25 00:26:10 +00:00
All the dynamic parts of the spec are automatically built with `python setup.py pyspecdev` .
Unlike the regular install, this outputs spec files to their original source location, instead of build output only.
2019-03-28 16:51:49 +00:00
2020-01-25 00:26:10 +00:00
Alternatively, you can build a sub-set of the pyspec with the distutil command:
```bash
2020-02-15 22:40:06 +00:00
python setup.py pyspec --spec-fork=phase0 --md-doc-paths="specs/phase0/beacon-chain.md specs/phase0/fork-choice.md" --out-dir=my_spec_dir
2020-01-25 00:26:10 +00:00
```
2019-04-17 07:47:56 +00:00
## Py-tests
2020-01-25 00:26:10 +00:00
After installing, you can install the optional dependencies for testing and linting.
With makefile: `make install_test` .
Or manually: run `pip install .[testing]` and `pip install .[linting]` .
2019-04-20 01:33:15 +00:00
2019-04-17 07:47:56 +00:00
These tests are not intended for client-consumption.
2020-01-25 00:26:10 +00:00
These tests are testing the spec itself, to verify consistency and provide feedback on modifications of the spec.
However, most of the tests can be run in generator-mode, to output test vectors for client-consumption.
2019-04-17 07:47:56 +00:00
### How to run tests
#### Automated
2019-06-16 23:38:48 +00:00
Run `make test` from the root of the specs repository (after running `make install_test` if have not before).
2019-04-17 07:47:56 +00:00
#### Manual
2020-01-25 00:26:10 +00:00
From the repository root:
2019-04-17 07:47:56 +00:00
2020-01-25 00:26:10 +00:00
Install venv and install:
2019-04-17 07:47:56 +00:00
```bash
python3 -m venv venv
. venv/bin/activate
2020-01-25 00:26:10 +00:00
python setup.py pyspecdev
2019-04-17 07:47:56 +00:00
```
2020-01-25 00:26:10 +00:00
Run the test command from the `tests/core/pyspec` directory:
2019-04-17 07:47:56 +00:00
```
2019-05-08 16:14:47 +00:00
pytest --config=minimal eth2spec
2019-04-17 07:47:56 +00:00
```
2020-05-11 17:18:49 +00:00
Options:
- `--config` , to change the config. Defaults to `minimal` , can be set to `mainnet` , or other configs from the configs directory.
- `--disable-bls` , to disable BLS (only for tests that can run without)
- `--bls-type` , `milagro` or `py_ecc` (default)
2019-06-16 23:38:48 +00:00
### How to view code coverage report
Run `make open_cov` from the root of the specs repository after running `make test` to open the html code coverage report.
2019-04-17 07:47:56 +00:00
2019-03-28 16:51:49 +00:00
## Contributing
2019-03-27 16:43:56 +00:00
Contributions are welcome, but consider implementing your idea as part of the spec itself first.
The pyspec is not a replacement.
2019-04-17 07:47:56 +00:00
2019-03-27 16:43:56 +00:00
## License
2020-01-10 18:42:55 +00:00
Same as the spec itself; see [LICENSE ](../../../LICENSE ) file in the specs repository root.
