Merge pull request #372 from sbillinge/depr-tests

depr tests

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/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>

src/diffpy/utils/_deprecator.py

@@ -20,7 +20,7 @@ def deprecated(message, *, category=DeprecationWarning, stacklevel=1):
 
     .. code-block:: python
 
-        from diffpy._deprecations import deprecated
+        from diffpy.utils._deprecator import deprecated
         import warnings
 
         @deprecated("old_function is deprecated; use new_function instead")
@@ -39,7 +39,6 @@ def new_function(x, y):
     .. code-block:: python
 
         from diffpy._deprecations import deprecated
-        import warnings
 
         warnings.simplefilter("always", DeprecationWarning)
 
@@ -83,7 +82,9 @@ def wrapper(*args, **kwargs):
     return decorator
 
 
-def deprecation_message(base, old_name, new_name, removal_version):
+def deprecation_message(
+    base, old_name, new_name, removal_version, new_base=None
+):
     """Generate a deprecation message.
 
     Parameters
@@ -102,7 +103,17 @@ def deprecation_message(base, old_name, new_name, removal_version):
     str
         A formatted deprecation message.
     """
+    if new_base is None:
+        new_base = base
     return (
         f"'{base}.{old_name}' is deprecated and will be removed in "
-        f"version {removal_version}. Please use '{base}.{new_name}' instead."
+        f"version {removal_version}. Please use '{new_base}.{new_name}' "
+        f"instead."
     )
+
+
+_DEPRECATION_DOCSTRING_TEMPLATE = (
+    "This function has been deprecated and will be "
+    "removed in version {removal_version}. Please use"
+    "{new_base}.{new_name} instead."
+)

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