From 54d77a69b3c021f4a5568f482bb6c122bfbcc002 Mon Sep 17 00:00:00 2001 From: Praise Tompane Date: Mon, 3 Mar 2025 19:51:53 +0200 Subject: [PATCH 1/2] docs: overview of Python packaging --- packaging_and_distribution/0_module.txt | 11 +++ .../{modules/REAMDE.md => 1_package.txt} | 12 ---- .../2_packaging_scenarios.txt | 68 +++++++++++++++++++ packaging_and_distribution/README.md | 18 ----- .../modules/{repl_run.sh => test_combine.sh} | 0 ...troubleshooting.md => troubleshooting.txt} | 0 6 files changed, 79 insertions(+), 30 deletions(-) create mode 100644 packaging_and_distribution/0_module.txt rename packaging_and_distribution/{modules/REAMDE.md => 1_package.txt} (87%) create mode 100644 packaging_and_distribution/2_packaging_scenarios.txt delete mode 100644 packaging_and_distribution/README.md rename packaging_and_distribution/modules/{repl_run.sh => test_combine.sh} (100%) mode change 100644 => 100755 rename packaging_and_distribution/modules/{troubleshooting.md => troubleshooting.txt} (100%) diff --git a/packaging_and_distribution/0_module.txt b/packaging_and_distribution/0_module.txt new file mode 100644 index 0000000..c812123 --- /dev/null +++ b/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 diff --git a/packaging_and_distribution/modules/REAMDE.md b/packaging_and_distribution/1_package.txt similarity index 87% rename from packaging_and_distribution/modules/REAMDE.md rename to packaging_and_distribution/1_package.txt index 80ed158..235bbd6 100644 --- a/packaging_and_distribution/modules/REAMDE.md +++ b/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 diff --git a/packaging_and_distribution/2_packaging_scenarios.txt b/packaging_and_distribution/2_packaging_scenarios.txt new file mode 100644 index 0000000..22ddffd --- /dev/null +++ b/packaging_and_distribution/2_packaging_scenarios.txt @@ -0,0 +1,68 @@ +packaging considerations: target environment + deployment experience + - target audience: + - developers + - datacenter 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. + - approaches: + - + - + - + - + - + - + - + +References: + https://packaging.python.org/en/latest/overview/#packaging-applications \ No newline at end of file diff --git a/packaging_and_distribution/README.md b/packaging_and_distribution/README.md deleted file mode 100644 index 2e4c46f..0000000 --- a/packaging_and_distribution/README.md +++ /dev/null @@ -1,18 +0,0 @@ -def: set of libraries for publishing and installing python software - designed to work with: Python Package Index - can use with: - local index server - no index server - - distutils - build and install addition modules into an existing Python installation - general user will use cross-version tools maintained by Python Packaging Authority - i.e. - setuptools - pip - ensurepip - bootstrap pip installer into an existing Python installation - venv - zip files - set of tools for creating zip files with Python code - executable by the Python interpreter \ No newline at end of file diff --git a/packaging_and_distribution/modules/repl_run.sh b/packaging_and_distribution/modules/test_combine.sh old mode 100644 new mode 100755 similarity index 100% rename from packaging_and_distribution/modules/repl_run.sh rename to packaging_and_distribution/modules/test_combine.sh diff --git a/packaging_and_distribution/modules/troubleshooting.md b/packaging_and_distribution/modules/troubleshooting.txt similarity index 100% rename from packaging_and_distribution/modules/troubleshooting.md rename to packaging_and_distribution/modules/troubleshooting.txt From c0a94789de8c238586d900aebc08f11a3afda004 Mon Sep 17 00:00:00 2001 From: Praise Tompane Date: Tue, 4 Mar 2025 15:42:42 +0200 Subject: [PATCH 2/2] docs: package and deploy user facing python applications --- .spellcheck_exceptions_dictionary.txt | 35 +++++++- 1_implementations/0_def.txt | 43 ++++++---- dictionary.dic | Bin 5216 -> 6272 bytes .../2_packaging_scenarios.txt | 76 +++++++++++++++--- 4 files changed, 127 insertions(+), 27 deletions(-) diff --git a/.spellcheck_exceptions_dictionary.txt b/.spellcheck_exceptions_dictionary.txt index 0da3573..6432d87 100644 --- a/.spellcheck_exceptions_dictionary.txt +++ b/.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 \ No newline at end of file diff --git a/1_implementations/0_def.txt b/1_implementations/0_def.txt index 9fac156..7a0aa54 100644 --- a/1_implementations/0_def.txt +++ b/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. - \ No newline at end of file + PyPA. 2025. Overview of Python Packaging. https://packaging.python.org/en/latest/overview/ \ No newline at end of file diff --git a/dictionary.dic b/dictionary.dic index b3bce5611dd7ed4593a6dcba42831f3512950b2d..f497c1b7e660105ac92eb6621754d41edd20cc61 100644 GIT binary patch literal 6272 zcmai&Ym6J$b%2jZ4#|Cx%iZO!ELpbX*m2U0?Z$BvCk1S4SJHYFau}8zdw1I=?kqXt zj+W$%hQr;Zprk>aq^aA)agtU@>Hv1o0>CXd5A@+ahsO6t43lE&{}8 z^FV(Hh5DVlvyGts=s?sr_jT^M_nv#snRN%D*X?$LV(n zE;0VFlJbp8`X5o!|0X5|6wJ9e@Dr{N0rF=2z1z--%}#zF(q>TK#81BD3S9?C2}5DGX4oA<39se*~C9o z((jLy)L(?_?APbv^^czYI6t-DvJwM2s$||f4Xft-7C6xNYncQ5xDt6Pe}RMhqOw*o z_i3S4m2aAIQ(iH2xQ=c%&;K`QhHx1G6$Ecj=W8Yp*)~$9G9w+4gP=l=nmd0EMMzi!x+pD4KqIUJMTw|T>g+-B&=y~_G=*;Y2H@^M33E*d)WtP(qU z$*>|XD>1BB4KXB(JGWGqBTDqTLy5xo8rpKwuqlp`^S)r%l*gdn+lz(``4hvYTrzaz z+e*&&btUs(QL_KJtg<3yLtA{qnp`lf%M*r8c}}@rlS{C+T#?I4yDtA?*pweBvA3(r zrY*BLZ&oA6ltYjTOGHl8f zCF_~bE0<-#up;*w*5wf;=RP!S%Hzs)N1lS}PhL>sur4WaOfMTY__5MCF8^(~ zB69?c2K#lpp)K!%OfM@+_NAfZ93C;OO4rblN0l7p7nHTS{IwzX($JCDm8|osVO_>? z1kFZ84l9}9ElTFS$FMH8VME%6O*v=i$R9(8!1TOwS>$Vm75R=5!+T9xZO9wSnj=?~ z%sVlmT#|WZb4A{2=*YX3jx9CAnzZ050qR3a?)C30ofY|*t!Cq>=}J{=82drL7qq>ucI9H}L|y-kOr-Fh zxk7r;J}r}J^`OO4+V6E_E{hv=u#Do|nAdLwZNJ|c$c%+k)lTIc0=;gpWjZz+*l2N< zj)P(3g?=c-^a8tEoXz-sKbD*Glxogets&NprPKYk*N5sr8y3xHUKSz7V;w+uD*@YoYECUW#-1VHgK(H}+&ci{I8OW|hZJM?t?niph^u z0qih0m04^)cv@yNlo(eY8xFjvGxXb@l&Hf~7fY5q81-8+rDc{eZ3TnA8%o()Xg0Z9 z#Theb5V|c-W>Z9gVlM5qhf*wN{Md_h-!L^c@gblEgcj(rYYMg$r_#f?r^-7GawwG7 zVeUp(mr1awVEF8Eyy^G1T7z&zPeO-o{Y-vi=yzkkKR}d*kzCPWIzueM4rX&3(cW@r zETRel*ed0g*sFLrz_oG#%HoeI`w9Ea@A0h$Ww zj_1o%S|ed`DtmTsFDFw(L=Jb$-yR{PLjKC(zV~5U3j{;Xv(xIL2Pdb-I6HoB=(o1m z_9$l8wMQ}4>9P;pSdv4muEk}=sCu3hGlWm#X91pcq>$o1TP5qg!DioQ5fyX4XY!q4 z-){v`Uk;@!dXdJgR?u&|+~@3B?b?<%PtfoSmvFSaSAU&jn9dN5nPDb(V*g@fh|5?~ zDRV+OV^tb986lhgVC44(TpbqHFy=QqjtT+3qwfu*lu{3qO|^E_V|C8sNQ`k5Gp!Z} zSxRddx2CfX4&&JEaJwioU@oiX)*8r-`HE9-R2;l{@rFVt2-;!fwqn19?5PYfUysV_ z`WxXnHc>U4(Ele>M2$=_vr|30$VpX6_N|#Lg`vHOrfQ&irN%H&zvXtjBUVHuF&@*V z((56=kXEOKly2|DkW;K`^JKc)<6foIMy4}8cPo&CS-a9O`!zRV`>iP0-?Ox>Ybjej zw-xA8?22O(uBkgz(2=p%3%L-Xg)hags7<;&AJFWAzv-VEy z?BWhJD#a$%u*wWsAK7PHMhwP+y7PIWfR6*-l_NCQYgN8liif6pejMOtyPg~M@$~E% zw{=g?Q|DFBb#7d)WZCPdYbP*bav;iv6w{gt;U@aS9`37b)okN9=f>3J6US+h9_dld zNPpBX-;f27_Ubi$xN-XMhut=eFZbuN~kNN|}a3HiZ_E*WPqvERF1v zGb&k;+xByw8M!EM+daba*a4a+Q#P7isvUE^Zz-Jcqt?)mlM8-pf#mdmuNAK1=F)EU?5W`|uGX)~e2(;> z(lEhpOf!U5NXXPdmePaKK=pMh%bFG*E|>%;*!H3`-C#!-=+vDmJ50Tfz}5En8&e zn%|bk$O7HH)b?=3(TQ^7*^{SEp3=7xZ;rlArZsCvpNCgYVyl|E<4d;pt}6-rIx1wh z{r2X_mVaS0>0*S#*$zsmCh-)BmF zKEgNqH~Eel@eTb7-@7({Gq{cK(7&UP{=Mc!+V*;0y?XJQ_x-wQzEz%~-|?jFGBW;* z@6G$D_pX^o`@fcy-vNJ0pVye{Z|L_?xGzunA!PhR(pUe^cpv&aM){+Bx9p(rzry|g z5%rU_Yx&*CxrhG0LZ6%XX4~ec_4@b0=aN2J*2kmmYm9vwS+}6W-@?17yOa07WW4tI z20H#ZW4}bXl8nEVIeyGuX}dn3OLTubTZGVI@`D8z} ztWT7T|0n1mcZmKC#=eM*_n_m4se3bHmZ;bM_tU2Q6ta~1{Dk%+jQ?HQo@4KvWZv&E zUfcgO*?)ci404tFTt@%9k+1J>@csq#U#0y?WPLa3XTcvNa<-Gbu#xvvGXGDR>vr0o zXYRKpx*bW{rV{>)IS!-a`Zap!oDVRMawC!ZZN`5+*~0>DDc1a8BIC2PjWgFpei41v zlCe7eaw7MuN#9Q-SP2X3M|LNqcz6x*VmrL~d81p?%{~sdj=gFSl cPup$D8T=_aKE%9R$@n|2S)ryCPo3*WrTcxc{yIo6Y|HG!G{cF#4n|qe(&CWHMEyc`EVYz6hOQmWHy}pcDhnO|%6n(R( z7?>fp!L->;a42cEQe?bJM7LT*w+1FsX6r=kJ#aW-cC+Z2trvNJi-`VKh`DMT)EP9p zO~hfN$eUh~gquVh`$Q6dLZslWA_ad^B;lt-0uR9CklCk2;(bOW-W?)wcES|nU1GLs zwp$$n>=6ktD2_1;nC54nh~uzG0r!aLiDA@X)M%MOd_;^$EQ9g$A_HkM{EUbcjH_k% zxmT=`kX(k{4v07$6md8tBD_yTcR!T#10sdxMG{VkB%BiQpBC|-6$v~i;y5o7rvL+1 zs0>p9fhsZ(=!i(5qauMG6bZB_65vZB0gk~@-m`c%%J?`OWBMmg-_ji}G;FI%*vBG& zRZM$!#xZGU9erDN4D1at6Igv6Wa=wLrnJQ|ZJ!lM;5jDjK1a{y980O=hR{IekwBO%OZi^b@c42(nM}g=1j5MD#u!P6U=0Ic19?6FMcbBu_&Y z%+88jkC#M_|3%TOCha$_%N^kv)6EF=PLR$)SwJBe2Sz-l`5IZgEW6PDkJF5t&KJ(YNDJ*Wq!;z@8M@ ziXV&Y`OigG?oCI}-f>LX_D0#$<~e5Uen;Pq!D?zOZC|64PI&f|n9A7mj=o(G(@DD| z`YHPpk)`~P==F7!H)i+j6c*7k@Lm=c3QJLEWQhaEk8#4%-OAbIV3A`|{W zGxtLGa#;p8|Cb_r@s3EMX1=+8IaNTPq~tTE`*VDEh;8ha-ni3{rN;F>NI{$}M_a z42JC~N8irEu~gDtg&%%e>-sD_*s?p;6D=N|oXeHxbERBivRDXTYUyo?M)Gsh6XDgC z$@se1-GvA8g-Wh6T`b&HDiurN>DJ93>uk^mpt&ou*WY)ybw&Do?sYWUm@6+9#>4Km z6OCOB-0bj$ww8)$ij4bENqP(XlSp`gvHp(c)T&=dwlt$-OUT-#qr|8WOz2Vqb1se zXTDqsug6~N?`bQ4aV|GEK9!$ev<;mchZH-M_EKs7>mnbGJ(!%i>u@R@jzFJa_@a|{mCirZA zP_xNCK~C}O&D^<@B-zLje;uAj^e_SHYK45ICY1PJ*sh}aJBcn3P_`Y6uaTe^w&7dP zyUpm{C*B07>>~XaXwt4n7bUj(t-L=*yVAg&lR?iZfV^$3p> za0P;8>;)X|CD_4Quq0)G|e&o^s@slONh^~7EGf7)w|2Z^x_ zjwoj%`!8{sK^HH+QQNCs1iFOdKWYKj66^|Xh8232f+Dn6ct1%|t7wnbiXFp0fqj-0 tI0Nrw{1Do2;dcSuW8`=fb}?4o>(_g4;5`a>o0h8;&`#n2;T42>{s(>4km~>d diff --git a/packaging_and_distribution/2_packaging_scenarios.txt b/packaging_and_distribution/2_packaging_scenarios.txt index 22ddffd..f223d2d 100644 --- a/packaging_and_distribution/2_packaging_scenarios.txt +++ b/packaging_and_distribution/2_packaging_scenarios.txt @@ -1,7 +1,7 @@ packaging considerations: target environment + deployment experience - target audience: - developers - - datacenter operators + - data center operators - non technical end users - ... - runtime environment: @@ -55,14 +55,72 @@ packaging scenarios: - 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: - https://packaging.python.org/en/latest/overview/#packaging-applications \ No newline at end of file + PyPA. 2025. Overview of Python Packaging. https://packaging.python.org/en/latest/overview/ \ No newline at end of file