docs: top-level code environment

.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:
@@ -112,6 +114,8 @@ WebAssembly
 emscripten
 wasi
 wasm
+pdb
+rlcompleter
 
 
 # institutions:
@@ -205,4 +209,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/entry_point.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/sub_module.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/test_entry_point.sh

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

4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/__main__.py

@@ -0,0 +1,5 @@
+from foo.bar import barring
+
+print("I am the foo packages's CLI.")
+print("Calling the bar module's barring to things started :).")
+barring()

4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/bar.py

@@ -0,0 +1,3 @@
+def barring():
+    print("In bar module")
+    return 0

4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/test_package_main.sh

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

Dockerfile

@@ -1,12 +1,12 @@
-FROM mcr.microsoft.com/devcontainers/python:3.11
+FROM mcr.microsoft.com/devcontainers/python:3
 
 WORKDIR /python
 
 COPY . .
 
 RUN apt-get update \
     && apt-get install aspell -y
-    
+
 RUN python -m pip install -r requirements.txt
 
 RUN adduser -u 5678 --disabled-password --gecos "" python && chown -R python /python

README.md

@@ -12,13 +12,13 @@
   - Python's design, implementation and ecosystem.
 
 ## Language Details
-- [Language Reference](https://docs.python.org/3.11/reference/index.html#reference*index)
+- [Language Reference](https://docs.python.org/3/reference/index.html)
 - [Interpreter](https://github.com/python/cpython)
   - [Bennett, J. 2019. See CPython run: Getting to know your Python interpreter. North Bay Python](https://www.youtube.com/watch?v=tzYhv61piNY)
 - [Modules Index](https://docs.python.org/3/py-modindex.html)
 - Memory Model:
   - [Computational Complexity Cost Model](https://ocw.mit.edu/courses/6-006-introduction-to-algorithms-fall-2011/pages/readings/python-cost-model/)
-- [Standard Library](https://docs.python.org/3.11/library/index.html)
+- [Standard Library](https://docs.python.org/3/library/index.html)
 - [Packaging and Distribution](https://packaging.python.org/en/latest/)
   - [Package Index](https://pypi.org)
   - [Python Packaging Authority](https://www.pypa.io/en/latest/)
@@ -29,10 +29,10 @@
     - [pipenv](https://pipenv.pypa.io/en/latest/)
   - Structuring Projects
     - ...
-- [Extending and Embedding](https://docs.python.org/3.11/extending/index.html)
+- [Extending and Embedding](https://docs.python.org/3/extending/index.html)
   - [PEP Index](https://www.python.org/dev/peps/)
 - [Developer Contribution Guide](https://devguide.python.org/)
-- [Glossary](https://docs.python.org/3.11/glossary.html)
+- [Glossary](https://docs.python.org/3/glossary.html)
 - [History](https://docs.python.org/3/license.html)
 
 ## Community