Merge pull request #272 from bobleesj/docformatter

Apply `docformatter` in `pre-commit` for PEP 257 docstring auto format, no manual modifications made

Author: sbillinge

.pre-commit-config.yaml

@@ -58,3 +58,10 @@ repos:
       - id: prettier
         additional_dependencies:
           - "prettier@^3.2.4"
+  # docformatter - formats docstrings using PEP 257
+  - repo: https://github.com/s-weigand/docformatter
+    rev: 5757c5190d95e5449f102ace83df92e7d3b06c6c
+    hooks:
+      - id: docformatter
+        additional_dependencies: [tomli]
+        args: [--in-place, --config, ./pyproject.toml]

news/docformatter.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* docforamtter in pre-commit for automatic formatting of docstrings to PEP 257
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/__init__.py

@@ -16,7 +16,6 @@
 # See LICENSE.rst for license information.
 #
 ##############################################################################
-
 """diffpy - tools for structure analysis by diffraction.
 
 Blank namespace package.

src/diffpy/utils/__init__.py

@@ -12,8 +12,7 @@
 # See LICENSE.rst for license information.
 #
 ##############################################################################
-
-"""Shared utilities for diffpy packages"""
+"""Shared utilities for diffpy packages."""
 
 # package version
 from diffpy.utils.version import __version__

src/diffpy/utils/parsers/__init__.py

@@ -12,6 +12,4 @@
 # See LICENSE_DANSE.txt for license information.
 #
 ##############################################################################
-
-"""Various utilities related to data parsing and manipulation.
-"""
+"""Various utilities related to data parsing and manipulation."""

src/diffpy/utils/parsers/serialization.py

@@ -33,8 +33,8 @@ def serialize_data(
     show_path=True,
     serial_file=None,
 ):
-    """Serialize file data into a dictionary. Can also save dictionary into a serial language file. Dictionary is
-    formatted as {filename: data}.
+    """Serialize file data into a dictionary. Can also save dictionary into a
+    serial language file. Dictionary is formatted as {filename: data}.
 
     Requires hdata and data_table (can be generated by loadData).
 

src/diffpy/utils/resampler.py

@@ -12,7 +12,6 @@
 # See LICENSE_DANSE.txt for license information.
 #
 ##############################################################################
-
 """Various utilities related to data parsing and manipulation."""
 
 import warnings
@@ -80,7 +79,8 @@ def wsinterp(x, xp, fp, left=None, right=None):
 
 
 def nsinterp(xp, fp, qmin=0, qmax=25, left=None, right=None):
-    """One-dimensional Whittaker-Shannon interpolation onto the Nyquist-Shannon grid.
+    """One-dimensional Whittaker-Shannon interpolation onto the Nyquist-Shannon
+    grid.
 
     Takes a band-limited function fp and original grid xp and resamples fp on the NS grid.
     Uses the minimum number of points N required by the Nyquist sampling theorem.

src/diffpy/utils/tools.py

@@ -4,9 +4,28 @@
 from pathlib import Path
 
 
-def _stringify(obj):
+def clean_dict(obj):
+    """Remove keys from the dictionary where the corresponding value is None.
+
+    Parameters
+    ----------
+    obj: dict
+        The dictionary to clean. If None, initialize as an empty dictionary.
+
+    Returns
+    -------
+    dict:
+        The cleaned dictionary with keys removed where the value is None.
     """
-    Convert None to an empty string.
+    obj = obj if obj is not None else {}
+    for key, value in copy(obj).items():
+        if not value:
+            del obj[key]
+    return obj
+
+
+def _stringify(obj):
+    """Convert None to an empty string.
 
     Parameters
     ----------
@@ -22,8 +41,7 @@ def _stringify(obj):
 
 
 def _load_config(file_path):
-    """
-    Load configuration from a .json file.
+    """Load configuration from a .json file.
 
     Parameters
     ----------
@@ -34,7 +52,6 @@ def _load_config(file_path):
     -------
     dict:
         The configuration dictionary or {} if the config file does not exist.
-
     """
     config_file = Path(file_path).resolve()
     if config_file.is_file():
@@ -46,8 +63,8 @@ def _load_config(file_path):
 
 
 def get_user_info(owner_name=None, owner_email=None, owner_orcid=None):
-    """
-    Get name, email and orcid of the owner/user from various sources and return it as a metadata dictionary
+    """Get name, email and orcid of the owner/user from various sources and
+    return it as a metadata dictionary.
 
     The function looks for the information in json format configuration files with the name 'diffpyconfig.json'.
     These can be in the user's home directory and in the current working directory.  The information in the
@@ -79,7 +96,6 @@ def get_user_info(owner_name=None, owner_email=None, owner_orcid=None):
     dict:
         The dictionary containing username, email and orcid of the user/owner, and any other information
         stored in the global or local config files.
-
     """
     runtime_info = {"owner_name": owner_name, "owner_email": owner_email, "owner_orcid": owner_orcid}
     for key, value in copy(runtime_info).items():
@@ -104,8 +120,7 @@ def get_user_info(owner_name=None, owner_email=None, owner_orcid=None):
 
 
 def get_package_info(package_names, metadata=None):
-    """
-    Fetches package version and updates it into (given) metadata.
+    """Fetches package version and updates it into (given) metadata.
 
     Package info stored in metadata as {'package_info': {'package_name': 'version_number'}}.
 
@@ -119,7 +134,6 @@ def get_package_info(package_names, metadata=None):
     -------
     dict:
         The updated metadata dict with package info inserted.
-
     """
     if metadata is None:
         metadata = {}

src/diffpy/utils/transforms.py

@@ -29,8 +29,7 @@ def _validate_inputs(q, wavelength):
 
 
 def q_to_tth(q, wavelength):
-    r"""
-    Helper function to convert q to two-theta.
+    r"""Helper function to convert q to two-theta.
 
     If wavelength is missing, returns x-values that are integer indexes
 
@@ -72,9 +71,7 @@ def q_to_tth(q, wavelength):
 
 
 def tth_to_q(tth, wavelength):
-    r"""
-
-    Helper function to convert two-theta to q on independent variable axis.
+    r"""Helper function to convert two-theta to q on independent variable axis.
 
     If wavelength is missing, returns independent variable axis as integer indexes.
 
@@ -120,8 +117,8 @@ def tth_to_q(tth, wavelength):
 
 
 def q_to_d(q):
-    r"""
-    Helper function to convert q to d on independent variable axis, using :math:`d = \frac{2 \pi}{q}`.
+    r"""Helper function to convert q to d on independent variable axis, using
+    :math:`d = \frac{2 \pi}{q}`.
 
     Parameters
     ----------
@@ -140,8 +137,7 @@ def q_to_d(q):
 
 
 def tth_to_d(tth, wavelength):
-    r"""
-    Helper function to convert two-theta to d on independent variable axis.
+    r"""Helper function to convert two-theta to d on independent variable axis.
 
     The formula is .. math:: d = \frac{\lambda}{2 \sin\left(\frac{2\theta}{2}\right)}.
 
@@ -174,8 +170,7 @@ def tth_to_d(tth, wavelength):
 
 
 def d_to_q(d):
-    r"""
-    Helper function to convert q to d using :math:`d = \frac{2 \pi}{q}`.
+    r"""Helper function to convert q to d using :math:`d = \frac{2 \pi}{q}`.
 
     Parameters
     ----------
@@ -194,8 +189,7 @@ def d_to_q(d):
 
 
 def d_to_tth(d, wavelength):
-    r"""
-    Helper function to convert d to two-theta on independent variable axis.
+    r"""Helper function to convert d to two-theta on independent variable axis.
 
     The formula is .. math:: 2\theta = 2 \arcsin\left(\frac{\lambda}{2d}\right).
 

src/diffpy/utils/version.py

@@ -12,7 +12,6 @@
 # See LICENSE.rst for license information.
 #
 ##############################################################################
-
 """Definition of __version__."""
 
 #  We do not use the other three variables, but can be added back if needed.