Add type hints (#507)

docs/source/conf.py

@@ -27,6 +27,9 @@
 
 autodoc_typehints = "description"
 autodoc_member_order = "groupwise"
+autodoc_type_aliases = {
+    "NumBuildingBlocks": "dict[Molecule, int]",
+}
 autoclass_content = "both"
 
 intersphinx_mapping = {

src/stk/__init__.py

@@ -13,6 +13,9 @@
 from stk._internal.bond_info import BondInfo
 from stk._internal.building_block import BuildingBlock
 from stk._internal.constructed_molecule import ConstructedMolecule
+from stk._internal.construction_result.construction_result import (
+    ConstructionResult,
+)
 from stk._internal.construction_state.construction_state import (
     ConstructionState,
 )
@@ -478,6 +481,7 @@
     "MoleculeKeyMaker",
     "Molecule",
     "ConstructionState",
+    "ConstructionResult",
     "ReactionResult",
     "GraphState",
     "OneOneReaction",

src/stk/_internal/atom_info.py

@@ -1,32 +1,20 @@
-"""
-Atom Info
-=========
-
-"""
-
-
-import typing
-
 from stk._internal.atom import Atom
 from stk._internal.molecule import Molecule
 
 
 class AtomInfo:
     """
     Holds additional info about :class:`.ConstructedMolecule` atoms.
-
     """
 
     def __init__(
         self,
         atom: Atom,
-        building_block_atom: typing.Optional[Atom],
-        building_block: typing.Optional[Molecule],
-        building_block_id: typing.Optional[int],
+        building_block_atom: Atom | None,
+        building_block: Molecule | None,
+        building_block_id: int | None,
     ) -> None:
         """
-        Initialize an :class:`.AtomInfo` instance.
-
         Parameters:
 
             atom:
@@ -53,9 +41,7 @@ def __init__(
                 Can be ``None``, if the atom was not part of a
                 building block, but was added by the construction
                 process instead.
-
         """
-
         self._atom = atom
         self._building_block_atom = building_block_atom
         self._building_block = building_block
@@ -73,7 +59,7 @@ def get_atom(self) -> Atom:
 
         return self._atom
 
-    def get_building_block_atom(self) -> typing.Optional[Atom]:
+    def get_building_block_atom(self) -> Atom | None:
         """
         Get the original atom held by the building block.
 
@@ -87,7 +73,7 @@ def get_building_block_atom(self) -> typing.Optional[Atom]:
 
         return self._building_block_atom
 
-    def get_building_block(self) -> typing.Optional[Molecule]:
+    def get_building_block(self) -> Molecule | None:
         """
         Get the building block from which the atom originates.
 
@@ -101,7 +87,7 @@ def get_building_block(self) -> typing.Optional[Molecule]:
 
         return self._building_block
 
-    def get_building_block_id(self) -> typing.Optional[int]:
+    def get_building_block_id(self) -> int | None:
         """
         Get the id of the atom's building block.
 

src/stk/_internal/bond.py

@@ -1,24 +1,13 @@
-"""
-Bond
-====
-
-"""
-
-from __future__ import annotations
-
-from typing import TypeVar
+import typing
 
 from stk._internal.atom import Atom
 
-_T = TypeVar("_T", bound="Bond")
-
 
 class Bond:
     """
     Represents an atomic bond.
 
     Examples:
-
         *Changing the Atoms of a Bond*
 
         You want to substitute the atoms in the bond for other atoms.
@@ -39,7 +28,6 @@ class Bond:
             assert isinstance(clone.get_atom1(), stk.H)
             assert clone.get_atom2().get_id() == 12
             assert isinstance(clone.get_atom2(), stk.C)
-
     """
 
     def __init__(
@@ -50,8 +38,6 @@ def __init__(
         periodicity: tuple[int, int, int] = (0, 0, 0),
     ) -> None:
         """
-        Initialize a :class:`Bond`.
-
         Parameters:
 
             atom1:
@@ -70,9 +56,7 @@ def __init__(
                 periodic across the x axis in the positive direction,
                 is not periodic across the y axis and is periodic
                 across the z axis in the negative direction.
-
         """
-
         self._atom1 = atom1
         self._atom2 = atom2
         self._order = order
@@ -83,43 +67,33 @@ def get_atom1(self) -> Atom:
         Get the first atom of the bond.
 
         Returns:
-
             The first atom of the bond.
-
         """
-
         return self._atom1
 
     def get_atom2(self) -> Atom:
         """
         Get the second atom of the bond.
 
         Returns:
-
             The second atom of the bond.
-
         """
-
         return self._atom2
 
     def get_order(self) -> int:
         """
         Get the bond order of the bond.
 
         Returns:
-
             The bond order.
-
         """
-
         return self._order
 
     def get_periodicity(self) -> tuple[int, int, int]:
         """
         Get the periodicity of the bond.
 
         Returns:
-
             The directions across which the bond is periodic. For
             example, ``(1, 0, -1)`` means that when going from
             `atom1` to `atom2` the bond is
@@ -128,19 +102,15 @@ def get_periodicity(self) -> tuple[int, int, int]:
             axis in the negative direction.
 
         """
-
         return self._periodicity
 
-    def clone(self) -> Bond:
+    def clone(self) -> typing.Self:
         """
         Return a clone.
 
         Returns:
-
-            The clone.
-
+            Bond: The clone.
         """
-
         clone = self.__class__.__new__(self.__class__)
         Bond.__init__(
             self=clone,
@@ -151,57 +121,48 @@ def clone(self) -> Bond:
         )
         return clone
 
-    def _with_atoms(self: _T, atom_map: dict[int, Atom]) -> _T:
+    def _with_atoms(self, atom_map: dict[int, Atom]) -> typing.Self:
         """
         Modify the bond.
 
         """
-
         self._atom1 = atom_map.get(self._atom1.get_id(), self._atom1)
         self._atom2 = atom_map.get(self._atom2.get_id(), self._atom2)
         return self
 
-    def with_atoms(self, atom_map: dict[int, Atom]) -> Bond:
+    def with_atoms(self, atom_map: dict[int, Atom]) -> typing.Self:
         """
         Return a clone holding different atoms.
 
         Parameters:
-
             atom_map:
                 Maps the id of an atom in the bond to the new atom the
                 clone should hold. If the id of an atom in the bond is
                 not found in `atom_map`, the atom will not be replaced
                 in the clone.
 
         Returns:
-
-            The clone.
-
+            Bond: The clone.
         """
-
         return self.clone()._with_atoms(atom_map)
 
-    def with_ids(self, id_map: dict[int, int]) -> Bond:
+    def with_ids(self, id_map: dict[int, int]) -> typing.Self:
         """
         Return a clone holding different atom ids.
 
         Parameters:
-
             id_map:
                 Maps the id of an atom in the bond to the new id the
                 clone should hold. If the id of an atom in the bond is
                 not found in `id_map`, the atom id will not be replaced
                 in the clone.
 
         Returns:
-
-            The clone.
-
+            Bond: The clone.
         """
-
         return self.clone()._with_ids(id_map)
 
-    def _with_ids(self, id_map: dict[int, int]) -> Bond:
+    def _with_ids(self, id_map: dict[int, int]) -> typing.Self:
         id1 = self._atom1.get_id()
         if id1 in id_map:
             self._atom1 = self._atom1.with_id(id_map[id1])
@@ -217,11 +178,8 @@ def is_periodic(self) -> bool:
         Return ``True`` if the bond is periodic.
 
         Returns:
-
             ``True`` if the bond is periodic.
-
         """
-
         return any(direction != 0 for direction in self._periodicity)
 
     def __repr__(self) -> str: