docs: overview of Python packaging and distribution

.spellcheck_exceptions_dictionary.txt

@@ -10,6 +10,10 @@ UTF
 MYINC
 ASGI
 WSGI
+PAAS
+VHD
+AMI
+FPM
 
 
 # authors
@@ -45,6 +49,10 @@ classname
 dunder
 bitwise
 executionmodel
+userspace
+userguide
+sdist
+exe
 
 
 # python keywords
@@ -65,6 +73,7 @@ init
 
 # technology:
 FastAPI
+flexx
 gunicorn
 JVM
 pyspelling
@@ -81,6 +90,22 @@ sqlalchemy
 libpq
 psycopg
 mako
+pynsist
+snapcraft
+virtualenv
+zipapp
+PEX
+macos
+osnap
+pacman
+kivy
+homebrew
+flatpack
+cx
+conda
+beeware
+gz
+AppImage
 
 
 # institutions:
@@ -95,9 +120,11 @@ runestone
 stackoverflow
 vidhya
 redhat
+Openstack
 
 
 # urls:
+pkgs
 readthedocs
 src
 txt
@@ -157,12 +184,18 @@ makotemplates
 ae
 
 
-# pythons implementations:
+# pythons implementations or runtimes:
 CPython
 IronPython
 jython
 pypy
 pythonnet
+brython
+pyscript
+Pyodide
+MicroPython
+CircuitPython
+
 
 # domain specific - C/Python API
 PyTypeObject

1_implementations/0_def.txt

@@ -1,24 +1,33 @@
-Known implementations (Python Software Foundation, 2023):
-* CPython:	Original and First Python. 
-            Implementations in C.
-            Compiles/Interprets to machine code.
+- known implementations (Python Software Foundation, 2023):
+    - CPython:	Original and First Python. 
+                Implementations in C.
+                Compiles/Interprets to machine code.
 
-* Jython:	Python implementations in Java.
-            Compiles/Interprets to to JVM bytecode
-                runs on the JVM.
-            details: https://www.jython.org/index
+    - Jython:	Python implementations in Java.
+                Compiles/Interprets to to JVM bytecode
+                    runs on the JVM.
+                details: https://www.jython.org/index
 
-* Python for .Net:	CPython running as .NET managed application.
-                    details: https://pythonnet.github.io/
+    - Python for .Net:	CPython running as .NET managed application.
+                        details: https://pythonnet.github.io/
 
-* IronPython:   Python Implementations using .NET framework.
-                Compiles/Interprets to .NET IL(Intermediate Language) and .NET assemblies.
-                runs on .NET DLR(Dynamic Language Runtime)
-                details
+    - IronPython:   Python Implementations using .NET framework.
+                    Compiles/Interprets to .NET IL(Intermediate Language) and .NET assemblies.
+                    runs on .NET DLR(Dynamic Language Runtime)
+                    details
 
-* PyPy:	Python implementations in Python.
-        details: https://www.pypy.org/
+    - PyPy:	Python implementations in Python.
+            details: https://www.pypy.org/
+
+    - MicroPython
+
+    - Brython: https://github.com/brython-dev/brython
+
+- ports:
+    - Pyodide: https://github.com/pyodide/pyodide
+        - platform:
+            - PyScript: https://github.com/pyscript/pyscript
 
 References:
     Python Software Foundation. 2023. The Python Language Reference. https://docs.python.org/3.11/reference/introduction.html#alternate-implementations.
-
+    PyPA. 2025. Overview of Python Packaging. https://packaging.python.org/en/latest/overview/

packaging_and_distribution/0_module.txt

@@ -0,0 +1,11 @@
+def: module: a collection of code 
+            1 type of module object
+            all modules are of this type
+            independent of technology(e..g python, C, etc)
+
+            has: 
+                name
+
+            on import:
+                whole module code ran, top to bottom and left to right
+                cached in sys.modules

packaging_and_distribution/modules/REAMDE.md → packaging_and_distribution/1_package.txt

@@ -1,15 +1,3 @@
-def: module: a collection of code 
-            1 type of module object
-            all modules are of this type
-            independent of technology(e..g python, C, etc)
-
-            has: 
-                name
-
-            on import:
-                whole module code ran, top to bottom and left to right
-                cached in sys.modules
-
 def: package: special kind of module for organizing other modules
                 has: 
                     __path__ attribute 

packaging_and_distribution/2_packaging_scenarios.txt

@@ -0,0 +1,126 @@
+packaging considerations: target environment + deployment experience 
+    - target audience:
+        - developers
+        - data center operators
+        - non technical end users
+        - ...
+    - runtime environment:
+        - servers
+        - mobile devices
+        - embedded systems
+        - ...
+    - deployment mechanism:
+        - one software install
+        - large deployment batches
+        - ...
+
+
+packaging scenarios:
+    - libraries & tools:
+        - target audience = developers AND runtime environment = development setting.
+        - approaches:
+            - python module: 
+                - properties:
+                    - constraints:
+                        - only depends on the standard library.
+                        - required python installed on runtime environment.
+                - use cases: a single pure python file.
+                - examples: 
+                    - bottle.py
+
+            - python source distributions: 
+                - properties:
+                    - specification: https://packaging.python.org/en/latest/specifications/source-distribution-format/#source-distribution-format
+                    - constraints:   
+                        - required python installed on runtime environment.
+                    - format: compressed zip(*.tar.gz)
+                    - alternative names:
+                        - sdist
+                    - remarks: this is Python's native distribution format.
+                - use cases: 
+                    - a collection of pure python files. 
+
+            - python binary distributions:
+                - properties:
+                    - specification: https://packaging.python.org/en/latest/specifications/binary-distribution-format/#binary-distribution-format
+                    - constraints:   
+                        - required python installed on runtime environment.
+                    - implementation: wheel
+                    - recommendation: default to publishing BOTH wheel and sdist archives.
+                    - remarks:
+                        - pip prefers wheel format for speed, even for source distributions.
+                - use cases: 
+                    - pure python files and compiled dependencies written in(C,C++,FORTRAN, Rust, etc)
+
+    - python applications:
+        - target audience: non-technical end users AND runtime environment = end user machines.
+        - key: selection of tools is reasoned from dependence on the runtime environment.
+        - console scripts(i.e. terminal programs) or plugin extensible apps:
+            - entry points: https://setuptools.pypa.io/en/latest/userguide/entry_point.html
+        - approaches:
+            - depend on a framework: use the framework's/platform's packaging tools and conventions.
+                - examples:
+                    - Platform-as-a-Service(PAAS)
+                    - web browsers:
+                        - https://brython.info
+                    - mobile applications
+                    - cross_platform:
+                        - https://beeware.org
+                        - https://github.com/kivy
+
+            - depend on a preexisting Python installation: use existing Python on the target runtime environment
+                - examples:
+                    - Python Executable (PEX)
+                    - zipapp
+                    - shiv
+
+            - depend on a separate software distribution ecosystem:
+                - python application packages(akin to apt, homebrew, pacman etc.):
+                    - Anaconda
+                        - packaging with Anaconda: https://docs.conda.io/projects/conda-build/en/latest/user-guide/tutorials/index.html
+                        - native Python to Anaconda: https://conda.io/projects/conda-build/en/latest/user-guide/tutorials/build-pkgs-skeleton.html
+
+            - bring your own Python executable:
+                - properties:
+                    - usually involves bundling the interpreter into the executable.
+                - freezing: package Python programs in a format native to the target runtime(e.g. OS)
+                    - tools(i.e. freezers):
+                        - single-user deployment:
+                            - cross_platform:
+                                - py_installer
+                                - cx_freeze
+                                - constructor
+                            - macos:
+                                - py2app
+                            - windows:
+                                - py2exe
+                                - pynsist
+                            - only windows and macos:
+                                - osnap
+                        - multi-user deployment:
+                            - chef omnibus
+
+            - bring your own userspace: Operating-System-Level virtualization or Containerization
+                - tools:
+                    - AppImage
+                    - Docker
+                    - flatpack
+                    - snapcraft
+
+            - bring your own kernel: classical virtualization
+                - tools:
+                    - Vagrant
+                    - Virtual Hard Disk(VHD), Amazon Machine Image(AMI)
+                    - Openstack
+
+            - bring your own hardware: Python programs bundled with the hardware as a deployment unit:
+                - tools:
+                    - MicroPython and CircuitPython for small devices and embedded devices
+                    - Conventional hardware to install in data centers. 
+
+            - other approaches:
+                - operating system packages(i.e. deb, rpm, etc):
+                    - tools: FPM
+                - virtualenv
+References:
+    PyPA. 2025. Overview of Python Packaging. https://packaging.python.org/en/latest/overview/