adding sentinel metaclass example

15-more-types/cafeteria/cafeteria.py

@@ -0,0 +1,95 @@
+from typing import TypeVar, Generic
+
+
+class Beverage:
+    """Any beverage."""
+
+
+class Juice(Beverage):
+    """Any fruit juice."""
+
+
+class OrangeJuice(Juice):
+    """Delicious juice from Brazilian oranges."""
+
+
+T_co = TypeVar('T_co', covariant=True)
+
+
+class BeverageDispenser(Generic[T_co]):
+    def __init__(self, beverage: T_co) -> None:
+        self.beverage = beverage
+
+    def dispense(self) -> T_co:
+        return self.beverage
+
+
+class Garbage:
+    """Any garbage."""
+
+
+class Biodegradable(Garbage):
+    """Biodegradable garbage."""
+
+
+class Compostable(Biodegradable):
+    """Compostable garbage."""
+
+
+T_contra = TypeVar('T_contra', contravariant=True)
+
+
+class TrashCan(Generic[T_contra]):
+    def put(self, trash: T_contra) -> None:
+        """Store trash until dumped."""
+
+
+class Cafeteria:
+    def __init__(
+        self,
+        dispenser: BeverageDispenser[Juice],
+        trash_can: TrashCan[Biodegradable],
+    ):
+        """Initialize..."""
+
+
+################################################ exact types
+
+juice_dispenser = BeverageDispenser(Juice())
+bio_can: TrashCan[Biodegradable] = TrashCan()
+
+arnold_hall = Cafeteria(juice_dispenser, bio_can)
+
+
+################################################ covariant dispenser
+
+orange_juice_dispenser = BeverageDispenser(OrangeJuice())
+
+arnold_hall = Cafeteria(orange_juice_dispenser, bio_can)
+
+
+################################################ non-covariant dispenser
+
+beverage_dispenser = BeverageDispenser(Beverage())
+
+## Argument 1 to "Cafeteria" has
+## incompatible type "BeverageDispenser[Beverage]"
+##          expected "BeverageDispenser[Juice]"
+# arnold_hall = Cafeteria(beverage_dispenser, bio_can)
+
+
+################################################ contravariant trash
+
+trash_can: TrashCan[Garbage] = TrashCan()
+
+arnold_hall = Cafeteria(juice_dispenser, trash_can)
+
+
+################################################ non-contravariant trash
+
+compost_can: TrashCan[Compostable] = TrashCan()
+
+## Argument 2 to "Cafeteria" has
+## incompatible type "TrashCan[Compostable]"
+##          expected "TrashCan[Biodegradable]"
+# arnold_hall = Cafeteria(juice_dispenser, compost_can)

15-more-types/cafeteria/contravariant.py

@@ -0,0 +1,45 @@
+# tag::TRASH_TYPES[]
+from typing import TypeVar, Generic
+
+class Refuse:  # <1>
+    """Any refuse."""
+
+class Biodegradable(Refuse):
+    """Biodegradable refuse."""
+
+class Compostable(Biodegradable):
+    """Compostable refuse."""
+
+T_contra = TypeVar('T_contra', contravariant=True)  # <2>
+
+class TrashCan(Generic[T_contra]):  # <3>
+    def put(self, refuse: T_contra) -> None:
+        """Store trash until dumped."""
+
+def deploy(trash_can: TrashCan[Biodegradable]):
+    """Deploy a trash can for biodegradable refuse."""
+# end::TRASH_TYPES[]
+
+
+################################################ contravariant trash can
+
+
+# tag::DEPLOY_TRASH_CANS[]
+bio_can: TrashCan[Biodegradable] = TrashCan()
+deploy(bio_can)
+
+trash_can: TrashCan[Refuse] = TrashCan()
+deploy(trash_can)
+# end::DEPLOY_TRASH_CANS[]
+
+
+################################################ more specific trash can
+
+# tag::DEPLOY_NOT_VALID[]
+compost_can: TrashCan[Compostable] = TrashCan()
+deploy(compost_can)
+# end::DEPLOY_NOT_VALID[]
+
+## Argument 1 to "deploy" has
+## incompatible type "TrashCan[Compostable]"
+##          expected "TrashCan[Biodegradable]"

15-more-types/cafeteria/covariant.py

@@ -0,0 +1,48 @@
+from typing import TypeVar, Generic
+
+
+class Beverage:
+    """Any beverage."""
+
+
+class Juice(Beverage):
+    """Any fruit juice."""
+
+
+class OrangeJuice(Juice):
+    """Delicious juice from Brazilian oranges."""
+
+
+# tag::BEVERAGE_TYPES[]
+T_co = TypeVar('T_co', covariant=True)  # <1>
+
+
+class BeverageDispenser(Generic[T_co]):  # <2>
+    def __init__(self, beverage: T_co) -> None:
+        self.beverage = beverage
+
+    def dispense(self) -> T_co:
+        return self.beverage
+
+def install(dispenser: BeverageDispenser[Juice]) -> None:  # <3>
+    """Install a fruit juice dispenser."""
+# end::BEVERAGE_TYPES[]
+
+################################################ covariant dispenser
+
+# tag::INSTALL_JUICE_DISPENSERS[]
+juice_dispenser = BeverageDispenser(Juice())
+install(juice_dispenser)
+
+orange_juice_dispenser = BeverageDispenser(OrangeJuice())
+install(orange_juice_dispenser)
+# end::INSTALL_JUICE_DISPENSERS[]
+
+################################################ not a juice dispenser
+
+beverage_dispenser = BeverageDispenser(Beverage())
+
+## Argument 1 to "install" has
+## incompatible type "BeverageDispenser[Beverage]"
+##          expected "BeverageDispenser[Juice]"
+install(beverage_dispenser)

15-more-types/cafeteria/invariant.py

@@ -0,0 +1,54 @@
+# tag::BEVERAGE_TYPES[]
+from typing import TypeVar, Generic
+
+class Beverage:  # <1>
+    """Any beverage."""
+
+class Juice(Beverage):
+    """Any fruit juice."""
+
+class OrangeJuice(Juice):
+    """Delicious juice from Brazilian oranges."""
+
+T = TypeVar('T')  # <2>
+
+class BeverageDispenser(Generic[T]):  # <3>
+    """A dispenser parameterized on the beverage type."""
+    def __init__(self, beverage: T) -> None:
+        self.beverage = beverage
+
+    def dispense(self) -> T:
+        return self.beverage
+
+def install(dispenser: BeverageDispenser[Juice]) -> None:  # <4>
+    """Install a fruit juice dispenser."""
+# end::BEVERAGE_TYPES[]
+
+################################################ exact type
+
+# tag::INSTALL_JUICE_DISPENSER[]
+juice_dispenser = BeverageDispenser(Juice())
+install(juice_dispenser)
+# end::INSTALL_JUICE_DISPENSER[]
+
+
+################################################ variant dispenser
+
+# tag::INSTALL_BEVERAGE_DISPENSER[]
+beverage_dispenser = BeverageDispenser(Beverage())
+install(beverage_dispenser)
+## Argument 1 to "install" has
+## incompatible type "BeverageDispenser[Beverage]"
+##          expected "BeverageDispenser[Juice]"
+# end::INSTALL_BEVERAGE_DISPENSER[]
+
+
+################################################ variant dispenser
+
+# tag::INSTALL_ORANGE_JUICE_DISPENSER[]
+orange_juice_dispenser = BeverageDispenser(OrangeJuice())
+install(orange_juice_dispenser)
+# end::INSTALL_ORANGE_JUICE_DISPENSER[]
+## Argument 1 to "install" has
+## incompatible type "BeverageDispenser[OrangeJuice]"
+##          expected "BeverageDispenser[Juice]"