Reformat docstrings to Google style and add type annotations

.github/workflows/lint.yml

@@ -27,7 +27,7 @@ jobs:
       - name: ruff
         run: |
           ruff --version
-          ruff .
+          ruff check .
           ruff format --check .
 
       - name: mypy

pymatgen/alchemy/materials.py

@@ -344,19 +344,21 @@ def as_dict(self) -> dict[str, Any]:
         return dct
 
     @classmethod
-    def from_dict(cls, dct) -> TransformedStructure:
+    def from_dict(cls, dct: dict) -> TransformedStructure:
         """Creates a TransformedStructure from a dict."""
         struct = Structure.from_dict(dct)
         return cls(struct, history=dct["history"], other_parameters=dct.get("other_parameters"))
 
-    def to_snl(self, authors, **kwargs) -> StructureNL:
-        """Generate SNL from TransformedStructure.
+    def to_snl(self, authors: list[str], **kwargs) -> StructureNL:
+        """
+        Generate a StructureNL from TransformedStructure.
 
-        :param authors: List of authors
-        :param **kwargs: All kwargs supported by StructureNL.
+        Args:
+            authors (List[str]): List of authors contributing to the generated StructureNL.
+            **kwargs (Any): All kwargs supported by StructureNL.
 
         Returns:
-            StructureNL
+            StructureNL: The generated StructureNL object.
         """
         if self.other_parameters:
             warn("Data in TransformedStructure.other_parameters discarded during type conversion to SNL")

pymatgen/analysis/bond_dissociation.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import logging
+import warnings
 
 import networkx as nx
 from monty.json import MSONable
@@ -48,7 +49,7 @@ def __init__(
 
         Args:
             molecule_entry (dict): Entry for the principle molecule. Should have the keys mentioned above.
-            fragment_entries (list of dicts): List of fragment entries. Each should have the keys mentioned above.
+            fragment_entries (list[dict]): Fragment entries. Each should have the keys mentioned above.
             allow_additional_charge_separation (bool): If True, consider larger than normal charge separation
                 among fragments. Defaults to False. See the definition of self.expected_charges below for more
                 specific information.
@@ -98,7 +99,7 @@ def __init__(
             self.fragment_and_process(bonds)
         # If multibreak, loop through pairs of ring bonds.
         if multibreak:
-            print(
+            warnings.warn(
                 "Breaking pairs of ring bonds. WARNING: Structure changes much more likely, meaning dissociation values"
                 " are less reliable! This is a bad idea!"
             )
@@ -120,6 +121,7 @@ def fragment_and_process(self, bonds):
         try:
             frags = self.mol_graph.split_molecule_subgraphs(bonds, allow_reverse=True)
             frag_success = True
+
         except MolGraphSplitError:
             # If split is unsuccessful, then we have encountered a ring bond
             if len(bonds) == 1:
@@ -152,23 +154,23 @@ def fragment_and_process(self, bonds):
                         pb_mol = bb.pybel_mol
                         smiles = pb_mol.write("smi").split()[0]
                         specie = nx.get_node_attributes(self.mol_graph.graph, "specie")
-                        print(
+                        warnings.warn(
                             f"Missing ring opening fragment resulting from the breakage of {specie[bonds[0][0]]} "
                             f"{specie[bonds[0][1]]} bond {bonds[0][0]} {bonds[0][1]} which would yield a "
                             f"molecule with this SMILES string: {smiles}"
                         )
                     elif len(good_entries) == 1:
-                        # If we have only one good entry, format it and add it to the list that will eventually return:
+                        # If we have only one good entry, format it and add it to the list that will eventually return
                         self.bond_dissociation_energies += [self.build_new_entry(good_entries, bonds)]
                     else:
                         # We shouldn't ever encounter more than one good entry.
                         raise RuntimeError("There should only be one valid ring opening fragment! Exiting...")
             elif len(bonds) == 2:
                 raise RuntimeError("Should only be trying to break two bonds if multibreak is true! Exiting...")
             else:
-                print("No reason to try and break more than two bonds at once! Exiting...")
-                raise ValueError
+                raise ValueError("No reason to try and break more than two bonds at once! Exiting...")
             frag_success = False
+
         if frag_success:
             # If the principle did successfully split, then we aren't dealing with a ring bond.
             # As above, we begin by making sure we haven't already encountered an identical pair of fragments:
@@ -203,14 +205,14 @@ def fragment_and_process(self, bonds):
                     smiles = pb_mol.write("smi").split()[0]
                     for charge in self.expected_charges:
                         if charge not in frag1_charges_found:
-                            print(f"Missing {charge=} for fragment {smiles}")
+                            warnings.warn(f"Missing {charge=} for fragment {smiles}")
                 if len(frag2_charges_found) < len(self.expected_charges):
                     bb = BabelMolAdaptor(frags[1].molecule)
                     pb_mol = bb.pybel_mol
                     smiles = pb_mol.write("smi").split()[0]
                     for charge in self.expected_charges:
                         if charge not in frag2_charges_found:
-                            print(f"Missing {charge=} for fragment {smiles}")
+                            warnings.warn(f"Missing {charge=} for fragment {smiles}")
                 # Now we attempt to pair fragments with the right total charge, starting with only fragments with no
                 # structural change:
                 for frag1 in frag1_entries[0]:  # 0 -> no structural change
@@ -241,7 +243,7 @@ def fragment_and_process(self, bonds):
                                 self.bond_dissociation_energies += [self.build_new_entry([frag1, frag2], bonds)]
                                 n_entries_for_this_frag_pair += 1
 
-    def search_fragment_entries(self, frag):
+    def search_fragment_entries(self, frag) -> list:
         """
         Search all fragment entries for those isomorphic to the given fragment.
         We distinguish between entries where both initial and final molgraphs are isomorphic to the
@@ -263,13 +265,14 @@ def search_fragment_entries(self, frag):
                 final_entries += [entry]
         return [entries, initial_entries, final_entries]
 
-    def filter_fragment_entries(self, fragment_entries):
+    def filter_fragment_entries(self, fragment_entries: list) -> None:
         """
         Filter the fragment entries.
 
-        :param fragment_entries:
+        Args:
+            fragment_entries (List): Fragment entries to be filtered.
         """
-        self.filtered_entries = []
+        self.filtered_entries: list = []
         for entry in fragment_entries:
             # Check and make sure that PCM dielectric is consistent with principle:
             if "pcm_dielectric" in self.molecule_entry:
@@ -305,8 +308,9 @@ def filter_fragment_entries(self, fragment_entries):
                 else:
                     entry["structure_change"] = "bond_change"
             found_similar_entry = False
+
             # Check for uniqueness
-            for ii, filtered_entry in enumerate(self.filtered_entries):
+            for idx, filtered_entry in enumerate(self.filtered_entries):
                 if filtered_entry["formula_pretty"] == entry["formula_pretty"] and (
                     filtered_entry["initial_molgraph"].isomorphic_to(entry["initial_molgraph"])
                     and filtered_entry["final_molgraph"].isomorphic_to(entry["final_molgraph"])
@@ -316,19 +320,23 @@ def filter_fragment_entries(self, fragment_entries):
                     # If two entries are found that pass the above similarity check, take the one with the lower
                     # energy:
                     if entry["final_energy"] < filtered_entry["final_energy"]:
-                        self.filtered_entries[ii] = entry
+                        self.filtered_entries[idx] = entry
                     # Note that this will essentially choose between singlet and triplet entries assuming both have
                     # the same structural details
                     break
             if not found_similar_entry:
                 self.filtered_entries += [entry]
 
-    def build_new_entry(self, frags, bonds):
+    def build_new_entry(self, frags: list, bonds: list) -> list:
         """
-        Simple function to format a bond dissociation entry that will eventually be returned to the user.
+        Build a new entry for bond dissociation that will be returned to the user.
 
-        :param frags:
-        :param bonds:
+        Args:
+            frags (list): Fragments involved in the bond dissociation.
+            bonds (list): Bonds broken in the dissociation process.
+
+        Returns:
+            list: Formatted bond dissociation entries.
         """
         specie = nx.get_node_attributes(self.mol_graph.graph, "specie")
         if len(frags) == 2:
@@ -348,6 +356,7 @@ def build_new_entry(self, frags, bonds):
                 frags[1]["initial_molecule"]["spin_multiplicity"],
                 frags[1]["final_energy"],
             ]
+
         else:
             new_entry = [
                 self.molecule_entry["final_energy"] - frags[0]["final_energy"],
@@ -360,4 +369,5 @@ def build_new_entry(self, frags, bonds):
                 frags[0]["initial_molecule"]["spin_multiplicity"],
                 frags[0]["final_energy"],
             ]
+
         return new_entry

pymatgen/analysis/chemenv/connectivity/connectivity_finder.py

@@ -24,9 +24,10 @@ def __init__(self, multiple_environments_choice=None):
         """
         Constructor for the ConnectivityFinder.
 
-        :param multiple_environments_choice: defines the procedure to apply when
-        the environment of a given site is described as a "mix" of more than one
-        coordination environments.
+        Args:
+            multiple_environments_choice: defines the procedure to apply when
+            the environment of a given site is described as a "mix" of more than one
+            coordination environments.
         """
         self.setup_parameters(multiple_environments_choice=multiple_environments_choice)
 
@@ -35,8 +36,9 @@ def get_structure_connectivity(self, light_structure_environments):
         Get the structure connectivity from the coordination environments provided
         as an input.
 
-        :param light_structure_environments: LightStructureEnvironments with the
-        relevant coordination environments in the structure
+        Args:
+            light_structure_environments: LightStructureEnvironments with the
+            relevant coordination environments in the structure
 
         Returns:
             a StructureConnectivity object describing the connectivity of