eth2 0.0.5
Eth2 API
License: MIT
Requires Python: >=3.8, <4
Keywords: eth2,ethereum,serenity,api

.. image:: https://raw.githubusercontent.com/protolambda/eth2.py/master/docs/_static/logo.png
   :width: 100 px

``eth2``
-----------------

.. image:: https://img.shields.io/pypi/l/eth2.svg
    :target: https://pypi.python.org/pypi/eth2

.. image:: https://img.shields.io/pypi/pyversions/eth2.svg
    :target: https://pypi.python.org/pypi/eth2

.. image::  https://img.shields.io/pypi/status/eth2.svg
    :target: https://pypi.python.org/pypi/eth2

.. image:: https://img.shields.io/pypi/implementation/eth2.svg
    :target: https://pypi.python.org/pypi/eth2

.. image:: https://github.com/protolambda/eth2.py/workflows/Eth2%20API%20Python%20CI/badge.svg
    :target: https://github.com/protolambda/eth2.py/actions


**Eth2.py**: Python API interface to the `Eth2.0 API <https://github.com/ethereum/eth2.0-apis>`_.

If you are looking for the Eth2 spec, see ``eth2spec`` on `PyPi <https://pypi.org/project/eth2spec/>`_ and `GitHub <https://github.com/ethereum/eth2.0-specs>`_.

Features
---------

- Uses the excellent `httpx <https://www.python-httpx.org/>`_ library, with `support <https://www.python-httpx.org/async/>`_
  for `Trio <https://github.com/python-trio/trio>`_ and `AsyncIO <https://docs.python.org/3/library/asyncio.html>`_ async runtimes.
- Full type annotations, type hints for every API method
- Compatible with the ``eth2spec`` package types and ``remerkleable`` for SSZ.
- Through the ``eth2spec`` package, Beacon types can be configured, to use the API for testnets or other Eth2 variants.
- Extensive use of Python 3.8 ``Protocol`` typing (`PEP 544 <https://www.python.org/dev/peps/pep-0544/>`_).
  Testing has your code has never been easier, just mock the object, type-safe!.
- Easy extension and definition of API routes. The API function signatures and object types are all you need.

Example
--------

Getting started
^^^^^^^^^^^^^^^^^

.. code-block:: python

    import trio
    from eth2.models import lighthouse
    from eth2.core import ContentType
    from eth2.providers.http import Eth2HttpClient, Eth2HttpOptions

    async def start():
        # Customize this to use your Beacon endpoint
        address = 'http://localhost:4000'
        # Optionally bring in your own HTTP client
        # async with httpx.AsyncClient() as client:
        #     prov = Eth2HttpProvider(client, options=Eth2HttpOptions(api_base_url=address))
        async with Eth2HttpClient(options=Eth2HttpOptions(
                api_base_url=address,
                default_req_type=ContentType.json,
                default_resp_type=ContentType.ssz)) as prov:
            # The provider can be extended with any API model.
            await fun(prov.extended_api(lighthouse.Eth2API))
        print("done!")

    trio.run(start)


Using the API model
^^^^^^^^^^^^^^^^^^^^^

.. code-block:: python

    from eth2.models.lighthouse import Eth2API

    async def fun(api: Eth2API):
        print("fetching state!")
        data = await api.beacon.state(slot=spec.Slot(1))
        print(data.beacon_state.eth1_data)

        # Much faster than retrieving full state!
        head = await api.beacon.head()
        print(f"finalized: {head.finalized_block_root.hex()} {head.finalized_slot}")

        enr = await api.network.enr()
        print(enr)

        # Will error, the slashing is invalid, two equal headers (and no signatures ofc)
        await api.beacon.post_proposer_slashing(spec.ProposerSlashing())


Advanced API calls
^^^^^^^^^^^^^^^^^^^^

When you need to tweak individual API call settings

.. code-block:: python

    from eth2.core import ContentType, APIEndpointFn
    from eth2.models.lighthouse import Eth2API, APIState

    async def advanced(api: Eth2API):
        # Make a copy of the callable function, to then change its settings
        fn = APIEndpointFn(api.beacon.state)
        fn.resp_type = ContentType.json  # Instead of default ssz, because why not

        # The most inefficient way to retrieve finalized checkpoint.
        # Full state, as json.
        # But hey, access any data, and process with the spec as you like.
        data: APIState = await fn(slot=spec.Slot(300))
        print(data.beacon_state.finalized_checkpoint)

Defining custom models
^^^^^^^^^^^^^^^^^^^^^^^^

The HTTP provider can "learn" how to use a model of routes, on the fly! No need to hardcode any API calls.
Just define the model as a Pytho 3.8 Protocol. The Eth2 API provider will shadow this model with an implementation.

- Any ``Protocol`` class with annotations can be interpreted as route model. Fields are sub-routes.
- ``api()`` decorator to make function calls usable endpoints. Customize endpoint options if you need.
- ``var_path()`` decorator to make function calls construct dynamic paths

Currently the Lighthouse API model is well supported, and the new standard-API is being experimented with, but incomplete.


Project Links
--------------

- Docs: https://eth2py.readthedocs.io/
- Changelog: https://eth2py.readthedocs.io/en/latest/changelog.html
- PyPI: https://pypi.python.org/pypi/eth2
- Issues: https://github.com/protolambda/eth2.py/issues


Contact
--------

Author: `@protolambda <https://github.com/protolambda>`_

License
--------

MIT, see `LICENSE <./LICENSE>`_ file.