asapo-notifier 0.1.0__tar.gz

asapo_notifier-0.1.0/.editorconfig

@@ -0,0 +1,10 @@
+[*.{js,json}]
+indent_style = space
+indent_size = 2
+max_line_length = 89
+
+[*.sh]
+indent_style = space
+indent_size = 2
+max_line_length = 89
+simplify = true

asapo_notifier-0.1.0/.gitignore

@@ -0,0 +1,145 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.pybuild/
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/
+nosetests.xml
+coverage.xml
+*.cover
+cover/
+*.py,cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv*/
+env/
+env.bak/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEA (PyCharm/IntelliJ)
+.idea
+
+# eclipse
+.project
+.pydevproject
+
+# visual studio code
+.vscode
+
+# temporary files
+/tmp
+/temp
+
+# miscellaneous
+.DS_Store
+*.orig

asapo_notifier-0.1.0/.gitlab-ci.yml

@@ -0,0 +1,64 @@
+---
+variables:
+  CI_DEBUG_SERVICES: "true"
+  # `WAIT_FOR_DIR` contains a script that a Docker service can run to wait until the
+  # provided directory is available.
+  # See https://docs.gitlab.com/ci/services/#shared-builds-directory
+  WAIT_FOR_DIR:
+    expand: false
+    value: |
+      function wait_for_dir() {
+        readonly DIR="$1"
+        while [ ! -d "$DIR" ]; do
+          echo "could not find '$DIR'" && sleep 1
+        done &&
+        echo "Found '$DIR'"
+      }
+
+.common_test_inputs: &common_test_inputs
+  install-commands:
+    - apt-get update && apt-get install -y --no-install-recommends curl
+    - python3 -m pip install "${PACKAGE}[asapo,tests]"
+    - $CI_PROJECT_DIR/etc/ci/synapse.sh check_server_running
+  pytest-options: "-vv --log-cli-level=DEBUG"
+  services:
+    - name: ghcr.io/element-hq/synapse:latest
+      alias: synapse
+      variables:
+        SYNAPSE_CONFIG_DIR: "$BUILD_DIR/synapse/config"
+        SYNAPSE_DATA_DIR: "$BUILD_DIR/synapse/data"
+      entrypoint: ["/bin/bash", "-c"]
+      command:
+        - |
+          eval "$WAIT_FOR_DIR" &&
+          wait_for_dir "$CI_PROJECT_DIR/etc/ci/" &&
+          "$CI_PROJECT_DIR/etc/ci/synapse.sh" config_and_start
+    - name: gitlab.desy.de:5555/asapo/asapo/asapo-standalone:26.02.0.dev01
+
+include:
+  - project: "fs-sc/ci/python"
+    file:
+      - "templates/workflows/branch-pipelines.yml"
+  - component: "gitlab.desy.de/fs-sc/ci/python/pre-commit@main"
+    inputs:
+      install-commands:
+        - apt-get install -y --no-install-recommends libatomic1 shellcheck
+        - python3 -m pip install -e .[pre-commit]
+  - component: "gitlab.desy.de/fs-sc/ci/python/pytest@main"
+    inputs:
+      !!merge <<: *common_test_inputs
+      python-versions: ["3.9", "3.10", "3.11", "3.12"]
+  - component: "gitlab.desy.de/fs-sc/ci/python/pytest-with-coverage@main"
+    inputs:
+      !!merge <<: *common_test_inputs
+      python-version: "3.9"
+  - component: "gitlab.desy.de/fs-sc/ci/python/build-wheel@main"
+  - component: "gitlab.desy.de/fs-sc/ci/python/pytest-wheel@main"
+    inputs:
+      !!merge <<: *common_test_inputs
+      python-versions: ["3.9"]
+  - component: "gitlab.desy.de/fs-sc/ci/python/pytest-tarball@main"
+    inputs:
+      !!merge <<: *common_test_inputs
+      python-versions: ["3.9"]
+  - component: "gitlab.desy.de/fs-sc/ci/python/publish-wheel@main"

asapo_notifier-0.1.0/.mdformat.toml

@@ -0,0 +1,2 @@
+wrap = 89
+number = true

asapo_notifier-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,77 @@
+---
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: meta
+    hooks:
+      # List all the files processed by pre-commit
+      - id: identity
+        name: list_of_files
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+      - id: end-of-file-fixer
+      - id: check-docstring-first
+      - id: check-toml
+      - id: check-yaml
+      - id: check-added-large-files
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.3
+    hooks:
+      - id: codespell
+  - repo: https://github.com/streetsidesoftware/cspell-cli
+    rev: v10.3.0
+    hooks:
+      - id: cspell
+  - repo: https://github.com/google/yamlfmt
+    rev: v0.21.0
+    hooks:
+      - id: yamlfmt
+        args: ["--conf", ".yamllint.yaml"]
+  - repo: https://github.com/adrienverge/yamllint
+    rev: v1.37.1
+    hooks:
+      - id: yamllint
+        args: ["--strict"]
+  - repo: https://github.com/executablebooks/mdformat/
+    rev: 0.7.22
+    hooks:
+      - id: mdformat
+        additional_dependencies:
+          - mdformat-gfm
+          - mdformat-gfm-alerts
+  - repo: https://github.com/psf/black
+    rev: 25.11.0
+    hooks:
+      - id: black
+  - repo: https://github.com/PyCQA/isort
+    rev: 6.1.0
+    hooks:
+      - id: isort
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.3.0
+    hooks:
+      - id: flake8
+  - repo: local
+    hooks:
+      - id: shfmt
+        name: shfmt
+        language: golang
+        additional_dependencies: [mvdan.cc/sh/v3/cmd/shfmt@v3.14.1]
+        entry: shfmt
+        args: [-w]
+        types: [shell]
+      - id: shellcheck
+        name: shellcheck
+        entry: shellcheck
+        language: system
+        types: [shell]
+        require_serial: true
+      - id: mypy
+        name: mypy
+        entry: mypy
+        language: system
+        require_serial: true
+        types_or: [python, pyi]

asapo_notifier-0.1.0/.yamllint.yaml

@@ -0,0 +1,15 @@
+---
+extends: default
+
+rules:
+  line-length:
+    max: 89
+
+formatter:
+  type: basic
+  include_document_start: true
+  eof_newline: true
+  max_line_length: 89
+  retain_line_breaks: true
+  retain_line_breaks_single: true
+  trim_trailing_whitespace: true

asapo_notifier-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+Many thanks for considering contributing to the project!
+
+If you want to make code changes, please create a merge request and make sure that the
+Continuous Integration (CI) pipeline passes for the changes. In particular, make sure
+that the changes follow the coding style of the project enforced by
+[`pre-commit`](https://pre-commit.com/) (see [Run pre-commit](#run-pre-commit)) and that
+all the tests pass (see [Run the tests](#run-the-tests)).
+
+If you need more information on the organization of the code, please consider reading the
+document [doc/architecture.md](/doc/architecture.md).
+
+## Merge Requests Requirements
+
+We request merge requests to be small and focused. If a merge request contains several
+commits, please consider splitting it into multiple merge requests. If a merge request
+consists of several commits, please keep in mind that the commits will be reviewed
+separately.
+
+__In particular, we will reject merge requests that contain a commit that fixes code
+changed in a previous commit of the same merge request__.
+
+Instead, please take the time to organise the structure of commits to facilitate reviews
+of the code (principle of written once, read many times).
+
+## Run pre-commit
+
+To run pre-commit, you need to install some packages locally. Execute the following
+commands to do so:
+
+```shell
+# Assumes a Linux distribution that uses `apt` to install packages...
+apt-get update &&
+apt-get install -y --no-install-recommends git shellcheck shfmt
+python3 -m pip install -e .[pre-commit]
+```
+
+To execute all pre-commit hooks on all files, execute the command `pre-commit run -a`.
+
+## Run the tests
+
+To run the tests, you need an Asapo server. Execute the following commands to start a
+local Asapo server using a Docker container:
+
+```shell
+docker run --rm --name asapo --network host \
+  gitlab.desy.de:5555/asapo/asapo/asapo-standalone:26.02.0.dev01
+```
+
+In addition, you need a Matrix server. Execute the following commands to start a local
+Synapse server using a Docker container:
+
+```shell
+CI_PROJECT_DIR="$PWD"
+docker run --rm --name synapse \
+  -v "$CI_PROJECT_DIR":"$CI_PROJECT_DIR" \
+  --env CI_PROJECT_DIR="$CI_PROJECT_DIR" \
+  --env SYNAPSE_CONFIG_DIR="$CI_PROJECT_DIR/build/synapse/config" \
+  --env SYNAPSE_DATA_DIR="$CI_PROJECT_DIR/build/synapse/data" \
+  -p 8008:8008 \
+  --entrypoint sh \
+  ghcr.io/element-hq/synapse:latest \
+  -c "$CI_PROJECT_DIR/etc/ci/synapse.sh config_and_start"
+```
+
+To check that the Synapse server is running, you can execute the following commands:
+
+```shell
+CI_PROJECT_DIR="$PWD"
+$CI_PROJECT_DIR/etc/ci/synapse.sh check_server_running
+# If cURL is missing: `apt-get install -y --no-install-recommends curl`
+```
+
+You also need to install the dependencies of the `Notifier`. We recommend to use a
+virtual environment for that:
+
+```shell
+# Create a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
+
+# Install dependencies
+python3 -m pip install -e .[asapo,tests]
+```
+
+You can now run the tests (with logs):
+
+```shell
+python3 -m pytest -vv --log-cli-level=DEBUG
+```

asapo_notifier-0.1.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 Marc-Olivier Andrez
+
+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.

asapo_notifier-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+prune etc/
+prune templates/
+global-exclude cspell.json

asapo_notifier-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: asapo_notifier
+Version: 0.1.0
+Summary: Application to notify (beamline) users.
+Author: Marc-Olivier Andrez
+Maintainer: Marc-Olivier Andrez
+License-Expression: MIT
+Project-URL: Repository, https://gitlab.desy.de/fs-sc/analysis-pipelines/notifier
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: asapo-utils
+Requires-Dist: matrix-nio
+Provides-Extra: asapo
+Requires-Dist: asapo-utils[asapo]; extra == "asapo"
+Provides-Extra: tests
+Requires-Dist: pytest; extra == "tests"
+Requires-Dist: pytest-asyncio; extra == "tests"
+Provides-Extra: pre-commit
+Requires-Dist: mypy; extra == "pre-commit"
+Requires-Dist: pre-commit; extra == "pre-commit"
+Requires-Dist: types-PyYAML; extra == "pre-commit"
+Requires-Dist: asapo_notifier[tests]; extra == "pre-commit"
+Provides-Extra: dev
+Requires-Dist: black[d]; extra == "dev"
+Requires-Dist: coverage; extra == "dev"
+Requires-Dist: asapo_notifier[pre-commit,tests]; extra == "dev"
+Dynamic: license-file
+
+# Notifier
+
+`Notifier` is an application that publishes notifications to a communication system such
+as [Matrix](https://matrix.org/) or, in the future, to electronic lab notebooks.
+
+The `Notifier` does not produce notifications itself, but reads messages that have been
+published by other components of a data processing pipeline such as connectors and
+workers to a queue. At the moment, the `actions` stream of a given
+[Asapo](https://asapo.pages.desy.de/asapo/) data source is used to store the queue of
+these messages. We recommend the name `misc` for this Asapo data source.
+
+```mermaid
+graph LR
+  dps@{ shape: procs, label: "Data Processing Units"}
+  actions_queue(["Queue of actions<br/>(Asapo stream)"])
+  notifier[Notifier]
+  comm_system["Communication system<br/>(e.g. Matrix)"]
+  users@{ shape: procs, label: "Users"}
+
+  actions_queue ~~~ notifier
+  dps -- publish actions ---> actions_queue
+  notifier -- read ---> actions_queue
+  notifier -- publish notifications ---> comm_system
+  comm_system -- notifies ---> users
+```
+
+The `Notifier` expects messages that describe notifications to be stored as Asapo
+messages metadata of the following format:
+
+```json
+{
+    "version": "0.1.0",
+    "from": "<component_description>",
+    "action": {"type": "alert", "message": "<message>"},
+}
+```
+
+## Getting started
+
+To run the `Notifier`, you will need a `device_id` and `access_token` that correspond to
+a Matrix account. To create a `device_id` and `access_token` for a given account, execute
+the following commands:
+
+```shell
+MATRIX_USER_ID=""   # Set the corresponding user ID
+MATRIX_PASSWORD=""  # Set the corresponding password
+
+AUTH_RESPONSE="$(curl -X POST "https://matrix.org/_matrix/client/v3/login" \
+     -H "Content-Type: application/json" \
+     -d '{
+       "type": "m.login.password",
+       "identifier": {
+         "type": "m.id.user",
+         "user": "'$MATRIX_USER_ID'"
+       },
+       "password": "'$MATRIX_PASSWORD'",
+       "initial_device_display_name": "bot session"
+     }')"
+# Result:
+# {"access_token":"<token>","device_id":"<device_id>","user_id":"<MATRIX_USER_ID>"}
+matrix_device_id="$(jq -r .device_id <<<"$AUTH_RESPONSE")"
+matrix_access_token="$(jq -r .access_token <<<"$AUTH_RESPONSE")"
+# echo "matrix_device_id='$matrix_device_id' && matrix_access_token='$matrix_access_token'"
+```
+
+> [!NOTE]
+> You can manage the Matrix device IDs on https://account.matrix.org/account/sessions.
+
+To run the `Notifier`, you also need to install its dependencies:
+
+```shell
+# Create a virtual environment
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
+
+# Install dependencies
+python3 -m pip install -e .[asapo]
+```
+
+You can now start the `Notifier` with the following commands:
+
+```shell
+# The values provided below assume using the Asapo standalone Docker container.
+# Edit these values to make the notifier use a different Asapo, beamline, or beamtime.
+asapo_endpoint="localhost:8400"
+asapo_beamline="test"
+asapo_beamtime="asapo_test"
+asapo_token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e\
+yJleHAiOjk1NzE3MTAyMTYsImp0aSI6Ind0ZmlzdGhpcyIsInN\
+1YiI6ImJ0X2FzYXBvX3Rlc3QiLCJFeHRyYUNsYWltcyI6eyJBY\
+2Nlc3NUeXBlcyI6WyJ3cml0ZSIsIndyaXRlcmF3IiwicmVhZCJ\
+dfX0.cz6R_kVf4yh7IJD6bJjDdgTaxPN3txudZx9DE6WaTtk"
+
+# Start the Notifier app:
+python3 -m notifier.app \
+  --asapo.endpoint "$asapo_endpoint" \
+  --beamline "$asapo_beamline" \
+  --beamtime "$asapo_beamtime" \
+  --asapo.token "$asapo_token" \
+  --matrix.device_id "$matrix_device_id" \
+  --matrix.access_token "$matrix_access_token" \
+  --log_level "debug"
+```
+
+> [!NOTE]
+> When starting, the `Notifier` first tries to find or create a room where it will
+> publish the messages. By default, this room is called
+> `desy_<beamline>_<beamtime>_alerts`, but you can provide the `Notifier` with a
+> `matrix.room` argument to specify a different room.
+>
+> If the user was not invited to a room with this name, the `Notifier` will create the
+> room and try to change the parent space of this room. By default, the `Notifier` will
+> use the name `desy_<beamline>` for the parent space, but you can change it by providing
+> the `Notifier` with a `matrix.space` argument. If the space is unknown to the account
+> used by the `Notifier`, the `Notifier` will first create the space.
+
+To test that the notifier works correctly, you can publish some notification messages to
+Asapo:
+
+```shell
+# The values provided below assume using the Asapo standalone Docker container.
+# Edit these values to make the notifier use a different Asapo, beamline, or beamtime.
+asapo_endpoint="localhost:8400"
+asapo_beamline="test"
+asapo_beamtime="asapo_test"
+asapo_token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e\
+yJleHAiOjk1NzE3MTAyMTYsImp0aSI6Ind0ZmlzdGhpcyIsInN\
+1YiI6ImJ0X2FzYXBvX3Rlc3QiLCJFeHRyYUNsYWltcyI6eyJBY\
+2Nlc3NUeXBlcyI6WyJ3cml0ZSIsIndyaXRlcmF3IiwicmVhZCJ\
+dfX0.cz6R_kVf4yh7IJD6bJjDdgTaxPN3txudZx9DE6WaTtk"
+
+# Publish messages to Asapo:
+python3 -m tests.notifier.publish_to_asapo \
+  --asapo.endpoint "$asapo_endpoint" \
+  --beamline "$asapo_beamline" \
+  --beamtime "$asapo_beamtime" \
+  --asapo.token "$asapo_token" \
+  --messages "tests/notifier/messages.json" \
+  --log_level "debug"
+```
+
+> [!CAUTION]
+> A message published to Asapo cannot be removed. If you publish messages to Asapo for
+> testing purposes, they will be part of the beamtime alert messages. In addition, the
+> corresponding messages published to Matrix will stay in the room as well.
+
+As a reminder, if you want to use an Asapo standalone Docker container, execute the
+following command:
+
+```shell
+docker run --rm --name asapo --network host \
+  gitlab.desy.de:5555/asapo/asapo/asapo-standalone:26.02.0.dev01
+```
+
+## Contributing
+
+If you want to contribute, please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
+
+In addition, you can find more information on the organization of the code in the
+document [doc/architecture.md](/doc/architecture.md).