b05-pypckg

import%20marimo%0A%0A__generated_with%20%3D%20%220.25.0%22%0Aapp%20%3D%20marimo.App()%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20import%20marimo%20as%20mo%0A%0A%20%20%20%20return%20(mo%2C)%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%20Packages%2C%20Modules%20and%20Libraries%0A%0A%20%20%20%20Import%20external%20libraries%20and%20organize%20your%20code%20into%20functional%20chunks.%0A%0A%20%20%20%20%3E%20**Requirements%3A**%20Make%20sure%20to%20understand%20%5BPython%20functions%5D(https%3A%2F%2Fhydro-informatics.com%2Fjupyter%2Fpyfun.html).%0A%0A%20%20%20%20%23%23%20Import%20Packages%20or%20Modules%0A%0A%20%20%20%20Importing%20a%20module%20or%20package%20in%20Python%20makes%20the%20names%20defined%20or%20exposed%20by%20that%20module%20or%20package%20accessible%20in%20a%20script.%20These%20may%20include%20functions%2C%20classes%2C%20variables%2C%20and%20other%20objects.%20Importable%20code%20can%20come%20from%20different%20locations%20and%20formats%3A%20it%20may%20be%20part%20of%20Python%20itself%2C%20belong%20to%20the%20standard%20library%2C%20be%20located%20in%20a%20local%20project%2C%20or%20be%20provided%20by%20an%20installed%20third-party%20package.%20Third-party%20packages%20are%20commonly%20installed%20into%20the%20interpreter%20environment%20using%20package-management%20tools%20such%20as%20*conda*%20(%5Bread%20more%20about%20conda-installing%5D(https%3A%2F%2Fhydro-informatics.com%2Fpyinstall%23install-pckg))%20or%20*pip*%20(%5Bread%20more%20about%20pip-installing%5D(https%3A%2F%2Fhydro-informatics.com%2Fpyinstall%23pip-install-pckg))%0A%0A%20%20%20%20Modules%20from%20Python's%20standard%20library%20(e.g.%2C%20%60os%60)%20and%20built-in%20modules%20(e.g.%2C%20%60sys%60)%20are%20normally%20available%20without%20installing%20additional%20packages.%20Other%20modules%20and%20packages%20may%20need%20to%20be%20installed%20first.%0A%0A%20%20%20%20%2F%2F%2F%20admonition%20%7C%20The%20Difference%20between%20a%20Module%20and%20a%20Package%0A%20%20%20%20%20%20%20%20type%3A%20note%0A%0A%20%20%20%20A%20**module**%20is%20a%20single%20importable%20unit%2C%20commonly%20represented%20by%20a%20Python%20file%20such%20as%20%60a_module.py%60%20(e.g.%2C%20%60import%20a_module%60).%20Modules%20can%20also%20be%20implemented%20in%20other%20ways%2C%20for%20example%20as%20built-in%20or%20compiled%20extension%20modules.%0A%0A%20%20%20%20A%20**package**%20organizes%20modules%20and%20potentially%20subpackages%20in%20a%20directory%20hierarchy%2C%20allowing%20imports%20such%20as%20%60from%20a_package.module%20import%20a_function%60.%20A%20package%20is%20itself%20importable%20and%20has%20a%20%60__path__%60%20attribute.%20Regular%20packages%20usually%20contain%20an%20%60__init__.py%60%20file%2C%20whereas%20*namespace%20packages*%20can%20exist%20without%20one.%0A%0A%20%20%20%20Sounds%20fuzzy%3F%20Read%20this%20section%20down%20to%20the%20bottom%20and%20come%20back%20here%20to%20re-read%20this%20note.%0A%20%20%20%20%2F%2F%2F%0A%20%20%20%20The%20%60os%60%20module%20provides%20functions%20for%20interacting%20with%20the%20operating%20system%2C%20for%20example%2C%20for%20working%20with%20files%2C%20directories%2C%20paths%2C%20and%20environment%20variables.%20So%20let's%20import%20this%20essential%20module%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20import%20os%0A%20%20%20%20print(os.getcwd())%20%23%20print%20current%20working%20directory%0A%20%20%20%20print(os.path.abspath(''))%20%23%20print%20directory%20of%20script%20running%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20Overview%20of%20Import%20Options%0A%0A%20%20%20%20Here%20is%20an%20overview%20of%20options%20to%20import%20packages%20or%20modules%20(hierarchical%20parts%20of%20packages)%3A%0A%0A%20%20%20%20%7C%20Command%20%7C%20Description%20%7C%20Usage%20of%20attributes%20%7C%0A%20%20%20%20%7C---------%7C-------------%7C---------------------%7C%0A%20%20%20%20%7C%20%60import%20package_name%60%20%7C%20Import%20an%20original%20module%20%7C%20%60package.item()%60%20%7C%0A%20%20%20%20%7C%20%60import%20package_name%20as%20nickname%60%20%7C%20Import%20module%20and%20rename%20(alias)%20it%20in%20the%20script%20%7C%20%20%60nickname.item()%60%20%7C%0A%20%20%20%20%7C%20%60from%20package-name%20import%20item%60%20%7C%20Import%20only%20a%20function%2C%20class%20or%20other%20items%20%7C%20%20%60item()%60%20%7C%0A%20%20%20%20%7C%20%60from%20package-name%20import%20*%60%20%7C%20Import%20all%20items%20%7C%20%20%60item()%60%20%7C%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20Example%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20import%20matplotlib.pyplot%20as%20plt%20%23%20import%20the%20pyplot%20module%20of%20the%20matplotlib%20package%20and%20alias%20it%20with%20plt%0A%0A%20%20%20%20x%20%3D%20%5B%5D%0A%20%20%20%20y%20%3D%20%5B%5D%0A%0A%20%20%20%20for%20e%20in%20range(1%2C%2010)%3A%0A%20%20%20%20%20%20%20%20x.append(e)%0A%20%20%20%20%20%20%20%20y.append(e**2)%0A%0A%20%20%20%20plt.plot(x%2C%20y)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20What%20is%20the%20best%20way%20to%20import%20a%20package%20or%20module%3F%0A%20%20%20%20There%20is%20no%20global%20answer%20to%20this%20question.%20However%2C%20be%20aware%20that%20%60from%20package-name%20import%20*%60%20shadows%20any%20existing%20variable%20or%20other%20items%20in%20the%20script.%20Thus%2C%20only%20use%20%60*%60%20when%20you%20are%20aware%20of%20all%20contents%20of%20a%20module%20or%20package.%20This%20is%20also%20why%20%5BPEP%208%5D(https%3A%2F%2Fpeps.python.org%2Fpep-0008%2F)%20discourages%20wildcard%20imports%20and%20recommends%20placing%20all%20imports%20at%20the%20top%20of%20a%20script.%20The%20import%20statement%20in%20the%20middle%20of%20the%20following%20example%20is%20for%20demonstration%20purposes%20only%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20pi%20%3D%209.112%20%20%23%20define%20a%20float%20called%20pi%0A%20%20%20%20print(f'Pi%20is%20not%20%7Bpi%3A.3f%7D.')%0A%20%20%20%20from%20math%20import%20pi%0A%20%20%20%20print(f'Pi%20is%20%7Bpi%3A.3f%7D.')%20%20%23%20this%20overwrites%20the%20previously%20defined%20variable%20pi%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%3E%20**Tip%3A**%20Define%20default%20import%20packages%20for%20*JupyterLab*'s%20*IPython*%20kernel%20(read%20more%20on%20the%20%5B*Python*%20installation%20page%5D(https%3A%2F%2Fhydro-informatics.com%2Fpython-basics%2Fpyinstall.html%23ipython-config)).%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20What%20items%20(attributes%2C%20classes%2C%20functions)%20are%20in%20a%20module%3F%0A%20%20%20%20Sometimes%20we%20want%20to%20explore%20modules%20or%20to%20check%20variable%20attributes.%20This%20is%20achieved%20with%20the%20%60dir()%60%20command%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20import%20sys%0A%20%20%20%20print(sys.path)%0A%20%20%20%20print(dir(sys))%0A%0A%20%20%20%20a_string%20%3D%20%22zabaglione%22%0A%20%20%20%20print(%22%2C%20%22.join(dir(a_string.split(%22gl%22))))%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%20Create%20a%20new%20Module%0A%0A%20%20%20%20In%20object-oriented%20programming%20and%20code%20factorization%2C%20writing%20custom%2C%20new%20modules%20is%20an%20essential%20task.%20To%20write%20a%20new%20module%2C%20first%2C%20create%20a%20new%20script.%20Then%2C%20open%20the%20new%20script%20and%20add%20some%20parameters%20and%20functions.%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20%23%20icecreamdialogue.py%0A%20%20%20%20_flavors%20%3D%20%5B'vanilla'%2C%20'chocolate'%2C%20'bread'%5D%0A%20%20%20%20_price_scoops%20%3D%20%7B1%3A%20'two%20euros'%2C%202%3A%20'three%20euros'%2C%203%3A%20'your%20health'%7D%0A%20%20%20%20_welcome_msg%20%3D%20f'Hi%2C%20I%20only%20have%20%7B_flavors%5B0%5D%7D.%20How%20many%20scoops%20do%20you%20want%3F'%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%5B%60icecreamdialogue.py%60%5D(https%3A%2F%2Fgithub.com%2Fhydro-informatics%2Ficecream%2Fraw%2Fmaster%2Fsingle-scripts%2Ficecreamdialogue.py)%20can%20now%20either%20be%20executed%20as%20a%20script%20(nothing%20will%20happen%20visibly)%20or%20imported%20as%20a%20module%20to%20access%20its%20variables%20(e.g.%2C%20%60icecreamdialogue.flavors%60)%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20import%20icecreamdialogue%20as%20icd%0A%20%20%20%20print(icd.welcome_msg)%0A%20%20%20%20_scoops_wanted%20%3D%202%0A%20%20%20%20print(f'That%20makes%20%7Bicd.price_scoops%5B_scoops_wanted%5D%7D%20please')%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20Make%20Script%20Stand-alone%0A%0A%20%20%20%20As%20an%20alternative%2C%20we%20can%20append%20the%20call%20to%20items%20in%20%5B%60icecreamdialogue.py%60%5D(https%3A%2F%2Fgithub.com%2Fhydro-informatics%2Ficecream%2Fraw%2Fmaster%2Fsingle-scripts%2Ficecreamdialogue.py)%20in%20the%20script%20and%20run%20it%20as%20a%20stand-alone%20script%20by%20adding%20an%20%60if%20__name__%20%3D%3D%20%22__main__%22%3A%60%20block%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20%23%20icecreamdialogue_standalone.py%0A%20%20%20%20_flavors%20%3D%20%5B'vanilla'%2C%20'chocolate'%2C%20'bread'%5D%0A%20%20%20%20_price_scoops%20%3D%20%7B1%3A%20'two%20euros'%2C%202%3A%20'three%20euros'%2C%203%3A%20'your%20health'%7D%0A%20%20%20%20_welcome_msg%20%3D%20f'Hi%2C%20I%20only%20have%20%7B_flavors%5B0%5D%7D.%20How%20many%20scoops%20do%20you%20want%3F'%0A%20%20%20%20if%20__name__%20%3D%3D%20'__main__'%3A%0A%20%20%20%20%20%20%20%20print(_welcome_msg)%0A%20%20%20%20%20%20%20%20_scoops_wanted%20%3D%202%0A%20%20%20%20%20%20%20%20print(f'That%20makes%20%7B_price_scoops%5B_scoops_wanted%5D%7D%20please')%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20Now%20we%20can%20run%20%5B%60icecreamdialogue_standalone.py%60%5D(https%3A%2F%2Fgithub.com%2Fhydro-informatics%2Ficecream%2Fraw%2Fmaster%2Fsingle-scripts%2Ficecreamdialogue_standalone.py)%20in%20a%20terminal%20(e.g.%2C%20Linux%20Terminal%2C%20*PyCharm*'s%20*Terminal*%20tab%20at%20the%20bottom%20of%20the%20window%2C%20or%20VS%20Code's%20integrated%20terminal).%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20***%0A%20%20%20%20%60%60%60%0A%20%20%20%20C%3A%5Ctemp%5C%20python%20icecreamdialogue_standalone.py%0A%20%20%20%20%60%60%60%0A%20%20%20%20***%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%3E%20**Note%3A**%20Depending%20on%20the%20definition%20of%20system%20variables%20used%20in%20the%20*Terminal*%20environment%2C%20Python%20must%20be%20called%20with%20a%20different%20variable%20name%20than%20%60python%60%20(e.g.%2C%20%60python3%60%20on%20some%20Linux%20platforms).%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20Standalone%20Scripts%20with%20Input%20Parameters%0A%0A%20%20%20%20To%20make%20the%20script%20more%20flexible%2C%20we%20can%20define%2C%20for%20instance%2C%20%60scoops_wanted%60%20as%20an%20input%20variable%20of%20a%20function.%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%60%60%60python%0A%20%20%20%20%23%20icecreamdialogue_standalone_withinput.py%0A%20%20%20%20import%20sys%20%23%20sys%20provides%20access%20to%20command%20line%20arguments%0A%0A%20%20%20%20flavors%20%3D%20%5B%22vanilla%22%2C%20%22chocolate%22%2C%20%22bread%22%5D%0A%20%20%20%20price_scoops%20%3D%20%7B1%3A%20%22two%20euros%22%2C%202%3A%20%22three%20euros%22%2C%203%3A%20%22your%20health%22%7D%0A%20%20%20%20welcome_msg%20%3D%20f%22Hi%2C%20I%20only%20have%20%7Bflavors%5B0%5D%7D.%20How%20many%20scoops%20do%20you%20want%3F%22%0A%0A%20%20%20%20def%20dialogue(scoops_wanted)%3A%20%23%20formerly%20in%20the%20__main__%20statement%0A%20%20%20%20%20%20%20%20print(welcome_msg)%0A%20%20%20%20%20%20%20%20print(f%22That%20makes%20%7Bprice_scoops%5Bscoops_wanted%5D%7D%20please%22)%0A%0A%20%20%20%20if%20__name__%20%3D%3D%20%22__main__%22%3A%0A%20%20%20%20%20%20%20%20if%20len(sys.argv)%20%3E%201%3A%20%23%20make%20sure%20input%20is%20provided%0A%20%20%20%20%20%20%20%20%20%20%20%20%23%20if%20true%3A%20call%20the%20dialogue%20function%20with%20the%20input%20argument%0A%20%20%20%20%20%20%20%20%20%20%20%20dialogue(int(sys.argv%5B1%5D))%0A%20%20%20%20%60%60%60%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20Now%2C%20we%20can%20run%20%60icecreamdialogue_standalone_withinput.py%60%20in%20a%20terminal%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20***%0A%20%20%20%20%60%60%60%0A%20%20%20%20C%3A%5Ctemp%5C%20python%20icecreamdialogue_standalone_withinput.py%202%0A%20%20%20%20%60%60%60%0A%20%20%20%20***%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20Initialization%20of%20a%20Package%20(Hierarchically%20Organized%20Module)%0A%0A%20%20%20%20Good%20practice%20involves%20module%20cohesion%20and%20maintainability.%20Consequently%2C%20a%20package%20will%20most%20likely%20consist%20of%20multiple%20scripts%20that%20are%20stored%20in%20one%20folder%20and%20one%20core%20script%20serves%20for%20the%20initiation%20of%20the%20scripts.%20This%20core%20script%20is%20called%20%60__init__.py%60%20and%20Python%20will%20look%20for%20this%20script%20name%20in%20a%20package%20folder.%20Namespace%20packages%20may%20omit%20%60__init__.py%60.%20Example%20structure%20of%20a%20package%20called%20%60icecreamery%60%3A%0A%0A%20%20%20%20*%20%60icecreamery%60%20(folder%20name)%0A%20%20%20%20%20%20-%20%60__init__.py%60%20%20%20-%20optional%20package%20initiation%20*Python*%20script%0A%20%20%20%20%20%20-%20%60icecreamdialogue.py%60%20%20-%20dialogue%20producing%20*Python*%20script%0A%20%20%20%20%20%20-%20%60icecream_maker.py%60%20%20%20-%20virtual%20ice%20cream%20producing%20*Python*%20script%0A%0A%20%20%20%20To%20automatically%20invoke%20the%20two%20relevant%20scripts%20(sub-modules)%20of%20the%20%60icecreamery%60%20package%2C%20the%20%60__init__.py%60%20needs%20to%20include%20the%20following%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20%23%20__init__.py%0A%20%20%20%20print(f'Invoking%20__init__.py%20for%20%7B__name__%7D')%20%20%23%20only%20for%20demonstration%20-%20keep%20__init__.py%20silent%20in%20production%20packages%0A%20%20%20%20import%20icecreamery.icecreamdialogue%2C%20icecreamery.icecream_maker%0A%0A%20%20%20%20return%20(icecreamery%2C)%0A%0A%0A%40app.cell%0Adef%20_(icecreamery)%3A%0A%20%20%20%20%23%20example%20usage%20of%20the%20icecreamery%20package%0A%20%20%20%20print(icecreamery.icecreamdialogue.welcome_msg)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20Do%20you%20remember%20the%20%60dir()%60%20function%3F%20Applied%20to%20a%20package%20(e.g.%2C%20%60dir(icecreamery)%60)%2C%20it%20lists%20the%20items%20that%20are%20currently%20defined%20in%20the%20package%20namespace.%20However%2C%20to%20control%20which%20sub-modules%20a%20wildcard%20import%20(%60from%20icecreamery%20import%20*%60)%20loads%2C%20define%20an%20%60__all__%60%20list%20in%20the%20%60__init__.py%60%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%60%60%60python%0A%20%20%20%20%23%20__init__.py%20with%20__all__%20list%0A%20%20%20%20__all__%20%3D%20%5B'icecreamdialogue'%2C%20'icecream_maker'%5D%0A%20%20%20%20%60%60%60%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20The%20full%20example%20of%20the%20%60icecreamery_all%60%20package%20is%20also%20available%20in%20an%20%5Bicecream%5D(https%3A%2F%2Fgithub.com%2Fhydro-informatics%2Ficecream)%20repository.%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell%0Adef%20_()%3A%0A%20%20%20%20%23%20example%20usage%20of%20the%20icecreamery%20package%0A%20%20%20%20from%20icecreamery_all%20import%20icecreamdialogue%0A%20%20%20%20print(icecreamdialogue.welcome_msg)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20Package%20Creation%20Summary%0A%0A%20%20%20%20The%20structure%20of%20a%20module%20can%20be%20more%20complex%20than%20the%20above%20example%20list%20(e.g.%2C%20with%20sub-folders).%20When%20you%20write%20a%20package%2C%20consider%20using%20%5Bmeaningful%20script%20and%20variable%20names%5D(https%3A%2F%2Fhydro-informatics.com%2Fpython-basics%2Fpystyle.html%23libs)%2C%20along%20with%20appropriate%20documentation.%0A%0A%20%20%20%20%3E%20**Try%20logging%3A**%20implement%20a%20custom%20%5Blogger%5D(https%3A%2F%2Fhydro-informatics.com%2Fpython-basics%2Fpyerror.html%23logging)%20in%20your%20module%20with%20%60logger%20%3D%20logging.getLogger(__name__)%60%20(replace%20%60__name__%60%20with%20for%20example%20%60my-module-log%60).%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%20Reload%20(Re-import)%20a%20Package%20or%20Module%0A%0A%20%20%20%20Since%20Python%203%2C%20reloading%20a%20module%20requires%20importing%20the%20%60importlib%60%20module%20first.%20Reloading%20only%20makes%20sense%20if%20you%20are%20actively%20writing%20a%20new%20module.%20To%20reload%20a%20module%2C%20type%3A%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%60%60%60python%0A%20%20%20%20import%20importlib%0A%20%20%20%20importlib.reload(my_module)%0A%20%20%20%20%60%60%60%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%3E%20**Tip%3A**%20In%20JupyterLab%20(IPython)%2C%20the%20two%20magic%20commands%20%60%25load_ext%20autoreload%60%20and%20%60%25autoreload%202%60%20automatically%20reload%20all%20modified%20modules%20before%20every%20cell%20execution%2C%20which%20makes%20manual%20%60importlib.reload()%60%20calls%20unnecessary%20during%20active%20module%20development.%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%20Package%20Development%20%26%20PyPI%20(pip)%20Deployment%0A%0A%20%20%20%20The%20%60icecreamery%60%20example%20shows%20how%20a%20package%20works%20internally.%20To%20make%20a%20package%20installable%20for%20anyone%20through%20%60pip%20install%20icecreamery%60%2C%20it%20needs%20to%20be%20deployed%20to%20%5BPyPI%5D(https%3A%2F%2Fpypi.org%2F)%2C%20the%20Python%20Package%20Index%20that%20*pip*%20queries%20in%20the%20background%20(%5Bread%20more%20about%20pip-installing%5D(https%3A%2F%2Fhydro-informatics.com%2Fpython-basics%2Fpyinstall.html%23pip-install-pckg)).%20This%20section%20first%20summarizes%20the%20deployment%20workflow%2C%20including%20automation%20with%20GitHub%20workflows%20and%20documentation%20on%20Read%20the%20Docs%2C%20and%20then%20explains%20good%20practice%20for%20developing%20a%20package%20collaboratively.%0A%0A%20%20%20%20%23%23%23%20From%20Local%20Code%20to%20a%20pip-installable%20Package%0A%0A%20%20%20%20Modern%20Python%20packaging%20is%20driven%20by%20a%20single%20%60pyproject.toml%60%20file%2C%20which%20replaces%20the%20formerly%20used%20%60setup.py%60%20(see%20%5BPEP%20621%5D(https%3A%2F%2Fpeps.python.org%2Fpep-0621%2F)).%20A%20deployment-ready%20repository%20resembles%20the%20following%20structure%2C%20which%20is%20known%20as%20the%20*src%20layout*%3A%0A%0A%20%20%20%20%60%60%60%0A%20%20%20%20icecreamery%2F%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20(repository%20root)%0A%20%20%20%20%20%20%20%20src%2F%0A%20%20%20%20%20%20%20%20%20%20%20%20icecreamery%2F%20%20%20%20%20%20%20%20%20%20(the%20package%20itself)%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20__init__.py%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20icecreamdialogue.py%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20icecream_maker.py%0A%20%20%20%20%20%20%20%20tests%2F%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20(automated%20tests%2C%20e.g.%2C%20for%20pytest)%0A%20%20%20%20%20%20%20%20docs%2F%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20(documentation%20source%2C%20e.g.%2C%20for%20Sphinx)%0A%20%20%20%20%20%20%20%20examples%2F%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20%20(functional%20usage%20examples)%0A%20%20%20%20%20%20%20%20pyproject.toml%20%20%20%20%20%20%20%20%20%20%20%20(package%20metadata%20and%20build%20configuration)%0A%20%20%20%20%20%20%20%20README.md%0A%20%20%20%20%20%20%20%20LICENSE%0A%20%20%20%20%60%60%60%0A%0A%20%20%20%20The%20%60pyproject.toml%60%20file%20defines%20how%20*pip*%20(or%20any%20other%20installer)%20builds%20and%20installs%20the%20package%3A%0A%0A%20%20%20%20%60%60%60toml%0A%20%20%20%20%5Bbuild-system%5D%0A%20%20%20%20requires%20%3D%20%5B%22setuptools%3E%3D77%22%5D%0A%20%20%20%20build-backend%20%3D%20%22setuptools.build_meta%22%0A%0A%20%20%20%20%5Bproject%5D%0A%20%20%20%20name%20%3D%20%22icecreamery%22%0A%20%20%20%20version%20%3D%20%220.1.0%22%0A%20%20%20%20description%20%3D%20%22Virtual%20ice%20cream%20sales%20dialogues%22%0A%20%20%20%20readme%20%3D%20%22README.md%22%0A%20%20%20%20license%20%3D%20%22BSD-3-Clause%22%0A%20%20%20%20requires-python%20%3D%20%22%3E%3D3.10%22%0A%20%20%20%20dependencies%20%3D%20%5B%0A%20%20%20%20%20%20%20%20%22matplotlib%22%2C%0A%20%20%20%20%20%20%20%20%22numpy%22%2C%0A%20%20%20%20%5D%0A%20%20%20%20%60%60%60%0A%0A%20%20%20%20While%20developing%2C%20install%20the%20package%20in%20**editable%20mode**%20into%20the%20active%20environment%3A%0A%0A%20%20%20%20%60%60%60%0A%20%20%20%20pip%20install%20-e%20.%0A%20%20%20%20%60%60%60%0A%0A%20%20%20%20The%20%60-e%60%20(editable)%20flag%20makes%20Python%20import%20the%20package%20directly%20from%20the%20local%20development%20clone%20instead%20of%20a%20static%20copy%20in%20the%20*site-packages*%20folder%2C%20so%20code%20modifications%20take%20effect%20immediately%20without%20re-installing.%0A%0A%20%20%20%20To%20deploy%20a%20release%20on%20PyPI%20manually%3A%0A%0A%20%20%20%201.%20Register%20(for%20free)%20at%20%5Bpypi.org%5D(https%3A%2F%2Fpypi.org%2F)%20and%2C%20for%20rehearsing%20uploads%2C%20at%20%5Btest.pypi.org%5D(https%3A%2F%2Ftest.pypi.org%2F).%0A%20%20%20%201.%20Build%20the%20distribution%20archives%20(a%20source%20archive%20and%20a%20wheel)%20with%20%60python%20-m%20build%60%20(install%20the%20builder%20once%20with%20%60pip%20install%20build%60).%20The%20archives%20land%20in%20a%20new%20%60dist%2F%60%20folder.%0A%20%20%20%201.%20Upload%20the%20archives%20with%20%5Btwine%5D(https%3A%2F%2Ftwine.readthedocs.io%2F)%3A%20%60python%20-m%20twine%20upload%20dist%2F*%60.%20Best%20practice%3A%20rehearse%20the%20upload%20with%20%60python%20-m%20twine%20upload%20--repository%20testpypi%20dist%2F*%60%20first.%0A%0A%20%20%20%20Done.%20From%20now%20on%2C%20everyone%20can%20%60pip%20install%20icecreamery%60.%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20Automate%20Testing%20and%20Deployment%20with%20GitHub%20Workflows%0A%0A%20%20%20%20Manually%20building%20and%20uploading%20every%20release%20is%20error-prone.%20%5BGitHub%20Actions%5D(https%3A%2F%2Fdocs.github.com%2Fen%2Factions)%20automate%20such%20recurring%20jobs%20with%20so-called%20workflows%2C%20which%20are%20YAML%20files%20stored%20in%20the%20%60.github%2Fworkflows%2F%60%20folder%20of%20a%20repository.%20Two%20workflows%20are%20particularly%20useful%20for%20package%20development%3A%0A%0A%20%20%20%20*%20A%20**test%20(continuous%20integration)%20workflow**%20that%20runs%20the%20test%20suite%20(e.g.%2C%20with%20%5Bpytest%5D(https%3A%2F%2Fdocs.pytest.org%2F))%20for%20every%20push%20and%20pull%20request%2C%20ideally%20on%20multiple%20Python%20versions%20and%20operating%20systems.%20Thus%2C%20broken%20code%20is%20flagged%20before%20it%20is%20merged%20into%20%60main%60%20(recall%20the%20%5BCollaboration%20%26%20Branches%5D(https%3A%2F%2Fhydro-informatics.com%2Fget-started%2Fgit.html%23collaboration)%20section).%0A%20%20%20%20*%20A%20**publish%20workflow**%20that%20builds%20and%20uploads%20the%20package%20to%20PyPI%20whenever%20a%20new%20release%20(version%20tag)%20is%20published%20on%20GitHub.%0A%0A%20%20%20%20Best%20practice%20for%20the%20publish%20workflow%20is%20PyPI's%20%5BTrusted%20Publishing%5D(https%3A%2F%2Fdocs.pypi.org%2Ftrusted-publishers%2F)%2C%20which%20links%20the%20GitHub%20repository%20directly%20to%20the%20PyPI%20project%20(a%20one-time%20setup%20in%20the%20PyPI%20account%20settings)%2C%20so%20that%20no%20API%20tokens%20need%20to%20be%20stored%20in%20the%20repository%20secrets%3A%0A%0A%20%20%20%20%60%60%60yaml%0A%20%20%20%20%23%20.github%2Fworkflows%2Fpublish.yml%0A%20%20%20%20name%3A%20Publish%20to%20PyPI%0A%0A%20%20%20%20on%3A%0A%20%20%20%20%20%20release%3A%0A%20%20%20%20%20%20%20%20types%3A%20%5Bpublished%5D%0A%0A%20%20%20%20jobs%3A%0A%20%20%20%20%20%20publish%3A%0A%20%20%20%20%20%20%20%20runs-on%3A%20ubuntu-latest%0A%20%20%20%20%20%20%20%20environment%3A%20pypi%0A%20%20%20%20%20%20%20%20permissions%3A%0A%20%20%20%20%20%20%20%20%20%20id-token%3A%20write%20%20%20%23%20required%20for%20PyPI%20Trusted%20Publishing%0A%20%20%20%20%20%20%20%20steps%3A%0A%20%20%20%20%20%20%20%20%20%20-%20uses%3A%20actions%2Fcheckout%40v4%0A%20%20%20%20%20%20%20%20%20%20-%20uses%3A%20actions%2Fsetup-python%40v5%0A%20%20%20%20%20%20%20%20%20%20%20%20with%3A%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20python-version%3A%20%223.12%22%0A%20%20%20%20%20%20%20%20%20%20-%20name%3A%20Build%20distribution%20archives%0A%20%20%20%20%20%20%20%20%20%20%20%20run%3A%20%7C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20python%20-m%20pip%20install%20build%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20python%20-m%20build%0A%20%20%20%20%20%20%20%20%20%20-%20name%3A%20Upload%20to%20PyPI%0A%20%20%20%20%20%20%20%20%20%20%20%20uses%3A%20pypa%2Fgh-action-pypi-publish%40release%2Fv1%0A%20%20%20%20%60%60%60%0A%0A%20%20%20%20With%20this%20workflow%20in%20place%2C%20publishing%20a%20new%20version%20reduces%20to%20increasing%20the%20version%20number%20in%20%60pyproject.toml%60%20and%20clicking%20on%20**Draft%20a%20new%20release**%20(with%20a%20tag%20such%20as%20%60v0.1.1%60)%20on%20GitHub.%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20Documentation%20on%20Read%20the%20Docs%20(Free%20Plan)%0A%0A%20%20%20%20A%20pip-installable%20package%20without%20documentation%20will%20hardly%20be%20used%20by%20anyone.%20The%20de-facto%20standard%20for%20hosting%20Python%20package%20documentation%20is%20%5BRead%20the%20Docs%5D(https%3A%2F%2Fabout.readthedocs.com%2F)%2C%20which%20builds%20and%20hosts%20documentation%20of%20public%20(open-source)%20repositories%20for%20free%20at%20%60PACKAGE-NAME.readthedocs.io%60%20(the%20free%20plan%20shows%20small%20ads).%20The%20workflow%3A%0A%0A%20%20%20%201.%20Write%20consistent%20docstrings%20(e.g.%2C%20in%20%5Bnumpy%5D(https%3A%2F%2Fnumpydoc.readthedocs.io%2Fen%2Flatest%2Fformat.html)%20or%20%5BGoogle%5D(https%3A%2F%2Fgoogle.github.io%2Fstyleguide%2Fpyguide.html%2338-comments-and-docstrings)%20style)%20for%20all%20modules%2C%20classes%2C%20and%20functions%2C%20so%20that%20documentation%20generators%20can%20render%20the%20API%20reference%20automatically.%0A%20%20%20%201.%20Create%20a%20%60docs%2F%60%20folder%20with%20a%20%5BSphinx%5D(https%3A%2F%2Fwww.sphinx-doc.org%2F)%20project%20(%60sphinx-quickstart%60)%20and%20enable%20the%20%60sphinx.ext.autodoc%60%20and%20%60sphinx.ext.napoleon%60%20extensions%20in%20%60docs%2Fconf.py%60%20to%20pull%20the%20docstrings%20into%20the%20documentation.%20%5BMkDocs%5D(https%3A%2F%2Fwww.mkdocs.org%2F)%20with%20the%20*mkdocstrings*%20plugin%20is%20a%20popular%20alternative.%0A%20%20%20%201.%20Add%20a%20%60.readthedocs.yaml%60%20configuration%20file%20(required%20by%20Read%20the%20Docs)%20to%20the%20repository%20root%3A%0A%0A%20%20%20%20%60%60%60yaml%0A%20%20%20%20%23%20.readthedocs.yaml%0A%20%20%20%20version%3A%202%0A%0A%20%20%20%20build%3A%0A%20%20%20%20%20%20os%3A%20ubuntu-24.04%0A%20%20%20%20%20%20tools%3A%0A%20%20%20%20%20%20%20%20python%3A%20%223.12%22%0A%0A%20%20%20%20sphinx%3A%0A%20%20%20%20%20%20configuration%3A%20docs%2Fconf.py%0A%0A%20%20%20%20python%3A%0A%20%20%20%20%20%20install%3A%0A%20%20%20%20%20%20%20%20-%20method%3A%20pip%0A%20%20%20%20%20%20%20%20%20%20path%3A%20.%0A%20%20%20%20%20%20%20%20-%20requirements%3A%20docs%2Frequirements.txt%0A%20%20%20%20%60%60%60%0A%0A%20%20%20%204.%20Sign%20in%20at%20%5Breadthedocs.org%5D(https%3A%2F%2Freadthedocs.org%2F)%20with%20a%20GitHub%20account%20and%20import%20the%20repository.%20Read%20the%20Docs%20installs%20a%20webhook%2C%20so%20every%20push%20to%20%60main%60%20triggers%20an%20automatic%20rebuild%20of%20the%20documentation%2C%20and%20every%20release%20tag%20can%20be%20published%20as%20a%20version-specific%20documentation%20build.%0A%0A%20%20%20%20Done.%20The%20documentation%20now%20updates%20itself%20with%20every%20push.%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0A%40app.cell(hide_code%3DTrue)%0Adef%20_(mo)%3A%0A%20%20%20%20mo.md(r%22%22%22%0A%20%20%20%20%23%23%23%20Collaborative%20Package%20Development%0A%0A%20%20%20%20As%20soon%20as%20several%20developers%20(e.g.%2C%20a%20research%20group)%20push%20code%20to%20the%20same%20package%20repository%2C%20working%20on%20%5Bdedicated%20branches%20with%20pull%20requests%5D(https%3A%2F%2Fhydro-informatics.com%2Fget-started%2Fgit.html%23collaboration)%20is%20only%20half%20of%20the%20story.%20The%20following%20good%20practice%20rules%20keep%20a%20growing%20package%20maintainable%20(this%20list%20stems%20from%20painful%20experience%20with%20real-world%20research%20code)%3A%0A%0A%20%20%20%20**Strictly%20follow%20%5BPEP%208%5D(https%3A%2F%2Fpeps.python.org%2Fpep-0008%2F)%3A**%0A%0A%20%20%20%20*%20*Naming%20conventions*%3A%20make%20sure%20that%20all%20script%20(module)%20filenames%20and%20variable%20names%20follow%20good%20practice%2C%20that%20is%2C%20short%2C%20%60lowercase_with_underscores%60%20names%20for%20modules%2C%20functions%2C%20and%20variables%2C%20%60CamelCase%60%20for%20classes%2C%20and%20%60UPPERCASE%60%20for%20constants%20(recall%20%5Bmeaningful%20script%20and%20variable%20names%5D(https%3A%2F%2Fhydro-informatics.com%2Fpython-basics%2Fpystyle.html%23libs)).%0A%20%20%20%20*%20*Module%20shadowing*%3A%20never%20name%20an%20internal%20script%20or%20folder%20after%20an%20installed%20library%20or%20module%20(e.g.%2C%20%60math.py%60%2C%20%60numpy.py%60%2C%20or%20a%20folder%20called%20%60matplotlib%2F%60).%20Because%20Python%20searches%20the%20script's%20own%20directory%20before%20the%20*site-packages*%20folder%2C%20the%20local%20file%20gets%20imported%20instead%20of%20the%20intended%20library%2C%20which%20leads%20to%20seemingly%20inexplicable%20import%20failures.%20Overly%20generic%20names%2C%20such%20as%20%60plots.py%60%20or%20%60plots%2F%60%2C%20are%20risky%20for%20the%20same%20reason%3A%20they%20easily%20collide%20with%20third-party%20modules%20and%20get%20confused%20with%20plotting%20libraries%20like%20%60matplotlib.pyplot%60.%0A%20%20%20%20*%20*Docstrings*%3A%20equip%20every%20module%20and%20every%20function%20with%20a%20docstring%2C%20so%20that%20collaborators%20(and%20documentation%20generators%2C%20see%20above)%20understand%20what%20the%20code%20does%20without%20reverse-engineering%20it.%0A%20%20%20%20*%20*File%20length%20and%20code%20redundancy*%3A%20a%20modular%20package%20structure%20means%20that%20scripts%20should%20remain%20concise.%20For%20context%2C%20we%20once%20had%20to%20refactor%20a%20plotting%20script%20that%20had%20grown%20to%20more%20than%203500%20lines%2C%20partly%20because%20of%20copy-pasted%20(redundant)%20code%20blocks.%20Break%20large%20files%20down%20into%20logical%20sub-modules%20and%20strictly%20follow%20the%20DRY%20(Don't%20Repeat%20Yourself)%20principle.%0A%0A%20%20%20%20**Use%20dedicated%20folders%20for%20examples%20and%20templates**%20to%20keep%20the%20core%20package%20(i.e.%2C%20the%20%60src%2F%60%20directory)%20clean%3A%0A%0A%20%20%20%20*%20%60dev-examples%2F%60%3A%20ongoing%20research%20or%20development%20cases%20(e.g.%2C%20%60dev-examples%2Fcylinder-flume-telemac%2F%60).%20Configure%20the%20repository%20to%20block%20large%20files%20(e.g.%2C%20anything%20above%2020%20MB)%2C%20because%20large%20simulation%20outputs%20do%20not%20belong%20in%20a%20*git*%20repository%20and%20should%20be%20backed%20up%20separately.%0A%20%20%20%20*%20%60examples%2F%60%3A%20finalized%2C%20cleaned-up%2C%20and%20functional%20examples%2C%20along%20with%20README%20information%20on%20how%20to%20run%20them.%0A%20%20%20%20*%20%60templates%2F%60%3A%20generalized%20versions%20of%20the%20example%20scripts%20that%20use%20keyword%20arguments%20instead%20of%20hardcoded%20paths.%0A%0A%20%20%20%20**Maintain%20strict%20top-level%20cleanliness**%3A%20do%20not%20add%20or%20move%20files%20directly%20into%20the%20repository%20root%20or%20the%20package%20source%20directory.%20For%20instance%2C%20keep%20environment%20activation%20scripts%20in%20a%20dedicated%20folder%20(e.g.%2C%20%60env-scripts%2F%60)%20and%20invoke%20them%20from%20your%20local%20environment%20or%20example%20directories%20as%20needed.%0A%0A%20%20%20%20**Stay%20synchronized%20with%20%60main%60**%3A%20pull%20the%20latest%20%60main%60%20branch%20regularly%20and%20always%20before%20creating%20a%20new%20branch.%20In%20addition%2C%20install%20the%20package%20from%20the%20local%20development%20clone%20in%20editable%20mode%20(%60pip%20install%20-e%20.%60)%20instead%20of%20manipulating%20relative%20imports%20or%20%60sys.path%60%20so%20that%20example%20scripts%20import%20your%20latest%20local%20code%20rather%20than%20a%20globally%20installed%20*site-packages*%20copy.%20AI%20assistants%20(e.g.%2C%20*Claude%20Code*%20or%20*Codex*)%20can%20help%20to%20robustly%20refactor%20legacy%20scripts%20with%20broken%20imports%2C%20but%20review%20their%20modifications%20as%20critically%20as%20any%20other%20pull%20request.%0A%20%20%20%20%22%22%22)%0A%20%20%20%20return%0A%0A%0Aif%20__name__%20%3D%3D%20%22__main__%22%3A%0A%20%20%20%20app.run()%0A