Merge branch 'develop' into signal_documentation

.github/workflows/discussions.yml

@@ -0,0 +1,90 @@
+---
+# This workflow notifies working groups about new discussions in their corresponding
+# categories, by mentioning the Team in a first comment.
+# It is necessary since GitHub doesn't support subsriptions to discussion categories
+# see related feature request: https://github.com/orgs/community/discussions/3951
+# If GitHub implements this feature, this workflow becomes obsolete.
+
+# To work, this workflow requires a GitHub App installed on the repository with the
+# following permissions:
+#   - Write and Read of repository Discussions
+#   - Read of Organization members (needed for reading the teams)
+
+# !! You need to make sure that the app's id and a generated private key are saved
+# as corresponding organization secrets !!
+
+name: Notify Team on New Discussion
+"on":
+  discussion:
+    types: [created]
+
+jobs:
+  notify_team:
+    runs-on: ubuntu-latest
+    steps:
+      # First generate the app token for authentication
+      - name: Get GitHub App token
+        id: github-app-token
+        uses: tibdex/github-app-token@v1
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - name: Notify Team
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ steps.github-app-token.outputs.token }}
+          script: |
+            const discussion = context.payload.discussion;
+            const category = discussion.category.name;
+
+            const query = `
+              query($discussionNumber: Int!) {
+                repository(
+                  owner: "${context.repo.owner}",
+                  name: "${context.repo.repo}"
+                ) {
+                  discussion(number: $discussionNumber) {
+                    id
+                  }
+                }
+              }
+            `;
+
+            const mutation = `
+              mutation($discussionId: ID!, $body: String!) {
+                addDiscussionComment(
+                  input: {discussionId: $discussionId, body: $body}
+                ) {
+                  comment {
+                    id
+                    body
+                  }
+                }
+              }
+            `;
+
+            const response = await github.graphql(query, {
+              discussionNumber: discussion.number
+            });
+
+            const discussionId = response.repository.discussion.id;
+
+            const teams = await github.rest.teams.list({
+              org: context.repo.owner,
+            });
+
+            const team = teams.data.find(t => t.name === category);
+
+            if (team) {
+              const teamMention = `${context.repo.owner}/${team.slug}`;
+              const commentBody = `@${teamMention} A new discussion was created in the`
+                                   + ` "${category}" category: ${discussion.html_url}`;
+
+              await github.graphql(mutation, {
+                discussionId: discussionId,
+                body: commentBody
+              });
+            } else {
+              console.log(`No team found for category: ${category}`);
+            }

.isort.cfg

@@ -1,11 +1,4 @@
 [settings]
-; see https://github.com/psf/black
-multi_line_output=3
-include_trailing_comma=True
-force_grid_wrap=0
-combine_as_imports=True
-use_parentheses=True
-line_length=88
-sections=FUTURE,STDLIB,THIRDPARTY,FIRSTPARTY,LOCALFOLDER
-default_section=THIRDPARTY
-ensure_newline_before_comments = True
+profile=black
+py_version=38
+force_grid_wrap=2

.pre-commit-config.yaml

@@ -1,8 +1,5 @@
 ---
 
-default_language_version:
-  python: python3.8
-
 repos:
 
   - repo: https://github.com/adrienverge/yamllint
@@ -13,12 +10,12 @@ repos:
           - --strict
 
   - repo: https://github.com/python-poetry/poetry
-    rev: 1.5.0
+    rev: 1.8.0
     hooks:
       - id: poetry-check
 
   - repo: https://github.com/myint/autoflake
-    rev: v1.6.0
+    rev: v2.3.1
     hooks:
       - id: autoflake
         name: Autoflake
@@ -29,14 +26,21 @@ repos:
           - --remove-duplicate-keys
           - --ignore-pass-after-docstring
 
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+
   - repo: https://github.com/psf/black
-    rev: 22.8.0
+    rev: 24.8.0  # The following version (`24.10.0`) dropped support for Python 3.8.
     hooks:
       - id: black
         name: Black
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.6.0
+    # The following version (pre-commit-hooks 5.0.0) requires pre-commit 3.2.0
+    # which does not support Python 3.8 (dropped in pre-commit 3.0.0).
     hooks:
       - id: trailing-whitespace
         # Exclude files from trailing-whitespace checks until we get around fixing them.
@@ -53,7 +57,6 @@ repos:
                 mxcubecore/HardwareObjects/EMBL/EMBL(Energy|DoorInterlock|OnlineProcessing)\.py|
                 mxcubecore/HardwareObjects/mockup/(ISPyBClient|Motor|PlateManipulator)Mockup\.py|
                 mxcubecore/HardwareObjects/abstract/(AbstractXRFSpectrum|sample_changer/Crims)\.py|
-                mxcubecore/HardwareObjects/Gphl/Transcal2MiniKappa\.py|
                 mxcubecore/HardwareObjects/SOLEIL/PX2/PX2Resolution\.py|
                 mxcubecore/HardwareObjects/ESRF/ID29XRFSpectrum\.py
             )$

CONTRIBUTING.md

@@ -111,22 +111,33 @@ The exact routine is described more preceisly in [MEP01](https://github.com/mxcu
 ### Coding convention and style guidelines
 
 #### Units
-Functions returning a value representing a physical quantity should in general be assoicated with
-a unit. It has been agreed that the following units should, where applicable, be used across the
-code base
-
- * mm (millimeter) for translative motors and sizes
- * degrees for rotative motors
- * perecent (%) for ratios like attenuation
- * keV for energy
- * K (Kelvin) for temperature
- * Å (Ångström) for resolution
- * Pixels are to be used for beam location (center)
- * Datetime YYYY-MM-DD HH:MM:SS(.ff) ,possibly with hundreds of seconds (ff), and with 24 hour clock.
 
+Units must be documented via docstrings
+for the parameters and return values of functions and methods,
+for variables,
+and for attributes of classes and objects.
+
+The units of variables within a function or method must be documented as well.
+For example, with simple comments or by including the unit in the variable name itself.
 When writing code that converts between different units,
-it is recommended to use utility functions from {py:mod}`mxcubecore.utils.units` module.
-This will to aid in the readability of the code.
+it is possible to use utility functions from {py:mod}`mxcubecore.utils.units` module,
+which will make the unit conversion explicit.
+
+Furthermore, it has been agreed that, whenever possible,
+the following units must be used across the code base:
+
+* mm (millimetre) for translational motors and sizes
+* degree for rotational motors
+* percentage (%) for ratios like attenuation
+* keV for energy
+* K (Kelvin) for temperature
+* Å (Ångström) for resolution
+* pixel for beam location (centre)
+* YYYY-MM-DD HH:MM:SS(.ff) for date and time,
+  possibly with hundreds of seconds (ff), and with 24-hour clock.
+
+Even if the code uses those units, they must be documented.
+
 
 #### Value update signals/callbacks
 The "valueChanged" and "stateChanged" signals should be used when a HardwareObjects value or state

deprecated/Command/Exporter/MDClient.py

@@ -1,7 +1,8 @@
-import sys
-import time
 import string
+import sys
 import threading
+import time
+
 from Command.exporter.ExporterClient import *
 
 SERVER_ADDRESS = "localhost"

deprecated/HardwareObjects/Camera.py

@@ -15,13 +15,18 @@
     </calibration> -->
   </object>
 """
-from mxcubecore import BaseHardwareObjects
-from mxcubecore import CommandContainer
-import gevent
+
 import logging
 import os
-import time
 import sys
+import time
+
+import gevent
+
+from mxcubecore import (
+    BaseHardwareObjects,
+    CommandContainer,
+)
 
 try:
     from Qub.CTools.qttools import BgrImageMmap

deprecated/HardwareObjects/EnhancedPopen.py

@@ -1,9 +1,9 @@
+import errno
+import fcntl
 import os
+import select
 import subprocess
-import errno
 import time
-import select
-import fcntl
 
 PIPE = subprocess.PIPE
 

deprecated/HardwareObjects/Mar225.py

@@ -3,7 +3,7 @@
 
 class Mar225(HardwareObject):
     def __init__(self, name):
-        Device.__init__(self, name)
+        super().__init__(name)
 
     def init(self):
         pass

deprecated/HardwareObjects/NamedState.py

@@ -17,15 +17,15 @@
 #  You should have received a copy of the GNU Lesser General Public License
 #  along with MXCuBE. If not, see <http://www.gnu.org/licenses/>.
 
+import logging
+
 from mxcubecore import HardwareRepository as HWR
 from mxcubecore.BaseHardwareObjects import HardwareObject
 
-import logging
-
 
 class NamedState(HardwareObject):
     def __init__(self, name):
-        Device.__init__(self, name)
+        super().__init__(name)
         self.stateList = []
 
     def _init(self):

deprecated/HardwareObjects/Server/Daemonize.py

@@ -1,5 +1,5 @@
-import sys
 import os
+import sys
 
 """This module is used to fork the current process into a daemon.
     Almost none of this is necessary (or advisable) if your daemon

deprecated/HardwareObjects/Server/SimpleXMLReadWriteSupport.py

@@ -1,10 +1,12 @@
-import sys
 import io
+import sys
+from xml.sax import (
+    SAXParseException,
+    make_parser,
+)
+from xml.sax.handler import ContentHandler
 from xml.sax.saxutils import XMLGenerator
-from xml.sax import make_parser
-from xml.sax import SAXParseException
 from xml.sax.xmlreader import AttributesImpl
-from xml.sax.handler import ContentHandler
 
 _parser = make_parser()
 

deprecated/HardwareObjects/Server/__init__.py

@@ -4,10 +4,12 @@
 from xml.sax import SAXParseException
 from xml.sax.handler import ContentHandler
 
-from SpecClient_gevent import SpecServer
-from SpecClient_gevent import SpecMessage
 import Daemonize
 import SimpleXMLReadWriteSupport
+from SpecClient_gevent import (
+    SpecMessage,
+    SpecServer,
+)
 
 
 class XMLNodesWithRolesReadingHandler(ContentHandler):

deprecated/HardwareObjects/SpecMotor.py

@@ -1,12 +1,13 @@
-from mxcubecore.BaseHardwareObjects import HardwareObject
 from SpecClient_gevent.SpecMotor import SpecMotorA
 
+from mxcubecore.BaseHardwareObjects import HardwareObject
+
 
-class SpecMotor(Device, SpecMotorA):
+class SpecMotor(HardwareObject, SpecMotorA):
     (NOTINITIALIZED, UNUSABLE, READY, MOVESTARTED, MOVING, ONLIMIT) = (0, 1, 2, 3, 4, 5)
 
     def __init__(self, name):
-        Device.__init__(self, name)
+        super().__init__(name)
         SpecMotorA.__init__(self)
 
     def _init(self):
@@ -53,7 +54,7 @@ def get_motor_mnemonic(self):
 
 class SpecVersionMotor(SpecMotor):
     def __init__(self, specversion, specname, username):
-        Device.__init__(self, specname)
+        super().__init__(specname)
         self.specversion = specversion
         self.specname = specname
         self.username = username

deprecated/HardwareObjects/SpecMotorWPositions.py

@@ -1,6 +1,7 @@
-from mxcubecore.HardwareObjects import SpecMotor
 import logging
 
+from mxcubecore.HardwareObjects import SpecMotor
+
 
 class SpecMotorWPositions(SpecMotor.SpecMotor):
     def init(self):

deprecated/HardwareObjects/SpecMotorWSpecPositions.py

@@ -11,6 +11,7 @@
          <delta>tolerance allowed between real motor position and defined position</delta> -->
   </object>
 """
+
 import logging
 
 from mxcubecore.HardwareObjects import SpecMotor

deprecated/HardwareObjects/SpecScan.py

@@ -1,6 +1,8 @@
 try:
-    from SpecClient_gevent import SpecEventsDispatcher
-    from SpecClient_gevent import SpecConnectionsManager
+    from SpecClient_gevent import (
+        SpecConnectionsManager,
+        SpecEventsDispatcher,
+    )
 except ImportError:
     from SpecClient import SpecEventsDispatcher
     from SpecClient import SpecConnectionsManager

deprecated/HardwareObjects/SpecShell.py

@@ -7,6 +7,7 @@
 """
 
 import logging
+
 from mxcubecore.BaseHardwareObjects import HardwareObject
 
 try:
@@ -30,7 +31,7 @@ def update(self, value):
 
 class SpecShell(HardwareObject):
     def __init__(self, *args):
-        Equipment.__init__(self, *args)
+        super().__init__(*args)
         self.isSpecReady = False
 
     def init(self):