Example of robust, flexible, and extensible model composition using dependency injection via protocols and immutability

[markcampanelli]

In the discussion of #2625, the benefits of dependency injection and immutability after validated construction were both discussed in terms of making the composition of models less fragile, easier to maintain and extend, and safer to use. So, here is an example of that.

@ramaroesilva I encourage you to add a Rectangle class that implements CylinderBase and that is constructed from length and width parameters. You should not have to touch the Cylinder class at all in order to use this new "component model" (!), because it meets the CylinderBase protocol. Bonus points for a refactor of the existing Square class to use the new Rectangle class. I'm happy to provide support and further discussion.

"""
Example of using dependency injection for model composition using Python protocols.
"""

import math
from typing import Protocol


class CyinderBase(Protocol):
    """Interface for the base shape of a cylindrical volume."""

    def area(self) -> float:
        """Compute the base shape's area."""
        ...  # Method that must be implemented


class Circle:
    """
    One example of a component model that "plugs in" to a composite model.

    Implements CyinderBase protocol. Note validation and immutability.
    """

    def __init__(self, *, radius: float) -> None:
        # Validation on initialization.
        if radius <= 0:
            raise ValueError(f"radius {radius} is not positive")

        self._radius = radius

    @property
    def radius(self) -> float:
        """Return the circle's radius."""

        return self._radius

    @property
    def area(self) -> float:
        """Compute the base shape's area (a CyinderBase protocol method)."""

        return math.pi * self._radius**2


class Square:
    """
    Another example of a component model that "plugs in" to a composite model.

    Implements CyinderBase protocol. Note validation and immutability.
    """

    def __init__(self, *, side: float) -> None:
        # Validation on initialization.
        if side <= 0:
            raise ValueError(f"side {side} is not positive")

        self._side = side

    @property
    def side(self) -> float:
        """Return the square's side."""

        return self._side

    @property
    def area(self) -> float:
        """Compute the base shape's area (a CyinderBase protocol method)."""

        return self.side**2


class Cylinder:
    """An example of a composite model that uses a protocol-compliant component."""

    def __init__(self, *, base: CyinderBase, height: float) -> None:
        self._base = base

        # Validation on initialization.
        if height <= 0:
            raise ValueError(f"height {height} is not positive")

        self._height = height

    @property
    def base(self) -> CyinderBase:
        """Return the base object, which is immutable."""

        return self._base

    @property
    def height(self) -> float:
        """Return the cyliner height"""

        return self._height

    @property
    def volume(self) -> float:
        """Compute the cyliner's volume."""

        return self.base.area * self.height


if __name__ == "__main__":

    # Dependency injection when constructing cylinder model.
    circle = Circle(radius=24)
    circular_cylinder = Cylinder(base=circle, height=42)
    circular_cylinder_volume = circular_cylinder.volume
    print(f"circular cylinder volume: {circular_cylinder_volume}")

    square = Square(side=24)
    square_cylinder = Cylinder(base=square, height=42)
    square_cylinder_volume = square_cylinder.volume
    print(f"square cylinder volume: {square_cylinder_volume}")

    # Immutability is enforced. This raises an AttributeError.
    square_cylinder.base = circle

[markcampanelli]

The example above is simple to emphasize the root concepts. To prove this approach's viability in pvlib-python, the next iteration here would be to demonstrate how to handle component-model computational method calls that each take a different, but possibly overlapping, set of inputs that may change between calls (in addition to the immutable model-configuration parameters defined at initialization). The above example is probably not great for that, so I will attempt to code this up for the motivating use case of pvlib.pvsystem.PVSystem.get_cell_temperature. I intuit that there is not one best solution here, so I will try to present at least one that's quite satisfactory.