hrm_omero.decorators

 1"""Decorator functions."""
 2
 3import functools
 4from loguru import logger as log
 5
 6from .misc import OmeroId
 7
 8
 9def connect_and_set_group(func):
10    """Decorator ensuring the connection is established and the group context is set.
11
12    This decorator is specifically made for functions that require an established
13    connection to OMERO as well as the group for the connection / session to be switched
14    explicitly.
15
16    In addition it also checks the `omero_id` parameter and ensures it is an
17    object of type `hrm_omero.misc.OmeroId`. In case the parameter received is a
18    string, it will automatically create the corresponding `OmeroId` object,
19    which also checks the values of the ID for sanity.
20
21    Other Parameters
22    ----------------
23    conn : omero.gateway.BlitzGateway
24        The OMERO connection object.
25    omero_id : str or hrm_omero.misc.OmeroId
26        The fully qualified ID of an OMERO object (e.g. `G:23:Image:42`) as
27        a string or as an `hrm_omero.misc.OmeroId` object directly.
28    """
29
30    @functools.wraps(func)
31    def wrapper_connect_and_set_group(conn, omero_id, *args, **kwargs):
32        """Inner wrapper function for the `connect_and_set_group` decorator.
33
34        Parameters
35        ----------
36        conn : omero.gateway.BlitzGateway
37            The OMERO connection object.
38        omero_id : str or hrm_omero.misc.OmeroId
39            The fully qualified ID of an OMERO object (e.g. `G:23:Image:42`) as
40            a string or as an `hrm_omero.misc.OmeroId` object directly.
41
42        Raises
43        ------
44        RuntimeError
45            Raised in case the OMERO connection can't be established.
46        ValueError
47            Raised in case a malformed `omero_id` was given.
48        """
49        # the connection might be closed (e.g. after importing an image), so force
50        # re-establish it (note that `conn._connected` might even report the wrong
51        # state initially, or also after reconnecting!)
52        #
53        ##### WARNING - WARNING - WARNING - WARNING - WARNING - WARNING - WARNING #####
54        #
55        # calling `conn.connect()` and `conn.setGroupForSession` subsequently (i.e.)
56        # multiple times during one session has unexpected side effects, e.g. when using
57        # the decorator for `transfer.fetch_thumbnail()` will make the call to
58        # `conn.getObject()` return `None`
59        #
60        ##### WARNING - WARNING - WARNING - WARNING - WARNING - WARNING - WARNING #####
61        conn.connect()
62        if not conn._connected:  # pylint: disable-msg=protected-access
63            raise RuntimeError("Failed to (re-)establish connection to OMERO!")
64        username = conn.getUser().getName()
65        log.success(f"Successfully (re-)connected to OMERO as [{username}].")
66
67        # if the ID is passed as a string parse it into an OmeroId object:
68        if isinstance(omero_id, str):
69            omero_id = OmeroId(omero_id)
70
71        # set the OMERO group for the current connection session:
72        conn.setGroupForSession(omero_id.group)
73        log.debug(f"Set OMERO session group to [{omero_id.group}].")
74
75        return func(conn, omero_id, *args, **kwargs)
76
77    return wrapper_connect_and_set_group