Merge pull request #39 from VaitaR/dev

Dev

Author: VaitaR

.github/workflows/README.md

@@ -0,0 +1,128 @@
+# GitHub Actions Workflows
+
+## Overview
+
+This project uses a simplified two-workflow strategy optimized for Python packages with Rust extensions.
+
+## Workflows
+
+### 1. ci.yml - Code Quality (Runs on every push/PR)
+
+**Purpose**: Fast feedback on code quality
+
+**Jobs**:
+- **lint** - Pre-commit hooks, mypy type checking, import-linter
+- **test** - Pytest across Python 3.10, 3.11, 3.12 with coverage
+
+**Does NOT**:
+- Build wheels (too slow, not needed on every push)
+- Publish to PyPI (only on release)
+
+**Runtime**: ~3-5 minutes
+
+---
+
+### 2. wheels.yml - Build & Publish (Runs on release)
+
+**Purpose**: Build production wheels and publish to PyPI
+
+**Triggers**:
+- On release creation (automatic)
+- Manual workflow dispatch (for testing)
+
+**Jobs**:
+- **build_wheels** - Uses cibuildwheel for Linux, Windows, macOS
+- **build_sdist** - Source distribution
+- **publish** - Publishes to PyPI (only on release)
+
+**Does**:
+- Builds wheels with maturin (Rust extension)
+- Tests each wheel after building
+- Handles cross-platform builds
+- Publishes to PyPI with trusted publishing
+
+**Runtime**: ~20-30 minutes (cross-platform builds)
+
+---
+
+## Why This Structure?
+
+### Problems with Previous Setup
+- Had 3 workflows, 2 were failing with maturin errors
+- Attempted to build wheels on every push (slow, unnecessary)
+- Duplicated testing across workflows
+
+### Current Benefits
+1. **Fast CI** - Code quality checks in minutes, not hours
+2. **Reliable** - No maturin builds in CI (only on release with proper tooling)
+3. **Standard Practice** - Follows Python+Rust project conventions
+4. **Clear Separation** - Code quality vs distribution packaging
+
+## Development Workflow
+
+### Daily Development
+```bash
+# Make changes
+git commit -m "feat: add new feature"
+git push
+
+# CI runs:
+# ✓ Lint (pre-commit, mypy, import-linter)
+# ✓ Test (pytest on Python 3.10, 3.11, 3.12)
+# → ~3-5 minutes
+```
+
+### Creating a Release
+```bash
+# Create release on GitHub
+gh release create v0.5.0 --generate-notes
+
+# wheels.yml runs automatically:
+# ✓ Build wheels (Linux, Windows, macOS)
+# ✓ Build sdist
+# ✓ Test wheels
+# ✓ Publish to PyPI
+# → ~20-30 minutes
+```
+
+## Testing Installation Locally
+
+### Editable Install (Development)
+```bash
+# No wheel needed, no maturin required
+pip install -e .
+python -c "import aiochainscan"
+```
+
+### Test Wheel Build (Before Release)
+```bash
+# Requires Rust toolchain
+pip install maturin
+maturin develop
+```
+
+### Test From GitHub (Any Branch)
+```bash
+pip install git+https://github.com/VaitaR/aiochainscan.git@develop
+```
+
+## Troubleshooting
+
+### CI Failing on Lint
+- Run `pre-commit run --all-files` locally
+- Fix issues, commit, push
+
+### CI Failing on Tests
+- Run `pytest` locally
+- Check test output for failures
+
+### Wheels Failing to Build
+- Check Rust is installed: `rustc --version`
+- Check maturin version: `pip show maturin` (should be ≥1.8)
+- Test locally: `maturin build --release`
+
+## Related Documentation
+
+- [CI_SIMPLIFICATION.md](../../docs/CI_SIMPLIFICATION.md) - Why we simplified
+- [PYPI_PUBLISHING.md](../../docs/PYPI_PUBLISHING.md) - Publishing guide
+- [CONTRIBUTING.md](../../CONTRIBUTING.md) - Development guide

.github/workflows/ci.yml

@@ -40,6 +40,10 @@ jobs:
       - name: Install dependencies
         run: uv sync --extra dev --frozen
 
+      # Run import tests FIRST to catch circular dependencies early
+      - name: Test imports (catch circular deps)
+        run: uv run pytest tests/test_imports.py -v --tb=short
+
       - name: Run pre-commit (all files)
         run: uv run pre-commit run --all-files --show-diff-on-failure
 
@@ -82,65 +86,3 @@ jobs:
 
       - name: Run tests
         run: uv run pytest --cov=aiochainscan --cov-report=xml --cov-report=term-missing
-
-
-
-  build:
-    name: Build Package
-    runs-on: ubuntu-latest
-    needs: [lint, test]
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-        with:
-          version: "latest"
-
-      - name: Cache uv packages
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cache/uv
-            ~/.local/share/uv
-          key: ${{ runner.os }}-uv-${{ env.PYTHON_VERSION }}-${{ hashFiles('uv.lock') }}
-          restore-keys: |
-            ${{ runner.os }}-uv-${{ env.PYTHON_VERSION }}-
-
-      - name: Set up Python
-        run: uv python install ${{ env.PYTHON_VERSION }}
-
-      - name: Install dependencies
-        run: uv sync --extra dev --frozen
-
-      - name: Build package
-        run: uv build
-
-      - name: Upload build artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: dist
-          path: dist/
-
-  publish:
-    name: Publish to PyPI
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.event_name == 'release' && github.event.action == 'published'
-    environment: pypi
-    permissions:
-      id-token: write
-      contents: read
-
-    steps:
-      - name: Download build artifacts
-        uses: actions/download-artifact@v4
-        with:
-          name: dist
-          path: dist/
-
-      - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          verbose: true