docs: type annotations

.spellcheck_exceptions_dictionary.txt

@@ -73,7 +73,10 @@ iterable
 init
 metaclasses
 hasattr
-
+GenericAlias
+classinfo
+isinstance
+issubclass
 
 # technology:
 FastAPI

1_core_language/3_datamodel/1_objects_values_and_types/def.txt

@@ -21,6 +21,8 @@ def data model:
     C/Python API for defining types: https://docs.python.org/3.11/c-api/typeobj.html#c.PyTypeObject.tp_iter
         - key structures:
             - PyTypeObject
+
+    - The Python Type System: https://typing.python.org/en/latest/spec/index.html
 
 References:
     Python Software Foundation. 2023. Objects, values and types. https://docs.python.org/3.12/reference/datamodel.html#objects-values-and-types

2_standard_library/0_def.txt

@@ -1,2 +1,19 @@
 def python standard library:
-
+    - formal: ???
+
+        - in words: ???
+
+    - plain english: ???
+
+    - intuition: ???
+
+    - properties: ???
+
+    - examples: ???
+
+    - use cases: ???
+
+    - proof: ???
+
+References: ???
+

2_standard_library/4_built_in_types/0_def.xt

@@ -0,0 +1,20 @@
+def built-in types:
+    - formal: ???
+
+        - in words: ???
+
+    - plain english: ???
+
+    - intuition: ???
+
+    - properties:
+        - all built-in type names in the STL https://docs.python.org/3/library/types.html#module-types
+
+    - examples: ???
+
+    - use cases: ???
+
+    - proof: ???
+
+References: ???
+

2_standard_library/4_built_in_types/13_type_annotation_types/1_type_annotation_types.txt

@@ -0,0 +1,26 @@
+def type_annotation_types
+    - formal: ???
+
+        - in words: core built-in types used for type annotations
+
+    - plain english: ???
+
+    - intuition: ???
+
+    - properties:
+        - members:
+            - Generic Alias Type
+                - class: types.GenericAlias
+                - properties:
+                    - not accepted as the 2nd parameter of `isinstance(object, classinfo)` or `issubclass(class, classinfo)`
+            - Union Type
+
+    - examples: ???
+
+    - use cases:
+        - function type annotations
+        - class type annotations
+    - proof: ???
+
+References:
+    - The Python Standard Library. 2025. Type Annotation Types. https://docs.python.org/3/library/stdtypes.html#type-annotation-types-generic-alias-union

4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/1_generic_alias.py

@@ -0,0 +1,12 @@
+from types import GenericAlias
+
+print("Creating GenericAlias by subscripting a generic type")
+subscription_generic_alias_creation = list[int]
+print(f"{subscription_generic_alias_creation=}\n")
+
+print("Creating GenericAlias directly")
+direct_generic_alias_creation = GenericAlias(list, (int))
+print(f"{direct_generic_alias_creation=}\n")
+
+
+assert subscription_generic_alias_creation == direct_generic_alias_creation

4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/2_functions.py

@@ -0,0 +1,29 @@
+from collections.abc import Sequence
+from typing import TypeVar
+
+
+def generic_function_type_parameter[T](values: Sequence[T]):
+    return values[0]
+
+
+def generic_function_bound_type_parameter[T: int](values: Sequence[T]):
+    return values[3]
+
+
+TypeVariable = TypeVar("TypeVariable")
+def independently_defined_type_variable(values: Sequence[TypeVariable]):
+    return values[1]
+
+
+BoundTypeVariable = TypeVar("BoundTypeVariable", bound=float)
+def independently_defined_and_bound_type_variable(values: Sequence[BoundTypeVariable]):
+    return values[2]
+
+
+if __name__ == "__main__":
+    values = [2, 4, 6, 8]
+    print(generic_function_type_parameter(values))
+    print(independently_defined_type_variable(values))
+    float_values = [2.0, 2.1, 4.5, 5.6]
+    print(independently_defined_and_bound_type_variable(float_values))
+    print(generic_function_bound_type_parameter(values))

4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/3_classes.py

@@ -0,0 +1,19 @@
+class IntToIntOrStringDictionary[int, T: (int | str)]:
+
+    def __init__(self,) -> None:
+        self.values: dict[int, T] = {}
+
+    def add(self, key: int, value: T):
+        self.values[key] = value
+
+    def __repr__(self):
+        return ",".join(f"{k}:{v}" for k, v in self.values.items())
+
+
+if __name__ == "__main__":
+    v = IntToIntOrStringDictionary()
+    v.add(1, "a")
+    v.add(2, 1)
+    print((type(v)))
+    print((type(v.values)))
+    print(v)

4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/4_subscriptable_generic_alias.py

@@ -0,0 +1,25 @@
+from typing import TypeVar
+
+"""
+dict[int][int] fails, because dict[int] returns a GenericAlias, which is not subscriptable.
+"""
+try:
+    a = dict[int][int]
+    print(type(a))
+except TypeError as e:
+    print("Expected Error")
+    print(f"{e} \n")
+
+
+print("subscriptable if TypeVar is used to create the Type Variable\n")
+print("Notice the second type parameter is ~T")
+T = TypeVar("T")
+d = dict[int, T]
+
+print(d)
+
+print("Subscripting `d`` to create dict[int, str]\n")
+dict_int_to_str = d[str]
+
+print(dict_int_to_str)
+print(type(dict_int_to_str))

4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/2_union_type/1_union_type.py

@@ -0,0 +1,17 @@
+from types import UnionType
+from typing import Optional
+# clean syntac for typing.Union
+
+print("Type of int | str")
+print(type(int | str))
+
+
+print("Optional type")
+d = int | None
+print(type(d))
+
+print("Test equivalence to Optional[int]")
+assert d == Optional[int]
+
+
+print(isinstance(d, UnionType))