pymodaq_utils 5.3.0a0__tar.gz → 5.3.2__tar.gz

{pymodaq_utils-5.3.0a0 → pymodaq_utils-5.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pymodaq_utils
-Version: 5.3.0a0
+Version: 5.3.2
 Summary: Modular Data Acquisition with Python
 Project-URL: Homepage, http://pymodaq.cnrs.fr
 Project-URL: Source, https://github.com/PyMoDAQ/PyMoDAQ
@@ -76,11 +76,11 @@ PyMoDAQ Utils
    :target: https://pypi.org/project/pymodaq_utils/
    :alt: Latest Version
 
-.. image:: https://readthedocs.org/projects/pymodaq/badge/?version=state-machine-simplify
-   :target: https://pymodaq.readthedocs.io/en/stable/?badge=state-machine-simplify
+.. image:: https://readthedocs.org/projects/pymodaq/badge/?version=patch-3
+   :target: https://pymodaq.readthedocs.io/en/stable/?badge=patch-3
    :alt: Documentation Status
 
-.. image:: https://codecov.io/gh/PyMoDAQ/PyMoDAQ/branch/state-machine-simplify/graph/badge.svg?token=IQNJRCQDM2 
+.. image:: https://codecov.io/gh/PyMoDAQ/PyMoDAQ/branch/patch-3/graph/badge.svg?token=IQNJRCQDM2 
  :target: https://codecov.io/gh/PyMoDAQ/PyMoDAQ
 
 +-------------+-------------+---------------+
@@ -99,28 +99,28 @@ PyMoDAQ Utils
 
 
 
-.. |310-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Linux_3.10.svg
+.. |310-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Linux_3.10.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |311-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Linux_3.11.svg
+.. |311-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Linux_3.11.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |312-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Linux_3.12.svg
+.. |312-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Linux_3.12.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |313-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Linux_3.13.svg
+.. |313-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Linux_3.13.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |310-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Windows_3.10.svg
+.. |310-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Windows_3.10.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |311-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Windows_3.11.svg
+.. |311-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Windows_3.11.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |312-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Windows_3.12.svg
+.. |312-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Windows_3.12.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |313-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Windows_3.13.svg
+.. |313-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Windows_3.13.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
 

{pymodaq_utils-5.3.0a0 → pymodaq_utils-5.3.2}/README.rst

@@ -11,11 +11,11 @@ PyMoDAQ Utils
    :target: https://pypi.org/project/pymodaq_utils/
    :alt: Latest Version
 
-.. image:: https://readthedocs.org/projects/pymodaq/badge/?version=state-machine-simplify
-   :target: https://pymodaq.readthedocs.io/en/stable/?badge=state-machine-simplify
+.. image:: https://readthedocs.org/projects/pymodaq/badge/?version=patch-3
+   :target: https://pymodaq.readthedocs.io/en/stable/?badge=patch-3
    :alt: Documentation Status
 
-.. image:: https://codecov.io/gh/PyMoDAQ/PyMoDAQ/branch/state-machine-simplify/graph/badge.svg?token=IQNJRCQDM2 
+.. image:: https://codecov.io/gh/PyMoDAQ/PyMoDAQ/branch/patch-3/graph/badge.svg?token=IQNJRCQDM2 
  :target: https://codecov.io/gh/PyMoDAQ/PyMoDAQ
 
 +-------------+-------------+---------------+
@@ -34,28 +34,28 @@ PyMoDAQ Utils
 
 
 
-.. |310-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Linux_3.10.svg
+.. |310-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Linux_3.10.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |311-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Linux_3.11.svg
+.. |311-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Linux_3.11.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |312-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Linux_3.12.svg
+.. |312-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Linux_3.12.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |313-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Linux_3.13.svg
+.. |313-linux| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Linux_3.13.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |310-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Windows_3.10.svg
+.. |310-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Windows_3.10.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |311-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Windows_3.11.svg
+.. |311-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Windows_3.11.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |312-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Windows_3.12.svg
+.. |312-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Windows_3.12.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
-.. |313-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/state-machine-simplify/tests_Windows_3.13.svg
+.. |313-windows| image:: https://raw.githubusercontent.com/PyMoDAQ/PyMoDAQ/badges/pymodaq_utils/patch-3/tests_Windows_3.13.svg
     :target: https://github.com/PyMoDAQ/PyMoDAQ/actions/workflows/tests-utils.yml
 
 

{pymodaq_utils-5.3.0a0 → pymodaq_utils-5.3.2}/src/pymodaq_utils/factory.py

@@ -34,13 +34,15 @@ class ObjectFactory(metaclass=ABCMeta):
 
     Examples
     --------
-    @ObjectFactory.register('custom')
-    def my_custom_builder():
-        pass
+    ::
+
+        @ObjectFactory.register('custom')
+        def my_custom_builder():
+            pass
 
     See Also
     --------
-    pymodaq.post_treatment.process_1d_to_scalar.Data1DProcessorFactory
+    pymodaq_data.post_treatment.process_to_scalar.DataProcessorFactory
     """
     _builders = {}
 

pymodaq_utils-5.3.2/src/pymodaq_utils/help.py

@@ -0,0 +1,47 @@
+"""Contextual help of the PyMoDAQ modules.
+
+By convention, the help of a module (control module, manager, extension...) is a short markdown text stored in a file
+named ``help.md`` in the same folder as the python file defining the module. The same text is used as the introduction
+of the module documentation.
+"""
+import inspect
+from pathlib import Path
+from types import ModuleType
+from typing import Optional, Union
+
+from pymodaq_utils.logger import set_logger, get_module_name
+
+logger = set_logger(get_module_name(__file__))
+
+HELP_FILE_NAME = 'help.md'
+
+
+def get_help_text(obj: Union[type, object, ModuleType, str, Path]) -> Optional[str]:
+    """Get the markdown help text associated with a module, a class or an object
+
+    Parameters
+    ----------
+    obj: type, object, ModuleType, str or Path
+        A class, an instance, a python module, or the path of a file (or a folder) from which the help is looked for.
+        The help file is ``help.md`` in the folder of the file defining the object.
+
+    Returns
+    -------
+    str or None
+        The markdown text, None if no help file is found.
+    """
+    if isinstance(obj, (str, Path)):
+        path = Path(obj)
+    else:
+        if not isinstance(obj, (type, ModuleType)):
+            obj = type(obj)
+        try:
+            path = Path(inspect.getfile(obj))
+        except (TypeError, OSError):
+            logger.warning(f'Could not find the source file of {obj}')
+            return None
+
+    help_path = (path if path.is_dir() else path.parent) / HELP_FILE_NAME
+    if not help_path.is_file():
+        return None
+    return help_path.read_text(encoding='utf-8')

{pymodaq_utils-5.3.0a0 → pymodaq_utils-5.3.2}/src/pymodaq_utils/math_utils.py

@@ -1,7 +1,7 @@
 import numbers
 from typing import Union
 
-import numpy
+
 import numpy as np
 from numbers import Number
 from typing import List, Union, Tuple
@@ -12,6 +12,31 @@ from pint import Quantity
 logger = set_logger(get_module_name(__file__))
 
 
+
+def get_si_prefix(number) -> tuple[Number, str]:
+    if number == 0:
+        return 0, ""
+
+    # Standard SI prefixes organized by their 10^(3*tier) powers
+    prefixes = {
+        24: 'Y', 21: 'Z', 18: 'E', 15: 'P', 12: 'T', 9: 'G', 6: 'M', 3: 'k',
+        0: '',
+        -3: 'm', -6: 'µ', -9: 'n', -12: 'p', -15: 'f', -18: 'a', -21: 'z', -24: 'y'
+    }
+
+    # Calculate the exponent tier (multiples of 3)
+    exponent = np.floor(np.log10(abs(number)) / 3) * 3
+
+    # Clip to maximum/minimum available prefixes
+    exponent = max(-24, min(24, exponent))
+
+    # Calculate the scaled number component
+    scaled_value = number / (10 ** exponent)
+    prefix_symbol = prefixes[exponent]
+
+    return scaled_value, prefix_symbol
+
+
 def my_moment(x, y):
     """Returns the moments of a distribution y over an axe x
 
@@ -462,28 +487,29 @@ def flatten(xs):
 class LSqEllipse:
 
     def fit(self, data):
-        """Lest Squares fitting algorithm
+        """Least Squares fitting algorithm
 
         Theory taken from (*)
-        Solving equation Sa=lCa. with a = |a b c d f g> and a1 = |a b c>
-            a2 = |d f g>
+        Solving equation ``Sa=lCa``, with ``a = |a b c d f g>``, ``a1 = |a b c>`` and ``a2 = |d f g>``
 
-        Args
-        ----
-        data (list:list:float): list of two lists containing the x and y data of the
-            ellipse. of the form [[x1, x2, ..., xi],[y1, y2, ..., yi]]
+        Parameters
+        ----------
+        data: list of list of float
+            list of two lists containing the x and y data of the ellipse, of the form
+            ``[[x1, x2, ..., xi],[y1, y2, ..., yi]]``
 
         Returns
-        ------
-        coef (list): list of the coefficients describing an ellipse
-           [a,b,c,d,f,g] corresponding to ax**2+2bxy+cy**2+2dx+2fy+g
+        -------
+        list
+            the coefficients ``[a,b,c,d,f,g]`` describing an ellipse corresponding to
+            ``ax**2+2bxy+cy**2+2dx+2fy+g``
         """
-        x, y = numpy.asarray(data, dtype=float)
+        x, y = np.asarray(data, dtype=float)
 
         # Quadratic part of design matrix [eqn. 15] from (*)
-        D1 = numpy.mat(numpy.vstack([x ** 2, x * y, y ** 2])).T
+        D1 = np.mat(np.vstack([x ** 2, x * y, y ** 2])).T
         # Linear part of design matrix [eqn. 16] from (*)
-        D2 = numpy.mat(numpy.vstack([x, y, numpy.ones(len(x))])).T
+        D2 = np.mat(np.vstack([x, y, np.ones(len(x))])).T
 
         # forming scatter matrix [eqn. 17] from (*)
         S1 = D1.T * D1
@@ -491,23 +517,23 @@ class LSqEllipse:
         S3 = D2.T * D2
 
         # Constraint matrix [eqn. 18]
-        C1 = numpy.mat('0. 0. 2.; 0. -1. 0.; 2. 0. 0.')
+        C1 = np.mat('0. 0. 2.; 0. -1. 0.; 2. 0. 0.')
 
         # Reduced scatter matrix [eqn. 29]
         M = C1.I * (S1 - S2 * S3.I * S2.T)
 
         # M*|a b c >=l|a b c >. Find eigenvalues and eigenvectors from this equation [eqn. 28]
-        eval, evec = numpy.linalg.eig(M)
+        eval, evec = np.linalg.eig(M)
 
         # eigenvector must meet constraint 4ac - b^2 to be valid.
-        cond = 4 * numpy.multiply(evec[0, :], evec[2, :]) - numpy.power(evec[1, :], 2)
-        a1 = evec[:, numpy.nonzero(cond.A > 0)[1]]
+        cond = 4 * np.multiply(evec[0, :], evec[2, :]) - np.power(evec[1, :], 2)
+        a1 = evec[:, np.nonzero(cond.A > 0)[1]]
 
         # |d f g> = -S3^(-1)*S2^(T)*|a b c> [eqn. 24]
         a2 = -S3.I * S2.T * a1
 
         # eigenvectors |a b c d f g>
-        self.coef = numpy.vstack([a1, a2])
+        self.coef = np.vstack([a1, a2])
         self._save_parameters()
 
     def _save_parameters(self):
@@ -515,17 +541,22 @@ class LSqEllipse:
 
         Theory taken form http://mathworld.wolfram
 
-        Args
-        -----
-        coef (list): list of the coefficients describing an ellipse
-           [a,b,c,d,f,g] corresponding to ax**2+2bxy+cy**2+2dx+2fy+g
+        Parameters
+        ----------
+        coef: list
+            list of the coefficients describing an ellipse ``[a,b,c,d,f,g]`` corresponding to
+            ``ax**2+2bxy+cy**2+2dx+2fy+g``
 
         Returns
-        _______
-        center (List): of the form [x0, y0]
-        width (float): major axis
-        height (float): minor axis
-        phi (float): rotation of major axis form the x-axis in radians
+        -------
+        center: list
+            of the form [x0, y0]
+        width: float
+            major axis
+        height: float
+            minor axis
+        phi: float
+            rotation of major axis form the x-axis in radians
         """
 
         # eigenvectors are the coefficients of an ellipse in general form
@@ -543,14 +574,14 @@ class LSqEllipse:
 
         # Find the semi-axes lengths [eqn. 21 and 22] from (**)
         numerator = 2 * (a * f * f + c * d * d + g * b * b - 2 * b * d * f - a * c * g)
-        denominator1 = (b * b - a * c) * ((c - a) * numpy.sqrt(1 + 4 * b * b / ((a - c) * (a - c))) - (c + a))
-        denominator2 = (b * b - a * c) * ((a - c) * numpy.sqrt(1 + 4 * b * b / ((a - c) * (a - c))) - (c + a))
-        width = numpy.sqrt(numerator / denominator1)
-        height = numpy.sqrt(numerator / denominator2)
+        denominator1 = (b * b - a * c) * ((c - a) * np.sqrt(1 + 4 * b * b / ((a - c) * (a - c))) - (c + a))
+        denominator2 = (b * b - a * c) * ((a - c) * np.sqrt(1 + 4 * b * b / ((a - c) * (a - c))) - (c + a))
+        width = np.sqrt(numerator / denominator1)
+        height = np.sqrt(numerator / denominator2)
 
         # angle of counterclockwise rotation of major-axis of ellipse to x-axis [eqn. 23] from (**)
         # or [eqn. 26] from (***).
-        phi = .5 * numpy.arctan((2. * b) / (a - c))
+        phi = .5 * np.arctan((2. * b) / (a - c))
 
         self._center = [x0, y0]
         self._width = width
@@ -583,25 +614,29 @@ class LSqEllipse:
 def make_test_ellipse(center=[1, 1], width=1, height=.6, phi=3.14 / 5):
     """Generate Elliptical data with noise
 
-    Args
-    ----
-    center (list:float): (<x_location>, <y_location>)
-    width (float): semimajor axis. Horizontal dimension of the ellipse (**)
-    height (float): semiminor axis. Vertical dimension of the ellipse (**)
-    phi (float:radians): tilt of the ellipse, the angle the semimajor axis
-        makes with the x-axis
+    Parameters
+    ----------
+    center: list of float
+        (<x_location>, <y_location>)
+    width: float
+        semimajor axis. Horizontal dimension of the ellipse
+    height: float
+        semiminor axis. Vertical dimension of the ellipse
+    phi: float
+        tilt of the ellipse in radians, the angle the semimajor axis makes with the x-axis
 
     Returns
     -------
-    data (list:list:float): list of two lists containing the x and y data of the
-        ellipse. of the form [[x1, x2, ..., xi],[y1, y2, ..., yi]]
+    list of list of float
+        list of two lists containing the x and y data of the ellipse, of the form
+        ``[[x1, x2, ..., xi],[y1, y2, ..., yi]]``
     """
-    t = numpy.linspace(0, 2 * numpy.pi, 1000)
-    x_noise, y_noise = numpy.random.rand(2, len(t))
+    t = np.linspace(0, 2 * np.pi, 1000)
+    x_noise, y_noise = np.random.rand(2, len(t))
 
-    ellipse_x = center[0] + width * numpy.cos(t) * numpy.cos(phi) - height * numpy.sin(t) * numpy.sin(
+    ellipse_x = center[0] + width * np.cos(t) * np.cos(phi) - height * np.sin(t) * np.sin(
         phi) + x_noise / 2.
-    ellipse_y = center[1] + width * numpy.cos(t) * numpy.sin(phi) + height * numpy.sin(t) * numpy.cos(
+    ellipse_y = center[1] + width * np.cos(t) * np.sin(phi) + height * np.sin(t) * np.cos(
         phi) + y_noise / 2.
 
     return [ellipse_x, ellipse_y]