status-im
/
eth2.0-specs
mirror of https://github.com/status-im/eth2.0-specs.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #2346 from ethereum/pyspecdocs 

update pyspec dev usage docs, improve makefile
This commit is contained in:
Alex Stokes 2021-04-22 08:30:44 -07:00 committed by GitHub
parent 9c189ffc4b 1c8f56c84b
commit b0aee5b271
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 56 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
Makefile
View File

@ -2,7 +2,10 @@ SPEC_DIR = ./specs
SSZ_DIR = ./ssz
TEST_LIBS_DIR = ./tests/core
TEST_GENERATORS_DIR = ./tests/generators
# The working dir during testing
PY_SPEC_DIR = $(TEST_LIBS_DIR)/pyspec
ETH2SPEC_MODULE_DIR = $(PY_SPEC_DIR)/eth2spec
TEST_REPORT_DIR = $(PY_SPEC_DIR)/test-reports
TEST_VECTOR_DIR = ../eth2.0-spec-tests/tests
GENERATOR_DIR = ./tests/generators
SOLIDITY_DEPOSIT_CONTRACT_DIR = ./solidity_deposit_contract
@ -27,7 +30,8 @@ MARKDOWN_FILES = $(wildcard $(SPEC_DIR)/phase0/*.md) $(wildcard $(SPEC_DIR)/alta
$(wildcard $(SPEC_DIR)/sharding/*.md)
COV_HTML_OUT=.htmlcov
COV_INDEX_FILE=$(PY_SPEC_DIR)/$(COV_HTML_OUT)/index.html
COV_HTML_OUT_DIR=$(PY_SPEC_DIR)/$(COV_HTML_OUT)
COV_INDEX_FILE=$(COV_HTML_OUT_DIR)/index.html
CURRENT_DIR = ${CURDIR}
LINTER_CONFIG_FILE = $(CURRENT_DIR)/linter.ini
@ -53,17 +57,17 @@ partial_clean:
rm -f .coverage
rm -rf $(PY_SPEC_DIR)/.pytest_cache
rm -rf $(DEPOSIT_CONTRACT_TESTER_DIR)/.pytest_cache
rm -rf $(PY_SPEC_DIR)/phase0
rm -rf $(PY_SPEC_DIR)/altair
rm -rf $(PY_SPEC_DIR)/merge
rm -rf $(PY_SPEC_DIR)/$(COV_HTML_OUT)
rm -rf $(PY_SPEC_DIR)/.coverage
rm -rf $(PY_SPEC_DIR)/test-reports
rm -rf $(ETH2SPEC_MODULE_DIR)/phase0
rm -rf $(ETH2SPEC_MODULE_DIR)/altair
rm -rf $(ETH2SPEC_MODULE_DIR)/merge
rm -rf $(COV_HTML_OUT_DIR)
rm -rf $(TEST_REPORT_DIR)
rm -rf eth2spec.egg-info dist build
rm -rf build
clean: partial_clean
rm -rf venv
# legacy cleanup. The pyspec venv should be located at the repository root
rm -rf $(PY_SPEC_DIR)/venv
rm -rf $(DEPOSIT_CONTRACT_COMPILER_DIR)/venv
rm -rf $(DEPOSIT_CONTRACT_TESTER_DIR)/venv
@ -88,7 +92,7 @@ pyspec:
# installs the packages to run pyspec tests
install_test:
python3 -m venv venv; . venv/bin/activate; python3 -m pip install .[lint]; python3 -m pip install -e .[test]
python3 -m venv venv; . venv/bin/activate; python3 -m pip install -e .[lint]; python3 -m pip install -e .[test]
test: pyspec
. venv/bin/activate; cd $(PY_SPEC_DIR); \

67
tests/core/pyspec/README.md
View File

@ -7,27 +7,30 @@ With this executable spec,
test-generators can easily create test-vectors for client implementations,
and the spec itself can be verified to be consistent and coherent through sanity tests implemented with pytest.
## Building
To build the pyspec: `python setup.py build`
(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.
## Dev Install
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.
First, create a `venv` and install the developer dependencies (`test` and `lint` extras):
Alternatively, you can build a sub-set of the pyspec with the distutil command:
```bash
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
```shell
make install_test
```
## Py-tests
All the dynamic parts of the spec are built with:
After installing, you can install the optional dependencies for testing and linting.
With makefile: `make install_test`.
Or manually: run `pip install .[test]` and `pip install .[lint]`.
```shell
(venv) python setup.py pyspecdev
```
Unlike the regular install, this outputs spec files to their intended source location,
to enable debuggers to navigate between packages and generated code, without fragile directory linking.
By default, when installing the `eth2spec` as package in non-develop mode,
the distutils implementation of the `setup` runs `build`, which is extended to run the same `pyspec` work,
but outputs into the standard `./build/lib` output.
This enables the `eth2.0-specs` repository to be installed like any other python package.
## Py-tests
These tests are not intended for client-consumption.
These tests are testing the spec itself, to verify consistency and provide feedback on modifications of the spec.
@ -39,20 +42,32 @@ However, most of the tests can be run in generator-mode, to output test vectors
Run `make test` from the root of the specs repository (after running `make install_test` if have not before).
Note that the `make` commands run through the build steps: it runs the `build` output, not the local package source files.
#### Manual
From the repository root:
See `Dev install` for test pre-requisites.
Install venv and install:
```bash
python3 -m venv venv
. venv/bin/activate
python setup.py pyspecdev
Tests are built for `pytest`.
Caveats:
- Working directory must be `./tests/core/pyspec`. The work-directory is important to locate eth2 configuration files.
- Run `pytest` as module. It avoids environment differences, and the behavior is different too:
`pytest` as module adds the current directory to the `sys.path`
Full test usage, with explicit configuration for illustration of options usage:
```shell
(venv) python -m pytest --config=minimal eth2spec
```
Run the test command from the `tests/core/pyspec` directory:
Or, to run a specific test file, specify the full path:
```shell
(venv) python -m pytest --config=minimal ./eth2spec/test/phase0/block_processing/test_process_attestation.py
```
pytest --config=minimal eth2spec
Or, to run a specific test function (specify the `eth2spec` module, or the script path if the keyword is ambiguous):
```shell
(venv) python -m pytest --config=minimal -k test_success_multi_proposer_index_iterations eth2spec
```
Options:
@ -64,6 +79,12 @@ Options:
Run `make open_cov` from the root of the specs repository after running `make test` to open the html code coverage report.
### Advanced
Building spec files from any markdown sources, to a custom location:
```bash
(venv) 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
```
## Contributing