Merge pull request #102 from OFFIS-DAI/development

v1.2.0
OFFIS-DAI · Sep 12, 2024 · d3a6b0e · d3a6b0e
2 parents f9de33d + 4b6f48a
commit d3a6b0e
Show file tree

Hide file tree

Showing 101 changed files with 1,539 additions and 739 deletions.
diff --git a/.github/workflows/test-mango.yml b/.github/workflows/test-mango.yml
@@ -1,20 +1,32 @@
 name: Test mango
 
-on: [push]
+on:
+  push:
+    branches:
+      - main
+      - development
+  pull_request:
+    types: [opened, synchronize, reopened]
+
 
 permissions:
   contents: read
 
-jobs: 
+jobs:
   build:
     runs-on: ubuntu-latest
-
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
-        python-version: '3.8'
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: '**/setup.py'
     - name: Install dependencies
       run: |
         pip install virtualenv
@@ -25,10 +37,15 @@ jobs:
         sudo apt update
         sudo apt install --assume-yes mosquitto
         sudo service mosquitto start
-        pip3 install pytest
-        pip3 install coverage
+        pip3 install pytest coverage ruff
+    - name: Lint with ruff
+      run: |
+        # stop the build if there are Python syntax errors or undefined names
+        source venv/bin/activate
+        ruff check .
+        ruff format --check .
     - name: Test+Coverage
       run: |
         source venv/bin/activate
-        coverage run --source ./mango -m pytest
-        coverage report
+        coverage run -m pytest
+        coverage report
diff --git a/.gitignore b/.gitignore
@@ -105,4 +105,4 @@ docs/build/
 docs/source/_build
 
 # Git
-*.orig
+*.orig
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: ASSUME Developers
+#
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff version.
+    rev: v0.4.9
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [ --fix ]
+      # Run the formatter.
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.3.0
+    hooks:
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.7"
+    python: "3.12"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -18,7 +18,6 @@ sphinx:
 formats:
    - pdf
 
-# Optionally set the version of Python and requirements required to build your docs
 python:
    install:
    - requirements: docs/requirements.txt
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,9 +1,4 @@
-alabaster==0.7.7
-decorator==4.3.0
-docopt==0.6.2
-docutils==0.16
-imagesize==0.7.1
-Jinja2==2.9
-MarkupSafe==0.23
-Sphinx==4.0.2
-sphinx-rtd-theme==0.5.2
+-e .
+sphinx-rtd-theme>=2.0.0
+pika
+pyzmq
diff --git a/docs/source/ACL messages.rst b/docs/source/ACL messages.rst
@@ -1 +0,0 @@
-

diff --git a/docs/source/agents-container.rst b/docs/source/agents-container.rst
@@ -1,6 +1,6 @@
-========
+====================
 Agents and container
-========
+====================
 
 ***************
 mango container
@@ -60,18 +60,19 @@ provided when :py:meth:`__init__()` of an agent is called.
 Custom agents that inherit from the ``Agent`` class have to call ``super().__init__(container, suggested_aid: str = None)__``
 on initialization.
 This will register the agent at the provided container instance and will assign a unique agent id
-(``self.aid``) to the agent. However, it is possible to suggest an aid by setting the variable ``suggested_aid`` to your aid wish. 
-The aid is granted if there is no other agent with this id, and if the aid doesn't interfere with the default aid pattern, otherwise 
+(``self.aid``) to the agent. However, it is possible to suggest an aid by setting the variable ``suggested_aid`` to your aid wish.
+The aid is granted if there is no other agent with this id, and if the aid doesn't interfere with the default aid pattern, otherwise
 the generated aid will be used. To check if the aid is available beforehand, you can use ``container.is_aid_available``.
 It will also create the task to check for incoming messages.
 
 ***************
 agent process
 ***************
-To improve multicore utilization, mango provides a way to distribute agents to processes. For this, it is necessary to create and 
+To improve multicore utilization, mango provides a way to distribute agents to processes. For this, it is necessary to create and
 register the agent in a slightly different way.
 
 .. code-block:: python3
+
     process_handle = await main_container.as_agent_process(
         agent_creator=lambda sub_container: TestAgent(
             container, aid_main_agent, suggested_aid=f"process_agent1"
@@ -82,9 +83,10 @@ The process_handle is awaitable and will finish exactly when the process is full
 
 Note that after the creation, the agent lives in a mirror container in another process. Therefore, it is not possible to interact
 with the agent directly from the main process. If you want to interact with the agent after the creation, it is possible to
-dispatch a task in the agent process using `dispatch_to_agent_process`. 
+dispatch a task in the agent process using `dispatch_to_agent_process`.
 
 .. code-block:: python3
+
     main_container.dispatch_to_agent_process(
         pid,
         your_function, # will be called with the mirror container + x as arguments

diff --git a/docs/source/api_ref/index.rst b/docs/source/api_ref/index.rst
@@ -5,10 +5,14 @@ API reference
 The API reference provides detailed descriptions of mango's classes and
 functions.
 
+Subpackages
+-----------
+
 .. toctree::
-   :glob:
    :maxdepth: 2
 
-   mango.core/index
-   mango.messages/index
-   mango.modules/index
+   mango.agent
+   mango.container
+   mango.messages
+   mango.modules
+   mango.util
diff --git a/docs/source/api_ref/mango.agent.rst b/docs/source/api_ref/mango.agent.rst
@@ -0,0 +1,18 @@
+mango.agent package
+===================
+
+mango.agent.core module
+-----------------------
+
+.. automodule:: mango.agent.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.agent.role module
+-----------------------
+
+.. automodule:: mango.agent.role
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api_ref/mango.container.rst b/docs/source/api_ref/mango.container.rst
@@ -0,0 +1,50 @@
+mango.container package
+=======================
+
+mango.container.core module
+---------------------------
+
+.. automodule:: mango.container.core
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.container.external\_coupling module
+-----------------------------------------
+
+.. automodule:: mango.container.external_coupling
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.container.factory module
+------------------------------
+
+.. automodule:: mango.container.factory
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.container.mqtt module
+---------------------------
+
+.. automodule:: mango.container.mqtt
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.container.protocol module
+-------------------------------
+
+.. automodule:: mango.container.protocol
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.container.tcp module
+--------------------------
+
+.. automodule:: mango.container.tcp
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api_ref/mango.core/index.rst b/docs/source/api_ref/mango.core/index.rst
diff --git a/docs/source/api_ref/mango.core/mango.core.agent.rst b/docs/source/api_ref/mango.core/mango.core.agent.rst
diff --git a/docs/source/api_ref/mango.core/mango.core.container.rst b/docs/source/api_ref/mango.core/mango.core.container.rst
diff --git a/docs/source/api_ref/mango.core/mango.core.container_protocols.rst b/docs/source/api_ref/mango.core/mango.core.container_protocols.rst
diff --git a/docs/source/api_ref/mango.messages.rst b/docs/source/api_ref/mango.messages.rst
@@ -0,0 +1,34 @@
+mango.messages package
+======================
+
+mango.messages.acl\_message\_pb2 module
+---------------------------------------
+
+.. automodule:: mango.messages.acl_message_pb2
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.messages.codecs module
+----------------------------
+
+.. automodule:: mango.messages.codecs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.messages.message module
+-----------------------------
+
+.. automodule:: mango.messages.message
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.messages.other\_proto\_msgs\_pb2 module
+---------------------------------------------
+
+.. automodule:: mango.messages.other_proto_msgs_pb2
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api_ref/mango.messages/index.rst b/docs/source/api_ref/mango.messages/index.rst
diff --git a/docs/source/api_ref/mango.messages/mango.messages.codecs.rst b/docs/source/api_ref/mango.messages/mango.messages.codecs.rst
diff --git a/docs/source/api_ref/mango.messages/mango.messages.message.rst b/docs/source/api_ref/mango.messages/mango.messages.message.rst
diff --git a/docs/source/api_ref/mango.modules.rst b/docs/source/api_ref/mango.modules.rst
@@ -0,0 +1,34 @@
+mango.modules package
+=====================
+
+mango.modules.base\_module module
+---------------------------------
+
+.. automodule:: mango.modules.base_module
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.modules.mqtt\_module module
+---------------------------------
+
+.. automodule:: mango.modules.mqtt_module
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.modules.rabbit\_module module
+-----------------------------------
+
+.. automodule:: mango.modules.rabbit_module
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+mango.modules.zero\_module module
+---------------------------------
+
+.. automodule:: mango.modules.zero_module
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/source/api_ref/mango.modules/index.rst b/docs/source/api_ref/mango.modules/index.rst
diff --git a/docs/source/api_ref/mango.modules/mango.modules.base_module.rst b/docs/source/api_ref/mango.modules/mango.modules.base_module.rst
diff --git a/docs/source/api_ref/mango.modules/mango.modules.mqtt_module.rst b/docs/source/api_ref/mango.modules/mango.modules.mqtt_module.rst
diff --git a/docs/source/api_ref/mango.modules/mango.modules.rabbit_module.rst b/docs/source/api_ref/mango.modules/mango.modules.rabbit_module.rst