chore: prepare for release; add versioning & packaging

.github/workflows/ci.yaml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test and lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba
+        with:
+          # version: ${{ vars.UV_VERSION }}
+          # python-version: ${{ vars.DEFAULT_PYTHON_VERSION }}
+          version: 0.7.3
+          python-version: 3.12
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Run linting
+        run: |
+          uv run black --check src/
+          uv run isort --check-only src/
+          uv run mypy src/
+
+      # requires hive --dev.
+      # - name: Run tests
+      #   run: uv run pytest

.github/workflows/release.yaml

@@ -0,0 +1,28 @@
+name: Release
+
+on:
+  push:
+    tags:
+      # Publish on any tag starting with a `v`, e.g. v1.2.3
+      - v*
+
+jobs:
+  pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    # Environment and permissions trusted publishing.
+    environment:
+      # Create this environment in the GitHub repository under Settings -> Environments
+      name: release
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+        uses: astral-sh/setup-uv@bd01e18f51369d5a26f1651c3cb451d3417e3bba
+      - run: uv build
+      # Check that basic features work and we didn't miss to include crucial files
+      - name: Smoke test (wheel)
+        run: uv run --isolated --no-project -p 3.12 --with dist/*.whl tests/smoke_test.py
+      - name: Smoke test (source distribution)
+        run: uv run --isolated --no-project -p 3.12 --with dist/*.tar.gz tests/smoke_test.py
+      - run: uv publish --trusted-publishing always

CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [v0.1.0] - 2025-07-09
+
+Initial release of the Python Hive Simulator API with:
+
+- Network configuration support.
+- Client management functionality.
+- Test suite management functionality.

README.md

@@ -1,23 +1,106 @@
 # Ethereum Hive Simulators Python Library
 
-Write hive simulators using python
+[![PyPI version](https://badge.fury.io/py/ethereum-hive.svg)](https://badge.fury.io/py/ethereum-hive)
+[![Python versions](https://img.shields.io/pypi/pyversions/ethereum-hive.svg)](https://pypi.org/project/ethereum-hive/)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![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)
 
-## Run tests
+Write [ethereum/hive](https://github.com/ethereum/hive) simulators using Python.
 
-#### Fetch and build hive:
+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.
+
+## Installation
 
 ```bash
-git clone https://github.com/ethereum/hive.git
-cd hive
-go build -v .
+pip install ethereum-hive
 ```
 
-#### Run hive in dev mode
-```bash
-./hive --dev --client go-ethereum,lighthouse-bn,lighthouse-vc
+## Features
+
+- **Client Management**: Start, stop, and manage Ethereum clients.
+- **Network Configuration**: Configure custom networks and genesis configuration.
+- **Test Simulation**: Run comprehensive test suites against Ethereum clients.
+
+## Quick Start
+
+Here's a basic example of how to use the Hive Python API:
+
+```python
+from hive import Hive
+from hive.client import Client
+
+# Initialize Hive simulator
+hive = Hive()
+
+# Start a client
+client = hive.start_client("go-ethereum")
+
+# Run your test logic
+# ...
+
+# Stop the client
+hive.stop_client(client)
 ```
 
-#### Run tests
-```bash
-pytest
-```
+For more detailed examples, check out the [unit tests](src/hive/tests/test_sanity.py) or explore the simulators in the [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) repository.
+
+## Development
+
+### Setup
+
+1. Install `uv`:
+
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+2. Clone and setup the project:
+
+   ```bash
+   git clone https://github.com/marioevz/hive.py.git
+   cd hive.py
+   uv sync --all-extras
+   ```
+
+### Running Tests
+
+#### Prerequisites
+
+1. Fetch and build hive:
+
+   ```bash
+   git clone https://github.com/ethereum/hive.git
+   cd hive
+   go build -v .
+   ```
+
+2. Run hive in dev mode:
+
+   ```bash
+   ./hive --dev --client go-ethereum,lighthouse-bn,lighthouse-vc
+   ```
+
+3. Run the test suite:
+
+   ```bash
+   uv run pytest
+   ```
+
+### Code Quality
+
+- **Linting**: `uv run black src/`
+- **Type checking**: `uv run mypy src/`
+- **Import sorting**: `uv run isort src/`
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
+
+## Related Projects
+
+- [ethereum/hive](https://github.com/ethereum/hive) - The main Hive testing framework.
+- [ethereum/execution-spec-tests](https://github.com/ethereum/execution-spec-tests) - Contains implementations of several Hive simulators.

pyproject.toml

@@ -1,49 +1,78 @@
 [build-system]
-requires = ["setuptools", "wheel"]
+requires = ["setuptools>=64", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "hive.py"
-description = "Ethereum Hive Simulators Python Interface"
+name = "ethereum-hive"
+description = "Ethereum Hive Simulator Python API"
 readme = "README.md"
-version = "0.1.0"
-urls = { "Homepage" = "https://github.com/marioevz/hive.py" }
+authors = [{ name = "Mario Vega", email = "[email protected]" }]
+maintainers = [
+    { name = "Mario Vega", email = "[email protected]" },
+    { name = "danceratopz", email = "[email protected]" },
+]
+keywords = ["ethereum", "hive", "simulator", "testing", "blockchain"]
+dynamic = ["version"]
 license = { file = "LICENSE" }
 classifiers = [
-    "License :: OSI Approved :: GPL3 License",
-    "Programming Language :: Python :: 3.10",
-]
-requires-python = ">=3.10"
-dependencies = [
-    "requests>=2.31.0,<3"
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Topic :: System :: Networking",
+    "Topic :: Internet :: WWW/HTTP :: HTTP Servers",
+    "Operating System :: OS Independent",
 ]
+requires-python = ">=3.11"
+dependencies = ["requests>=2.31.0,<3"]
+
+[project.urls]
+Homepage = "https://github.com/marioevz/hive.py"
+Repository = "https://github.com/marioevz/hive.py"
+Issues = "https://github.com/marioevz/hive.py/issues"
+Documentation = "https://github.com/marioevz/hive.py#readme"
 
 [project.optional-dependencies]
-test = [
-    "pytest>=7.4.0,<8",
-    "pytest-cov>=4.1.0,<5"
-]
+test = ["pytest>=8.4.0,<9", "pytest-cov>=4.1.0,<5"]
 lint = [
-    "black==22.3.0; implementation_name == 'cpython'",
+    "black>=23.1.0; implementation_name == 'cpython'",
     "isort>=5.8,<6",
     "mypy>=1.4.1,<2",
-    "types-requests>=2.25.0,<3"
+    "types-requests>=2.25.0,<3",
 ]
+dev = ["setuptools-scm"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
 exclude = ["*tests*"]
 
+[tool.setuptools_scm]
+version_scheme = "post-release"
+local_scheme = "dirty-tag"
+
 [tool.isort]
 profile = "black"
 multi_line_output = 3
 line_length = 99
 
 [tool.black]
 line-length = 99
-target-version = ["py310"]
+target-version = ["py311"]
 
 [tool.pytest.ini_options]
 console_output_style = "count"
 minversion = "7.0"
 testpaths = ["src"]
+
+# pypi test index; use `uv publish --index testpypi` to publish to this index
+# uv publish will default to the production pypi index by default
+# https://docs.astral.sh/uv/guides/package/#publishing-your-package
+#
+# [[tool.uv.index]]
+# name = "testpypi"
+# url = "https://test.pypi.org/simple/"
+# publish-url = "https://test.pypi.org/legacy/"
+# explicit = true

src/hive/__init__.py

@@ -0,0 +1,28 @@
+"""
+Ethereum Hive Simulators Python Library
+
+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.
+"""
+
+from importlib.metadata import version
+
+from .client import Client, ClientRole, ClientType
+from .network import Network
+from .simulation import Simulation
+from .testing import HiveTestSuite
+
+try:
+    __version__ = version("ethereum-hive")
+except Exception:
+    __version__ = "unknown"
+
+__all__ = [
+    "__version__",
+    "Client",
+    "ClientRole",
+    "ClientType",
+    "Network",
+    "Simulation",
+    "HiveTestSuite",
+]