Merge pull request #12 from praisetompane/container_abcs

docs: abstract base classes and container abstract base classes

Author: praisetompane

.spellcheck_exceptions_dictionary.txt

@@ -52,7 +52,11 @@ userspace
 userguide
 sdist
 exe
-
+hashable
+checksubclass
+issubclasshook
+issubclass
+metaclass
 
 # python keywords
 pprint

…ary/29_python_runtime_services/0_def.txt …e_services/0_python_runtime_services.txt2_standard_library/29_python_runtime_services/0_def.txt renamed to 2_standard_library/29_python_runtime_services/0_python_runtime_services.txt 2_standard_library/29_python_runtime_services/0_def.txt renamed to 2_standard_library/29_python_runtime_services/0_python_runtime_services.txt

@@ -15,4 +15,5 @@ def python_runtime_services:
 
     - proof: ???
 
-References: ???
+References:
+    The Python Standard Library. Python Runtime Services. 2025. https://docs.python.org/3/library/python.html

2_standard_library/29_python_runtime_services/9_abcs.txt

@@ -0,0 +1,27 @@
+def abcs:
+    - formal: ???
+
+        - in words: ???
+
+    - plain english: ???
+
+    - intuition: ???
+
+    - properties:
+        - specification: 
+            - https://peps.python.org/pep-3119/
+            - https://docs.python.org/3/library/abc.html#module-abc
+
+        - implementation: https://github.com/python/cpython/blob/3.13/Lib/abc.py
+        
+
+    - examples: ???
+
+    - use cases:
+        - register a third-party class as a subclass of our own abstract class(i.e. metaclass)
+            this enables using the third-party class in polymorphic code as a subclass.
+        
+    - proof: ???
+    
+References:
+    The Python Standard Library. Python Runtime Services. 2025. https://docs.python.org/3/library/python.html

2_standard_library/4_built_in_types/5_iterator_types/1_iterator.txt

@@ -26,5 +26,5 @@ def iterator:
   - proof: None. It is a definition.
 
 References:
-  https://docs.python.org/3.11/glossary.html#term-iterator
+  The Python Standard Library. 2025. https://docs.python.org/3/glossary.html#term-iterator
 

2_standard_library/4_built_in_types/5_iterator_types/2_generator.txt

@@ -21,6 +21,6 @@ def generator | generator function:
   - proof: None. It is a definition.
 
 References:
-  https://docs.python.org/3.11/glossary.html#term-generator
+  The Python Standard Library. 2025. https://docs.python.org/3/glossary.html#term-generator
 
 

2_standard_library/4_built_in_types/5_iterator_types/3_generator_expression.txt

@@ -19,5 +19,5 @@
   - proof: None. It is a definition.
 
 References:
-  https://docs.python.org/3.11/glossary.html#term-generator-iterator
+  The Python Standard Library. 2025. https://docs.python.org/3/glossary.html#term-generator-iterator
 

2_standard_library/8_data_types/5_collections_abstract_base_classes/0_collections_abcs.txt

@@ -0,0 +1,27 @@
+def collections_abcs:
+    - formal: ???
+
+        - in words: ???
+
+    - plain english: ???
+
+    - intuition: ???
+
+    - properties:
+        - implementation: https://github.com/python/cpython/tree/3.11/Lib/_collections_abc.py
+        - specification: https://docs.python.org/3/library/collections.abc.html
+    - examples: 
+        - test interface compliance:
+            - hashable
+            - iterable
+            - mapping
+            - ...
+
+    - use cases:
+        - implement custom classes that satisfy the container API.
+        - test compliance to a collections' interface using `issubclass` or `isinstance`.
+        
+    - proof: ???
+    
+References: 
+    The Python Standard Library. 2025. collections.abc — Abstract Base Classes for Containers, Data Types. https://docs.python.org/3/library/collections.abc.html

4_experiments/2_standard_library/29_python_runtime_services/9_abcs/1_abc_meta/app.py

@@ -0,0 +1,20 @@
+from workers.worker import Worker
+from thirdparty.third_party_class import ThirdPartyWorker
+from interfaces.s_one import SOneContract
+from interfaces.s_two import STwoContract
+
+if __name__ == "__main__":
+
+    """
+        This is the registration of the third party to enable our system to treat it as a subclass of SOneContract".
+        This makes ThirdPartyWorker a virtual subclass of SOneContract
+    """
+    SOneContract.register(ThirdPartyWorker)
+
+    workers = [Worker(), ThirdPartyWorker()]
+
+    for worker in workers:
+        if(isinstance(worker, SOneContract)):
+            worker.do_work()
+        if(isinstance(worker, STwoContract)):
+            worker.s_two_work()

4_experiments/2_standard_library/29_python_runtime_services/9_abcs/1_abc_meta/interfaces/__init__.py

@@ -0,0 +1,22 @@
+from abc import ABCMeta, abstractmethod
+
+class SOneContract(metaclass = ABCMeta):
+    
+    @abstractmethod
+    def do_work(self):
+        raise NotImplemented
+
+    """    
+        # NB: @abstractmethod only applies to subclasses created using regular inheritance.
+              virtual sub classes can be instantiated without implementing it, while regular subclasses cannot.
+    @abstractmethod
+    def s_one_specialty(self):
+        raise NotImplemented
+    """
+
+    def __issubclasshook__(cls):
+        """
+            NB: Alternativeltm we overload the behvaiour of `issubclass` function for SOneContract
+                    and define what it means to be a SOneContract.
+        """
+        pass