power-events 1.0.0__tar.gz

power_events-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,201 @@
+name: Checks
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  workflow_dispatch:
+
+env:
+  UV_PYTHON: "3.9"
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref_name }}-${{ github.event.pull_request.number || github.sha }}
+  cancel-in-progress: true
+
+jobs:
+  typos:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: crate-ci/typos@master
+
+  lint:
+    name: "Lint"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: "Install UV"
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+
+      - name: "Install lint dependencies"
+        run: uv sync --only-group lint
+
+      - name: "Python format"
+        run: uvx ruff format --diff .
+
+      - name: "Python lint"
+        run: uvx ruff check .
+
+      - name: "Python type check"
+        run: uv run mypy
+
+  build-docs:
+    name: "Build docs"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: "Install docs dependencies"
+        run: uv sync --only-group docs
+
+      - run: uv run mkdocs build --strict
+
+  tests:
+    name: "Testing with Python ${{ matrix.python-version }}"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.13"
+          - "3.12"
+          - "3.11"
+          - "3.10"
+          - "3.9"
+      fail-fast: false
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+
+      - name: "Install dev dependencies"
+        run: uv sync --python ${{ matrix.python-version }} --only-dev
+
+      - name: "Run tests"
+        run: uv run pytest
+        env:
+          COVERAGE_FILE: .coverage.py${{ matrix.python-version }}
+      - name: Upload coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: .coverage.py${{ matrix.python-version }}
+          path: .coverage.py${{ matrix.python-version }}
+          if-no-files-found: error
+          include-hidden-files: true
+
+
+  combine-coverage:
+    name: "Combine coverages"
+    runs-on: ubuntu-latest
+    needs: [ tests ]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+      - name: Update pip
+        run: pip install --upgrade pip
+      - name: Install coverage
+        run: pip install coverage[toml]
+
+      - name: Download coverage files
+        uses: actions/download-artifact@v4
+        with:
+          path: coverage
+          merge-multiple: true
+
+      - run: coverage combine coverage
+      - run: coverage report
+      - run: coverage html --title "Coverage for ${{ github.sha }}" -d htmlcov
+
+      - name: Store coverage data
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-data
+          path: .coverage
+          include-hidden-files: true
+
+      - name: Upload coverage html
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: htmlcov
+          include-hidden-files: true
+          if-no-files-found: error
+
+
+  comment-coverage:
+    name: "Comment coverage on PR"
+    runs-on: ubuntu-latest
+    needs: [ combine-coverage ]
+    if: github.event_name == 'pull_request'
+    permissions:
+      pull-requests: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Download coverage files
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-data
+
+      - name: Generate coverage comment
+        id: coverage-comment
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Store coverage comment
+        uses: actions/upload-artifact@v4
+        if: steps.coverage-comment.outputs.COMMENT_FILE_WRITTEN == 'true'
+        with:
+          name: python-coverage-comment-action
+          path: python-coverage-comment-action.txt
+
+
+  report-coverage:
+    name: Report coverages
+    runs-on: ubuntu-latest
+    needs: [ combine-coverage ]
+    permissions:
+      statuses: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+      - name: Update pip
+        run: pip install --upgrade pip
+
+      - name: Download coverage files
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-html
+          path: htmlcov
+
+      - run: pip install smokeshow
+
+      - name: "Upload report"
+        run: smokeshow upload htmlcov
+        env:
+          SMOKESHOW_GITHUB_STATUS_DESCRIPTION: Coverage {coverage-percentage}
+          SMOKESHOW_GITHUB_COVERAGE_THRESHOLD: 100
+          SMOKESHOW_GITHUB_CONTEXT: coverage
+          SMOKESHOW_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SMOKESHOW_GITHUB_PR_HEAD_SHA: ${{ github.sha }}
+          SMOKESHOW_AUTH_KEY: ${{ secrets.SMOKESHOW_KEY }}

power_events-1.0.0/.github/workflows/coverage-comment.yml

@@ -0,0 +1,27 @@
+name: Post coverage comment
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types:
+      - completed
+
+jobs:
+  post-coverage-comment:
+    name: Push coverage comment
+    runs-on: ubuntu-latest
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+    permissions:
+      pull-requests: write
+      contents: write
+      actions: read
+    steps:
+      # DO NOT run actions/checkout here, for security reasons
+      # For details, refer to https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+      - name: Post comment
+        uses: py-cov-action/python-coverage-comment-action@v3
+        with:
+          GITHUB_TOKEN: ${{ secret.GITHUB_TOKEN }}
+          GITHUB_PR_RUN_ID: ${{ github.event.workflow_run.id }}
+          ANNOTATE_MISSING_LINES: true
+          ANNOTATION_TYPE: warning

power_events-1.0.0/.github/workflows/publish-docs.yml

@@ -0,0 +1,55 @@
+name: publish-docs
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+  workflow_dispatch:
+
+env:
+  UV_PYTHON: "3.9"
+
+jobs:
+  docs:
+    name: "Publish documentation"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout gh-pages
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+
+      - name: Checkout current branch
+        uses: actions/checkout@v4
+
+      - name: "set up env"
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+
+      - name: "Install doc deps"
+        run: uv sync --only-group docs
+
+      - name: "Configure Git Credentials"
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email github-actions[bot]@users.noreply.github.com
+
+      - name: "Get version"
+        if: "startsWith(github.ref, 'refs/tags/')"
+        run: echo "TAG=$(python -c "print('.'.join('${{ github.ref_name }}'.split('.')[:2]))")">>$GITHUB_ENV
+
+      - name: "Publish version $TAG"
+        if: "startsWith(github.ref, 'refs/tags/')"
+        run: uv run mike deploy --push --update-aliases $TAG latest
+
+      - name: "Update dev docs"
+        if: "github.ref =='refs/heads/main'"
+        run: uv run mike deploy --push --update-aliases dev

power_events-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,84 @@
+name: "Release"
+
+on:
+  push:
+    tags:
+      - "[0-9]+.[0-9]+.[0-9]+"
+
+jobs:
+  build:
+    name: "Build distribution package"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.9'
+
+      - name: "Install 'build' library"
+        run: pip install -U build
+
+      - name: build
+        run: python -m build
+
+      - name: "Upload distribution artifacts"
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: "Publish to PyPI"
+    needs: [ build ]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # IMPORTANT: mandatory for trusted publishing
+    environment:
+      name: pypi
+      url: https://pypi.org/p/power-events
+    steps:
+      - name: "Download distribution artifacts"
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  gh-release:
+    name: "Create a github release"
+    needs: [ publish-pypi ]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write # IMPORTANT: mandatory for sigstore
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.9"
+
+      - name: "Download distribution artifacts"
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: "Sign the distribution artifacts with Sigstore"
+        uses: sigstore/gh-action-sigstore-python@v3.0.0
+        with:
+          inputs: ./dist/*
+
+      - run: pip install commitizen
+
+      - name: "Generate release body"
+        run: cz changelog --incremental --dry-run > note.md
+
+      - name: "Create Github release"
+        uses: ncipollo/release-action@v1
+        with:
+          artifacts: "dist/*"
+          bodyFile: "note.md"

power_events-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+# Byte-compiled
+**/__pycache__/***
+
+**/*.egg-info/***
+# Caches
+/.*_cache
+
+# Virtual envs
+/*venv*
+
+# Distribution / packaging
+/dist
+
+# Unit test / coverage reports
+***/.coverage*
+***/tests-reports/***
+*.xml
+.idea/***

power_events-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,39 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff
+        name: ruff lint
+        entry: uvx ruff check --fix --exit-non-zero-on-fix
+        language: python
+        types_or: [python, pyi]
+        require_serial: true
+        stages: [pre-commit]
+        additional_dependencies:
+          - "uv>=0.5.0"
+
+      - id: ruff-format
+        name: ruff format
+        entry: uvx ruff format
+        language: python
+        types_or: [ python, pyi ]
+        require_serial: true
+        stages: [pre-commit]
+        additional_dependencies:
+          - "uv>=0.5.0"
+
+      - id: mypy
+        name: mypy
+        entry: uvx mypy
+        language: python
+        types_or: [ python, pyi ]
+        stages: [pre-push]
+        additional_dependencies:
+          - "uv>=0.5.0"
+
+      - id: tests
+        name: tests
+        entry: uvx pytest
+        language: python
+        stages: [pre-push]
+        additional_dependencies:
+          - "uv>=0.5.0"

power_events-1.0.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+## Power-events
+
+## 1.0.0 (2024-11-24)
+
+### :sparkles: Features
+
+- change ValuePath
+- raise error when value missing
+- allow equals at None
+- add resolver
+- add conditions

power_events-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Mathieu LETRONE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

power_events-1.0.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.3
+Name: power-events
+Version: 1.0.0
+Summary: Add your description here
+Author-email: mathieu LETRONE <mathieu.letrone@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Mathieu LETRONE
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: maypy>=1.1.2
+Description-Content-Type: text/markdown
+
+# Power-Events
+<div align="center" style="margin:40px;">
+<!-- --8<-- [start:overview-header] -->
+
+  [![Test](https://github.com/MLetrone/power-events/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/MLetrone/power-events/actions/workflows/ci.yml)
+  [![Coverage](https://coverage-badge.samuelcolvin.workers.dev/MLetrone/power-events.svg)](https://coverage-badge.samuelcolvin.workers.dev/redirect/MLetrone/power-events)
+  [![Language](https://img.shields.io/badge/Language-python≥3.9-3776ab?style=flat-square&logo=Python)](https://www.python.org/)
+  ![License](https://img.shields.io/badge/License-MIT-yellow?style=flat-square)
+  ![Style](https://img.shields.io/badge/Style-ruff-9a9a9a?style=flat-square)
+  ![Lint](https://img.shields.io/badge/Lint-ruff,%20mypy-brightgreen?style=flat-square)
+
+<!-- --8<-- [end:overview-header] -->
+
+---
+
+Source Code: [https://github.com/MLetrone/power-events](https://github.com/MLetrone/power-events)
+
+documentation: [https://mletrone.github.io/power-events](https://mletrone.github.io/power-events/)
+
+---
+</div>
+<!-- --8<-- [start:overview-body] -->
+
+_Take control of your event routing, effortlessly and tailored to your needs._
+
+## Description
+
+**Power-events** is a lightweight yet powerful library that manages event routing by defining routes with precise conditions,
+inspired by FastAPI’s endpoint routing system.
+It simplifies the organization of complex events by applying specific routing rules defined
+ by the user and enables actions to be triggered in response to events in a structured manner.
+
+## Key features:
+- **Syntax**: Lean to standards like Powertools or FastAPI.
+- **Easy**: Design to be easy to read and use.
+- **Flexible**: You can do whatever condition at any depth level in your event.
+- **Fully tested**: 100% coverage.
+- **Fully typed**: compatible out of the box with `mypy` !
+- **Lightweight**
+
+<!-- --8<-- [end:overview-body] -->
+## installation
+
+```shell
+pip install power-events
+```
+
+That's all ! _Ready to use_
+<!-- --8<-- [start:body] -->
+## Examples
+---
+### Simple conditions
+
+- create a `main.py` with:
+
+```python
+from typing import Any
+from power_events import EventResolver
+
+app = EventResolver()
+
+@app.equal("type", "order_created")
+def handler_order_created(event: dict[str, Any]) -> str:
+  return f"Order created: {event['order_id']}"
+
+@app.one_of("type", ["order_update", "order_delete"])
+def handle_order_modification(event: dict[str, Any]) -> str:
+  return f"Order modification <{event['type']}>: {event['order_id']}"
+
+```
+
+- use routing:
+
+> N.B: assert is here to show which route has been called.
+> In real condition, don't need to use it.
+
+```python
+assert app.resolve({
+    "type": "order_created",
+    "order_id": "12345",
+    "user_id": "67890"
+}) == ["Order created: 12345"]
+# Note: `resolve` returns a list, because you can allow multiple routes for one event.
+
+assert app.resolve({
+    "type": "order_delete",
+    "order_id": "12345",
+    "user_id": "67890"
+})== ["Order modification <order_delete>: 12345"]
+
+```
+### Complex conditions
+
+_in depth field condition and condition combinations_
+
+```python
+from power_events import EventResolver
+from power_events.conditions import Value, Neg
+
+app = EventResolver()
+
+# Order created and digital purchase.
+@app.when(Value("type").equals("order_created") & Value("cart.is_digital").is_truthy())
+def handle_digital_purchase(event: dict) -> str:
+    return f"The order created is a digital purchase: {event['order_id']}"
+
+# Order created and physical.
+@app.when(Value("type").equals("order_created") & Neg(Value("cart.is_digital").is_truthy()))
+def handle_physical_purchase(event: dict) -> str:
+    return f"The order created is a physical purchase: {event['order_id']}"
+
+
+assert app.resolve({
+    "type": "order_created",
+    "order_id": "12345",
+    "user_id": "67890",
+    "cart": {
+        "is_digital": True,
+        "items": [
+            "$10 voucher"
+        ]
+    }
+}) == ["The order created is a digital purchase: 12345"]
+assert app.resolve({
+    "type": "order_created",
+    "order_id": "12345",
+    "user_id": "67890",
+    "cart": {
+        "is_digital": False,
+        "items": [
+            "keyboard"
+        ]
+    }
+}) == ["The order created is a physical purchase: 12345"]
+```
+
+It's possible to perform `OR`, `AND`, `NEG` operation over conditions.
+<!-- --8<-- [end:body] -->