# eth-pydantic-types
The types in this package are pydantic types for Ethereum inspired from [eth-typing](https://github.com/ethereum/eth-typing/blob/master/eth_typing/evm.py).
## HexStr
When your model involves a string serializes to a hex-str, `HexStr` is the type to use.
Examples of `HexStr` might be a hash.
Use `HexStr` in your models:
```python
from pydantic import BaseModel
from eth_pydantic_types import HexStr, HexStr32
class TransactionData(BaseModel):
hash_any_size: HexStr
sized_hash: HexStr32
data = TransactionData(hash_any_size="0x123", sized_hash="0x000123")
assert isinstance(data.nonce, str)
assert isinstance(data.gas, str)
```
## HexBytes
When your model involves bytes that serialize to a hex-str, `HexBytes` is the type to use.
Examples of `HexBytes` might be a hash.
Use `HexBytes` in your models:
```python
from pydantic import BaseModel
from eth_pydantic_types import HexBytes, HexBytes32
class TransactionData(BaseModel):
hash_any_size: HexBytes
sized_hash: HexBytes32
data = TransactionData(hash_any_size="0x123", sized_hash="0x000123")
assert isinstance(data.nonce, str)
assert isinstance(data.gas, str)
```
## HexInt
When your model involves an integer that serializes to a hex-str, `HexInt` is the type to use.
Examples of `HexInt` are transaction-type, nonce, and gas values.
Use `HexInt` in your models:
```python
from pydantic import BaseModel
from eth_pydantic_types import HexInt
class TransactionData(BaseModel):
nonce: HexInt
gas: HexInt
data = TransactionData(nonce="0x123", gas="0x000123")
assert isinstance(data.nonce, int)
assert isinstance(data.gas, int)
```
## Address
Use the Address class for working with checksummed-addresses.
Addresses get validated and checksummed in model construction.
Addresses serialize to `str` in the Pydantic core schema and `string` in the JSON schema with a binary format.
```python
from pydantic import BaseModel
from eth_pydantic_types import Address
class Account(BaseModel):
address: Address
# NOTE: The address ends up checksummed
# ("0x0837207e343277CBd6c114a45EC0e9Ec56a1AD84")
account = Account(address="0x837207e343277cbd6c114a45ec0e9ec56a1ad84")
```
## HexStr
Use hex str when you only care about un-sized hex strings.
The `HexStr` type serializes to `str` in the Pydantic core schema and a `string` in the JSON schema with a binary format.
```python
from eth_pydantic_types import HexStr
from pydantic import BaseModel
class Tx(BaseModel):
data: HexStr
tx = Tx(data="0x0123")
```
## Bip122Uri
Use BIP-122 URIs in your models by annotating with the `Bip122Uri` type.
This type serializes to a `str` in the Pydantic core schema as well as a `string` in the JSON schema, however the individual hashes are validated.
```python
from eth_pydantic_types import Bip122Uri
from pydantic import BaseModel
class Message(BaseModel):
path: Bip122Uri
message = Message(
path=(
"blockchain://d4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3"
"/block/752820c0ad7abc1200f9ad42c4adc6fbb4bd44b5bed4667990e64565102c1ba6"
)
)
```
## Padding
For types like `HexStr` or `HexBytes`, you can control the padding by using `@field_validator()`.
```python
from pydantic import BaseModel, field_validator
from eth_pydantic_types import HexStr20, HexBytes20
from eth_pydantic_types.utils import Pad
class MyModel(BaseModel):
my_str: HexStr20
my_bytes: HexBytes20
@field_validator("my_str", "my_bytes", mode="before")
@classmethod
def validate_value(cls, value, info):
field_type = cls.model_fields[info.field_name].annotation
return field_type.__eth_pydantic_validate__(value, pad=Pad.RIGHT)
```
Else, by default, if you validate integer values, it will pad left.
Other inputs pad right.
This mirrors Solidity types, like `bytes32`, that automatically pad-right when given smaller values.
Integer and address types automatically pad-left.
Raw data
{
"_id": null,
"home_page": "https://github.com/ApeWorX/eth-pydantic-types",
"name": "eth-pydantic-types",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": null,
"keywords": "ethereum",
"author": "ApeWorX Ltd.",
"author_email": "admin@apeworx.io",
"download_url": "https://files.pythonhosted.org/packages/0a/c4/304928d02331fc69107fa089d7b503fb3f0baa241470b48cabe9109e5bb8/eth_pydantic_types-0.2.2.tar.gz",
"platform": null,
"description": "# eth-pydantic-types\n\nThe types in this package are pydantic types for Ethereum inspired from [eth-typing](https://github.com/ethereum/eth-typing/blob/master/eth_typing/evm.py).\n\n## HexStr\n\nWhen your model involves a string serializes to a hex-str, `HexStr` is the type to use.\nExamples of `HexStr` might be a hash.\n\nUse `HexStr` in your models:\n\n```python\nfrom pydantic import BaseModel\nfrom eth_pydantic_types import HexStr, HexStr32\n\nclass TransactionData(BaseModel):\n hash_any_size: HexStr\n sized_hash: HexStr32\n\ndata = TransactionData(hash_any_size=\"0x123\", sized_hash=\"0x000123\")\nassert isinstance(data.nonce, str)\nassert isinstance(data.gas, str)\n```\n\n## HexBytes\n\nWhen your model involves bytes that serialize to a hex-str, `HexBytes` is the type to use.\nExamples of `HexBytes` might be a hash.\n\nUse `HexBytes` in your models:\n\n```python\nfrom pydantic import BaseModel\nfrom eth_pydantic_types import HexBytes, HexBytes32\n\nclass TransactionData(BaseModel):\n hash_any_size: HexBytes\n sized_hash: HexBytes32\n\ndata = TransactionData(hash_any_size=\"0x123\", sized_hash=\"0x000123\")\nassert isinstance(data.nonce, str)\nassert isinstance(data.gas, str)\n```\n\n## HexInt\n\nWhen your model involves an integer that serializes to a hex-str, `HexInt` is the type to use.\nExamples of `HexInt` are transaction-type, nonce, and gas values.\n\nUse `HexInt` in your models:\n\n```python\nfrom pydantic import BaseModel\nfrom eth_pydantic_types import HexInt\n\nclass TransactionData(BaseModel):\n nonce: HexInt\n gas: HexInt\n\ndata = TransactionData(nonce=\"0x123\", gas=\"0x000123\")\nassert isinstance(data.nonce, int)\nassert isinstance(data.gas, int)\n```\n\n## Address\n\nUse the Address class for working with checksummed-addresses.\nAddresses get validated and checksummed in model construction.\nAddresses serialize to `str` in the Pydantic core schema and `string` in the JSON schema with a binary format.\n\n```python\nfrom pydantic import BaseModel\nfrom eth_pydantic_types import Address\n\nclass Account(BaseModel):\n address: Address\n\n# NOTE: The address ends up checksummed\n# (\"0x0837207e343277CBd6c114a45EC0e9Ec56a1AD84\")\naccount = Account(address=\"0x837207e343277cbd6c114a45ec0e9ec56a1ad84\")\n```\n\n## HexStr\n\nUse hex str when you only care about un-sized hex strings.\nThe `HexStr` type serializes to `str` in the Pydantic core schema and a `string` in the JSON schema with a binary format.\n\n```python\nfrom eth_pydantic_types import HexStr\nfrom pydantic import BaseModel\n\nclass Tx(BaseModel):\n data: HexStr\n\ntx = Tx(data=\"0x0123\")\n```\n\n## Bip122Uri\n\nUse BIP-122 URIs in your models by annotating with the `Bip122Uri` type.\nThis type serializes to a `str` in the Pydantic core schema as well as a `string` in the JSON schema, however the individual hashes are validated.\n\n```python\nfrom eth_pydantic_types import Bip122Uri\nfrom pydantic import BaseModel\n\nclass Message(BaseModel):\n path: Bip122Uri\n\nmessage = Message(\n path=(\n \"blockchain://d4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3\"\n \"/block/752820c0ad7abc1200f9ad42c4adc6fbb4bd44b5bed4667990e64565102c1ba6\"\n )\n)\n```\n\n## Padding\n\nFor types like `HexStr` or `HexBytes`, you can control the padding by using `@field_validator()`.\n\n```python\nfrom pydantic import BaseModel, field_validator\nfrom eth_pydantic_types import HexStr20, HexBytes20\nfrom eth_pydantic_types.utils import Pad\n\nclass MyModel(BaseModel):\n my_str: HexStr20\n my_bytes: HexBytes20\n\n @field_validator(\"my_str\", \"my_bytes\", mode=\"before\")\n @classmethod\n def validate_value(cls, value, info):\n field_type = cls.model_fields[info.field_name].annotation\n return field_type.__eth_pydantic_validate__(value, pad=Pad.RIGHT)\n```\n\nElse, by default, if you validate integer values, it will pad left.\nOther inputs pad right.\nThis mirrors Solidity types, like `bytes32`, that automatically pad-right when given smaller values.\nInteger and address types automatically pad-left.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "eth-pydantic-types: Pydantic Types for Ethereum",
"version": "0.2.2",
"project_urls": {
"Homepage": "https://github.com/ApeWorX/eth-pydantic-types"
},
"split_keywords": [
"ethereum"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f305706c95e0a578e68f662be8c61581ae2a7f0c2a3460ea559d47893d45955c",
"md5": "774b4793ef9affe55d3151dec6b887da",
"sha256": "3eabd97d1896119e68a2539170e1a42bd50b2ce15e0256ab869eabebaa33909c"
},
"downloads": -1,
"filename": "eth_pydantic_types-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "774b4793ef9affe55d3151dec6b887da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 19477,
"upload_time": "2025-08-26T20:27:39",
"upload_time_iso_8601": "2025-08-26T20:27:39.645242Z",
"url": "https://files.pythonhosted.org/packages/f3/05/706c95e0a578e68f662be8c61581ae2a7f0c2a3460ea559d47893d45955c/eth_pydantic_types-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0ac4304928d02331fc69107fa089d7b503fb3f0baa241470b48cabe9109e5bb8",
"md5": "16824e7e1bdcbd9417a7493275df4a8b",
"sha256": "0e02a29662bf94578d03b1c6ed8ab225a993ab8e386a7d5ff341bd0a7b5fdfb1"
},
"downloads": -1,
"filename": "eth_pydantic_types-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "16824e7e1bdcbd9417a7493275df4a8b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.9",
"size": 72063,
"upload_time": "2025-08-26T20:27:41",
"upload_time_iso_8601": "2025-08-26T20:27:41.001878Z",
"url": "https://files.pythonhosted.org/packages/0a/c4/304928d02331fc69107fa089d7b503fb3f0baa241470b48cabe9109e5bb8/eth_pydantic_types-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 20:27:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ApeWorX",
"github_project": "eth-pydantic-types",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "eth-pydantic-types"
}
JSON
