rdmo 2.4.3__tar.gz → 2.5.0__tar.gz

rdmo-2.5.0/.github/dependabot.yml

@@ -0,0 +1,94 @@
+version: 2
+updates:
+- package-ecosystem: pip
+  directory: /
+  schedule:
+    interval: monthly
+  versioning-strategy: increase-if-necessary
+  open-pull-requests-limit: 10
+  target-branch: dependency-updates
+  labels:
+  - dependencies
+  - python
+  - type:maintenance
+  ignore:
+  - dependency-name: django
+    update-types: [ "version-update:semver-major"] # ignore major for django
+  groups:
+    # create a single pull request containing all updates for the optional dependencies
+    optional:
+      patterns:
+      - django-allauth
+      - django-auth-ldap
+      - gunicorn
+      - mysqlclient
+      - pre-commit
+      - psycopg*
+      - pytest*
+    # create a single pull request containing all updates for django related dependencies
+    django:
+      patterns:
+      - django*
+      - drf*
+  cooldown:
+    default-days: 7
+- package-ecosystem: github-actions
+  directory: /
+  schedule:
+    interval: monthly
+  target-branch: dependency-updates
+  labels:
+  - dependencies
+  - github_actions
+  - type:maintenance
+  groups:
+    # create a single pull request containing all updates for GitHub Actions
+    github-actions:
+      patterns:
+      - '*'
+  cooldown:
+    default-days: 7
+- package-ecosystem: npm
+  directory: /
+  schedule:
+    interval: monthly
+  open-pull-requests-limit: 10
+  target-branch: dependency-updates
+  labels:
+  - dependencies
+  - javascript
+  - type:maintenance
+  ignore:
+  - dependency-name: react-bootstrap # rdmo still uses bootstrap 3, which is not supported by react-bootstrap > 0.33.1
+  - dependency-name: "*"
+    update-types: ["version-update:semver-patch"] # ignore patch versions for all JavaScript dependencies
+  - dependency-name: react-redux
+    update-types: ["version-update:semver-major"] # ignore major for react-redux
+  - dependency-name: eslint
+    update-types: ["version-update:semver-major"] # keep eslint 8.56.0 for now
+  - dependency-name: jquery
+    update-types: [ "version-update:semver-major" ] # keep jQuery 3.x until Bootstrap is upgraded
+  groups:
+    react:
+      patterns:
+      - react*
+    redux:
+      patterns:
+      - redux*
+    babel:
+      patterns:
+      - '@babel*'
+      - babel*
+    webpack:
+      patterns:
+      - webpack*
+      - copy-webpack-plugin
+    eslint:
+      patterns:
+      - eslint*
+    prod-dependencies:
+      dependency-type: production
+    dev-dependencies:
+      dependency-type: development
+  cooldown:
+    default-days: 7

rdmo-2.5.0/.github/workflows/ci.yml

@@ -0,0 +1,284 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - '*'
+  pull_request:
+    # run CI only if files in these whitelisted paths are changed
+    paths:
+      - '.github/workflows/**'
+      - 'rdmo/**'
+      - 'testing/**'
+      - 'webpack/**'
+      - .eslintrc.js
+      - .nvmrc
+      - .pre-commit-config.yaml
+      - conftest.py
+      - package.json
+      - pyproject.toml
+
+# Ref: https://docs.github.com/en/actions/using-jobs/using-concurrency
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONDONTWRITEBYTECODE: 1
+  FORCE_COLOR: 1 # colored output by pytest etc.
+
+permissions: {}
+
+jobs:
+
+  build:
+    name: Build python package
+    runs-on: ubuntu-24.04
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        persist-credentials: false
+        fetch-depth: 0  # important for setuptools_scm
+    - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+      with:
+        node-version: 22.22
+        cache: ${{ startsWith(github.ref, 'refs/tags/') && '' || 'npm' }}  # disable cache on tags
+    - name: build front end
+      run: npm ci && npm run build:dist
+    - name: Build and inspect package
+      uses: hynek/build-and-inspect-python-package@d44ca7d91762de7a7d5436ddae667c6da6d1c3df # v2.18.0
+
+  test:
+    name: "Test (Python: ${{ matrix.python-version }}, DB: ${{ matrix.db-backend }})"
+    needs: build
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.14']
+        db-backend: [mysql, postgres]
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        persist-credentials: false
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: pip
+    - name: Download wheel
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+      with:
+        name: Packages
+        path: dist
+    - name: Install Dependencies
+      run: |
+        sudo apt-get update && sudo apt-get install --yes pandoc texlive-latex-base texlive-latex-extra texlive-luatex librsvg2-bin
+        pandoc --version
+        python -m pip install --upgrade pip
+        python -m pip --version
+    - name: Install rdmo[mysql] from wheel and start mysql
+      run: |
+        python -m pip install "$(ls dist/*.whl)[ci,mysql]"
+        sudo systemctl start mysql.service
+      if: matrix.db-backend == 'mysql'
+    - name: Install rdmo[postgres] from wheel and start postgresql
+      run: |
+        python -m pip install "$(ls dist/*.whl)[ci,postgres]"
+        sudo systemctl start postgresql.service
+        pg_isready
+        sudo -u postgres psql --command="CREATE USER postgres_user PASSWORD 'postgres_password' CREATEDB"
+      if: matrix.db-backend == 'postgres'
+    - name: Prepare Env
+      run: |
+        cp -r testing/media testing/media_root && mkdir testing/log
+    - name: Run package status tests first
+      run: |
+        pytest rdmo/core/tests/test_package_status.py --nomigrations --verbose
+      if: matrix.python-version == '3.14' && matrix.db-backend == 'postgres'
+    - name: Run Tests
+      run: |
+        pytest -p randomly -p no:cacheprovider --cov --reuse-db --numprocesses=auto --dist=loadscope
+      env:
+        GITHUB_DB_BACKEND: ${{ matrix.db-backend }}
+    - name: Upload coverage data to coveralls.io
+      uses: coverallsapp/github-action@5cbfd81b66ca5d10c19b062c04de0199c215fb6e # v2.3.7
+      with:
+        flag-name: '${{ matrix.db-backend }}: ${{ matrix.python-version }}'
+        parallel: true
+        fail-on-error: false
+        allow-empty: true
+
+  test-e2e:
+    name: "End-to-end Test (Python: ${{ matrix.python-version }}, DB: ${{ matrix.db-backend }})"
+    needs: build
+    runs-on: ubuntu-24.04
+    strategy:
+      matrix:
+        python-version: ['3.14']
+        db-backend: [postgres]
+    steps:
+    - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      with:
+        persist-credentials: false
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: pip
+    - name: Download package
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+      with:
+        name: Packages
+        path: dist
+    - name: Install Dependencies
+      run: |
+        sudo apt-get update && sudo apt install --yes pandoc texlive-latex-base texlive-latex-extra texlive-luatex librsvg2-bin
+        python -m pip install --upgrade pip
+    - name: Install rdmo[postgres] from wheel and start postgresql
+      run: |
+        python -m pip install "$(ls dist/*.whl)[ci,postgres]"
+        sudo systemctl start postgresql.service
+        pg_isready
+        sudo -u postgres psql --command="CREATE USER postgres_user PASSWORD 'postgres_password' CREATEDB"
+    - name: Prepare Env
+      run: |
+        cp -r testing/media testing/media_root && mkdir testing/log
+    - name: Install e2e tests dependencies
+      run: |
+        playwright install --with-deps chromium
+    - run: mkdir screenshots
+    - name: Collect static files into static root (only required if rdmo is installed from wheel)
+      run: python testing/manage.py collectstatic --noinput
+    - name: Run end-to-end tests
+      run: pytest -p randomly -p no:cacheprovider --reuse-db --numprocesses=auto --dist=loadscope -m e2e --nomigrations
+      env:
+        DJANGO_DEBUG: True
+        GITHUB_DB_BACKEND: ${{ matrix.db-backend }}
+    - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+      with:
+        name: screenshots
+        path: screenshots/**/*.png
+
+  coveralls:
+    name: Indicate completion to coveralls
+    needs: test
+    if: ${{ always() }}
+    runs-on: ubuntu-slim
+    steps:
+    - name: Run Coveralls finish
+      uses: coverallsapp/github-action@5cbfd81b66ca5d10c19b062c04de0199c215fb6e # v2.3.7
+      with:
+        parallel-finished: true
+        fail-on-error: false
+
+  dev-setup:
+    # Ref: structlog (MIT licensed) <https://github.com/hynek/structlog/blob/main/.github/workflows/ci.yml>
+    name: "Test dev setup on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.14"
+          cache: pip
+      - run: python -Im pip install --editable .[dev]
+      - run: python -Ic 'import rdmo; print(rdmo.__version__)'
+
+  dependencies:
+    name: Test installation of all dependencies
+    needs: build
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.14"
+          cache: pip
+      - name: Download package
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+        with:
+          name: Packages
+          path: dist
+      - name: Install os requirements for python-ldap
+        run: sudo apt-get update && sudo apt-get install --yes libldap2-dev libsasl2-dev
+      - run: python -m pip install --upgrade pip
+      - name: Install rdmo wheel with all optional dependency groups
+        run: python -m pip install --no-compile "$(ls dist/*.whl)[all]"
+      - name: Verify installed packages have compatible dependencies
+        run: python -m pip check
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm install --include=dev
+      - name: Write info to step summary
+        run: |
+          {
+            echo -e "# ✓ All dependency groups successfully installed in combination\n\n"
+            echo '<details><summary>Installed Python packages (dependency tree)</summary>'
+            echo -e "\n\`\`\`console"
+            echo "$ python -m pipdeptree --local-only --exclude=pip,pipdeptree"
+            python -m pipdeptree --local-only --exclude=pip,pipdeptree
+            echo -e "\`\`\`\n</details>"
+            echo '<details><summary>Outdated Python dependencies</summary>'
+            echo -e "\n\`\`\`console"
+            echo "$ python -m pip list --outdated"
+            python -m pip list --outdated
+            echo -e "\`\`\`\n</details>"
+            echo '<details><summary>Installed JavaScript packages (dependency tree)</summary>'
+            echo -e "\n\`\`\`console"
+            echo "$ npm list --all"
+            npm list --all
+            echo -e "\`\`\`\n</details>"
+            echo '<details><summary>Outdated JavaScript dependencies</summary>'
+            echo -e "\n\`\`\`console"
+            echo "$ npm outdated --long"
+            npm outdated --long || true
+            echo -e "\`\`\`\n</details>"
+          } >> $GITHUB_STEP_SUMMARY
+
+  pypi-release:
+    name: Publish distribution to PyPI
+    if: startsWith(github.ref, 'refs/tags/')
+    needs:
+    - build
+    - test
+    - test-e2e
+    runs-on: ubuntu-24.04
+    environment:
+      name: pypi
+      url: https://pypi.org/p/rdmo
+    permissions:
+      id-token: write
+    steps:
+    - name: Download package
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+      with:
+        name: Packages
+        path: dist
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b  # v1.14.0
+
+  required-checks-pass:
+    if: always()
+    needs:
+      - build
+      - test
+      - coveralls
+      - test-e2e
+      - dev-setup
+      - dependencies
+    runs-on: ubuntu-slim
+    steps:
+      - uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
+        with:
+          jobs: ${{ toJSON(needs) }}

rdmo-2.5.0/.github/zizmor.yml

@@ -0,0 +1,4 @@
+rules:
+  cache-poisoning:
+    ignore:
+    - ci.yml

rdmo-2.5.0/.pre-commit-config.yaml

@@ -0,0 +1,61 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+# Run manual autoupdate with:
+#   pre-commit autoupdate --freeze
+#   pre-commit run --all-files
+
+# do not touch the migration files at all: these are auto-generated by Django
+exclude: \/migrations\/
+
+repos:
+  - repo: meta
+    hooks:
+      - id: check-hooks-apply
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c  # frozen: v6.0.0
+    hooks:
+      - id: check-ast
+      - id: check-json
+      - id: check-xml
+        exclude: error\.xml$
+      - id: check-yaml
+      - id: end-of-file-fixer
+        exclude: \.html$|\.txt$
+      - id: trailing-whitespace
+        exclude: \.dot$
+      - id: debug-statements
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: 3b3f7c3f57fe9925356faf5fe6230835138be230  # frozen: v0.15.17
+    hooks:
+      - id: ruff-check
+        args: [--fix, --exit-non-zero-on-fix]
+  - repo: https://github.com/pre-commit/mirrors-eslint
+    rev: 97a8e4af05a8fa8a0ed79d2fbd1f4c86bf1a0178  # frozen: v10.5.0
+    hooks:
+      - id: eslint
+        args: [--fix, --color]
+        additional_dependencies:
+          - eslint@8.56.0
+          - eslint-plugin-react@7.37.0
+          - react@18.3.1
+  - repo: https://github.com/crate-ci/typos
+    rev: 37bb98842b0d8c4ffebdb75301a13db0267cef89  # frozen: v1.47.2
+    hooks:
+    - id: typos
+      exclude: |
+        (?x)^(
+            rdmo/locale/.*|
+            rdmo/.*_de.html$|
+            rdmo/.*_es.html$|
+            rdmo/.*_fr.html$|
+            rdmo/.*_it.html$|
+            testing/.*.json|
+            testing/.*.xml
+        )$
+  - repo: https://github.com/zizmorcore/zizmor-pre-commit
+    rev: 9257c6050c0261b8c57e712f632dc4a8010109a9  # frozen: v1.25.2
+    hooks:
+    - id: zizmor
+      args: [--fix, --offline]
+ci:
+  autofix_prs: false

rdmo-2.5.0/ARCHITECTURE.md

@@ -0,0 +1,141 @@
+# Architecture
+
+This document provides an overview over the architecture of RDMO and provides information about the different modules.
+
+## Core dependencies
+
+RDMO is a [Django](https://www.djangoproject.com/) application with an integrated [React](https://react.dev/) frontend.
+
+On the backend, it makes heavy use of:
+
+* [Django Rest Framework](https://www.django-rest-framework.org/) (DRF) for the REST API,
+* [rules](https://github.com/dfunckt/django-rules) for object based permissions.
+
+The frontend code relies on:
+
+* [webpack](https://webpack.js.org) for bundling,
+* [Redux](https://redux.js.org/) for state management,
+* [Redux Thunk](https://github.com/reduxjs/redux-thunk) for asynchronous Redux actions,
+* [Bootstrap](https://getbootstrap.com/) as CSS framework,
+* [lodash](https://lodash.com/) for various utilities.
+
+Testing is done with:
+
+* [pytest](https://docs.pytest.org) for the backend,
+* [Playwright](https://playwright.dev) for the frontend.
+
+## File layout
+
+The main `rdmo` package consists of the following modules:
+
+```
+rdmo/
+├── core/              ← Core functionality
+├── accounts/          ← Authentication & user profiles
+├── domain/            ← Domain model
+├── questions/         ← Structure of the questionnaire
+├── conditions/        ← Conditional display of questions or answers
+├── options/           ← Controlled vocabularies for answers
+├── tasks/             ← Follow up actions based on answers
+├── views/             ← Templating for output and export
+├── projects/          ← User projects, snapshots and answers
+├── management/        ← Management editing backend
+└── services/          ← OAuth / external integrations
+```
+
+Each module (an *app* in Django terms) tries to follow the conventional layout and naming conventions:
+
+* `admin.py` → Django admin interface configuration
+* `apps.py` → Django app configuration
+* `assets/` → Source files for the frontend (JavaScript, CSS, ...)
+* `constants.py` → Definition of constant values
+* `exports.py` → Export plugin functionality
+* `filters.py` → Filters for DRF viewsets
+* `forms.py` → Django forms
+* `handlers/` or `handlers.py` → Handlers for Django signals
+* `imports.py` → Helper functionality for the XML import
+* `managers.py` → Managers for Django models
+* `migrations/` → Django database migrations
+* `mixins.py` → Mixins for different classes
+* `models/` or `models.py` → Django database models
+* `permissions.py` → DRF permission classes
+* `providers.py` → Optionset provider plugins
+* `renderers/` or `renderers.py` → Render functionality for the XML export
+* `rules.py` → Object based permissions
+* `serializers/` or `serializers.py` → DRF serializers
+* `signals.py` → Signals for Django signals
+* `static/` → Build front end assets, ignored by Git
+* `templates/` → Django templates
+* `templatetags/` → Django template tags and filters
+* `tests/` → Tests
+* `urls/` or `urls.py` → Django URL mapping
+* `utils.py` → Utility functions
+* `validators.py` → Additional validators for DRF
+* `views/` or `views.py` → Django views
+* `viewsets.py` → DRF viewsets for the REST API
+
+In addition, the `rdmo` repository contains the following notable files or directories:
+
+* `pyproject.toml` → Python package configuration
+* `rdmo/locale` → Translation files
+* `rdmo/share` → Supplemental files
+* `testing` → Test configuration & fixtures
+* `conftest.py` → pytest setup
+* `webpack.config.js` → Frontend build configuration
+* `package.json` and `package-lock.json` → Frontend dependencies
+
+The `assets` directories in the modules use the following structure:
+
+* `assets/js/` → JavaScript front-end code, separated by React app
+    * `actions/` → Actions for the Redux store
+    * `api/` → API classes with methods mapping the endpoints of the REST API
+    * `components/` → React components
+    * `factories/` → Factory functions for front end objects
+    * `hooks/` → React hooks
+    * `reducers/` → Reducers for the Redux store
+    * `store/` → Configuration and initialization of the Redux store
+    * `utils/` → Utility functions
+* `assets/scss/` → Sass files, separated by React app
+* `assets/fonts/`, `assets/img/` → Additional, static assets
+
+## Internal dependencies
+
+The modules directly depend on each other (e.g. by importing classes or functions) in the following way:
+
+* `core` does not depend on the other modules.
+* `accounts` and `domain` depend only on `core`.
+* `conditions` depends on `core`, `domain`, and `options`.
+* `options` depends on `core` and `conditions`.
+* `questions` depends on `core`, `conditions`, `domain`, and `options`.
+* `tasks` depends on `core`, `conditions`, `domain`, and `questions`.
+* `views` depends on `core` and `questions`.
+* `project` and `management` depend on `core`, `conditions`, `domain`, `options`, `questions`, `tasks`, and `views`.
+
+Besides those dependencies:
+
+* `utils.py` and `managers.py` must not depend on anything inside the module.
+* `models.py` must only depend on `utils.py` and `managers.py`.
+
+If utility functions are needed, which depend on the models they are put in special files, e.g. `process.py`. Utility functions for tests are placed in `tests/helpers.py`.
+
+Besides those relationships, which should not be extended, implicit dependencies exists, e.g. when functions take objects from other modules as arguments.
+
+Only after careful consideration, functions can use local imports (in the function body) to circumvent the described dependency rules.
+
+## Backend considerations
+
+RDMO tries to follow the conventional style of Django projects. It should work with all database backends and with all common web server setups. The aim is to limit the dependencies and the effort to maintain an instance to a minimum. For the same reason, RDMO does not depend on a caching solution or an infrastructure for asynchronous tasks.
+
+While some parts of RDMO use the common Django MVC-pattern using models, (class-based) views and templates, other parts use the Django Rest Service pattern using viewsets, serializers and renderers. The latter is used by the interactive frontend (see below), but also as scriptable API.
+
+## Frontend considerations
+
+As already mentioned, major parts of RDMO are implemented as separate interactive *single page applications*. In particular:
+
+* the projects table located at `/projects/`,
+* the project dashboard located at `/projects/<id>/`,
+* the management interface located at `/management/`.
+
+The Django template of these pages contain just an empty element, and the functionality is implemented with JavaScript, React and Redux, and makes heavy use of the REST API.
+
+In order to keep the deployment effort low, no node dependencies need to be handled by the maintainers of the instances. Instead, the frontend is build when creating the release and is then shipped as part of the `rdmo` Python package. Frontend source files reside in `rdmo/<module>/assets/` and the build is stored in `rdmo/<module>/static/`, from where Django handles them as regular static files.