More Google-style class attribute doc strings (#3323)

* rename variables: d->dct

* :param to google-style

* fix typos

* staticmethod to classmethod where applicable

* more class attribute doc strings to google style

* fix doc str indentation

pymatgen/alchemy/transmuters.py

@@ -32,9 +32,8 @@ class StandardTransmuter:
     """An example of a Transmuter object, which performs a sequence of
     transformations on many structures to generate TransformedStructures.
 
-    .. attribute: transformed_structures
-
-        List of all transformed structures.
+    Attributes:
+        transformed_structures (list[Structure]): List of all transformed structures.
     """
 
     def __init__(
@@ -204,8 +203,8 @@ def append_transformed_structures(self, trafo_structs_or_transmuter):
                 assert isinstance(ts, TransformedStructure)
             self.transformed_structures.extend(trafo_structs_or_transmuter)
 
-    @staticmethod
-    def from_structures(structures, transformations=None, extend_collection=0):
+    @classmethod
+    def from_structures(cls, structures, transformations=None, extend_collection=0):
         """Alternative constructor from structures rather than
         TransformedStructures.
 
@@ -222,7 +221,7 @@ def from_structures(structures, transformations=None, extend_collection=0):
             StandardTransmuter
         """
         trafo_struct = [TransformedStructure(s, []) for s in structures]
-        return StandardTransmuter(trafo_struct, transformations, extend_collection)
+        return cls(trafo_struct, transformations, extend_collection)
 
 
 class CifTransmuter(StandardTransmuter):
@@ -235,7 +234,7 @@ def __init__(self, cif_string, transformations=None, primitive=True, extend_coll
         containing multiple structures.
 
         Args:
-            cif_string: A string containing a cif or a series of cifs
+            cif_string: A string containing a cif or a series of CIFs
             transformations: New transformations to be applied to all
                 structures
             primitive: Whether to generate the primitive cell from the cif.
@@ -259,8 +258,8 @@ def __init__(self, cif_string, transformations=None, primitive=True, extend_coll
             transformed_structures.append(trafo_struct)
         super().__init__(transformed_structures, transformations, extend_collection)
 
-    @staticmethod
-    def from_filenames(filenames, transformations=None, primitive=True, extend_collection=False):
+    @classmethod
+    def from_filenames(cls, filenames, transformations=None, primitive=True, extend_collection=False):
         """Generates a TransformedStructureCollection from a cif, possibly
         containing multiple structures.
 
@@ -271,12 +270,12 @@ def from_filenames(filenames, transformations=None, primitive=True, extend_colle
             primitive: Same meaning as in __init__.
             extend_collection: Same meaning as in __init__.
         """
-        allcifs = []
+        cif_files = []
         for fname in filenames:
-            with open(fname) as f:
-                allcifs.append(f.read())
-        return CifTransmuter(
-            "\n".join(allcifs),
+            with open(fname) as file:
+                cif_files.append(file.read())
+        return cls(
+            "\n".join(cif_files),
             transformations,
             primitive=primitive,
             extend_collection=extend_collection,

pymatgen/analysis/chemenv/coordination_environments/coordination_geometry_finder.py

@@ -1305,15 +1305,17 @@ def coordination_geometry_symmetry_measures(
         points_perfect=None,
         optimization=None,
     ):
-        """
-        Returns the symmetry measures of a given coordination_geometry for a set of permutations depending on
-        the permutation setup. Depending on the parameters of the LocalGeometryFinder and on the coordination
-         geometry, different methods are called.
+        """Returns the symmetry measures of a given coordination_geometry for a set of
+        permutations depending on the permutation setup. Depending on the parameters of
+        the LocalGeometryFinder and on the coordination geometry, different methods are called.
+
         :param coordination_geometry: Coordination geometry for which the symmetry measures are looked for
 
+        Raises:
+            NotImplementedError: if the permutation_setup does not exist
+
         Returns:
             the symmetry measures of a given coordination_geometry for a set of permutations
-        :raise: NotImplementedError if the permutation_setup does not exists.
         """
         if tested_permutations:
             tested_permutations = set()
@@ -1351,15 +1353,17 @@ def coordination_geometry_symmetry_measures(
     def coordination_geometry_symmetry_measures_sepplane_optim(
         self, coordination_geometry, points_perfect=None, nb_set=None, optimization=None
     ):
-        """
-        Returns the symmetry measures of a given coordination_geometry for a set of permutations depending on
-        the permutation setup. Depending on the parameters of the LocalGeometryFinder and on the coordination
-         geometry, different methods are called.
+        """Returns the symmetry measures of a given coordination_geometry for a set of
+        permutations depending on the permutation setup. Depending on the parameters of
+        the LocalGeometryFinder and on the coordination geometry, different methods are called.
+
         :param coordination_geometry: Coordination geometry for which the symmetry measures are looked for
 
+        Raises:
+            NotImplementedError: if the permutation_setup does not exist
+
         Returns:
             the symmetry measures of a given coordination_geometry for a set of permutations
-        :raise: NotImplementedError if the permutation_setup does not exists.
         """
         csms = []
         permutations = []

pymatgen/analysis/chemenv/coordination_environments/structure_environments.py

@@ -618,11 +618,11 @@ def get_csm(self, isite, mp_symbol):
     def get_csms(self, isite, mp_symbol):
         """
         Returns the continuous symmetry measure(s) of site with index isite with respect to the
-         perfect coordination environment with mp_symbol. For some environments, a given mp_symbol might not
-         be available (if there is no voronoi parameters leading to a number of neighbors corresponding to
-         the coordination number of environment mp_symbol). For some environments, a given mp_symbol might
-         lead to more than one csm (when two or more different voronoi parameters lead to different neighbors
-         but with same number of neighbors).
+        perfect coordination environment with mp_symbol. For some environments, a given mp_symbol might not
+        be available (if there is no voronoi parameters leading to a number of neighbors corresponding to
+        the coordination number of environment mp_symbol). For some environments, a given mp_symbol might
+        lead to more than one csm (when two or more different voronoi parameters lead to different neighbors
+        but with same number of neighbors).
 
         Args:
             isite: Index of the site.

pymatgen/analysis/chemenv/utils/coordination_geometry_utils.py

@@ -68,10 +68,10 @@ def function_comparison(f1, f2, x1, x2, numpoints_check=500):
         numpoints_check: Number of points used to compare the functions
 
     Returns:
-        Whether the function are equal ("="), f1 is always lower than f2 ("<"), f1 is always larger than f2 (">"),
-         f1 is always lower than or equal to f2 ("<"), f1 is always larger than or equal to f2 (">") on the
-         interval [x1, x2]. If the two functions cross, a RuntimeError is thrown (i.e. we expect to compare
-         functions that do not cross...)
+        str: '=' if the functions are equal, '<' if f1 is always lower than f2, '>' if f1 is always larger than f2,
+            f1 is always lower than or equal to f2 ("<"), f1 is always larger than or equal to f2 (">") on the
+            interval [x1, x2]. If the two functions cross, a RuntimeError is thrown (i.e. we expect to compare
+            functions that do not cross...)
     """
     xx = np.linspace(x1, x2, num=numpoints_check)
     y1 = f1(xx)

pymatgen/analysis/chemenv/utils/graph_utils.py

@@ -287,10 +287,10 @@ def from_edges(cls, edges, edges_are_ordered=True):
 
     def as_dict(self):
         """MSONable dict"""
-        d = MSONable.as_dict(self)
+        dct = MSONable.as_dict(self)
         # Transforming tuple object to a list to allow BSON and MongoDB
-        d["nodes"] = list(d["nodes"])
-        return d
+        dct["nodes"] = list(dct["nodes"])
+        return dct
 
     @classmethod
     def from_dict(cls, d, validate=False):

pymatgen/analysis/diffraction/tem.py

@@ -286,10 +286,10 @@ def get_pattern(
         Args:
             structure (Structure): The input structure.
             scaled (bool): Required value for inheritance, does nothing in TEM pattern
-            two_theta_range (Tuple): Required value for inheritance, does nothing in TEM pattern
+            two_theta_range (tuple[float, float]): Required value for inheritance, does nothing in TEM pattern
 
         Returns:
-            PandasDataFrame
+            pd.DataFrame
         """
         if self.symprec:
             finder = SpacegroupAnalyzer(structure, symprec=self.symprec)

pymatgen/analysis/excitation.py

@@ -9,12 +9,9 @@ class ExcitationSpectrum(Spectrum):
     """
     Basic excitation spectrum object.
 
-    .. attribute: x
-        The sequence of energies
-
-    .. attribute: y
-        The sequence of mu(E)
-
+    Attributes:
+        x (Sequence[float]): The sequence of energies.
+        y (Sequence[float]): The sequence of mu(E).
     """
 
     XLABEL = "Energy (eV)"

pymatgen/analysis/gb/grain.py

@@ -274,18 +274,18 @@ def as_dict(self):
         Returns:
             Dictionary representation of GrainBoundary object.
         """
-        d = super().as_dict()
-        d["@module"] = type(self).__module__
-        d["@class"] = type(self).__name__
-        d["init_cell"] = self.init_cell.as_dict()
-        d["rotation_axis"] = self.rotation_axis
-        d["rotation_angle"] = self.rotation_angle
-        d["gb_plane"] = self.gb_plane
-        d["join_plane"] = self.join_plane
-        d["vacuum_thickness"] = self.vacuum_thickness
-        d["ab_shift"] = self.ab_shift
-        d["oriented_unit_cell"] = self.oriented_unit_cell.as_dict()
-        return d
+        dct = super().as_dict()
+        dct["@module"] = type(self).__module__
+        dct["@class"] = type(self).__name__
+        dct["init_cell"] = self.init_cell.as_dict()
+        dct["rotation_axis"] = self.rotation_axis
+        dct["rotation_angle"] = self.rotation_angle
+        dct["gb_plane"] = self.gb_plane
+        dct["join_plane"] = self.join_plane
+        dct["vacuum_thickness"] = self.vacuum_thickness
+        dct["ab_shift"] = self.ab_shift
+        dct["oriented_unit_cell"] = self.oriented_unit_cell.as_dict()
+        return dct
 
     @classmethod
     def from_dict(cls, d):
@@ -458,7 +458,7 @@ def gb_from_parameters(
                 find the smallest cell.
 
         Returns:
-           Grain boundary structure (GB object).
+            Grain boundary structure (GB object).
         """
         lat_type = self.lat_type
         # if the initial structure is primitive cell in cubic system,

pymatgen/analysis/local_env.py

@@ -1171,7 +1171,7 @@ def _get_elements(site):
     Get the list of elements for a Site.
 
     Args:
-         site (Site): Site to assess
+        site (Site): Site to assess
 
     Returns:
         [Element]: List of elements
@@ -4195,14 +4195,13 @@ def extend_structure_molecules(self):
         """
         return True
 
-    @staticmethod
-    def from_preset(preset):
+    @classmethod
+    def from_preset(cls, preset):
         """
         Initialize a CutOffDictNN according to a preset set of cut-offs.
 
         Args:
             preset (str): A preset name. The list of supported presets are:
-
                 - "vesta_2019": The distance cut-offs used by the VESTA
                   visualisation program.
 
@@ -4211,7 +4210,7 @@ def from_preset(preset):
         """
         if preset == "vesta_2019":
             cut_offs = loadfn(f"{_directory}/vesta_cutoffs.yaml")
-            return CutOffDictNN(cut_off_dict=cut_offs)
+            return cls(cut_off_dict=cut_offs)
 
         raise ValueError(f"Unknown {preset=}")