Skip to content

depr tests #372

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sbillinge merged 6 commits into from
Feb 2, 2026
Merged

depr tests #372

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
7cd01f1
deprecated: loadData to load_data, and move it
sbillinge Jan 17, 2026
0b46822
fix: bad imports so tests pass
sbillinge Jan 17, 2026
4a1ee18
change: change structure so load_data is back in parsers
sbillinge Jan 18, 2026
8d11075
docs: change docstring so API docs are correctly updated
sbillinge Jan 18, 2026
34bfb90
docs; fix typos in examples text that had load_data in tools
sbillinge Jan 18, 2026
7ac6862
fix: caught a couple of tools typos fixed to parsers
sbillinge Jan 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions docs/source/examples/parsers_example.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.tools 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:
Expand All @@ -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.
Expand Down Expand Up @@ -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``.
Expand Down
6 changes: 3 additions & 3 deletions docs/source/examples/resample_example.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.tools 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 ...
Expand Down
4 changes: 2 additions & 2 deletions docs/source/utilities/parsers_utility.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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>`.
23 changes: 23 additions & 0 deletions news/depr-tests.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.tools.load_data

**Removed:**

* <news item>

**Fixed:**

* <news item>

**Security:**

* <news item>
12 changes: 8 additions & 4 deletions src/diffpy/utils/_deprecator.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -39,7 +39,6 @@ def new_function(x, y):
.. code-block:: python

from diffpy._deprecations import deprecated
import warnings

warnings.simplefilter("always", DeprecationWarning)

Expand Down Expand Up @@ -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
Expand All @@ -102,7 +103,10 @@ 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."
)
15 changes: 14 additions & 1 deletion src/diffpy/utils/parsers/loaddata.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,21 @@
import numpy

from diffpy.utils import validators
from diffpy.utils._deprecator import deprecated, deprecation_message

base = "diffpy.utils.parsers.loaddata"
removal_version = "4.0.0"

loaddata_deprecation_msg = deprecation_message(
base,
"loadData",
"load_data",
removal_version,
new_base="diffpy.utils.tools",
)


@deprecated(loaddata_deprecation_msg)
def loadData(
filename, minrows=10, headers=False, hdel="=", hignore=None, **kwargs
):
Expand Down Expand Up @@ -254,7 +267,7 @@ def readfp(self, fp, append=False):

File details include:
* File name.
* All data blocks findable by loadData.
* All data blocks findable by load_data.
* Headers (if present) for each data block. (Generally the headers
contain column name information).
"""

@cadenmyers13 cadenmyers13 Jan 17, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to replace the code of the deprecated function so it points to the new function? that way we don't have duplicate code. So it would look something like:

@ deprecated(loaddata_deprecation_msg)
def loadData(inputs):
   '''leave the docstring here unchanged so mouse-over shows it properly```
   from diffpy.utils.tools import load_data
   return load_data(inputs)

This is a unique case because youve moved this function to tools.py, but in most cases it would be something like return self.new_func_name()

@sbillinge sbillinge Jan 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yah, that's a good point. The docstrings will be wrong for the old function, but we kind of want to point people to the new one anyway.

Do you know what happens to the API docs with the deprecated function? We kind of don't want it showing up in the API docs. I just thought of that too. Your way is probably better in this regard too as there is no explicit discussing in the old function any more.

@sbillinge sbillinge Jan 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yah, that's a good point. The docstrings will be wrong for the old function, but we kind of want to point people to the new one anyway.

Do you know what happens to the API docs with the deprecated function? We kind of don't want it showing up in the API docs. I just thought of that too. Your way is probably better in this regard too as there is no explicit discussing in the old function any more.

@cadenmyers13 cadenmyers13 Jan 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sbillinge thats a good point about api docs. In that case I think we should probably replace the docstring in the old function with something like "This function is deprecated. Please use diffpy.utils.wherever.new_function." That way, if someone tries to mouse-over it, they can see what the new function is. I think no matter what we will have duplicates in the api docs temporarily, but the docstring will point to the new function so no big deal. I don't know how the api docs are built from the docstring in the deprecated function case however we can easily check.

@sbillinge sbillinge Jan 18, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes yes yes! Nice. OK, we are making progress here. I like this approach. I wonder if we want to quickly catch the steps and write a little chapter in the docs of scikit-package (which is our kind of de-facto group standards for doing everything)? The advantage is that we can then share around these deprecation tasks. I am about to make anaother push.

In other news, I have changed the base branch of this PR to a branch called v3.7.0. Let's make all our deprecation work into that. I can then make a patch-release from main when we get our free minutes back from GH and we can start this work in earnest starting on Feb 1!

@cadenmyers13 cadenmyers13 Jan 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sbillinge I did this here a while ago. It might need a little update based on this convo but the bones are good: #366 (comment)

Expand Down
2 changes: 1 addition & 1 deletion src/diffpy/utils/parsers/serialization.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ def serialize_data(
into a serial language file. Dictionary is formatted as {filename:
data}.

Requires hdata and data_table (can be generated by loadData).
Requires hdata and data_table (can be generated by load_data).

Parameters
----------
Expand Down
Loading
Loading