build: deprecate CamelCase function for structure.py

[stevenhua0320]

@sbillinge ready to review. Note that for diffpy.structure there are too many CamelCase function that needs to be deprecated, I decide to split into several PRs to make and once we have finished all of these we add a news item.

[stevenhua0320]

@sbillinge The test fails because we don't have diffpy.utils as a dependency for diffpy.structure before. On local the test passes when I install diffpy.utils as a dependency.

(diffpy.structure) ~/dbs/diffpy.structure git:[deprecate-camel-case]
pytest
============================================================================================================== test session starts ==============================================================================================================
platform darwin -- Python 3.14.3, pytest-9.0.2, pluggy-1.6.0
rootdir: /Users/huarundong/dbs/diffpy.structure
configfile: pyproject.toml
collected 139 items                                                                                                                                                                                                                             

tests/test_atom.py ..                                                                                                                                                                                                                     [  1%]
tests/test_lattice.py ............                                                                                                                                                                                                        [ 10%]
tests/test_loadstructure.py ......                                                                                                                                                                                                        [ 14%]
tests/test_p_cif.py .....................                                                                                                                                                                                                 [ 29%]
tests/test_p_discus.py .....                                                                                                                                                                                                              [ 33%]
tests/test_p_pdffit.py .........                                                                                                                                                                                                          [ 39%]
tests/test_parsers.py .............                                                                                                                                                                                                       [ 48%]
tests/test_spacegroups.py .....                                                                                                                                                                                                           [ 52%]
tests/test_structure.py .........................................                                                                                                                                                                         [ 82%]
tests/test_supercell.py ...                                                                                                                                                                                                               [ 84%]
tests/test_symmetryutilities.py .....................                                                                                                                                                                                     [ 99%]
tests/test_version.py .                                                                                                                                                                                                                   [100%]

=============================================================================================================== warnings summary ================================================================================================================
tests/test_structure.py::TestStructure::test_assignUniqueLabels
  /Users/huarundong/dbs/diffpy.structure/tests/test_structure.py:126: DeprecationWarning: 'diffpy.structure.Structure.assignUniqueLabels' is deprecated and will be removed in version 3.8.0. Please use 'diffpy.structure.Structure.assign_unique_labels' instead.
    self.stru.assignUniqueLabels()

tests/test_structure.py::TestStructure::test_placeInLattice
  /Users/huarundong/dbs/diffpy.structure/tests/test_structure.py:164: DeprecationWarning: 'diffpy.structure.Structure.placeInLattice' is deprecated and will be removed in version 3.8.0. Please use 'diffpy.structure.Structure.place_in_lattice' instead.
    stru.placeInLattice(new_lattice)

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
======================================================================================================== 139 passed, 2 warnings in 0.60s ========================================================================================================

Do we need to add diffpy.utils as a requirement in both conda.txt and pip.txt?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.95%. Comparing base (1b565c8) to head (ac77bc0).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #154      +/-   ##
==========================================
+ Coverage   98.93%   98.95%   +0.02%     
==========================================
  Files          13       13              
  Lines        1878     1916      +38     
==========================================
+ Hits         1858     1896      +38     
  Misses         20       20              

Files with missing lines	Coverage Δ
tests/test_p_cif.py	99.63% <100.00%> (+0.03%)	⬆️
tests/test_p_discus.py	98.85% <100.00%> (ø)
tests/test_p_pdffit.py	99.41% <100.00%> (ø)
tests/test_parsers.py	99.47% <100.00%> (ø)
tests/test_structure.py	99.78% <100.00%> (+<0.01%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sbillinge]

P lease see inline comments. Also. Make sure that both versions of the function are tested. To do this copy paste the tests then only modify one version to the new function name.

[sbillinge]

This should be 4.0.0.

Removal will be breaking so we put it to a top level release

[stevenhua0320]

Have changed this and in any corresponding docstring that would affected.

[sbillinge]

Added another comment

[sbillinge]

This shouldn't have any functional code in it I think. It should just return the correct form of the function

[sbillinge]

Please check with @cadenmyers13 but I think there are still some issues. I think that all the deprecated functions should look something like:

@deprecated(writeStr_deprecation_msg)
    def writeStr(self, format):
        """This function has been deprecated and will be removed in
        version 4.0.0.

        Please use diffpy.structure.Structure.write_str instead.
        """
       return self.write_structure(format)

(not sure if str means structure or string but I am guessing. Better to fix it since we are deprecating...don't want to have to deprecate again)

Also, we want to leave all the existing tests so the deprecated functions are getting tested but then copy-paste them and replace the old name for the new name. I see that you have done this last step but I want to make sure that you have also left the tests for the old function names.

[cadenmyers13]

@stevenhua0320 Thanks for getting started on this. If you havent already, please see the documentation on how to deprecate: https://scikit-package.github.io/scikit-package/programming-guides/billinge-group-standards.html#deprecating-functions.

@sbillinge can you create a new branch upstream to merge into? I guess it would be called v3.4.0. @stevenhua0320 do all your deprecations into this branch once created.

@sbillinge is correct. the deprecated function should call the new function like exemplified above. Additionally, it is best to take this slow and do one function per PR. At least at first. Also, it helps if your commit messages or PR title reflect which functions are being deprecated so we know exactly what to look for.

As for tests, I think the best way to handle it is for each deprecated function have it emit 1 DeprecationWarning when you run pytest. If the function has a test associated with it (for example if test_writeStr() exists) you can duplicated the test and rename it to not be camelcase (for example test_write_structure()). In the camelcase test you leave the deprecated function, in the new test you call the new function. Then, everywhere else in tests where writeStr() is called, replace it with write_structure(). Then, when you run pytest, only one DeprecationWarning is emitted and we'll know exactly where from so when it comes time to remove we know what needs to be changed in tests.

let me know if you have any questions!

[stevenhua0320]

@stevenhua0320 Thanks for getting started on this. If you havent already, please see the documentation on how to deprecate: https://scikit-package.github.io/scikit-package/programming-guides/billinge-group-standards.html#deprecating-functions.

@sbillinge can you create a new branch upstream to merge into? I guess it would be called v3.4.0. @stevenhua0320 do all your deprecations into this branch once created.

@sbillinge is correct. the deprecated function should call the new function like exemplified above. Additionally, it is best to take this slow and do one function per PR. At least at first. Also, it helps if your commit messages or PR title reflect which functions are being deprecated so we know exactly what to look for.

As for tests, I think the best way to handle it is for each deprecated function have it emit 1 DeprecationWarning when you run pytest. If the function has a test associated with it (for example if test_writeStr() exists) you can duplicated the test and rename it to not be camelcase (for example test_write_structure()). In the camelcase test you leave the deprecated function, in the new test you call the new function. Then, everywhere else in tests where writeStr() is called, replace it with write_structure(). Then, when you run pytest, only one DeprecationWarning is emitted and we'll know exactly where from so when it comes time to remove we know what needs to be changed in tests.

let me know if you have any questions!

It might be a good idea to initiate the workflow like this. @sbillinge could you open a new branch called v3.4.0 and once it is opened we could work all the commits on that. Note this is a very big library package, so there will be about hundreds of functions that we need to deprecate as I have roughly checked for the functions. So, it is better we gonna work slowly at the beginning on this one.

[sbillinge]

ok, done!. lets assign modules to different people to try and build momentum

[stevenhua0320]

Closed due to split into individual functions.