feat: Extend builders, improve users and maintainers quality of life

.github/workflows/build_and_deploy.yaml

@@ -1,14 +1,13 @@
 name: Build and Deploy to PyPI
-on: [workflow_dispatch]
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "*"
 
 jobs:
   build_and_deploy:
-    strategy:
-      matrix:
-        os: [ubuntu-22.04, ubuntu-latest, macos-14, macos-latest]
-        python-version: ["3.11", "3.12", "3.13"]
-    runs-on: ${{ matrix.os }}
-    continue-on-error: true
+    runs-on: ubuntu-latest
 
     steps:
       - name: Checkout Source Code
@@ -17,7 +16,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v6
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: "3.11"
 
       - name: Install Dependencies
         run: make setup-build

.github/workflows/upload_coverage.yaml

@@ -25,7 +25,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: [ "3.11", "3.12", "3.13" ]
     steps:
       - name: Checkout Source Code
         uses: actions/checkout@v6
@@ -39,7 +39,7 @@ jobs:
         run: make setup-test
 
       - name: Run tests
-        run: pytest
+        run: poetry run pytest
 
       - name: Upload results to Codecov
         if: matrix.python-version == '3.11'

.pre-commit-config.yaml

@@ -25,6 +25,8 @@ repos:
     rev: 8.0.1
     hooks:
       - id: isort
+        pass_filenames: false
+        args: [eclypse]
 
   - repo: https://github.com/commitizen-tools/commitizen
     rev: v4.13.9
@@ -41,14 +43,17 @@ repos:
         args: [--fix, --select, "F401"]
         name: ruff pycln
       - id: ruff-check
+        pass_filenames: false
+        args: [eclypse]
       - id: ruff-format
+        pass_filenames: false
+        args: [eclypse]
 
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.20.0
     hooks:
       - id: mypy
         pass_filenames: false
         args: [eclypse]
-        exclude: ^(docs/|tests/)
 
 exclude: "examples/.*"

CONTRIBUTING.md

@@ -104,7 +104,7 @@ We use `pytest` for the test suite.
 Useful command:
 
 ```bash
-make test
+pytest
 ```
 
 ## Pre-commit Hooks

Makefile

@@ -13,12 +13,13 @@ setup:
 	python -m pip install --upgrade pip
 	pip install poetry
 	poetry config virtualenvs.create false
+	echo "Poetry virtualenv creation disabled for CI. To re-enable, run `poetry config virtualenvs.create true`."
 
 setup-build: setup
 	poetry install --with=dev,deploy --no-root
 
 setup-test: setup
-	poetry install --with=test --extras remote --extras tboard --no-root
+	poetry install --with=test --no-root
 
 format:
 	isort eclypse

README.md

@@ -12,11 +12,8 @@
 
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 [![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
-[![Checked with pylint](https://img.shields.io/badge/pylint-10/10-green)](https://pylint.pycqa.org/en/latest/)
 [![Import sorted with isort](https://img.shields.io/badge/isort-checked-brightgreen)](https://pycqa.github.io/isort/)
-[![Import cleaned with pycln](https://img.shields.io/badge/pycln-checked-brightgreen)](https://github.com/hadialqattan/pycln)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-black)](https://github.com/psf/black)
-[![Doc style: docformatter](https://img.shields.io/badge/doc%20style-docformatter-black)](https://github.com/PyCQA/docformatter)
+[![Doc style: docformatter](https://img.shields.io/badge/doc%20style-docformatter-blue)](https://github.com/PyCQA/docformatter)
 
 **ECLYPSE** (**E**dge-**CL**oud p**Y**thon **P**latform for **S**imulated runtime **E**nvironments) is the first simulation library entirely written in Python, for experimenting with deployment strategies in varying infrastructure conditions. It provides an interface to simulate deployments of service-based applications onto life-like infrastructures, without and with an actual application implementation to be deployed.
 

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -W
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build
@@ -19,9 +19,7 @@ help:
 livehtml:
 	sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)"/html $(SPHINXOPTS) $(O)
 
-# check docstrings using pylint in ../eclypse module
 check:
-# 	pylint --rcfile=../.pylintrc --enable=C0114,C0115,C0116 --disable=R0801,E0611 ../eclypse
 	ruff check --select D,E501 ../eclypse
 
 .PHONY: help Makefile

docs/conf.py

@@ -35,7 +35,6 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.coverage",
-    "sphinx.ext.napoleon",
     "sphinxcontrib.icon",
     "sphinx_copybutton",
     "sphinx_favicon",
@@ -48,7 +47,31 @@
 myst_enable_extensions = ["colon_fence"]
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "README.md"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "README.md",
+    "source/api/reference/graph/application/Application/"
+    "eclypse.graph.application.Application.has_logic.rst",
+    "source/api/reference/graph/infrastructure/Infrastructure/"
+    "eclypse.graph.infrastructure.Infrastructure.contains.rst",
+    "source/api/reference/graph/infrastructure/Infrastructure/"
+    "eclypse.graph.infrastructure.Infrastructure.has_strategy.rst",
+    "source/api/reference/workflow/trigger/bucket/TriggerBucket/"
+    "eclypse.workflow.trigger.bucket.TriggerBucket.init.rst",
+    "source/api/reference/workflow/trigger/cascade/RandomCascadeTrigger/"
+    "eclypse.workflow.trigger.cascade.RandomCascadeTrigger.init.rst",
+    "source/api/reference/workflow/trigger/trigger/RandomTrigger/"
+    "eclypse.workflow.trigger.trigger.RandomTrigger.init.rst",
+    "source/api/reference/workflow/trigger/trigger/ScheduledTrigger/"
+    "eclypse.workflow.trigger.trigger.ScheduledTrigger.init.rst",
+    "source/api/reference/workflow/trigger/trigger/Trigger/"
+    "eclypse.workflow.trigger.trigger.Trigger.init.rst",
+    "source/api/reference/workflow/event/decorator/"
+    "eclypse.workflow.event.decorator.event.rst",
+]
+suppress_warnings = ["toc.not_included"]
 
 coverage_show_missing_items = True
 # Automatically extract typehints when specified and place them in
@@ -156,12 +179,9 @@
 def patch_autosummary_name_collisions():
     """Resolve package-level name collisions for autosummary generation.
 
-    The ``eclypse.workflow.event`` package re-exports the ``event`` decorator,
-    which shadows the ``event`` submodule when autosummary resolves dotted
-    names. During the docs build we point the package attribute to the submodule
-    so the generated module page documents ``eclypse.workflow.event.event``
-    rather than the decorator function. The decorator remains documented through
-    ``eclypse.workflow.event.decorator``.
+    The ``eclypse.workflow.event`` package contains an ``event`` submodule. During
+    the docs build we point the package attribute to the submodule so the
+    generated module page documents ``eclypse.workflow.event.event`` reliably.
 
     Recent autosummary releases also expect package-level attributes for
     relative submodule entries such as ``simulation`` under ``eclypse`` and
@@ -177,7 +197,6 @@ def patch_autosummary_name_collisions():
     metrics_pkg.defaults = import_module("eclypse.report.metrics.defaults")
 
     event_pkg = import_module("eclypse.workflow.event")
-    event_pkg.decorator_event = event_pkg.event
     event_pkg.event = import_module("eclypse.workflow.event.event")
 
 

docs/index.rst

@@ -21,7 +21,7 @@
 =====================
 ECLYPSE documentation
 =====================
-**ECLYPSE** (Edge-Cloud raY-based Platform for Simulated Environments) stands as a groundbreaking simulation library, crafted entirely in Python.
+**ECLYPSE** (Edge-CLoud pYthon Platform for Simulated runtime Environments) stands as a groundbreaking simulation library, crafted entirely in Python.
 It offers a practical interface for experimenting with deployment strategies across different infrastructure settings.
 
 One of its key strengths lies in its ability to simulate the deployment of service-based applications in environments that closely mimic real-world conditions, with or without actual application implementation.

docs/source/overview/advanced/reporting.rst

@@ -40,8 +40,8 @@ There are 7 decorators corresponding to different metric types:
 - :py:func:`~eclypse.report.metrics.metric.service`
 - :py:func:`~eclypse.report.metrics.metric.interaction`
 
-See :ref:`event-decorator` for details on defining and triggering events. A
-metric lets you specify:
+See :ref:`event-decorator` for details on scheduled event helpers. A metric lets
+you specify:
 
 - **What data to collect**
 - **How often to report** (using :doc:`triggers <triggers>`)
@@ -61,6 +61,28 @@ Example:
 .. note::
    Metrics are executed like events, and use the same underlying logic, including support for cascade triggers and trigger conditions.
 
+Custom metric recipe
+~~~~~~~~~~~~~~~~~~~~
+
+Use the metric decorator that matches the object you want to inspect, choose
+when it activates, and return either a scalar or a mapping.
+
+.. code-block:: python
+   :caption: Custom service metric
+
+   from eclypse.report.metrics import metric
+
+   @metric.service(activates_on="step", report=["csv"])
+   def requested_cpu(service_id, requirements, placement, infrastructure):
+       return {
+           "service": service_id,
+           "value": requirements["cpu"],
+       }
+
+The reporting pipeline records the event metadata and stores the returned
+``value``. For multi-field mappings, keep a stable ``value`` key for the main
+measurement and use the other keys as context.
+
 Metric and callback types
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -162,6 +184,14 @@ Example usage:
    report = Report("./output")
    df = report.service(application_ids="app1", service_ids="srv2")
 
+For a quick run summary, call
+:py:meth:`~eclypse.report.report.Report.describe`:
+
+.. code-block:: python
+
+   print(report.describe())
+   # 84 rows x 10 steps x 12 metrics | 5 applications | ...
+
 Each accessor method supports filtering by:
 
 - `report_range` (e.g., only events between 10 and 100)