Skip to content

Commit 6272c54

Browse files
danceratopzdanceratopz
authored
chore: prepare for release; add versioning & packaging (#11)
1 parent e4a1108 commit 6272c54

File tree

7 files changed

+729
-31
lines changed

7 files changed

+729
-31
lines changed

‎.github/workflows/ci.yaml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
jobs:
9+
test:
10+
name: Test and lint
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.11", "3.12"]
15+
16+
steps:
17+
- name: Checkout code
18+
uses: actions/checkout@v4
19+
20+
- name: Install uv
21+
uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba
22+
with:
23+
# version: ${{ vars.UV_VERSION }}
24+
# python-version: ${{ vars.DEFAULT_PYTHON_VERSION }}
25+
version: 0.7.3
26+
python-version: 3.12
27+
28+
- name: Install dependencies
29+
run: uv sync --all-extras
30+
31+
- name: Run linting
32+
run: |
33+
uv run black --check src/
34+
uv run isort --check-only src/
35+
uv run mypy src/
36+
37+
# requires hive --dev.
38+
# - name: Run tests
39+
# run: uv run pytest

‎.github/workflows/release.yaml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
# Publish on any tag starting with a `v`, e.g. v1.2.3
7+
- v*
8+
9+
jobs:
10+
pypi:
11+
name: Publish to PyPI
12+
runs-on: ubuntu-latest
13+
# Environment and permissions trusted publishing.
14+
environment:
15+
# Create this environment in the GitHub repository under Settings -> Environments
16+
name: release
17+
permissions:
18+
id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
19+
steps:
20+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
21+
uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba
22+
- run: uv build
23+
# Check that basic features work and we didn't miss to include crucial files
24+
- name: Smoke test (wheel)
25+
run: uv run --isolated --no-project -p 3.12 --with dist/*.whl tests/smoke_test.py
26+
- name: Smoke test (source distribution)
27+
run: uv run --isolated --no-project -p 3.12 --with dist/*.tar.gz tests/smoke_test.py
28+
- run: uv publish --trusted-publishing always

‎CHANGELOG.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Changelog
2+
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [v0.1.0] - 2025-07-09
9+
10+
Initial release of the Python Hive Simulator API with:
11+
12+
- Network configuration support.
13+
- Client management functionality.
14+
- Test suite management functionality.

‎README.md‎

Lines changed: 122 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,132 @@
11
# Ethereum Hive Simulators Python Library
22

3-
Write hive simulators using python
3+
[![PyPI version](https://badge.fury.io/py/ethereum-hive.svg)](https://badge.fury.io/py/ethereum-hive)
4+
[![Python versions](https://img.shields.io/pypi/pyversions/ethereum-hive.svg)](https://pypi.org/project/ethereum-hive/)
5+
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
6+
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
47

5-
## Run tests
8+
Write [ethereum/hive](https://github.com/ethereum/hive) simulators using Python.
69

7-
#### Fetch and build hive:
10+
This library provides a Python API for creating and running Ethereum Hive simulation tests, allowing you to test Ethereum clients against various scenarios and network conditions.
11+
12+
## Installation
813

914
```bash
10-
git clone https://github.com/ethereum/hive.git
11-
cd hive
12-
go build -v .
15+
pip install ethereum-hive
1316
```
1417

15-
#### Run hive in dev mode
16-
```bash
17-
./hive --dev --client go-ethereum,lighthouse-bn,lighthouse-vc
18+
## Features
19+
20+
- **Client Management**: Start, stop, and manage Ethereum clients.
21+
- **Network Configuration**: Configure custom networks and genesis configuration.
22+
- **Test Simulation**: Run comprehensive test suites against Ethereum clients.
23+
24+
## Quick Start
25+
26+
### Start a Hive Development Server
27+
28+
```console
29+
./hive --dev --client go-ethereum
1830
```
1931

20-
#### Run tests
21-
```bash
22-
pytest
23-
```
32+
### Basic Example
33+
34+
Here's a basic example of how to use the Hive Python API with Hive running in developer mode. It requires a [genesis file](https://github.com/ethereum/hive-python-api/blob/e4a1108f3a8feab4c0d638f1393a94319733ae89/src/hive/tests/genesis.json); please modify the path as required.
35+
36+
```python
37+
from pathlib import Path
38+
39+
from hive.simulation import Simulation
40+
from hive.testing import HiveTestResult
41+
42+
# Create a simulation on a development hive server
43+
simulator = Simulation(url="http://127.0.0.1:3000")
44+
45+
# Get information about the hive instance cli args and clients
46+
hive_info = simulator.hive_instance()
47+
48+
# Start a test suite
49+
suite = simulator.start_suite("my_test_suite", "my test suite description")
50+
51+
# Start a test
52+
test = suite.start_test("my_test", "my test description")
53+
54+
# Start a client for the test
55+
all_clients = simulator.client_types()
56+
print(all_clients[0].version)
57+
58+
# Specify the genesis file; here we use the genesis from the unit test
59+
files = {"genesis.json": Path("src/hive/tests/genesis.json").as_posix()}
60+
env = {"HIVE_CHAIN_ID": "1"}
61+
client = test.start_client(client_type=all_clients[0], environment=env, files=files)
62+
63+
# Run your test logic
64+
# ...
65+
66+
# Stop the test and the suite (will clean-up clients)
67+
test.end(result=HiveTestResult(test_pass=True, details="test details"))
68+
suite.end()
69+
```
70+
71+
For more detailed examples, check out the [unit tests](https://github.com/ethereum/hive-python-api/blob/e4a1108f3a8feab4c0d638f1393a94319733ae89/src/hive/tests/test_sanity.py) or explore the simulators in the [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repository.
72+
73+
## Development
74+
75+
### Setup
76+
77+
1. Install `uv`:
78+
79+
```bash
80+
curl -LsSf https://astral.sh/uv/install.sh | sh
81+
```
82+
83+
2. Clone and setup the project:
84+
85+
```bash
86+
git clone https://github.com/marioevz/hive.py.git
87+
cd hive.py
88+
uv sync --all-extras
89+
```
90+
91+
### Running Tests
92+
93+
#### Prerequisites
94+
95+
1. Fetch and build hive:
96+
97+
```bash
98+
git clone https://github.com/ethereum/hive.git
99+
cd hive
100+
go build -v .
101+
```
102+
103+
2. Run hive in dev mode:
104+
105+
```bash
106+
./hive --dev --client go-ethereum,lighthouse-bn,lighthouse-vc
107+
```
108+
109+
3. Run the test suite:
110+
111+
```bash
112+
uv run pytest
113+
```
114+
115+
### Code Quality
116+
117+
- **Linting**: `uv run black src/`
118+
- **Type checking**: `uv run mypy src/`
119+
- **Import sorting**: `uv run isort src/`
120+
121+
## Contributing
122+
123+
Contributions are welcome! Please feel free to submit a Pull Request.
124+
125+
## License
126+
127+
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
128+
129+
## Related Projects
130+
131+
- [ethereum/hive](https://github.com/ethereum/hive) - The main Hive testing framework.
132+
- [ethereum/execution-spec-tests](https://github.com/ethereum/execution-spec-tests) - Contains implementations of several Hive simulators.

‎pyproject.toml‎

Lines changed: 47 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,78 @@
11
[build-system]
2-
requires = ["setuptools", "wheel"]
2+
requires = ["setuptools>=64", "setuptools-scm>=8"]
33
build-backend = "setuptools.build_meta"
44

55
[project]
6-
name = "hive.py"
7-
description = "Ethereum Hive Simulators Python Interface"
6+
name = "ethereum-hive"
7+
description = "Ethereum Hive Simulator Python API"
88
readme = "README.md"
9-
version = "0.1.0"
10-
urls = { "Homepage" = "https://github.com/marioevz/hive.py" }
9+
authors = [{ name = "Mario Vega", email = "[email protected]" }]
10+
maintainers = [
11+
{ name = "Mario Vega", email = "[email protected]" },
12+
{ name = "danceratopz", email = "[email protected]" },
13+
]
14+
keywords = ["ethereum", "hive", "simulator", "testing", "blockchain"]
15+
dynamic = ["version"]
1116
license = { file = "LICENSE" }
1217
classifiers = [
13-
"License :: OSI Approved :: GPL3 License",
14-
"Programming Language :: Python :: 3.10",
15-
]
16-
requires-python = ">=3.10"
17-
dependencies = [
18-
"requests>=2.31.0,<3"
18+
"Development Status :: 4 - Beta",
19+
"Intended Audience :: Developers",
20+
"License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
21+
"Programming Language :: Python :: 3",
22+
"Programming Language :: Python :: 3.11",
23+
"Programming Language :: Python :: 3.12",
24+
"Topic :: Software Development :: Testing",
25+
"Topic :: System :: Networking",
26+
"Topic :: Internet :: WWW/HTTP :: HTTP Servers",
27+
"Operating System :: OS Independent",
1928
]
29+
requires-python = ">=3.11"
30+
dependencies = ["requests>=2.31.0,<3"]
31+
32+
[project.urls]
33+
Homepage = "https://github.com/marioevz/hive.py"
34+
Repository = "https://github.com/marioevz/hive.py"
35+
Issues = "https://github.com/marioevz/hive.py/issues"
36+
Documentation = "https://github.com/marioevz/hive.py#readme"
2037

2138
[project.optional-dependencies]
22-
test = [
23-
"pytest>=7.4.0,<8",
24-
"pytest-cov>=4.1.0,<5"
25-
]
39+
test = ["pytest>=8.4.0,<9", "pytest-cov>=4.1.0,<5"]
2640
lint = [
27-
"black==22.3.0; implementation_name == 'cpython'",
41+
"black>=23.1.0; implementation_name == 'cpython'",
2842
"isort>=5.8,<6",
2943
"mypy>=1.4.1,<2",
30-
"types-requests>=2.25.0,<3"
44+
"types-requests>=2.25.0,<3",
3145
]
46+
dev = ["setuptools-scm"]
3247

3348
[tool.setuptools.packages.find]
3449
where = ["src"]
3550
exclude = ["*tests*"]
3651

52+
[tool.setuptools_scm]
53+
version_scheme = "post-release"
54+
local_scheme = "dirty-tag"
55+
3756
[tool.isort]
3857
profile = "black"
3958
multi_line_output = 3
4059
line_length = 99
4160

4261
[tool.black]
4362
line-length = 99
44-
target-version = ["py310"]
63+
target-version = ["py311"]
4564

4665
[tool.pytest.ini_options]
4766
console_output_style = "count"
4867
minversion = "7.0"
4968
testpaths = ["src"]
69+
70+
# pypi test index; use `uv publish --index testpypi` to publish to this index
71+
# uv publish will default to the production pypi index by default
72+
# https://docs.astral.sh/uv/guides/package/#publishing-your-package
73+
#
74+
# [[tool.uv.index]]
75+
# name = "testpypi"
76+
# url = "https://test.pypi.org/simple/"
77+
# publish-url = "https://test.pypi.org/legacy/"
78+
# explicit = true

‎src/hive/__init__.py‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
"""
2+
Ethereum Hive Simulators Python Library
3+
4+
This library provides a Python API for creating and running Ethereum Hive simulation tests,
5+
allowing you to test Ethereum clients against various scenarios and network conditions.
6+
"""
7+
8+
from importlib.metadata import version
9+
10+
from .client import Client, ClientRole, ClientType
11+
from .network import Network
12+
from .simulation import Simulation
13+
from .testing import HiveTestSuite
14+
15+
try:
16+
__version__ = version("ethereum-hive")
17+
except Exception:
18+
__version__ = "unknown"
19+
20+
__all__ = [
21+
"__version__",
22+
"Client",
23+
"ClientRole",
24+
"ClientType",
25+
"Network",
26+
"Simulation",
27+
"HiveTestSuite",
28+
]

0 commit comments

Comments
 (0)