docs: top-level code environment definition and usecases.

Author: praisetompane

.gitignore

@@ -163,4 +163,5 @@ cython_debug/
 .vscode
 
 ecosystem/
-scratch_pad.py
+scratch_pad.py
+journal

.spellcheck_exceptions_dictionary.txt

@@ -71,6 +71,8 @@ formatspec
 sys
 iterable
 init
+metaclasses
+hasattr
 
 
 # technology:
@@ -205,4 +207,4 @@ CircuitPython
 
 
 # domain specific - C/Python API
-PyTypeObject
+PyTypeObject

2_standard_library/29_python_runtime_services/0_def.txt

@@ -0,0 +1,18 @@
+def python_runtime_services:
+    - formal: ???
+
+        - in words: ???
+
+    - plain english: modules to interact with the Python interpreter and its runtime environment.
+
+    - intuition: ???
+
+    - properties: ???
+
+    - examples: ???
+
+    - use cases: ???
+
+    - proof: ???
+
+References: ???

2_standard_library/29_python_runtime_services/5___main__.txt

@@ -0,0 +1,44 @@
+def __main__"
+    - formal: ???
+
+        - in words:
+            - name for two Python constructs:
+                1. default name of the top-level environment.
+                2. __main__.py in Python packages
+
+    - plain english: 
+        1. default name of the entry-point of a Python program:
+            - akin to Java's: public static void main, C's int main, etc 
+        2. __main__.py in Python packages: entry point for package when ran using `python -m package_name`
+
+
+    - intuition: ???
+
+    - properties:
+
+
+    - examples:
+        see: 4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment
+
+    - use cases:
+        - a module can use it to detect if it is the entry-point of the program, with the idiomatic pattern below:
+            ``` python
+                if __name__ == __main__:
+                    # perform entry-point code
+            ```
+    
+        - access top-level(entry-point) module's namespace
+            - in practices usages:
+                - pdb: https://docs.python.org/3/library/pdb.html#module-pdb
+                - rlcompleter: https://docs.python.org/3/library/rlcompleter.html#module-rlcompleter
+        
+            see: 4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/1_top_level_code/2_top_level_environment_namespace/test_entry_point.sh
+
+        - provide a command line interface to a package.
+            see: 4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/test_package_main.sh
+
+
+    - proof: ???
+
+References: ???
+    Python Software Foundation. 2025.  Python Runtime Services, The Python Standard Library. https://docs.python.org/3/library/__main__.html#

4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/1_top_level_code/1_top_level_environment_name/bar.py

@@ -0,0 +1,12 @@
+from foo import foo
+
+
+def bar():
+    print("In bar function")
+    print(f"top-level code module: {__name__}")
+    foo()
+
+
+if __name__ == "__main__":
+    print("In bar module, as top-level code environment")
+    bar()

4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/1_top_level_code/1_top_level_environment_name/foo.py

@@ -0,0 +1,13 @@
+"""
+top level code is also called the entry-point.
+"""
+
+
+def foo():
+    print("In foo function")
+    print(f"top-level code module: {__name__}")
+
+
+if __name__ == "__main__":
+    print("In foo module, as top-level code environment")
+    foo()

4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/1_top_level_code/2_top_level_environment_namespace/__init__.py

@@ -0,0 +1,7 @@
+from sub_module import print_entry_point_state
+
+variable = None
+
+if __name__ == "__main__":
+    variable = input("Please supply a value: ")
+    print_entry_point_state()

4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/1_top_level_code/2_top_level_environment_namespace/entry_point.py

@@ -0,0 +1,6 @@
+import __main__
+
+
+def print_entry_point_state():
+    print(
+        f"Printing a value set in __main__(i.e. top-level | entry-point) module. Value is {__main__.variable}")

4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/1_top_level_code/2_top_level_environment_namespace/sub_module.py

@@ -0,0 +1,3 @@
+#!sh
+
+python -m entry_point