Web3.py
Project description
Web3.py
|Join the chat at https://gitter.im/ethereum/web3.py|
|Build Status|
A Python implementation of
web3.js <https://github.com/ethereum/web3.js>
__
- Python 3.6+ support
Read more in the documentation on ReadTheDocs <http://web3py.readthedocs.io/>
. View the change log on Github <docs/releases.rst>
.
Developer Setup
.. code:: sh
git clone git@github.com:ethereum/web3.py.git cd web3.py
Please see OS-specific instructions for:
Linux <docs/README-linux.md#Developer-Setup>
__Mac <docs/README-osx.md#Developer-Setup>
__Windows <docs/README-windows.md#Developer-Setup>
__FreeBSD <docs/README-freebsd.md#Developer-Setup>
__
Then run these install commands:
.. code:: sh
virtualenv venv . venv/bin/activate pip install -e .[dev]
For different environments, you can set up multiple virtualenv
. For
example, if you want to create a venvdocs
, then you do the
following:
.. code:: sh
virtualenv venvdocs . venvdocs/bin/activate pip install -e .[docs] pip install -e .
Using Docker
If you would like to develop and test inside a Docker environment, use the sandbox container provided in the docker-compose.yml file.
To start up the test environment, run:
::
docker-compose up -d
This will build a Docker container set up with an environment to run the Python test code.
Note: This container does not have go-ethereum
installed, so you
cannot run the go-ethereum test suite.
To run the Python tests from your local machine:
::
docker-compose exec sandbox bash -c 'pytest -n 4 -f -k "not goethereum"'
You can run arbitrary commands inside the Docker container by using the
bash -c
prefix.
::
docker-compose exec sandbox bash -c ''
Or, if you would like to just open a session to the container, run:
::
docker-compose exec sandbox bash
Testing Setup
During development, you might like to have tests run on every file save.
Show flake8 errors on file change:
.. code:: sh
# Test flake8
when-changed -v -s -r -1 web3/ tests/ ens/ -c "clear; flake8 web3 tests ens && echo 'flake8 success' || echo 'error'"
You can use ``pytest-watch``, running one for every Python environment:
.. code:: sh
pip install pytest-watch
cd venv
ptw --onfail "notify-send -t 5000 'Test failure ⚠⚠⚠⚠⚠' 'python 3 test on web3.py failed'" ../tests ../web3
Or, you can run multi-process tests in one command, but without color:
.. code:: sh
# in the project root:
pytest --numprocesses=4 --looponfail --maxfail=1
# the same thing, succinctly:
pytest -n 4 -f --maxfail=1
How to Execute the Tests?
^^^^^^^^^^^^^^^^^^^^^^^^^
1. `Setup your development
environment <https://github.com/ethereum/web3.py/#developer-setup>`__.
2. Execute ``tox`` for the tests
There are multiple
`components <https://github.com/ethereum/web3.py/blob/master/.circleci/config.yml#L144>`__
of the tests. You can run test to against specific component. For
example:
.. code:: sh
# Run Tests for the Core component (for Python 3.6):
tox -e py36-core
# Run Tests for the Core component (for Python 3.7):
tox -e py37-core
If for some reason it is not working, add ``--recreate`` params.
``tox`` is good for testing against the full set of build targets. But
if you want to run the tests individually, ``pytest`` is better for
development workflow. For example, to run only the tests in one file:
.. code:: sh
pytest tests/core/gas-strategies/test_time_based_gas_price_strategy.py
Release setup
For Debian-like systems:
::
apt install pandoc
The final step before releasing is to build and test the code that will be released. There is a test script that will build and install the wheel locally, then generate a temporary virtualenv where you can do some smoke testing:
::
Branch name could be either master or a version branch - ex. v5
$ git checkout && git pull
$ make package
in another shell, navigate to the virtualenv mentioned in output of ^
load the virtualenv with the packaged trinity release
$ source package-smoke-test/bin/activate
smoke test the release
$ pip install ipython $ ipython
from web3.auto import w3 w3.isConnected() ...
Preview the upcoming release notes
$ towncrier --draft
To release a new version:
.. code:: sh
make release bump=$$VERSION_PART_TO_BUMP$$
To preview the upcoming release notes:
.. code:: sh
towncrier --draft
How to bumpversion ^^^^^^^^^^^^^^^^^^
The version format for this repo is {major}.{minor}.{patch}
for
stable, and {major}.{minor}.{patch}-{stage}.{devnum}
for unstable
(stage
can be alpha or beta).
To issue the next version in line, specify which part to bump, like
make release bump=minor
or make release bump=devnum
.
If you are in a beta version, make release bump=stage
will switch to
a stable.
To issue an unstable version when the current version is stable, specify
the new version explicitly, like
make release bump="--new-version 4.0.0-alpha.1 devnum"
.. |Join the chat at https://gitter.im/ethereum/web3.py| image:: https://badges.gitter.im/ethereum/web3.py.svg :target: https://gitter.im/ethereum/web3.py?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge .. |Build Status| image:: https://circleci.com/gh/ethereum/web3.py.svg?style=shield :target: https://circleci.com/gh/ethereum/web3.py
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.