diffpy.utils 3.6.1rc0__py3-none-any.whl → 3.7.0rc0__py3-none-any.whl

diffpy/utils/_deprecator.py

@@ -0,0 +1,178 @@
+import functools
+import warnings
+
+# Deprecated decorator is available for Python 3.13+, once
+# Support for earlier versions is dropped, this custom
+# implementation can be removed.
+try:
+    from warnings import deprecated as _builtin_deprecated
+except ImportError:
+    _builtin_deprecated = None
+
+
+def deprecated(message, *, category=DeprecationWarning, stacklevel=1):
+    """Deprecation decorator for functions and classes that is
+    compatible with Python versions prior to 3.13.
+
+    Examples
+    --------
+    Basic usage with a deprecated function:
+
+    .. code-block:: python
+
+        from diffpy.utils._deprecator import (
+            deprecated, build_deprecation_message
+        )
+
+        deprecation_warning = build_deprecation_message("diffpy.utils",
+                                                        "old_function",
+                                                        "new_function",
+                                                        "4.0.0")
+
+        @deprecated(deprecation_warning)
+        def old_function(x, y):
+            '''This function is deprecated and will be removed in version
+            4.0.0. Please use new_function instead'''
+            return new_function(x, y)
+
+        def new_function(x, y):
+            return x + y
+
+        old_function(1, 2)   # Works but emits DeprecationWarning
+        new_function(1, 2)   # Works, no warning
+
+
+    Deprecating a class:
+
+    .. code-block:: python
+
+        from diffpy.utils._deprecator import (
+            deprecated, build_deprecation_message
+        )
+        deprecation_warning = build_deprecation_message("diffpy.utils",
+                                                        "OldAtom",
+                                                        "NewAtom",
+                                                        "4.0.0")
+
+        @deprecated(deprecation_warning)
+        class OldAtom:
+            def __new__(cls, *args, **kwargs):
+                warnings.warn(
+                    "OldAtom is deprecated and will be removed in
+                    version 4.0.0. Use NewClass instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                return NewAtom(*args, **kwargs)
+
+        class NewAtom:
+            def __init__(self, symbol):
+                self.symbol = symbol
+
+        a = OldAtom("C")     # Works but emits DeprecationWarning
+        b = NewAtom("C")     # Works with no warning
+    """
+    if _builtin_deprecated is not None:
+        return _builtin_deprecated(
+            message, category=category, stacklevel=stacklevel
+        )
+    if not isinstance(message, str):
+        raise TypeError(
+            f"Expected an object of type str for 'message', not "
+            f"{type(message).__name__!r}"
+        )
+
+    def decorator(obj):
+        setattr(obj, "__deprecated__", message)
+        if callable(obj):
+
+            @functools.wraps(obj)
+            def wrapper(*args, **kwargs):
+                warnings.warn(message, category, stacklevel=stacklevel + 1)
+                return obj(*args, **kwargs)
+
+            return wrapper
+        raise TypeError(
+            "deprecated decorator can only be applied to functions or classes"
+        )
+
+    return decorator
+
+
+def build_deprecation_message(
+    old_base, old_name, new_name, removal_version, new_base=None
+):
+    """Generate a deprecation message.
+
+    Parameters
+    ----------
+    old_base : str
+        The base module or class where the deprecated item resides.
+        This will look like the import statement used in the code
+        currently
+    old_name : str
+        The name of the deprecated item.
+    new_name : str
+        The name of the new item to use.
+    removal_version : str
+        The version when the deprecated item will be removed.
+    new_base : str Optional. Defaults to old_base.
+        The base module or class where the new item resides.
+        This will look like the import statement that
+        will be used in the code moving forward. If not specified,
+        the new base defaults to the old one.
+
+    Returns
+    -------
+    str
+        A formatted deprecation message.
+    """
+    if new_base is None:
+        new_base = old_base
+    return (
+        f"'{old_base}.{old_name}' is deprecated and will be removed in "
+        f"version {removal_version}. Please use '{new_base}.{new_name}' "
+        f"instead."
+    )
+
+
+def generate_deprecation_docstring(new_name, removal_version, new_base=None):
+    """Generate a docstring for copy-pasting into a deprecated function.
+
+    This function will print the text to the terminal for copy-pasting.
+
+    Parameters
+    ----------
+    new_name : str
+        The name of the new function or class to replace the existing one.
+    removal_version : str
+        The version when the deprecated item is targeted for removal,
+        e.g., 4.0.0.
+    new_base : str, optional
+        The new base for importing. The new import statement would look like
+        "from new_base import new_name". Defaults to None.
+
+    Example
+    -------
+    >>> from diffpy.utils._deprecator import generate_deprecation_docstring
+    >>> generate_deprecation_docstring("new_name", "4.0.0")
+
+    The message looks like:
+        This function has been deprecated and will be removed in version
+        {removal_version}. Please use {new_base}.{new_name} instead.
+
+
+    Returns
+    -------
+    None
+    """
+    if new_base is None:
+        function_location = new_name
+    else:
+        function_location = f"{new_base}.{new_name}"
+    print(
+        f"This function has been deprecated and will be removed in version "
+        f"{removal_version}.\n"
+        f"Please use {function_location} instead."
+    )
+    return

diffpy/utils/diffraction_objects.py

@@ -108,18 +108,18 @@ class DiffractionObject:
 
         Parameters
         ----------
-        xarray : ndarray
+        xarray : ``ndarray``
             The independent variable array containing "q", "tth", or "d" values.
-        yarray : ndarray
+        yarray : ``ndarray``
             The dependent variable array corresponding to intensity values.
         xtype : str
             The type of the independent variable in `xarray`. Must be one of
             {*XQUANTITIES}.
-        wavelength : float, optional, default is None.
+        wavelength : float, ``optional``, default is None.
             The wavelength of the incoming beam, specified in angstroms (Å)
-        scat_quantity : str, optional, default is an empty string "".
+        scat_quantity : str, ``optional``, default is an empty string "".
             The type of scattering experiment (e.g., "x-ray", "neutron").
-        name : str, optional, default is an empty string "".
+        name : str, ``optional``, default is an empty string "".
             The name or label for the scattering data.
         metadata : dict, optional, default is an empty dictionary {}
             The additional metadata associated with the diffraction object.
@@ -211,8 +211,8 @@ class DiffractionObject:
         return True
 
     def __add__(self, other):
-        """Add a scalar value or another DiffractionObject to the yarray of the
-        DiffractionObject.
+        """Add a scalar value or another DiffractionObject to the yarray
+        of the DiffractionObject.
 
         Parameters
         ----------
@@ -262,8 +262,8 @@ class DiffractionObject:
     __radd__ = __add__
 
     def __sub__(self, other):
-        """Subtract scalar value or another DiffractionObject to the yarray of
-        the DiffractionObject.
+        """Subtract scalar value or another DiffractionObject to the
+        yarray of the DiffractionObject.
 
         This method behaves similarly to the `__add__` method, but performs
         subtraction instead of addition. For details on parameters, returns
@@ -290,8 +290,8 @@ class DiffractionObject:
     __rsub__ = __sub__
 
     def __mul__(self, other):
-        """Multiply a scalar value or another DiffractionObject with the yarray
-        of this DiffractionObject.
+        """Multiply a scalar value or another DiffractionObject with the
+        yarray of this DiffractionObject.
 
         This method behaves similarly to the `__add__` method, but performs
         multiplication instead of addition. For details on parameters,
@@ -318,8 +318,8 @@ class DiffractionObject:
     __rmul__ = __mul__
 
     def __truediv__(self, other):
-        """Divide the yarray of this DiffractionObject by a scalar value or
-        another DiffractionObject.
+        """Divide the yarray of this DiffractionObject by a scalar value
+        or another DiffractionObject.
 
         This method behaves similarly to the `__add__` method, but performs
         division instead of addition. For details on parameters, returns,
@@ -360,7 +360,7 @@ class DiffractionObject:
 
         Returns
         -------
-        ndarray
+        ``ndarray``
             The shape (len(data), 4) 2D array with columns containing the `
             yarray` (intensity) and the `xarray` values in q, tth, and d.
 
@@ -386,7 +386,7 @@ class DiffractionObject:
         Returns
         -------
         input_xtype : str
-            The type of `xarray`, which must be one of {*XQUANTITIES}.
+            The type of `xarray`, which must be one of ``{*XQUANTITIES}``.
         """
         return self._input_xtype
 
@@ -400,7 +400,7 @@ class DiffractionObject:
 
         Returns
         -------
-        uuid : UUID
+        uuid : ``UUID``
             The unique identifier of the DiffractionObject instance.
         """
         return self._uuid
@@ -409,17 +409,17 @@ class DiffractionObject:
     def uuid(self, _):
         raise AttributeError(_setter_wmsg("uuid"))
 
-    def get_array_index(self, xtype, xvalue):
-        """Return the index of the closest value in the array associated with
+    def get_array_index(self, xvalue, xtype=None):
+        f"""Return the index of the closest value in the array associated with
         the specified xtype and the value provided.
 
         Parameters
         ----------
-        xtype : str
-            The type of the independent variable in `xarray`. Must be one
-            of {*XQUANTITIES}.
         xvalue : float
             The value of the xtype to find the closest index for.
+        xtype : str, optional
+            The type of the independent variable in `xarray`. Must be one
+            of {*XQUANTITIES, }. Default is {self._input_xtype}
 
         Returns
         -------
@@ -427,8 +427,11 @@ class DiffractionObject:
             The index of the closest value in the array associated with the
             specified xtype and the value provided.
         """
-
-        xtype = self._input_xtype
+        if xtype is None:
+            xtype = self._input_xtype
+        else:
+            if xtype not in XQUANTITIES:
+                raise ValueError(_xtype_wmsg(xtype))
         xarray = self.on_xtype(xtype)[0]
         if len(xarray) == 0:
             raise ValueError(
@@ -471,31 +474,34 @@ class DiffractionObject:
             return self.on_d(), "d"
 
     def on_q(self):
-        """Return the tuple of two 1D numpy arrays containing q and y data.
+        """Return the tuple of two 1D numpy arrays containing q and y
+        data.
 
         Returns
         -------
-        (q-array, y-array) : tuple of ndarray
+        (q-array, y-array) : tuple of ``ndarray``
             The tuple containing two 1D numpy arrays with q and y data
         """
         return [self.all_arrays[:, 1], self.all_arrays[:, 0]]
 
     def on_tth(self):
-        """Return the tuple of two 1D numpy arrays containing tth and y data.
+        """Return the tuple of two 1D numpy arrays containing tth and y
+        data.
 
         Returns
         -------
-        (tth-array, y-array) : tuple of ndarray
+        (tth-array, y-array) : tuple of ``ndarray``
             The tuple containing two 1D numpy arrays with tth and y data
         """
         return [self.all_arrays[:, 2], self.all_arrays[:, 0]]
 
     def on_d(self):
-        """Return the tuple of two 1D numpy arrays containing d and y data.
+        """Return the tuple of two 1D numpy arrays containing d and y
+        data.
 
         Returns
         -------
-        (d-array, y-array) : tuple of ndarray
+        (d-array, y-array) : tuple of ``ndarray``
             The tuple containing two 1D numpy arrays with d and y data
         """
         return [self.all_arrays[:, 3], self.all_arrays[:, 0]]
@@ -503,8 +509,8 @@ class DiffractionObject:
     def scale_to(
         self, target_diff_object, q=None, tth=None, d=None, offset=None
     ):
-        """Return a new diffraction object which is the current object but
-        rescaled in y to the target.
+        """Return a new diffraction object which is the current object
+        but rescaled in y to the target.
 
         By default, if `q`, `tth`, or `d` are not provided, scaling is
         based on the max intensity from each object. Otherwise, y-value in
@@ -519,12 +525,12 @@ class DiffractionObject:
         target_diff_object: DiffractionObject
             The diffraction object you want to scale the current one onto.
 
-        q, tth, d : float, optional, default is None
+        q, tth, d : float, ``optional``, default is None
             The value of the x-array where you want the curves to line up
             vertically. Specify a value on one of the allowed grids, q, tth,
             or d), e.g., q=10.
 
-        offset : float, optional, default is None
+        offset : float, ``optional``, default is None
             The offset to add to the scaled y-values.
 
         Returns
@@ -565,22 +571,23 @@ class DiffractionObject:
         return scaled_do
 
     def on_xtype(self, xtype):
-        """Return a tuple of two 1D numpy arrays containing x and y data.
+        """Return a tuple of two 1D numpy arrays containing x and y
+        data.
 
         Parameters
         ----------
         xtype : str
             The type of quantity for the independent variable chosen from
-            {*XQUANTITIES, }
+            ``{*XQUANTITIES, }``
 
         Raises
         ------
         ValueError
-            Raised when the specified xtype is not among {*XQUANTITIES, }
+            Raised when the specified xtype is not among ``{*XQUANTITIES, }``
 
         Returns
         -------
-        (xarray, yarray) : tuple of ndarray
+        (xarray, yarray) : tuple of ``ndarray``
             The tuple containing two 1D numpy arrays with x and y data for
             the specified xtype.
         """
@@ -594,16 +601,17 @@ class DiffractionObject:
             raise ValueError(_xtype_wmsg(xtype))
 
     def dump(self, filepath, xtype=None):
-        """Dump the xarray and yarray of the diffraction object to a two-column
-        file, with the associated information included in the header.
+        """Dump the xarray and yarray of the diffraction object to a
+        two-column file, with the associated information included in the
+        header.
 
         Parameters
         ----------
         filepath : str
             The filepath where the diffraction object will be dumped
-        xtype : str, optional, default is q
+        xtype : str, ``optional``, default is q
             The type of quantity for the independent variable chosen from
-            {*XQUANTITIES, }
+            ``{*XQUANTITIES, }``
 
         Examples
         --------

diffpy/utils/parsers/__init__.py

@@ -6,10 +6,18 @@
 #                   (c) 2010 The Trustees of Columbia University
 #                   in the City of New York.  All rights reserved.
 #
-# File coded by:    Chris Farrow
+# File coded by:    Simon Billinge
 #
 # See AUTHORS.txt for a list of people who contributed.
 # See LICENSE_DANSE.txt for license information.
 #
 ##############################################################################
 """Various utilities related to data parsing and manipulation."""
+
+# this  allows load_data to be imported from diffpy.utils.parsers
+# it is needed during deprecation of the old loadData structure
+# when we remove loadData we can move all the parser functionality
+# a parsers.py module (like tools.py) and remove this if we want
+from .loaddata import load_data
+
+__all__ = ["load_data"]