Merge pull request #377 from cadenmyers13/import-bug

V3.7.0

Author: sbillinge

docs/source/examples/parsers_example.rst

@@ -13,23 +13,23 @@ Using the parsers module, we can load file data into simple and easy-to-work-wit
    Our goal will be to extract the data, and the parameters listed in the header, from this file and
    load it into our program.
 
-2) To get the data table, we will use the ``loadData`` function. The default behavior of this
+2) To get the data table, we will use the ``load_data`` function. The default behavior of this
    function is to find and extract a data table from a file.
 
 .. code-block:: python
 
-     from diffpy.utils.parsers.loaddata import loadData
-     data_table = loadData('<PATH to data.txt>')
+     from diffpy.utils.parsers import load_data
+     data_table = load_data('<PATH to data.txt>')
 
 While this will work with most datasets, on our ``data.txt`` file, we got a ``ValueError``. The reason for this is
 due to the comments ``$ Phase Transition Near This Temperature Range`` and ``--> Note Significant Jump in Rw <--``
 embedded within the dataset. To fix this, try using the ``comments`` parameter.
 
 .. code-block:: python
 
-     data_table = loadData('<PATH to data.txt>', comments=['$', '-->'])
+     data_table = load_data('<PATH to data.txt>', comments=['$', '-->'])
 
-This parameter tells ``loadData`` that any lines beginning with ``$`` and ``-->`` are just comments and
+This parameter tells ``load_data`` that any lines beginning with ``$`` and ``-->`` are just comments and
 more entries in our data table may follow.
 
 Here are a few other parameters to test out:
@@ -39,30 +39,30 @@ Here are a few other parameters to test out:
 
 .. code-block:: python
 
-       loadData('<PATH to data.txt>', comments=['$', '-->'], delimiter=',')
+       load_data('<PATH to data.txt>', comments=['$', '-->'], delimiter=',')
 
 returns an empty list.
    * ``minrows=50``: Only look for data tables with at least 50 rows. Since our data table has much less than that many
      rows, running
 
 .. code-block:: python
 
-       loadData('<PATH to data.txt>', comments=['$', '-->'], minrows=50)
+       load_data('<PATH to data.txt>', comments=['$', '-->'], minrows=50)
 
 returns an empty list.
    * ``usecols=[0, 3]``: Only return the 0th and 3rd columns (zero-indexed) of the data table. For ``data.txt``, this
      corresponds to the temperature and rw columns.
 
 .. code-block:: python
 
-       loadData('<PATH to data.txt>', comments=['$', '-->'], usecols=[0, 3])
+       load_data('<PATH to data.txt>', comments=['$', '-->'], usecols=[0, 3])
 
-3) Next, to get the header information, we can again use ``loadData``,
+3) Next, to get the header information, we can again use ``load_data``,
    but this time with the ``headers`` parameter enabled.
 
 .. code-block:: python
 
-     hdata = loadData('<PATH to data.txt>', comments=['$', '-->'], headers=True)
+     hdata = load_data('<PATH to data.txt>', comments=['$', '-->'], headers=True)
 
 4) Rather than working with separate ``data_table`` and ``hdata`` objects, it may be easier to combine them into a single
    dictionary. We can do so using the ``serialize_data`` function.
@@ -116,8 +116,8 @@ The returned value, ``parsed_file_data``, is the dictionary we just added to ``s
 
 .. code-block:: python
 
-     data_table = loadData('<PATH to moredata.txt>')
-     hdata = loadData('<PATH to moredata.txt>', headers=True)
+     data_table = load_data('<PATH to moredata.txt>')
+     hdata = load_data('<PATH to moredata.txt>', headers=True)
      serialize_data('<PATH to moredata.txt>', hdata, data_table, serial_file='<PATH to serialdata.json>')
 
 The serial file ``serialfile.json`` should now contain two entries: ``data.txt`` and ``moredata.txt``.

docs/source/examples/resample_example.rst

@@ -16,9 +16,9 @@ given enough datapoints.
 
 .. code-block:: python
 
-       from diffpy.utils.parsers.loaddata import loadData
-       nickel_datatable = loadData('<PATH to Nickel.gr>')
-       nitarget_datatable = loadData('<PATH to NiTarget.gr>')
+       from diffpy.utils.parsers import load_data
+       nickel_datatable = load_data('<PATH to Nickel.gr>')
+       nitarget_datatable = load_data('<PATH to NiTarget.gr>')
 
 Each data table has two columns: first is the grid and second is the function value.
 To extract the columns, we can utilize the serialize function ...

docs/source/utilities/parsers_utility.rst

@@ -5,7 +5,7 @@ Parsers Utility
 
 The ``diffpy.utils.parsers`` module allows users to easily and robustly load file data into a Python project.
 
-- ``loaddata.loadData()``: Find and load a data table/block from a text file. This seems to work for most datafiles
+- ``loaddata.load_data()``: Find and load a data table/block from a text file. This seems to work for most datafiles
   including those generated by diffpy programs. Running only ``numpy.loadtxt`` will result in errors
   for most these files as there is often excess data or parameters stored above the data block.
   Users can instead choose to load all the parameters of the form ``<param_name> = <param_value>`` into a dictionary
@@ -17,7 +17,7 @@ The ``diffpy.utils.parsers`` module allows users to easily and robustly load fil
 - ``serialization.deserialize_data()``: Load data from a serial file format into a Python dictionary. Currently, the only supported
   serial format is ``.json``.
 
-- ``serialization.serialize_data()``: Serialize the data generated by ``loadData()`` into a serial file format. Currently, the only
+- ``serialization.serialize_data()``: Serialize the data generated by ``load_data()`` into a serial file format. Currently, the only
   supported serial format is ``.json``.
 
 For a more in-depth tutorial for how to use these parser utilities, click :ref:`here <Parsers Example>`.

news/dep-msg-helper.rst

@@ -1,6 +1,8 @@
 **Added:**
 
-* Add ``deprecation_message`` helper for printing consistent deprecation messages.
+* Add ``build_deprecation_message`` helper for printing consistent deprecation messages.
+* Add ``generate_deprecation_docstring`` for generating a template docstring for deprecated functions.
+
 
 **Changed:**
 

news/depr-tests.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* <news item>
+
+**Changed:**
+
+* load_data now takes a Path or a string for the file-path
+
+**Deprecated:**
+
+* diffpy.utils.parsers.loaddata.loadData replaced by diffpy.utils.parsers.load_data
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

news/deprecator.rst

@@ -1,6 +1,5 @@
 **Added:**
 
-* added a function in _deprecator to generate a deprecation message for copy pasting
 * Add ``@deprecated`` decorator.
 
 **Changed:**

news/python-version.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Support for Python 3.14
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* Support for Python 3.11
+
+**Fixed:**
+
+* All references to ``loadData`` changed to ``load_data`` due to that deprecation
+
+**Security:**
+
+* <news item>

pyproject.toml

@@ -14,7 +14,7 @@ maintainers = [
 description = "General utilities for analyzing diffraction data"
 keywords = ['text data parsers', 'wx grid', 'diffraction objects']
 readme = "README.rst"
-requires-python = ">=3.11, <3.14"
+requires-python = ">=3.12, <3.15"
 classifiers = [
         'Development Status :: 5 - Production/Stable',
         'Environment :: Console',
@@ -25,9 +25,9 @@ classifiers = [
         'Operating System :: Microsoft :: Windows',
         'Operating System :: POSIX',
         'Operating System :: Unix',
-        'Programming Language :: Python :: 3.11',
         'Programming Language :: Python :: 3.12',
         'Programming Language :: Python :: 3.13',
+        'Programming Language :: Python :: 3.14',
         'Topic :: Scientific/Engineering :: Physics',
         'Topic :: Scientific/Engineering :: Chemistry',
 ]

src/diffpy/utils/_deprecator.py

@@ -20,7 +20,9 @@ def deprecated(message, *, category=DeprecationWarning, stacklevel=1):
 
     .. code-block:: python
 
-        from diffpy.utils._deprecator import deprecated, deprecation_message
+        from diffpy.utils._deprecator import (
+            deprecated, build_deprecation_message
+        )
 
         deprecation_warning = build_deprecation_message("diffpy.utils",
                                                         "old_function",
@@ -44,8 +46,9 @@ def new_function(x, y):
 
     .. code-block:: python
 
-        from diffpy.utils._deprecator import deprecated, deprecation_message
-
+        from diffpy.utils._deprecator import (
+            deprecated, build_deprecation_message
+        )
         deprecation_warning = build_deprecation_message("diffpy.utils",
                                                         "OldAtom",
                                                         "NewAtom",
@@ -136,35 +139,36 @@ def build_deprecation_message(
 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
-
-    usage:
-      python
-      >>> import diffpy.utils._deprecator.generate_deprecation_docstring as gdd
-      >>> gdd("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.
+    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
+    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. Defaults to old_base.
-        The new base for importing.  The new import statement would look like
-        "from new_base import new_name"
+        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
     """
     print(
-        f"This function has been deprecated and will be "
-        f"removed in version {removal_version}. Please use"
-        f"{new_base}.{new_name} instead."
+        f"This function has been deprecated and will be removed in version "
+        f"{removal_version}.\n"
+        f"Please use {new_base}.{new_name} instead."
     )
     return

src/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"]