run.py

@@ -205,7 +205,7 @@ def action_app() -> None:
 	subprocess.run([
 		"podman", "run", "--rm", "-it",
 		"--publish", "8787:8787",
-		f"{IMAGE_NAME}:{get_git_revision_hash()}",
+		f"{IMAGE_NAME}:dev",
 	])
 
 

src/SUMMARY.md

@@ -1,69 +1,6 @@
 # Summary
 - [Introduction](introduction.md)
 
-- [How to Ask for Help](how-to.md)
-	- [DTU Python Support Community](help.md)
-
-
-
-# Computer Essentials
-- [Handbook of Presumed Knowledge](basics/nonobvious_stuff/README.md)
-	- ["File"? "Filesystem"?](basics/nonobvious_stuff/files.md)
-	- [Your password sucks...](basics/nonobvious_stuff/passwords.md)
-	- ["Command"? "Executable"?](basics/nonobvious_stuff/execute.md)
-	- [...and so does your router!](basics/nonobvious_stuff/networks.md)
-	- [Licenses - "Can I Use That Code?"](basics/nonobvious_stuff/foss.md)
-	- [Why Word Sucks feat. "Markdown"](basics/nonobvious_stuff/markdown.md)
-	- [Professionals > Sum of Tools](basics/nonobvious_stuff/conclusion.md)
-
-- [The Terminal: How I Learned to Stop Worrying and Love the Shell 🐚](basics/terminal/README.md)
-	- [Linux\*](basics/terminal/linux.md)
-	- [Windows - Powershell](basics/terminal/windows.md)
-	- [Mac](basics/terminal/mac.md)
-
-
-
-# Installing Python w/Packages
-- [Getting Python](installing/native/README.md)
-	- [Debian](installing/native/debian.md)
-	- [Ubuntu](installing/native/ubuntu.md)
-	- [Arch](installing/native/arch.md)
-	- [Fedora](installing/native/fedora.md)
-	- [Windows](installing/native/windows.md)
-	- [MacOS](installing/native/mac.md)
-
-- [Getting Packages](installing/packages/README.md)
-	- [Getting Packages - venv](installing/packages/venv.md)
-	- [Saving Packages - requirements.txt](installing/packages/requirements.txt.md)
-
-
-
-# Managing Python Projects
-- [Software Collaboration Essentials](basics/collaboration/README.md)
-	- [The Story of 1000 Monkeys 🐒](basics/collaboration/monkeys.md)
-	- [How Professional Monkeys Work 🍌](basics/collaboration/dvcs.md)
-	- [The git Video Game](basics/collaboration/git.md)
-
-- [Anatomy of a Python Project](projects/basics/README.md)
-	- [pyproject.toml](projects/basics/pyproject.toml.md)
-	- [poetry](projects/basics/poetry.md)
-
-- [Filling the Python Toolbelt](projects/tooling/README.md)
-	- [Auto-Formatting](projects/tooling/formatting.md)
-	- [Type Checking](projects/tooling/types.md)
-	- [Code Quality Analysis](projects/tooling/quality.md)
-	- [Parameterized Testing](projects/tooling/testing.md)
-	- [Containerization](projects/tooling/containers.md)
-	- ["Do I need all this?"](projects/tooling/conclusion.md)
-
-- [Anatomy of a Serious (TM) Python Project](projects/real_world/README.md)
-	- [podman + poetry](projects/real_world/podman_poetry.md)
-	- [.editorconfig](projects/real_world/editorconfig.md)
-	- [ruff](projects/real_world/ruff.md)
-	- [black](projects/real_world/black.md)
-	- [pre-commit](projects/real_world/pre_commit.md)
-	- [run.py](projects/real_world/run.py.md)
-
 
 
 # Python Guides for DTU Courses
@@ -75,23 +12,82 @@
 
 
 
+# Computer Essentials
+- [Handbook of Presumed Knowledge](basics/nonobvious_stuff/README.md)
+	- ["File"? "Filesystem"?](basics/nonobvious_stuff/files.md)
+	- [Your password sucks...](basics/nonobvious_stuff/passwords.md)
+	- ["Command"? "Executable"?](basics/nonobvious_stuff/execute.md)
+	- [...and so does the internet!](basics/nonobvious_stuff/http.md)
+	- [Licenses - "Can I Use That Code?"](basics/nonobvious_stuff/foss.md)
+	- [Markdown: The Gentler Text Format](basics/nonobvious_stuff/markdown.md)
+	- [Professionals > Sum of Tools](basics/nonobvious_stuff/conclusion.md)
+
+- [The Terminal: How I Learned to Stop Worrying and Love the Shell 🐚](basics/terminal/README.md)
+	- [Linux\*](basics/terminal/linux.md)
+	- [Windows - Powershell](basics/terminal/windows.md)
+	- [Mac](basics/terminal/mac.md)
+
+
+
+# Installing Python w/Packages
+- [Getting System Python 🐍](installing/native/README.md)
+	- [Debian](installing/native/debian.md)
+	- [Ubuntu](installing/native/ubuntu.md)
+	- [Arch](installing/native/arch.md)
+	- [Fedora](installing/native/fedora.md)
+	- [Windows](installing/native/windows.md)
+	- [macOS](installing/native/mac.md)
+
+- [Getting Python Packages 📦](installing/packages/README.md)
+	- [Getting Packages - `venv`](installing/packages/venv.md)
+	- [Saving Packages - `requirements.txt`](installing/packages/requirements.txt.md)
+
+
+
+# Managing Python Projects
+- [Software Collaboration Essentials](projects/collaboration/README.md)
+	- ["Collaborative Complexity": Story of 1000 Monkeys 🐒](projects/collaboration/monkeys.md)
+	- [A Practical Guide to `git` 🍌](projects/collaboration/git.md)
+
+- [Anatomy of a Python Project 🚧](projects/simple/README.md)
+	- [pyproject.toml](projects/simple/pyproject.toml.md)
+	- [poetry](projects/simple/poetry.md)
+
+- [Filling the Python Toolbelt](projects/tooling/README.md)
+	- [Auto-Formatting](projects/tooling/formatting.md)
+	- [Code Quality Analysis](projects/tooling/quality.md)
+	- [Parameterized Testing](projects/tooling/testing.md)
+	- [Type Checking](projects/tooling/types.md)
+	- [Containerization](projects/tooling/containers.md)
+	- ["Do I need all this?"](projects/tooling/conclusion.md)
+
+- [Anatomy of a Serious (TM) Python Project 🚧🚧](projects/real_world/README.md)
+	- [podman + poetry](projects/real_world/podman_poetry.md)
+	- [.editorconfig](projects/real_world/editorconfig.md)
+	- [ruff](projects/real_world/ruff.md)
+	- [black](projects/real_world/black.md)
+	- [pre-commit](projects/real_world/pre_commit.md)
+	- [run.py](projects/real_world/run.py.md)
+
+
+
 # Reference
 - [Cheat Sheets](reference/cheat_sheets/README.md)
-	- [git Cheat Sheet](reference/cheat_cheets/git.md)
+	- [Terminal Cheat Sheet](reference/cheat_sheets/terminal.md)
-	- [import Cheat Sheet](reference/cheat_shets/import.md)
+	- [git Cheat Sheet](reference/cheat_sheets/git.md)
-	- [Package Cheat Sheet](reference/cheat_shets/package.md)
+	- [Python Built-In Cheat Sheet](reference/cheat_sheets/stdlib.md)
+	- [Python Package Cheat Sheet](reference/cheat_sheets/package.md)
 
 - [Tips & Tricks](reference/tips/README.md)
-	- [Sofus' Tips](reference/tips/sofus.md)
+	- [\[Student\] Sofus' Hot Takes](reference/tips/sofus.md)
 
 - [Managed Ecosystems](installing/ecosystems/README.md)
 	- [conda](installing/ecosystems/conda.md)
 
-# Meta
-- [Improve This Book](meta/contributing/README.md)
-	- [How To: Report Bugs/Confusion](meta/contributing/bugs.md)
-	- [How To: Propose a Change](meta/contributing/change.md)
 
-- [Moderating Chat](meta/chat/README.md)
+
-	- [Using for Courses](meta/chat/course.md)
+# Meta
-	- [Rules / Code of Conduct](meta/chat/rules.md)
+- [Improve This Book: We Need You!](meta/contributing/README.md)
+	- [How To: Report Mistakes/Bugs/Confusion](meta/contributing/bugs.md)
+	- [How To: Run/Change this Book Locally](meta/contributing/preview.md)
+	- [How To: Propose a Change](meta/contributing/change.md)

src/basics/nonobvious_stuff/README.md

@@ -0,0 +1,10 @@
+*To be written...*
+
+The purpose of this section is to give a quick, readable summary of all the "stuff any person who needs to use software as a tool should know", which is rarely (if ever) covered in one go.
+- What's a file? What's a filesystem? 
+- What are the basic principles of keeping secret secret? Why do passwords suck? What can one do?
+- What is a "binary"? What does "executing" mean? Why does Python not make "double-clickable" files? How does it work instead? What does that mean for sharing my code?
+- What's an "IP"? What does it mean to "buy a website name"? What does "trust" mean when using the internet? What's an "HTTP", and what what are the basics of interacting with ex. remote data files?
+- Who owns code, when? What does "own" even mean? If I want to use someone's code, when am I allowed to do that? When I use other's code, what do I have to do wrt. attribution, citation, etc.? Which general kinds of abilities / freedoms might I be interested in buying, or insisting on (if I got the software without paying), when using other's software?
+- What does "text" mean, and what do you mean `.docx` isn't text? What methods of formatting raw text can I use  can I use to express myself using text?
+- What are some practical, career-boosting ways of thinking about software, when software isn't what I want to do with my life? What are some examples of non-obvious abilities I'll have, which my colleagues won't?

src/basics/nonobvious_stuff/conclusion.md

@@ -0,0 +1 @@
+*To be written...*

src/basics/nonobvious_stuff/execute.md

@@ -0,0 +1 @@
+*To be written...*

src/basics/nonobvious_stuff/files.md

@@ -0,0 +1 @@
+*To be written...*

src/basics/nonobvious_stuff/foss.md

@@ -0,0 +1 @@
+*To be written...*

src/basics/nonobvious_stuff/http.md

@@ -0,0 +1 @@
+*To be written...*

src/basics/nonobvious_stuff/markdown.md

@@ -0,0 +1 @@
+*To be written...*

src/basics/nonobvious_stuff/passwords.md

@@ -0,0 +1 @@
+*To be written...*

src/basics/terminal/README.md

@@ -0,0 +1,40 @@
+*To be written...*
+
+The purpose of this section is to give a very basic, practical summary of terminal concepts and practice.
+In this author's opinion, there exists no truly simple way of working with Python without this (no, busy IDE GUIs that presume the user to *already know what things mean*, or *replaces knowledge with magic to promote lock-in*, doesn't count).
+
+The goal is to make sure the reader understands the following, in all OSes:
+- `pwd`
+	- "Working Directory" is a thing.
+	- "Path" is a thing, "/" (or "\\", ick) is how.
+
+- `ls`
+	- A program that "lists" things (files/folders) in the "working directory".
+
+- `ls .`
+	- Identical to "ls"
+	- "." always means "curent working directory"
+	- `<program> <"argument">`, seperated by a space, runs "program" and gives it "argument"
+- `ls ..`
+	- Lists files in the "parent" of the "working directory"
+	- ".." always means "parent of current working directory"
+- `ls Desktop`
+	- Lists files in the folder "Desktop", under the current "working directory".
+- `ls ./Desktop` or `ls .\Desktop`
+	- Same as `ls Desktop`.
+
+- `ls -l -a`
+	- "Flags" change how programs work, and go behind "-". "-l" prints the list as a, well, more listy list.
+- `ls -al`
+	- Many programs let you smush "flags" together behind a single "-"
+
+- `cd Desktop`
+	- A program that lets you change your "working directory".
+- `cd ..`
+	- Changes "working directory" to the parent of the current "working directory".
+- `cd ../..`
+	- Changes "working directory" to the parent of the parent of the current "working directory".
+
+- Gotcha. But where do I find other programs can I use?
+	- See <https://terminalcheatsheet.com/>
+	- Powershell probably needs a different resource. Or to just go away.

src/basics/terminal/linux.md

@@ -0,0 +1 @@
+*To be written...*

src/basics/terminal/mac.md

@@ -0,0 +1 @@
+*To be written...*

src/basics/terminal/windows.md

@@ -0,0 +1 @@
+*To be written...*

src/course_guides/dtu_compute/02502.md

@@ -1 +1,4 @@
 # 02502 - Image Analysis
+*To be written...*
+
+See <https://github.com/RasmusRPaulsen/DTUImageAnalysis> for where to publically source info.

src/course_guides/dtu_compute/README.md

@@ -1 +1,10 @@
-# DTU Compute
+*To be written...*
+
+The goal with this section is to provide step-by-step guides to courses found at "DTU Compute".
+This should be accomplished primarily by **linking to other guides in this book**, rather than writing dedicated material, whenever possible.
+
+For teaching content with minor variations, the sustainable path is for professors / TAs to personally make pull requests into the `site-support` repo.
+This opens up the ability to have an effective, asynchronous review process involving all courses that share reliance on any particular subset of this book's articles (`git`-enabled efficient politics, what's not to love?)
+
+This also opens up the ability of students at any DTU Compute course to themselves make a contribution describing their course.
+This should, of course, be talked over with the professor first.

src/course_guides/polytech/01001_01003.md

@@ -1 +1,2 @@
 # 01001/01003 - Mathematics 1a
+*To be written...*

src/course_guides/polytech/02002_02003.md

@@ -1 +1,2 @@
 # 02002/02003 - Computer Programming
+*To be written...*

src/course_guides/polytech/README.md

@@ -1 +1,7 @@
-# Polytech Foundation
+*To be written...*
+
+The goal with this section is to provide step-by-step guides to courses in the "polytechnical foundation".
+This should be accomplished primarily by **linking to other guides in this book**, rather than writing dedicated material, whenever possible.
+
+For teaching content with minor variations, the sustainable path is for professors / TAs to personally make pull requests into the `site-support` repo.
+This opens up the ability to have an effective, asynchronous review process involving all courses that share reliance on any particular subset of this book's articles (`git`-enabled efficient politics, what's not to love?)

src/installing/here-be-magic.md

@@ -1 +0,0 @@
-# BEWARE: Here Be Magic

src/installing/native/README.md

@@ -1,3 +1,7 @@
-# TODO
+*To Be Finished...*
-- Decide which Python versions the book will deal with.
+
-- Incorporate more native Python install docs: https://docs.python.org/3/using/index.html
+The goal of this section is to provide a practical, step-by-step guide to getting Python on any OS with minimal pain, now and later.
+It is also intended to convey basic, critical stuff to watch out for.
+Finally, it should include thorough references for those wanting to dig deeper.
+
+As with the rest of the book, it should be written in an accessible style.

src/installing/packages/README.md

@@ -0,0 +1,11 @@
+*To Be Written...*
+
+The goal of this section is to provide a practical, step-by-step guide to getting Python packages installed, presuming **any** already-working Python installation.
+
+At this stage, the **greatest danger is "easy just-works """solutions"""**.
+In this ecosystem, they tend to be *ridden* with little gotchas, OS-dependent behavior, and confusing ways of misconfiguring them.
+
+Thus, a deliberate decision is taken to presume *very basic* terminal knowledge (as provided by the dedicated section of this very book), and barebones working system Python installation, and explain packaging in the only reliably built-in and future-proof way: `venv` and `pip`.
+Special care is especially paid to `requirements.txt`, which at this stage is the only comprehensible way of "saving" what packages (and at what versions!) are installed in a `.venv` for ex. use by others.
+
+As with the rest of the book, it should be written in an accessible style.

src/installing/packages/requirements.txt.md

@@ -0,0 +1 @@
+*To Be Written...*

src/installing/packages/venv.md

@@ -0,0 +1 @@
+*To Be Written...*

src/introduction.md

@@ -0,0 +1,35 @@
+# DTU Python Support Guide
+Welcome!
+This book is written to help DTU students install and use Python at DTU.
+Use the left sidebar to find the guide you're looking for.
+
+You can expect guides explaining:
+- **Python in DTU Courses**: Helping you use Python in specific courses.
+- **Computer Essentials**: Helping anybody that uses software as a tool get a sense of the essential ideas behind how computers work.
+- **Installing Python w/Packages**: Helping you install Python, and Python packages like `numpy`, on any OS.
+- **Managing Python Projects**: Helping you use Python on a team, with just enough tools to make your life easier.
+- **Reference**: Resources for you! Cheat sheets, tips & tricks, and more niche ways of installing and using Python.
+- **Meta**: Step-by-step instruction for reporting mistakes and helping improve this book. We need you!
+
+We **strongly suggest** you engage with the Support Team and/or your fellow students on our help forum, <https://chat.timesigned.com>.
+Login is your **DTU account**.
+
+We hope you find this book useful!
+
+
+
+# Development & Contribution
+If you find the book useful, please help us make it better by reporting bugs and/or helping improve the book!
+- Source Code: <https://git.sofus.io/python-support/site-support>
+- Current Issues / Roadmap: <https://git.sofus.io/python-support/site-support/issues>
+- Current Proposed Changes: <https://git.sofus.io/python-support/site-support/pulls>
+
+You can find detailed detailed instructions on how to contribute at the [dedicated page of the book](./meta/contributing/README.md).
+
+
+
+# License
+This book is released under the [AGPL software license](https://www.tldrlegal.com/license/gnu-affero-general-public-license-v3-agpl-3-0).
+In general (**NOTE: This is not legal advice, and is not legally binding**), the AGPL is designed to protect your freedom to ex. use, sell, modify, and distribute the contents of the book & associated source code, so long as you *also extend the same freedoms to anybody you distribute it/derivative works to*.
+
+For the legally valid license terms, please refer to the full license text: <https://www.gnu.org/licenses/agpl-3.0.en.html>.

src/meta/chat/course.md

@@ -1 +0,0 @@
-# Using for Courses

src/meta/contributing/README.md

@@ -0,0 +1,9 @@
+*To be written...*
+
+The goal of this section is to describe, to anybody interested in helping out with the book in any way, how they can do that.
+
+Potential contributors have many different skill levels, experiences, and willingness to overcome barriers to entry.
+We segment them as follows:
+- Bug Reporter: Sees something wrong, wants to tell us about it. This guide focuses on how they login to gitea (with their DTU account) to create an "Issue".
+- Experimenter: Wants to play around with the book in their own sandbox. This guide focuses on how to clone & run the book locally.
+- Change Proposer: Wants to write something new. Their tolerance for barriers to entry is higher. This guide should presume "bug reporter" and "experimenter" was read, ask them to read the `git` section, and focuses on making a Pull Request from a personal branch.

src/meta/contributing/bugs.md

@@ -0,0 +1 @@
+*To be written...*

src/meta/contributing/change.md

@@ -0,0 +1 @@
+*To be written...*

src/meta/contributing/preview.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/basics/README.md

@@ -1 +0,0 @@
-# Anatomy of a Python Project

src/projects/collaboration/README.md

@@ -0,0 +1,9 @@
+*To be finished...*
+
+The goal of this section is to concisely and effectively explain:
+- The complexities of collaboration, feat. real world problems (not just in software!).
+- What DVCS solves, and when/why "easier" solutions just don't cut it.
+- A barebones practical, working guide to using `git` every day.
+
+A general guide in `git.md` is already written as a starting point.
+To be sure, it needs adjusting.

src/projects/real_world/README.md

@@ -1 +1,8 @@
-# Anatomy of a Serious (TM) Python Project
+*To be written...*
+
+The goal of this section is to describe a "real-world" Python project, which has the essential nice tooling that one would expect be used in any well-tooled project.
+It is **not** an attempt to *cram everything into one project*, and it's not designed to be more than a learning resource (though that goal may incidentally lead to it being a decent boilerplate for new Python projects).
+
+Currently `poetry` is also used, but this may not be the best idea.
+Supposedly, `pip`s dependency resolver is now on-par with Poetry, as well as natively supporting `pyproject.toml`.
+`poetry` has a bunch of gotchas that may be perfectly avoidable.

src/projects/real_world/black.md

@@ -1 +1 @@
-# black
+*To be written...*

src/projects/real_world/editorconfig.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/real_world/podman_poetry.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/real_world/pre_commit.md

@@ -1 +1 @@
-# pre-commit
+*To be written...*

src/projects/real_world/ruff.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/real_world/run.py.md

@@ -1 +1 @@
-# run.py
+*To be written...*

src/projects/reproducibility/README.md

@@ -1 +0,0 @@
-# Reproducible Python

src/projects/simple/README.md

@@ -0,0 +1,9 @@
+*To be written...*
+
+The goal of this section is to describe a small, real-world Python project using `pyproject.toml`.
+
+Currently `poetry` is also used, but this may not be the best idea.
+Supposedly, `pip`s dependency resolver is now on-par with Poetry, as well as natively supporting `pyproject.toml`.
+`poetry` has a bunch of gotchas that may be perfectly avoidable.
+
+Certain tools like `.editorconfig` may also be worth putting in this first project.

src/projects/simple/poetry.md

@@ -0,0 +1 @@
+*To be written (or not?)...*

src/projects/simple/pyproject.toml.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/tooling/README.md

@@ -0,0 +1,10 @@
+*To be written...*
+
+The goal of this section is to describe the most important tools that help one work with Python projects, *especially* those that effectivize collaboration.
+- Auto-formatting: Exceptionally underrated, and a TA's dream.
+- Code quality analysis: In dynamic Python especially, having to satisfy a decent linter is one of the easiest ways to get started finding and expelling bugs.
+- Parameterized testing: Without going into too much detail, working with `pytest` and a little `hypothesis` for that contracty flavor.
+- Type checking: Just a bit about Python actually being a perfectly static language, if one works a little for it.
+
+When one particular tool shines as a mostly-uncontested standard (ex. `pytest`, `black`), it should be presumed and talked about specifically.
+Otherwise (ex. `ruff`), some options can be mentioned but otherwise left for the Serious (TM) Python Project section.

src/projects/tooling/conclusion.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/tooling/containers.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/tooling/formatting.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/tooling/quality.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/tooling/testing.md

@@ -0,0 +1 @@
+*To be written...*

src/projects/tooling/types.md

@@ -0,0 +1 @@
+*To be written...*

src/reference/cheat_cheets/git.md

@@ -1 +0,0 @@
-# git Cheat Sheet

src/reference/cheat_sheets/README.md

@@ -1 +1,7 @@
-# Cheat Sheets
+*To be written...*
+
+The goal of this section is to provide quick and easy reference to running/using:
+- Terminal commands
+- git commands
+- Built-in Python libraries
+- Common/useful Python libraries.

src/reference/cheat_sheets/git.md

@@ -0,0 +1 @@
+*To be written...*

src/reference/cheat_sheets/package.md

@@ -0,0 +1 @@
+# Python Package Cheat Sheet

src/reference/cheat_sheets/packages.md

@@ -0,0 +1 @@
+*To be written...*

src/reference/cheat_sheets/stdlib.md

@@ -0,0 +1 @@
+*To be written...*

src/reference/cheat_sheets/terminal.md

@@ -0,0 +1 @@
+*To be written...*

src/reference/cheat_shets/import.md

@@ -1 +0,0 @@
-# import Cheat Sheet

src/reference/cheat_shets/package.md

@@ -1 +0,0 @@
-# Package Cheat Sheet

src/reference/ecosystems/README.md

@@ -0,0 +1,5 @@
+*To be written...*
+
+Ecosystems may be required by a course.
+The goal of this section is to provide basic instructions thereof.
+Special attention should be paid to their unique "gotchas".

src/reference/ecosystems/conda.md

@@ -0,0 +1 @@
+*To be written...*

src/reference/tips/README.md

@@ -1 +1,7 @@
-# Tips & Tricks
+*To be writen...*
+
+The goal of this section is to collect several hot takes (read: personal, opinionated) on tips & tricks when using Python, to give a wider range of perspectives on the language - ESPECIALLY across fields.
+Thus helping the "but how is the *actually* useful to *me*"?
+
+Perspectives should be wide-ranging: The support team itself, beginners just discovering things, researchers, working engineers, and so on.
+It should not be considered officially endorsed, but it should be reviewed for correctness), but rather treated as some food-for-thought for anybody interested in learning from a wider community.

src/reference/tips/sofus.md

@@ -1,25 +1,21 @@
-To be Written...
+*To be Finished...*
 
+*Important to me is the intuition that allows me to express any engineering needs "semantically". This involves trying to remain curious, and not simply take the "easy" way (at least, what seems easy ,but isn't. Global variables and for..append come to mind), but to make a goal of exploring new ways to more elegantly express concepts whenever using any tool. For fun, for some, but more importantly, to be better at mapping engineering needs to the abilities of my tools.*
 
-# Email Copy/Paste
+Some initial stuff I think is nice to start with.
-From my own email.
-
-*Especially important to me is to support the development of the intuition that allows students to express their engineering needs semantically, and the curiosity to not simply take the "easy" way (at least, what seems easy ex. global variables and for..append), but to make a daily goal of exploring new ways to more elegantly express concepts using the available language tools. For fun, for some, but more importantly, so that all can create better behaved software tools to accomplish their own unique engineering goals.*
-
-With those big words, here goes!
 - `import this`: I think PEP 20 really sets the tone for the whole 'computational thinking' buzz. 10min evangelizing it is time well-spent. I think so, anyway :)
 - `help(anything)` and `dir()`: Python's own help system is actually quite nice. People should know built-in help systems like this. It especially helps when trying to figure out what to google / cutting through too-dense library documentation.
 
 Moving past day 1:
-- `complex(real = 1, imag = 2)`: A godsend for any student checking their imaginary calculations.
+- `complex(real = 1, imag = 2)`: Complex numbers got you down? No they don't :)!
-- `range(10, -1, -1)`: That `range` is [s,e) with a direction too is strange at first, and this is a helpful explainer.
+- `range(10, -1, -1)`: That `range` is [s,e) with a direction too is strange at first, and trying to parse this is a helpful explainer.
-- `from pathlib import Path`: It's not immediately obvious what's wrong with `open("C:\Users\MrBean\...")`, until the TA tries to run the code. `pathlib` has been solving headaches since 2012's PEP 428.
+- `from pathlib import Path`: It's not immediately obvious what's wrong with `open("C:\Users\MrBean\...")`, until your TA / friend / cat tries to run the code. `pathlib` has been solving headaches since 2012's PEP 428.
-- `{s % 2 for s in range(10)}`: Friends don't let friends `for...append`! Especially not when deduplication is desired!
+- `{s % 2 for s in range(10)}`: Friends don't let friends `for...append`! Especially not when deduplication is desired! Set comprehensions are near-magic, and so are their cousins (list-comprehensions, dict-comprehensions)!
 
-As students get stronger:
+What about day 3?
-- `with open(...) as f: ...`: `close()` has icky `free(*ptr)` vibes. `with` has such a nice mental model, which I feel everyone using Python deserves to be introduced to from the start.
+- `with open(...) as f: ...`: `close()` has icky `free(*ptr)` vibes. `with` has such a nice mental model, which I feel everyone using Python deserves to be introduced to.
-- `settings_dict = tomllib.load(settings_file)`: Most people will need to configure their software one day. Config files are the lowest barrier to entry, and TOML is one of the simplest and least brittle. *Hopefully PEP 723 makes it through, in which case having met TOML will be even more vital!*
+- (3.11+ only) `settings_dict = tomllib.load(settings_file)`: Most people will need to have a way of configuring a script one day. Config files are nice for doing that without asking people to change source code. TOML is one of the simplest and least brittle. *Hopefully PEP 723 makes it through, in which case having met TOML will be even more vital!*
-- `itertools.count`: That iterators can run forever, and that this is super useful, is one of those "aha" moments that I think is kind of important for everyone to get behind.
+- `itertools.count`: That iterators can run forever, and that this is super useful, is one of those "aha" moments that I can get behind. "But when does it stop them?", well - whenever it's done, just hit that `break` :)!
-- `functools.lru_cache`: I've always found recursive `fibbonacci` a good little mind bender when unfamiliar with recursion. `lru_cache` makes it and other things fast! Plus, what better way to stimulate respect for caches than demonstrating how to abuse a simple one?
+- `functools.lru_cache`: Recursive `fibbonacci` is nice. But it's slow, you say! `lru_cache` makes it fast, by keeping the function result around if the function is ever called with the same arguments. The insight of, "wait, this will break horribly if the result ever changes with the same arguments" is a healthy one. The dangers of caching is one of those things we don't really believe until it's too late.
 
-There are more, of course; `re` with regex101.com should be common knowledge, as should `shutil` for the more dangerous filesystem operations, `subprocess.run`, `print(file=<some_file_object>)`, and so on... It is all subjective anyway, but I hope this gave a nice overview of how I like to think about things.
+There are more, of course; `re` with regex101.com should be common knowledge, as should `shutil` for the more dangerous filesystem operations, `subprocess.run` to run shell commands, `print(file=<some_file_object>)` to print directly to an `open()`ed file, and so on... It is all subjective anyway. Go play!