From 0fbc8f5e4a705b8029904a8730507e46f6620722 Mon Sep 17 00:00:00 2001
From: Praise Tompane <praisetompane@icloud.com>
Date: Thu, 20 Mar 2025 19:40:11 +0200
Subject: [PATCH] docs: type annotations

---
 .spellcheck_exceptions_dictionary.txt         |   5 ++-
 .../3_datamodel/{def.txt => 0_def.txt}        |   0
 .../1_objects_values_and_types/def.txt        |   2 ++
 2_standard_library/0_def.txt                  |  19 +++++++++++-
 2_standard_library/4_built_in_types/0_def.xt  |  20 ++++++++++++
 .../1_type_annotation_types.txt               |  26 ++++++++++++++++
 .../1_generic_alias_type/1_generic_alias.py   |  12 ++++++++
 .../1_generic_alias_type/2_functions.py       |  29 ++++++++++++++++++
 .../1_generic_alias_type/3_classes.py         |  19 ++++++++++++
 .../4_subscriptable_generic_alias.py          |  25 +++++++++++++++
 .../2_union_type/1_union_type.py              |  17 ++++++++++
 dictionary.dic                                | Bin 6272 -> 6592 bytes
 12 files changed, 172 insertions(+), 2 deletions(-)
 rename 1_core_language/3_datamodel/{def.txt => 0_def.txt} (100%)
 create mode 100644 2_standard_library/4_built_in_types/0_def.xt
 create mode 100644 2_standard_library/4_built_in_types/13_type_annotation_types/1_type_annotation_types.txt
 create mode 100644 4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/1_generic_alias.py
 create mode 100644 4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/2_functions.py
 create mode 100644 4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/3_classes.py
 create mode 100644 4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/4_subscriptable_generic_alias.py
 create mode 100644 4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/2_union_type/1_union_type.py

diff --git a/.spellcheck_exceptions_dictionary.txt b/.spellcheck_exceptions_dictionary.txt
index 7e2e202..8afb3f4 100644
--- a/.spellcheck_exceptions_dictionary.txt
+++ b/.spellcheck_exceptions_dictionary.txt
@@ -73,7 +73,10 @@ iterable
 init
 metaclasses
 hasattr
-
+GenericAlias
+classinfo
+isinstance
+issubclass
 
 # technology:
 FastAPI
diff --git a/1_core_language/3_datamodel/def.txt b/1_core_language/3_datamodel/0_def.txt
similarity index 100%
rename from 1_core_language/3_datamodel/def.txt
rename to 1_core_language/3_datamodel/0_def.txt
diff --git a/1_core_language/3_datamodel/1_objects_values_and_types/def.txt b/1_core_language/3_datamodel/1_objects_values_and_types/def.txt
index a851227..2c73023 100644
--- a/1_core_language/3_datamodel/1_objects_values_and_types/def.txt
+++ b/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
\ No newline at end of file
diff --git a/2_standard_library/0_def.txt b/2_standard_library/0_def.txt
index 9a05760..018a5f9 100644
--- a/2_standard_library/0_def.txt
+++ b/2_standard_library/0_def.txt
@@ -1,2 +1,19 @@
 def python standard library:
-    
\ No newline at end of file
+    - formal: ???
+
+        - in words: ???
+
+    - plain english: ???
+
+    - intuition: ???
+
+    - properties: ???
+    
+    - examples: ???
+
+    - use cases: ???
+        
+    - proof: ???
+    
+References: ???
+
diff --git a/2_standard_library/4_built_in_types/0_def.xt b/2_standard_library/4_built_in_types/0_def.xt
new file mode 100644
index 0000000..1b11ee5
--- /dev/null
+++ b/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: ???
+
diff --git a/2_standard_library/4_built_in_types/13_type_annotation_types/1_type_annotation_types.txt b/2_standard_library/4_built_in_types/13_type_annotation_types/1_type_annotation_types.txt
new file mode 100644
index 0000000..dae832e
--- /dev/null
+++ b/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
diff --git a/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/1_generic_alias.py b/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/1_generic_alias.py
new file mode 100644
index 0000000..a4c9668
--- /dev/null
+++ b/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
diff --git a/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/2_functions.py b/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/2_functions.py
new file mode 100644
index 0000000..2acc7fc
--- /dev/null
+++ b/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))
diff --git a/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/3_classes.py b/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/3_classes.py
new file mode 100644
index 0000000..8a398f7
--- /dev/null
+++ b/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)
diff --git a/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/4_subscriptable_generic_alias.py b/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/1_generic_alias_type/4_subscriptable_generic_alias.py
new file mode 100644
index 0000000..0223d63
--- /dev/null
+++ b/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))
diff --git a/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/2_union_type/1_union_type.py b/4_experiments/2_standard_library/4_built_in_types/13_type_annotation_types/2_union_type/1_union_type.py
new file mode 100644
index 0000000..d3cbd41
--- /dev/null
+++ b/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))
diff --git a/dictionary.dic b/dictionary.dic
index f497c1b7e660105ac92eb6621754d41edd20cc61..66e5003119188cd430e74439591d652773c582f3 100644
GIT binary patch
delta 3383
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
Xv8QM%T4D80;NUg0l;GM>h&uLviLx}p

delta 3088
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