Safe-eth-py (previously known as Gnosis-py)
###########################################
.. class:: no-web no-pdf
|ci| |coveralls| |python| |django| |pipy| |readthedocs| |black|
Safe-eth-py includes a set of libraries to work with Ethereum and relevant Ethereum projects:
- `EthereumClient`, a wrapper over Web3.py `Web3` client including utilities to deal with ERC20/721
tokens and tracing.
- `Safe <https://github.com/safe-global/safe-contracts>`_ classes and utilities.
- Price oracles for `Uniswap`, `Kyber`...
- Django serializers, models and utils.
Quick start
-----------
Just run ``pip install safe-eth-py`` or add it to your **requirements.txt**
If you want django ethereum utils (models, serializers, filters...) you need to run
``pip install safe-eth-py[django]``
If you have issues building **coincurve** maybe
`you are missing some libraries <https://ofek.dev/coincurve/install/#source>`_
Contributing to safe-eth-py
---------------------------
Clone the repo, then to set it up:
.. code-block:: bash
python -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt
pre-commit install -f
Add new address for new chains
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to add Safe Smart Account support for a new chain you must `open a new issue <https://github.com/safe-global/safe-eth-py/issues/new?assignees=&labels=add-new-address&projects=&template=add_safe_address_new_chain.yml&title=%5BNew+chain%5D%3A+%7Bchain+name%7D>`_.
Once the issue is created or edited, an automatic validation will be executed and a **Pull Request** will be created if everything is ok. Finally, the Safe team will review and merge the automatic **Pull Request** generated from the issue.
Ethereum utils
--------------
safe_eth.eth
~~~~~~~~~~~~
- ``class EthereumClient (ethereum_node_url: str)``: Class to connect and do operations
with an ethereum node. Uses web3 and raw rpc calls for things not supported in web3.
Only ``http/https`` urls are supported for the node url.
``EthereumClient`` has some utils that improve a lot performance using Ethereum nodes, like
the possibility of doing ``batch_calls`` (a single request making read-only calls to multiple contracts):
.. code-block:: python
from safe_eth.eth import EthereumClient
from safe_eth.eth.contracts import get_erc721_contract
ethereum_client = EthereumClient(ETHEREUM_NODE_URL)
erc721_contract = get_erc721_contract(self.w3, token_address)
name, symbol = ethereum_client.batch_call([
erc721_contract.functions.name(),
erc721_contract.functions.symbol(),
])
If you want to use the underlying `web3.py <https://github.com/ethereum/web3.py>`_ library:
.. code-block:: python
from safe_eth.eth import EthereumClient
ethereum_client = EthereumClient(ETHEREUM_NODE_URL)
ethereum_client.w3.eth.get_block(57)
safe_eth.eth.constants
~~~~~~~~~~~~~~~~~~~~~~
- ``NULL_ADDRESS (0x000...0)``: Solidity ``address(0)``.
- ``SENTINEL_ADDRESS (0x000...1)``: Used for Safe's linked lists (modules, owners...).
- Maximum and minimum values for `R`, `S` and `V` in ethereum signatures.
safe_eth.eth.oracles
~~~~~~~~~~~~~~~~~~~~
Price oracles for Uniswap, UniswapV2, Kyber, SushiSwap, Aave, Balancer, Curve, Mooniswap, Yearn...
Example:
.. code-block:: python
from safe_eth.eth import EthereumClient
from safe_eth.eth.oracles import UniswapV2Oracle
ethereum_client = EthereumClient(ETHEREUM_NODE_URL)
uniswap_oracle = UniswapV2Oracle(ethereum_client)
gno_token_mainnet_address = '0x6810e776880C02933D47DB1b9fc05908e5386b96'
weth_token_mainnet_address = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
price = uniswap_oracle.get_price(gno_token_mainnet_address, uniswap_oracle.weth_address)
safe_eth.eth.utils
~~~~~~~~~~~~~~~~~~
Contains utils for ethereum operations:
- ``mk_contract_address_2(from_: Union[str, bytes], salt: Union[str, bytes], init_code: [str, bytes]) -> str``:
Calculates the address of a new contract created using the new CREATE2 opcode.
Ethereum django (REST) utils
----------------------------
Django utils are available under ``safe_eth.eth.django``.
You can find a set of helpers for working with Ethereum using Django and Django Rest framework.
It includes:
- **safe_eth.eth.django.filters**: EthereumAddressFilter.
- **safe_eth.eth.django.models**: Model fields (Ethereum address, Ethereum big integer field).
- **safe_eth.eth.django.serializers**: Serializer fields (Ethereum address field, hexadecimal field).
- **safe_eth.eth.django.validators**: Ethereum related validators.
- **safe_eth.safe.serializers**: Serializers for Safe (signature, transaction...).
- All the tests are written using Django Test suite.
Safe APIs
--------------
safe_eth.safe.api
~~~~~~~~~~~~~~~~~
Interaction with the Safe Transaction Service API to manage Safes, transactions, delegates, and messages.
To use the default Transaction Service, you need an API key. You can set this API key either as an environment variable
or pass it directly to the constructor using the `api_key` parameter. To obtain your API key, create an account on the
Safe Developer Portal at https://developer.safe.global. Additionally, you can choose to use a custom service by setting
the `base_url` parameter, the API key may not be required.
.. code-block:: bash
export SAFE_TRANSACTION_SERVICE_API_KEY=[api-key-jwt-token-value]
Example:
.. code-block:: python
from safe_eth.eth import EthereumNetwork
from safe_eth.safe.api import TransactionServiceApi
transaction_service_api = TransactionServiceApi(EthereumNetwork.GNOSIS)
transactions = transaction_service_api.get_transactions("0xAedF684C1c41B51CbD228116e11484425d2FACB9")
Contributors
------------
`See contributors <https://github.com/safe-global/safe-eth-py/graphs/contributors>`_
.. |ci| image:: https://github.com/safe-global/safe-eth-py/actions/workflows/python.yml/badge.svg
:alt: Github Actions CI build
.. |coveralls| image:: https://coveralls.io/repos/github/safe-global/safe-eth-py/badge.svg
:target: https://coveralls.io/github/safe-global/safe-eth-py
.. |python| image:: https://img.shields.io/badge/Python-3.13-blue.svg
:alt: Python 3.13
.. |django| image:: https://img.shields.io/badge/Django-5-blue.svg
:alt: Django 5
.. |pipy| image:: https://badge.fury.io/py/safe-eth-py.svg
:target: https://badge.fury.io/py/safe-eth-py
:alt: Pypi package
.. |readthedocs| image:: https://readthedocs.org/projects/safe-eth-py/badge/?version=latest
:target: https://safe-eth-py.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Black
Raw data
{
"_id": null,
"home_page": null,
"name": "safe-eth-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "cowswap, django, ethereum, gnosis, safe, safe_eth, web3",
"author": null,
"author_email": "Ux\u00edo <uxio@safe.global>",
"download_url": "https://files.pythonhosted.org/packages/26/e7/22bf427935cc0cd7df605d67d0beb2e853c4cfbbbe847c3d3abf5e4b9e11/safe_eth_py-7.7.0.tar.gz",
"platform": null,
"description": "Safe-eth-py (previously known as Gnosis-py)\n###########################################\n\n.. class:: no-web no-pdf\n\n|ci| |coveralls| |python| |django| |pipy| |readthedocs| |black|\n\nSafe-eth-py includes a set of libraries to work with Ethereum and relevant Ethereum projects:\n - `EthereumClient`, a wrapper over Web3.py `Web3` client including utilities to deal with ERC20/721\n tokens and tracing.\n - `Safe <https://github.com/safe-global/safe-contracts>`_ classes and utilities.\n - Price oracles for `Uniswap`, `Kyber`...\n - Django serializers, models and utils.\n\nQuick start\n-----------\n\nJust run ``pip install safe-eth-py`` or add it to your **requirements.txt**\n\nIf you want django ethereum utils (models, serializers, filters...) you need to run\n``pip install safe-eth-py[django]``\n\nIf you have issues building **coincurve** maybe\n`you are missing some libraries <https://ofek.dev/coincurve/install/#source>`_\n\n\nContributing to safe-eth-py\n---------------------------\nClone the repo, then to set it up:\n\n.. code-block:: bash\n\n python -m venv venv\n source venv/bin/activate\n pip install -r requirements-dev.txt\n pre-commit install -f\n\nAdd new address for new chains\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\nIf you want to add Safe Smart Account support for a new chain you must `open a new issue <https://github.com/safe-global/safe-eth-py/issues/new?assignees=&labels=add-new-address&projects=&template=add_safe_address_new_chain.yml&title=%5BNew+chain%5D%3A+%7Bchain+name%7D>`_.\n\nOnce the issue is created or edited, an automatic validation will be executed and a **Pull Request** will be created if everything is ok. Finally, the Safe team will review and merge the automatic **Pull Request** generated from the issue.\n\nEthereum utils\n--------------\nsafe_eth.eth\n~~~~~~~~~~~~\n- ``class EthereumClient (ethereum_node_url: str)``: Class to connect and do operations\n with an ethereum node. Uses web3 and raw rpc calls for things not supported in web3.\n Only ``http/https`` urls are supported for the node url.\n\n``EthereumClient`` has some utils that improve a lot performance using Ethereum nodes, like\nthe possibility of doing ``batch_calls`` (a single request making read-only calls to multiple contracts):\n\n.. code-block:: python\n\n from safe_eth.eth import EthereumClient\n from safe_eth.eth.contracts import get_erc721_contract\n ethereum_client = EthereumClient(ETHEREUM_NODE_URL)\n erc721_contract = get_erc721_contract(self.w3, token_address)\n name, symbol = ethereum_client.batch_call([\n erc721_contract.functions.name(),\n erc721_contract.functions.symbol(),\n ])\n\nIf you want to use the underlying `web3.py <https://github.com/ethereum/web3.py>`_ library:\n\n.. code-block:: python\n\n from safe_eth.eth import EthereumClient\n ethereum_client = EthereumClient(ETHEREUM_NODE_URL)\n ethereum_client.w3.eth.get_block(57)\n\n\nsafe_eth.eth.constants\n~~~~~~~~~~~~~~~~~~~~~~\n- ``NULL_ADDRESS (0x000...0)``: Solidity ``address(0)``.\n- ``SENTINEL_ADDRESS (0x000...1)``: Used for Safe's linked lists (modules, owners...).\n- Maximum and minimum values for `R`, `S` and `V` in ethereum signatures.\n\nsafe_eth.eth.oracles\n~~~~~~~~~~~~~~~~~~~~\nPrice oracles for Uniswap, UniswapV2, Kyber, SushiSwap, Aave, Balancer, Curve, Mooniswap, Yearn...\nExample:\n\n.. code-block:: python\n\n from safe_eth.eth import EthereumClient\n from safe_eth.eth.oracles import UniswapV2Oracle\n ethereum_client = EthereumClient(ETHEREUM_NODE_URL)\n uniswap_oracle = UniswapV2Oracle(ethereum_client)\n gno_token_mainnet_address = '0x6810e776880C02933D47DB1b9fc05908e5386b96'\n weth_token_mainnet_address = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'\n price = uniswap_oracle.get_price(gno_token_mainnet_address, uniswap_oracle.weth_address)\n\n\n\nsafe_eth.eth.utils\n~~~~~~~~~~~~~~~~~~\n\nContains utils for ethereum operations:\n\n- ``mk_contract_address_2(from_: Union[str, bytes], salt: Union[str, bytes], init_code: [str, bytes]) -> str``:\n Calculates the address of a new contract created using the new CREATE2 opcode.\n\nEthereum django (REST) utils\n----------------------------\nDjango utils are available under ``safe_eth.eth.django``.\nYou can find a set of helpers for working with Ethereum using Django and Django Rest framework.\n\nIt includes:\n\n- **safe_eth.eth.django.filters**: EthereumAddressFilter.\n- **safe_eth.eth.django.models**: Model fields (Ethereum address, Ethereum big integer field).\n- **safe_eth.eth.django.serializers**: Serializer fields (Ethereum address field, hexadecimal field).\n- **safe_eth.eth.django.validators**: Ethereum related validators.\n- **safe_eth.safe.serializers**: Serializers for Safe (signature, transaction...).\n- All the tests are written using Django Test suite.\n\n\nSafe APIs\n--------------\nsafe_eth.safe.api\n~~~~~~~~~~~~~~~~~\nInteraction with the Safe Transaction Service API to manage Safes, transactions, delegates, and messages.\n\nTo use the default Transaction Service, you need an API key. You can set this API key either as an environment variable\nor pass it directly to the constructor using the `api_key` parameter. To obtain your API key, create an account on the\nSafe Developer Portal at https://developer.safe.global. Additionally, you can choose to use a custom service by setting\nthe `base_url` parameter, the API key may not be required.\n\n.. code-block:: bash\n\n export SAFE_TRANSACTION_SERVICE_API_KEY=[api-key-jwt-token-value]\n\nExample:\n\n.. code-block:: python\n\n from safe_eth.eth import EthereumNetwork\n from safe_eth.safe.api import TransactionServiceApi\n\n transaction_service_api = TransactionServiceApi(EthereumNetwork.GNOSIS)\n transactions = transaction_service_api.get_transactions(\"0xAedF684C1c41B51CbD228116e11484425d2FACB9\")\n\nContributors\n------------\n`See contributors <https://github.com/safe-global/safe-eth-py/graphs/contributors>`_\n\n.. |ci| image:: https://github.com/safe-global/safe-eth-py/actions/workflows/python.yml/badge.svg\n :alt: Github Actions CI build\n\n.. |coveralls| image:: https://coveralls.io/repos/github/safe-global/safe-eth-py/badge.svg\n :target: https://coveralls.io/github/safe-global/safe-eth-py\n\n.. |python| image:: https://img.shields.io/badge/Python-3.13-blue.svg\n :alt: Python 3.13\n\n.. |django| image:: https://img.shields.io/badge/Django-5-blue.svg\n :alt: Django 5\n\n.. |pipy| image:: https://badge.fury.io/py/safe-eth-py.svg\n :target: https://badge.fury.io/py/safe-eth-py\n :alt: Pypi package\n\n.. |readthedocs| image:: https://readthedocs.org/projects/safe-eth-py/badge/?version=latest\n :target: https://safe-eth-py.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Black\n",
"bugtrack_url": null,
"license": null,
"summary": "Safe Ecosystem Foundation utilities for Ethereum projects",
"version": "7.7.0",
"project_urls": {
"Documentation": "https://safe-eth-py.readthedocs.io/en/latest/",
"Homepage": "https://github.com/safe-global/safe-eth-py",
"Source": "https://github.com/safe-global/safe-eth-py",
"Tracker": "https://github.com/safe-global/safe-eth-py/issues"
},
"split_keywords": [
"cowswap",
" django",
" ethereum",
" gnosis",
" safe",
" safe_eth",
" web3"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6aa2da7fcc4f27614ab18ea3d4299f7ccf3e8e771fd02a7def1f1fdd69682c79",
"md5": "aac8f1f273447bb0c817252f2b4c3690",
"sha256": "328262b0ae50e583538e1498f5df625f876442d139eedec458a3f57d3f8a38d2"
},
"downloads": -1,
"filename": "safe_eth_py-7.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "aac8f1f273447bb0c817252f2b4c3690",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 913306,
"upload_time": "2025-07-09T12:19:58",
"upload_time_iso_8601": "2025-07-09T12:19:58.818039Z",
"url": "https://files.pythonhosted.org/packages/6a/a2/da7fcc4f27614ab18ea3d4299f7ccf3e8e771fd02a7def1f1fdd69682c79/safe_eth_py-7.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "26e722bf427935cc0cd7df605d67d0beb2e853c4cfbbbe847c3d3abf5e4b9e11",
"md5": "c86c097761ad5cd722ff5d61158d5bbe",
"sha256": "469df796f6a01c93bd79f9814c627acae565e70032811f6e39bb10c44eaf3fa3"
},
"downloads": -1,
"filename": "safe_eth_py-7.7.0.tar.gz",
"has_sig": false,
"md5_digest": "c86c097761ad5cd722ff5d61158d5bbe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 800942,
"upload_time": "2025-07-09T12:20:00",
"upload_time_iso_8601": "2025-07-09T12:20:00.939406Z",
"url": "https://files.pythonhosted.org/packages/26/e7/22bf427935cc0cd7df605d67d0beb2e853c4cfbbbe847c3d3abf5e4b9e11/safe_eth_py-7.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-09 12:20:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "safe-global",
"github_project": "safe-eth-py",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "django",
"specs": [
[
"==",
"5.1.10"
]
]
},
{
"name": "django-filter",
"specs": [
[
"==",
"25.1"
]
]
},
{
"name": "djangorestframework",
"specs": [
[
"==",
"3.16.0"
]
]
},
{
"name": "hexbytes",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "packaging",
"specs": []
},
{
"name": "psycopg",
"specs": [
[
"==",
"3.2.9"
]
]
},
{
"name": "py-evm",
"specs": [
[
"==",
"0.12.1b1"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.4"
]
]
},
{
"name": "safe-pysha3",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "web3",
"specs": [
[
"==",
"7.12.0"
]
]
}
],
"lcname": "safe-eth-py"
}
JSON
