Small fixes and typing (#527)

src/stk/_internal/building_block.py

@@ -782,6 +782,7 @@ def _with_functional_groups(
         """
 
         self._functional_groups = tuple(functional_groups)
+        self._fg_repr = repr(self._functional_groups)
         return self
 
     def with_functional_groups(
@@ -812,6 +813,7 @@ def _with_canonical_atom_ordering(self) -> typing.Self:
             functional_group.with_ids(id_map)
             for functional_group in self._functional_groups
         )
+        self._fg_repr = repr(self._functional_groups)
         self._placer_ids = frozenset(
             id_map[placer_id] for placer_id in self._placer_ids
         )

src/stk/_internal/topology_graphs/host_guest/complex.py

@@ -37,7 +37,7 @@ def __init__(
         building_block: BuildingBlock,
         start_vector: tuple[float, float, float] = (1.0, 0.0, 0.0),
         end_vector: tuple[float, float, float] = (1.0, 0.0, 0.0),
-        displacement: tuple[float, float, float] = (1.0, 0.0, 0.0),
+        displacement: tuple[float, float, float] = (0.0, 0.0, 0.0),
     ) -> None:
         """
         Initialize a :class:`.Guest` instance.
@@ -410,7 +410,7 @@ class Complex(TopologyGraph):
         *Changing the Position of the Guest*
 
         You can change the position and orientation of the
-        :class:`.Guest`, as well as its displacement
+        :class:`.Guest`.
 
         .. testcode:: changing-the-position-of-the-guest
 
@@ -449,6 +449,13 @@ class Complex(TopologyGraph):
                 ),
             )
 
+    .. tip::
+
+        The host of a :class:`.Complex` will always be placed at the
+        origin, not at the centroid of the input building block. Therefore,
+        to place a guest at the centroid of the host use
+        `displacement=(0, 0, 0)`, which is the default behaviour.
+
     """
 
     def __init__(
@@ -521,7 +528,7 @@ def _get_vertices_from_guests(
                         target=guest.get_end_vector(),
                     ),
                 ]
-        return building_block_vertices  # type: ignore
+        return building_block_vertices  # type: ignore[return-value]
 
     def clone(self) -> Complex:
         return self._clone()

src/stk/_internal/writers/turbomole.py

@@ -1,16 +1,11 @@
-"""
-Turbomole Writer
-================
-
-"""
-
 from __future__ import annotations
 
 import typing
 
 from stk._internal.molecule import Molecule
 from stk._internal.periodic_info import PeriodicInfo
 from stk._internal.utilities.utilities import OneOrMany
+import pathlib
 
 
 class TurbomoleWriter:
@@ -144,7 +139,7 @@ def to_string(
     def write(
         self,
         molecule: Molecule,
-        path: str,
+        path: pathlib.Path | str,
         atom_ids: typing.Optional[OneOrMany[int]] = None,
         periodic_info: typing.Optional[PeriodicInfo] = None,
     ) -> None:

tests/molecular/molecules/building_block/case_data.py

@@ -1,59 +1,12 @@
-class CaseData:
-    """
-    A test case.
-
-    Attributes
-    ----------
-    building_block : :class:`.BuildingBlock`
-        The building block to test.
-
-    functional_groups : :class:`tuple` of :class:`.FunctionalGroup`
-        The functional groups :attr:`.building_block` should be
-        holding.
-
-    known_repr : str
-        The representation of the building block.
-
-    core_atom_ids : :class:`tuple` of :class:`int`
-        The correct core atom ids for :attr:`.building_block`.
-
-    placer_ids : :class:`tuple` of :class:`int`
-        The correct *placer* ids for :attr:`.building_block`.
-
-    """
+import stk
+from dataclasses import dataclass
+from collections.abc import Sequence
 
-    def __init__(
-        self,
-        building_block,
-        functional_groups,
-        known_repr,
-        core_atom_ids,
-        placer_ids,
-    ):
-        """
-        Initialize a :class:`.CaseData` instance.
 
-        Parameters
-        ----------
-        building_block : :class:`.BuildingBlock`
-            The building block to test.
-
-        functional_groups : :class:`tuple` of :class:`.FunctionalGroup`
-            The functional groups `building_block` should be holding.
-
-        known_repr : str
-            The representation of the building block.
-
-        core_atom_ids : :class:`tuple` of :class:`int`
-            The correct core atom ids for `building_block`.
-
-        placer_ids : :class:`tuple` of :class:`int`
-            The correct *placer* ids for `building_block`.
-
-        """
-
-        self.building_block = building_block
-        self.functional_groups = functional_groups
-        self.known_repr = known_repr
-        self.core_atom_ids = core_atom_ids
-        self.placer_ids = placer_ids
+@dataclass(slots=True, frozen=True)
+class CaseData:
+    building_block: stk.BuildingBlock
+    functional_groups: Sequence[stk.FunctionalGroup]
+    known_repr: str
+    core_atom_ids: Sequence[int]
+    placer_ids: Sequence[int]

tests/molecular/molecules/building_block/conftest.py

@@ -3,10 +3,13 @@
 import pytest
 import stk
 from pytest_lazyfixture import lazy_fixture
+from collections import abc
 
 # Fixtures need be visible for lazy_fixture() calls.
 from .fixtures import *  # noqa
 
+from .case_data import CaseData
+
 
 @pytest.fixture(
     params=(
@@ -17,7 +20,7 @@
         lazy_fixture("init_from_rdkit_mol"),
     ),
 )
-def case_data(request):
+def case_data(request) -> CaseData:
     """
     A :class:`.CaseData` instance.
 
@@ -27,7 +30,7 @@ def case_data(request):
 
 
 @pytest.fixture
-def building_block(case_data):
+def building_block(case_data: CaseData) -> stk.BuildingBlock:
     """
     A :class:`.BuildingBlock` instance.
 
@@ -48,18 +51,17 @@ def building_block(case_data):
         ),
     )
 )
-def get_functional_groups(request):
+def get_functional_groups(
+    request: pytest.FixtureRequest,
+) -> abc.Iterable[stk.FunctionalGroup]:
     """
-    Yield the functional groups of a `molecule`.
+    Get the functional groups of a `molecule`.
 
-    Parameters
-    ----------
-    molecule : :class:`.Molecule`
-        The molecule whose functional groups should be gotten.
+    Parameters:
+        molecule:
+            The molecule whose functional groups should be gotten.
 
-    Yields
-    ------
-    :class:`.FunctionalGroup`
+    Returns:
         A functional group of `molecule`.
 
     """

tests/molecular/molecules/building_block/fixtures/init_from_file.py

@@ -1,104 +1,26 @@
 import pytest
 import stk
-
+from collections.abc import Sequence
 from ..case_data import CaseData
+from dataclasses import dataclass
 
 
 @pytest.fixture(
-    params=[
-        "building_block.mol",
-    ],
+    params=["building_block.mol"],
 )
 def path(tmpdir, request):
     return tmpdir / request.param
 
 
+@dataclass(frozen=True, slots=True)
 class InitFromFileData:
-    """
-    Stores data for the :meth:`.BuildingBlock.init_from_file`.
-
-    Attributes
-    ----------
-    building_block : :class:`.BuildingBlock`
-        The building block, which will be written to a file, so that it
-        can be initialized from it.
-
-    init_functional_groups : :class:`iterable`
-        Passed to the `functional_groups` parameter of
-        :meth:`.BuildingBlock.init_from_file`.
-
-    init_placer_ids : :class:`tuple` or :class:`NoneType`
-        Passed to the `placer_ids` parameter of
-        :meth:`.BuildingBlock.init_from_file`.
-
-    case_data_functional_groups : :class:`tuple`
-        The functional groups the initialized building block should
-        have.
-
-    case_data_core_atom_ids : :class:`tuple` of :class:`int`
-        The ids of core atoms the initialized building block should
-        have.
-
-    case_data_placer_ids : :class:`tuple` of :class:`int`
-        The ids of *placer* atoms the initialized building block should
-        have.
-
-    known_repr : str
-        The representation of the building block.
-
-    """
-
-    def __init__(
-        self,
-        building_block,
-        init_functional_groups,
-        init_placer_ids,
-        case_data_functional_groups,
-        case_data_core_atom_ids,
-        case_data_placer_ids,
-        known_repr,
-    ):
-        """
-        Initialize a :class:`.InitFromData` instance.
-
-        Parameters
-        ----------
-        building_block : :class:`.BuildingBlock`
-            The building block, which will be written to a file, so
-            that it can be initialized from it.
-
-        init_functional_groups : :class:`iterable`
-            Passed to the `functional_groups` parameter of
-            :meth:`.BuildingBlock.init_from_file`.
-
-        init_placer_ids : :class:`tuple` or :class:`NoneType`
-            Passed to the `placer_ids` parameter of
-            :meth:`.BuildingBlock.init_from_file`.
-
-        case_data_functional_groups : :class:`tuple`
-            The functional groups the initialized building block should
-            have.
-
-        case_data_core_atom_ids : :class:`tuple` of :class:`int`
-            The ids of core atoms the initialized building block should
-            have.
-
-        case_data_placer_ids : :class:`tuple` of :class:`int`
-            The ids of *placer* atoms the initialized building block
-            should have.
-
-        known_repr : str
-            The representation of the building block.
-
-        """
-
-        self.building_block = building_block
-        self.init_functional_groups = init_functional_groups
-        self.init_placer_ids = init_placer_ids
-        self.case_data_functional_groups = case_data_functional_groups
-        self.case_data_core_atom_ids = case_data_core_atom_ids
-        self.case_data_placer_ids = case_data_placer_ids
-        self.known_repr = known_repr
+    building_block: stk.BuildingBlock
+    init_functional_groups: Sequence[stk.FunctionalGroup]
+    init_placer_ids: Sequence[int] | None
+    case_data_functional_groups: Sequence[stk.FunctionalGroup]
+    case_data_core_atom_ids: Sequence[int]
+    case_data_placer_ids: Sequence[int]
+    known_repr: str
 
 
 @pytest.fixture(

tests/molecular/molecules/building_block/test_get_core_atom_ids.py

@@ -1,19 +1,16 @@
 import itertools as it
 
+from .case_data import CaseData
 
-def test_get_core_atom_ids(case_data):
+
+def test_get_core_atom_ids(case_data: CaseData) -> None:
     """
     Test :meth:`.BuildingBlock.get_core_atom_ids`.
 
-    Parameters
-    ----------
-    case_data : :class:`.CaseData`
-        A test case. Holds the building block to test and the correct
-        core atom ids.
-
-    Returns
-    -------
-    None : :class:`NoneType`
+    Parameters:
+        case_data:
+            A test case. Holds the building block to test and the correct
+            core atom ids.
 
     """