From 5825888410a17662f8c542550e6a4cf8623e1be9 Mon Sep 17 00:00:00 2001 From: Praise Tompane Date: Tue, 18 Mar 2025 00:53:02 +0200 Subject: [PATCH] docs: top-level code environment definition and use cases. --- .gitignore | 3 +- .spellcheck_exceptions_dictionary.txt | 6 ++- .../29_python_runtime_services/0_def.txt | 18 ++++++++ .../29_python_runtime_services/5___main__.txt | 44 +++++++++++++++++++ .../1_top_level_environment_name/bar.py | 12 +++++ .../1_top_level_environment_name/foo.py | 13 ++++++ .../__init__.py | 0 .../entry_point.py | 7 +++ .../sub_module.py | 6 +++ .../test_entry_point.sh | 3 ++ .../2_package_entry_point/foo/__init__.py | 0 .../2_package_entry_point/foo/__main__.py | 5 +++ .../2_package_entry_point/foo/bar.py | 3 ++ .../test_package_main.sh | 3 ++ .../top_level_environment_name.py | 12 ----- .../top_level_environment_name_sub_routine.py | 11 ----- Dockerfile | 4 +- README.md | 8 ++-- 18 files changed, 127 insertions(+), 31 deletions(-) create mode 100644 2_standard_library/29_python_runtime_services/0_def.txt create mode 100644 2_standard_library/29_python_runtime_services/5___main__.txt create mode 100755 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 create mode 100755 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 create mode 100644 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 create mode 100644 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 create mode 100644 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 create mode 100755 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 create mode 100644 4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/__init__.py create mode 100644 4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/__main__.py create mode 100644 4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/bar.py create mode 100755 4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/test_package_main.sh delete mode 100644 4_experiments/2_standard_library/29_python_runtime_services/top_level_environment_name.py delete mode 100644 4_experiments/2_standard_library/29_python_runtime_services/top_level_environment_name_sub_routine.py diff --git a/.gitignore b/.gitignore index d9df404..be35ab2 100644 --- a/.gitignore +++ b/.gitignore @@ -163,4 +163,5 @@ cython_debug/ .vscode ecosystem/ -scratch_pad.py \ No newline at end of file +scratch_pad.py +journal diff --git a/.spellcheck_exceptions_dictionary.txt b/.spellcheck_exceptions_dictionary.txt index 80a4518..7e2e202 100644 --- a/.spellcheck_exceptions_dictionary.txt +++ b/.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 \ No newline at end of file +PyTypeObject diff --git a/2_standard_library/29_python_runtime_services/0_def.txt b/2_standard_library/29_python_runtime_services/0_def.txt new file mode 100644 index 0000000..23cb54f --- /dev/null +++ b/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: ??? diff --git a/2_standard_library/29_python_runtime_services/5___main__.txt b/2_standard_library/29_python_runtime_services/5___main__.txt new file mode 100644 index 0000000..1f57394 --- /dev/null +++ b/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# \ No newline at end of file diff --git a/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 b/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 new file mode 100755 index 0000000..b14862b --- /dev/null +++ b/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() diff --git a/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 b/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 new file mode 100755 index 0000000..3de3b10 --- /dev/null +++ b/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() diff --git a/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 b/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 new file mode 100644 index 0000000..e69de29 diff --git a/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 b/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 new file mode 100644 index 0000000..15649f3 --- /dev/null +++ b/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() diff --git a/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 b/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 new file mode 100644 index 0000000..0272625 --- /dev/null +++ b/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}") diff --git a/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 b/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 new file mode 100755 index 0000000..a5077a2 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/__init__.py b/4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/__main__.py b/4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/__main__.py new file mode 100644 index 0000000..3c64a2e --- /dev/null +++ b/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() diff --git a/4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/bar.py b/4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/foo/bar.py new file mode 100644 index 0000000..42d65f5 --- /dev/null +++ b/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 diff --git a/4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/test_package_main.sh b/4_experiments/2_standard_library/29_python_runtime_services/5_top_level_code_environment/2_package_entry_point/test_package_main.sh new file mode 100755 index 0000000..3dd6a08 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/4_experiments/2_standard_library/29_python_runtime_services/top_level_environment_name.py b/4_experiments/2_standard_library/29_python_runtime_services/top_level_environment_name.py deleted file mode 100644 index 9b7e294..0000000 --- a/4_experiments/2_standard_library/29_python_runtime_services/top_level_environment_name.py +++ /dev/null @@ -1,12 +0,0 @@ -""" -top level code is also called the entry-point. -""" - - -def foo(): - print("In foo") - print(f"{__name__ = }") - - -if __name__ == "__main__": - foo() diff --git a/4_experiments/2_standard_library/29_python_runtime_services/top_level_environment_name_sub_routine.py b/4_experiments/2_standard_library/29_python_runtime_services/top_level_environment_name_sub_routine.py deleted file mode 100644 index 8ec6e98..0000000 --- a/4_experiments/2_standard_library/29_python_runtime_services/top_level_environment_name_sub_routine.py +++ /dev/null @@ -1,11 +0,0 @@ -from top_level_environment_name import foo - - -def bar(): - print("In bar") - print(f"{__name__ = }") - foo() - - -if __name__ == "__main__": - bar() diff --git a/Dockerfile b/Dockerfile index a112e22..3759ba5 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,4 +1,4 @@ -FROM mcr.microsoft.com/devcontainers/python:3.11 +FROM mcr.microsoft.com/devcontainers/python:3 WORKDIR /python @@ -6,7 +6,7 @@ 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 diff --git a/README.md b/README.md index 1d6a90b..72318cd 100644 --- a/README.md +++ b/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