document args missing from doc strings

standardize to Google doc str format
add type hints

Author: janosh

crystal_toolkit/apps/main.py

@@ -15,6 +15,7 @@
 from dash.exceptions import PreventUpdate
 from flask_caching import Cache
 from monty.serialization import loadfn
+from pymatgen.core import Structure
 from pymatgen.core import __version__ as pmg_version
 from pymatgen.ext.matproj import MPRester, MPRestError
 
@@ -455,7 +456,9 @@ def update_search_term_on_page_load(href: str) -> str:
     [Input(search_component.id("input"), "value")],
     [State(search_component.id("input"), "n_submit")],
 )
-def perform_search_on_page_load(search_term: str, n_submit: int | None):
+def perform_search_on_page_load(
+    search_term: str, n_submit: int | None
+) -> tuple[int, int]:
     """
     Loading with an mpid in the URL requires populating the search term with
     the mpid, this callback forces that search to then take place by force updating
@@ -495,7 +498,9 @@ def update_url_pathname_from_search_term(mpid: str | None) -> str:
     Output(transformation_component.id("input_structure"), "data"),
     [Input(search_component.id(), "data"), Input(upload_component.id(), "data")],
 )
-def master_update_structure(search_mpid: str | None, upload_data: dict | None):
+def master_update_structure(
+    search_mpid: str | None, upload_data: dict | None
+) -> Structure:
     """
     A new structure is loaded either from the search component or from the
     upload component. This callback triggers the update, and uses the callback

crystal_toolkit/components/diffraction.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import math
 
 import numpy as np
@@ -33,7 +35,7 @@ def __init__(self, *args, initial_structure=None, **kwargs):
         super().__init__(*args, **kwargs)
         self.create_store("structure", initial_data=initial_structure)
 
-    def layout(self):
+    def layout(self) -> Columns:
 
         voltage = self.get_numerical_input(
             kwarg_label="voltage",
@@ -84,7 +86,7 @@ def generate_diffraction_pattern(structure, *args):
             return dcc.Graph(
                 figure=calculator.get_plot_2d(structure),
                 responsive=False,
-                config={"displayModeBar": False, "displaylogo": False},
+                config=dict(displayModeBar=False, displaylogo=False),
             )
 
 
@@ -166,32 +168,39 @@ def V(x, c, alphagamma):
         )
 
     @staticmethod
-    def twotheta_to_q(twotheta, xray_wavelength):
-        """
-        Convert twotheta to Q.
+    def two_theta_to_q(two_theta: float, xray_wavelength: float) -> float:
+        """Angular conversion from 2*theta to q in small-angle scattering (SAS).
 
-        :param twotheta: in degrees
-        :param xray_wavelength: in Ångstroms
-        :return:
+        Args:
+            two_theta (float): in degrees
+            xray_wavelength (float): in Ångstroms
+
+        Returns:
+            float: Q in Ångstroms^-1
         """
         # thanks @rwoodsrobinson
-        return (4 * np.pi / xray_wavelength) * np.sin(np.deg2rad(twotheta) / 2)
+        return (4 * np.pi / xray_wavelength) * np.sin(np.deg2rad(two_theta) / 2)
 
     @staticmethod
-    def grain_to_hwhm(tau, two_theta, K=0.9, wavelength="CuKa"):
-        """
-        :param tau: grain size in nm
-        :param two_theta: angle (in 2-theta)
-        :param K: shape factor (default 0.9)
-        :param wavelength: wavelength radiation in nm
-        :return: half-width half-max (alpha or gamma), for line profile
+    def grain_to_hwhm(
+        tau: float, two_theta: float, K: float = 0.9, wavelength: float | str = "CuKa"
+    ) -> float:
+        """_summary_
+
+        Args:
+            tau (float): grain size in nm
+            two_theta (float): angle (in 2-theta)
+            K (float, optional): shape factor (default 0.9). Defaults to 0.9.
+            wavelength (float | str, optional): wavelength radiation in nm. Defaults to "CuKa".
+
+        Returns:
+            float: half-width half-max (alpha or gamma), for line profile
         """
         if isinstance(wavelength, str):
             wavelength = WAVELENGTHS[wavelength]
+        # Scherrer equation for half-width half max
         # factor of 0.1 to convert wavelength to nm
-        return (
-            0.5 * K * 0.1 * wavelength / (tau * abs(np.cos(two_theta / 2)))
-        )  # Scherrer equation for half-width half max
+        return 0.5 * K * 0.1 * wavelength / (tau * abs(np.cos(two_theta / 2)))
 
     @property
     def _sub_layouts(self):
@@ -200,7 +209,7 @@ def _sub_layouts(self):
             "peak_profile": "G",
             "shape_factor": 0.94,
             "rad_source": "CuKa",
-            "x_axis": "twotheta",
+            "x_axis": "two_theta",
             "crystallite_size": 0.1,
         }
 
@@ -288,7 +297,7 @@ def _sub_layouts(self):
                     help_str="Can choose between 2𝜃 or Q, where Q is the magnitude of the reciprocal lattice and "
                     "independent of radiation source.",  # TODO: improve
                     options=[
-                        {"label": "2𝜃", "value": "twotheta"},
+                        {"label": "2𝜃", "value": "two_theta"},
                         {"label": "Q", "value": "Q"},
                     ],
                 )
@@ -323,14 +332,16 @@ def _sub_layouts(self):
             "static_image": static_image,
         }
 
-    def layout(self, static_image=False):
-        """
-        Get the standard XRD diffraction pattern layout.
+    def layout(self, static_image: bool = False) -> Columns:
+        """Get the standard XRD diffraction pattern layout.
 
-        :param static_image: If True, will show a static image instead of an interactive graph.
-        :return:
-        """
+        Args:
+            static_image (bool, optional): If True, will show a static image instead of an interactive graph.
+                Defaults to False.
 
+        Returns:
+            Columns: from crystal_toolkit.helpers.layouts
+        """
         sub_layouts = self._sub_layouts
         if static_image:
             inner = sub_layouts["static_image"]
@@ -415,10 +426,10 @@ def get_figure(
         layout = XRayDiffractionComponent.default_xrd_plot_style
 
         if x_axis == "Q":
-            x_peak = XRayDiffractionComponent.twotheta_to_q(
+            x_peak = XRayDiffractionComponent.two_theta_to_q(
                 x_peak, WAVELENGTHS[rad_source]
             )
-            x = XRayDiffractionComponent.twotheta_to_q(x, WAVELENGTHS[rad_source])
+            x = XRayDiffractionComponent.two_theta_to_q(x, WAVELENGTHS[rad_source])
             layout["xaxis"]["title"] = "Q / Å⁻¹"
         else:
             layout["xaxis"]["title"] = "2𝜃 / º"

crystal_toolkit/components/phase_diagram.py

@@ -715,11 +715,21 @@ def create_table(chemsys, pd_time, n_clicks, pd, rows):
                 Input(self.id("chemsys-external"), "data"),
             ],
         )
-        def get_chemsys_from_mpid_or_chemsys(mpid, chemsys_external: str):
-            """
-            :param mpid: mpid
-            :param chemsys_external: chemsys, e.g. "Co-O"
-            :return: chemsys
+        def get_chemsys_from_mpid_or_chemsys(
+            mpid: str, chemsys_external: str
+        ) -> str | None:
+            """Get the chemical system as a string of elements sorted alphabetically and joined by dashes,
+            by convention for use in database keys.
+
+            Args:
+                mpid (str): MP material ID.
+                chemsys_external (str): chemsys, e.g. "Co-O"
+
+            Raises:
+                PreventUpdate: ctx is None or not triggered or trigger["value"] is None.
+
+            Returns:
+                str | None: chemical system, e.g. "O-Si" for SiO2.
             """
             ctx = dash.callback_context
 

crystal_toolkit/components/pourbaix.py

@@ -751,7 +751,7 @@ def get_pourbaix_diagram(pourbaix_entries, **kwargs):
                 Input(self.get_all_kwargs_id(), "value"),
             ],
         )
-        def make_figure(pourbaix_entries, *args):
+        def make_figure(pourbaix_entries, *args) -> go.Figure:
 
             if pourbaix_entries is None:
                 raise PreventUpdate

crystal_toolkit/components/structure.py

@@ -115,33 +115,40 @@ def __init__(
         show_position_button: bool = DEFAULTS["show_position_button"],
         **kwargs,
     ):
+        """Create a StructureMoleculeComponent from a structure or molecule.
+
+        Args:
+            struct_or_mol (None |, optional): input structure or molecule. Defaults to None.
+            id (str, optional): canonical id. Defaults to None.
+            className (str, optional): extra geometric elements to add to the 3D scene. Defaults to "box".
+            scene_additions (Scene | None, optional): bonding strategy from pymatgen NearNeighbors class.
+                Defaults to None.
+            bonding_strategy (str, optional): options for the bonding strategy.
+            bonding_strategy_kwargs (dict | None, optional): color scheme, see Legend class.
+                Defaults to None.
+            color_scheme (str, optional): color scale, see Legend class.
+            color_scale (str | None, optional): radius strategy, see Legend class.
+                Defaults to None.
+            radius_strategy (str, optional):  optional): radius strategy, see Legend class.
+            unit_cell_choice (str, optional): whether to draw repeats of atoms on periodic images.
+            draw_image_atoms (bool, optional): whether to draw sites bonded outside the unit cell.
+            bonded_sites_outside_unit_cell (bool, optional): whether to hide or show incomplete bonds.
+                Defaults to DEFAULTS[ "bonded_sites_outside_unit_cell" ].
+            hide_incomplete_bonds (bool, optional): whether to hide or show the compass.
+            show_compass (bool, optional): scene settings (lighting etc.) to pass to CrystalToolkitScene.
+            scene_settings (dict | None, optional): a site property used for grouping of atoms for
+                mouseover/interaction. Defaults to None.
+            group_by_site_property (str | None, optional): a site property used for grouping of atoms for
+                mouseover/interaction. Defaults to None.
+            show_legend (bool, optional):  optional): show or hide legend panel within the scene.
+            show_settings (bool, optional): show or hide scene control bar.
+            show_controls (bool, optional): show or hide the full screen button within the scene control bar.
+            show_expand_button (bool, optional): show or hide the image download button within the scene control bar.
+            show_image_button (bool, optional): show or hide the file export button within the scene control bar.
+            show_export_button (bool, optional): show or hide the revert position button within the scene control bar.
+            show_position_button (bool, optional): extra keyword arguments to pass to MPComponent. e.g. Wyckoff label.
+            **kwargs: a CSS dimension specifying width/height of Div.
         """
-        Create a StructureMoleculeComponent from a structure or molecule.
-
-        :param struct_or_mol: input structure or molecule
-        :param id: canonical id
-        :param scene_additions: extra geometric elements to add to the 3D scene
-        :param bonding_strategy: bonding strategy from pymatgen NearNeighbors class
-        :param bonding_strategy_kwargs: options for the bonding strategy
-        :param color_scheme: color scheme, see Legend class
-        :param color_scale: color scale, see Legend class
-        :param radius_strategy: radius strategy, see Legend class
-        :param draw_image_atoms: whether to draw repeats of atoms on periodic images
-        :param bonded_sites_outside_unit_cell: whether to draw sites bonded outside the unit cell
-        :param hide_incomplete_bonds: whether to hide or show incomplete bonds
-        :param show_compass: whether to hide or show the compass
-        :param scene_settings: scene settings (lighting etc.) to pass to CrystalToolkitScene
-        :param group_by_site_property: a site property used for grouping of atoms for mouseover/interaction,
-        :param show_legend: show or hide legend panel within the scene
-        :param show_controls: show or hide scene control bar
-        :param show_expand_button: show or hide the full screen button within the scene control bar
-        :param show_image_button: show or hide the image download button within the scene control bar
-        :param show_export_button: show or hide the file export button within the scene control bar
-        :param show_position_button: show or hide the revert position button within the scene control bar
-        e.g. Wyckoff label
-        :param kwargs: extra keyword arguments to pass to MPComponent
-        """
-
         super().__init__(id=id, default_data=struct_or_mol, **kwargs)
         self.className = className
         self.show_legend = show_legend
@@ -898,9 +905,13 @@ def _sub_layouts(self):
         }
 
     def layout(self, size: str = "500px") -> html.Div:
-        """
-        :param size: a CSS dimension specifying width/height of Div
-        :return: A html.Div containing the 3D structure or molecule
+        """Get the layout for this component.
+
+        Args:
+            size (str, optional): a CSS dimension specifying width/height of Div. Defaults to "500px".
+
+        Returns:
+            html.Div: A html.Div containing the 3D structure or molecule
         """
         return html.Div(
             self._sub_layouts["struct"], style={"width": size, "height": size}