From 26e33cfd25b251d840af6f0ac3f606103a158bf1 Mon Sep 17 00:00:00 2001 From: anin Date: Mon, 10 Aug 2026 22:42:55 +0800 Subject: [PATCH 1/6] docs: rewrite image paths to jsDelivr CDN, add VS Code setup screenshots - build_release.py: rewrite ../assets/img/ paths to jsDelivr CDN URLs - pages/ide-setup.md: add VS Code interpreter screenshot, CDN image links - release/*.html: regenerate with CDN-hosted images --- build_release.py | 11 +- pages/ide-setup.md | 4 +- release/ide-setup.html | 848 +++++++++--------- release/index.html | 804 ++++++++--------- release/installation.html | 1292 ++++++++++++++-------------- release/recommended-reading.html | 838 +++++++++--------- release/unix-basics.html | 1382 +++++++++++++++--------------- release/virtual-environment.html | 1116 ++++++++++++------------ 8 files changed, 3151 insertions(+), 3144 deletions(-) diff --git a/build_release.py b/build_release.py index fc6503a..b24fb6e 100644 --- a/build_release.py +++ b/build_release.py @@ -76,8 +76,15 @@ def slugify(s): def render_body(md_text): """Render markdown to HTML and add heading ids / collect a TOC.""" html = _md.markdown(md_text, extensions=MD_EXTENSIONS) - # TODO: image src still uses the local relative path (`../assets/img/...`). - # Rewrite to a GitHub permalink before publishing (see file header). + # Rewrite local image paths (../assets/img/...) to GitHub permalink + # via jsDelivr CDN, so the release HTML is fully self-contained and + # needs no bundled assets/ folder. + GITHUB_CDN = "https://cdn.jsdelivr.net/gh/fyq163/python-setup-moodle@main" + html = re.sub( + r'src="\.\./assets/img/([^"]+)"', + lambda mo: 'src="%s/assets/img/%s"' % (GITHUB_CDN, mo.group(1)), + html, + ) # Turn any leftover GitHub-style alert markers into emoji callouts. html = re.sub( r'
\s*

\s*\[!(NOTE|TIP|WARNING|IMPORTANT|CAUTION)\]\s*', diff --git a/pages/ide-setup.md b/pages/ide-setup.md index aef3a88..0ba6511 100644 --- a/pages/ide-setup.md +++ b/pages/ide-setup.md @@ -18,10 +18,11 @@ identical: 4. Select the interpreter: press `Ctrl/Cmd + Shift + P`, type **"Python: Select Interpreter"**, and choose the environment you made in Chapter 3 (the `.venv` or conda env). The bottom-right status bar then shows that Python. + ![vscode plugin marketplace](https://cdn.jsdelivr.net/gh/fyq163/python-setup-moodle@main/assets/img/vscode-extension-python.png) 5. Use the built-in terminal (`Ctrl/Cmd + `` `) to run `uv run main.py` or `python main.py`. -![TODO: Screenshot of VS Code β€” the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.](../assets/img/placeholder.svg) +![Screenshot of VS Code β€” the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.](https://cdn.jsdelivr.net/gh/fyq163/python-setup-moodle@main/assets/img/vscode-interpreter-selection.png) > πŸ’‘ > Once the interpreter is selected, the play button (β–Ά) and the terminal both use *your* @@ -57,4 +58,3 @@ Python your shell currently has active. GitHub Copilot is an AI pair-programmer that suggests code as you type. **Students get it free** (and many other developer tools) through the [GitHub Copilot - Information Technology Services - HKU](https://its.hku.hk/software/github-copilot/) -pack with a school email. \ No newline at end of file diff --git a/release/ide-setup.html b/release/ide-setup.html index 77b4730..49f88a7 100644 --- a/release/ide-setup.html +++ b/release/ide-setup.html @@ -1,424 +1,424 @@ - - - - - -4 Β· Code Editors & IDEs - - - -

Python Setup Guide
-
- -
- -
-

Pick any editor and point it at the Python interpreter you created in Chapter 3. You -can also use the terminal skills from Chapter 1 inside the editor's built-in terminal.

-

Visual Studio Code family (VS Code, Cursor, CodeBuddy, Trae…)

-

These editors share the same engine and the same Python extension, so the steps are -identical:

-
    -
  1. Install VS Code (or Cursor / CodeBuddy / Trae).
    2. -
  2. Open the Extensions view (Ctrl/Cmd + Shift + X) and install Python (by - Microsoft). This also installs the Pylance language server.
    3. -
  3. Open your project folder (File β†’ Open Folder).
    4. -
  4. Select the interpreter: press Ctrl/Cmd + Shift + P, type "Python: Select - Interpreter", and choose the environment you made in Chapter 3 (the .venv or conda - env). The bottom-right status bar then shows that Python.
    5. -
  5. Use the built-in terminal (Ctrl/Cmd + ``) to run uv run main.py or - python main.py.
    6. -
-

TODO: Screenshot of VS Code β€” the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.

-
-

πŸ’‘ -Once the interpreter is selected, the play button (β–Ά) and the terminal both use your -project's Python β€” not the system one. That is the whole point.

-
-

PyCharm Community Edition

-

PyCharm is a Python-focused IDE with a free Community edition (the Professional -edition adds web/DB features and is paid, though free for students).

-
    -
  1. Download PyCharm Community.
    2. -
  2. New Project β†’ choose a location. Under "Python Interpreter", select Previously - configured interpreter and point it at your conda env or the python inside - .venv/bin (macOS/Linux) / .venv\Scripts\python.exe (Windows). Or let PyCharm create - a new venv for you.
    3. -
  3. Right-click a .py file and choose Run.
    4. -
-

References: PyCharm + conda, -Python path

- -

A newer wave of editors runs inside the terminal β€” perfect if you liked Chapter 1:

-
    -
  • opencode β€” an open agentic coding CLI.
    • -
  • kilo (within OpenCode) and mimo β€” terminal-based assistants.
    • -
-

They are just editors with an AI chat bolted on; everything from Chapter 1 (paths, cd, -running scripts) still applies. Launch them in your project folder and they use whatever -Python your shell currently has active.

-

GitHub Copilot β€” university subscription

-

GitHub Copilot is an AI pair-programmer that suggests code as you type. Students get it -free (and many other developer tools) through the GitHub Copilot - Information Technology Services - HKU -pack with a school email.

-
-
-
- -
-

Python Setup Guide · Back to home

-

Content is a work in progress — see the project readme for status.

-
- - + + + + + +4 Β· Code Editors & IDEs + + + +
Python Setup Guide
+
+ +
+ +
+

Pick any editor and point it at the Python interpreter you created in Chapter 3. You +can also use the terminal skills from Chapter 1 inside the editor's built-in terminal.

+

Visual Studio Code family (VS Code, Cursor, CodeBuddy, Trae…)

+

These editors share the same engine and the same Python extension, so the steps are +identical:

+
    +
  1. Install VS Code (or Cursor / CodeBuddy / Trae).
    2. +
  2. Open the Extensions view (Ctrl/Cmd + Shift + X) and install Python (by + Microsoft). This also installs the Pylance language server.
    3. +
  3. Open your project folder (File β†’ Open Folder).
    4. +
  4. Select the interpreter: press Ctrl/Cmd + Shift + P, type "Python: Select + Interpreter", and choose the environment you made in Chapter 3 (the .venv or conda + env). The bottom-right status bar then shows that Python. + vscode plugin marketplace
    5. +
  5. Use the built-in terminal (Ctrl/Cmd + ``) to run uv run main.py or + python main.py.
    6. +
+

Screenshot of VS Code β€” the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.

+
+

πŸ’‘ +Once the interpreter is selected, the play button (β–Ά) and the terminal both use your +project's Python β€” not the system one. That is the whole point.

+
+

PyCharm Community Edition

+

PyCharm is a Python-focused IDE with a free Community edition (the Professional +edition adds web/DB features and is paid, though free for students).

+
    +
  1. Download PyCharm Community.
    2. +
  2. New Project β†’ choose a location. Under "Python Interpreter", select Previously + configured interpreter and point it at your conda env or the python inside + .venv/bin (macOS/Linux) / .venv\Scripts\python.exe (Windows). Or let PyCharm create + a new venv for you.
    3. +
  3. Right-click a .py file and choose Run.
    4. +
+

References: PyCharm + conda, +Python path

+ +

A newer wave of editors runs inside the terminal β€” perfect if you liked Chapter 1:

+
    +
  • opencode β€” an open agentic coding CLI.
    • +
  • kilo (within OpenCode) and mimo β€” terminal-based assistants.
    • +
+

They are just editors with an AI chat bolted on; everything from Chapter 1 (paths, cd, +running scripts) still applies. Launch them in your project folder and they use whatever +Python your shell currently has active.

+

GitHub Copilot β€” university subscription

+

GitHub Copilot is an AI pair-programmer that suggests code as you type. Students get it +free (and many other developer tools) through the GitHub Copilot - Information Technology Services - HKU

+
+
+
+ +
+

Python Setup Guide · Back to home

+

Content is a work in progress — see the project readme for status.

+
+ + diff --git a/release/index.html b/release/index.html index 9d8ad6d..8c750fa 100644 --- a/release/index.html +++ b/release/index.html @@ -1,402 +1,402 @@ - - - - - -Python Setup Guide for HKU Beginners - - - -
Python Setup Guide
-
-The University of Hong Kong · Programming Bootcamp -

Welcome, new HKU students 👋

-

This guide helps you set up a Python environment on your own computer and use it to -learn your first Python lessons — even if you have never opened a terminal before. -Pick the chapters you need; skip the ones you already know.

-
-🐍 CPython (reference implementation) -💻 macOS · Windows · Linux -🚀 Beginner friendly -
-
-
-
-

Why learn this when AI agents can code for you?

-

An agent can write Python, but -it cannot install the interpreter on your machine, fix a broken PATH, or tell -you why python points to the wrong binary. When a script crashes, you still have -to run it, read the traceback, and rebuild the environment yourself β€” and you -cannot do any of that without a working setup. Learning this once means you are -never blocked just because a tool failed.

-

python version

-

We use CPython, the official -reference implementation of Python, rather than alternatives such as PyPy. -PyPy is a different implementation with a JIT compiler that can run some programs -much faster, but it is not the standard interpreter, may lag behind on new Python -features, and is rarely what courseware or libraries expect. CPython is what -python.org ships and what every tutorial in this guide assumes.

-

How to use this guide:

-

click a card below to jump to that chapter. Tags show -whether a chapter is required or can be skipped.

-
-

Chapters

- -
-
-

Python Setup Guide · Back to home

-

Content is a work in progress — see the project readme for status.

-
- - + + + + + +Python Setup Guide for HKU Beginners + + + +
Python Setup Guide
+
+The University of Hong Kong · Programming Bootcamp +

Welcome, new HKU students 👋

+

This guide helps you set up a Python environment on your own computer and use it to +learn your first Python lessons — even if you have never opened a terminal before. +Pick the chapters you need; skip the ones you already know.

+
+🐍 CPython (reference implementation) +💻 macOS · Windows · Linux +🚀 Beginner friendly +
+
+
+
+

Why learn this when AI agents can code for you?

+

An agent can write Python, but +it cannot install the interpreter on your machine, fix a broken PATH, or tell +you why python points to the wrong binary. When a script crashes, you still have +to run it, read the traceback, and rebuild the environment yourself β€” and you +cannot do any of that without a working setup. Learning this once means you are +never blocked just because a tool failed.

+

python version

+

We use CPython, the official +reference implementation of Python, rather than alternatives such as PyPy. +PyPy is a different implementation with a JIT compiler that can run some programs +much faster, but it is not the standard interpreter, may lag behind on new Python +features, and is rarely what courseware or libraries expect. CPython is what +python.org ships and what every tutorial in this guide assumes.

+

How to use this guide:

+

click a card below to jump to that chapter. Tags show +whether a chapter is required or can be skipped.

+
+

Chapters

+ +
+
+

Python Setup Guide · Back to home

+

Content is a work in progress — see the project readme for status.

+
+ + diff --git a/release/installation.html b/release/installation.html index e58a221..7853e64 100644 --- a/release/installation.html +++ b/release/installation.html @@ -1,646 +1,646 @@ - - - - - -3 Β· Installing Python - - - -
Python Setup Guide
-
- -
- -
-

The detailed chapter. Three methods (standalone / conda / uv) Γ— three platforms (macOS -arm64, Windows amd64, Linux x86_64). Pick one method β€” we recommend uv for -beginners. You only need Python installed once per machine.

-

How to choose a version & architecture

-
    -
  • Version: pick a recent stable release β€” Python 3.12 or 3.13 are safe choices - in 2026. Not Python 2 (dead since 2020) and the very latest .0 release if a package - you need hasn't caught up yet.
    • -
  • Architecture (your CPU type):
    • -
  • macOS: Apple Silicon Macs (M1/M2/M3/M4) β†’ arm64. Intel Macs β†’ x86_64.
    • -
  • Windows: almost all modern PCs β†’ amd64 (also called x64).
    • -
  • Linux: most desktops/servers β†’ x86_64; newer ARM boards β†’ aarch64.
    • -
-

If you are unsure, the installer pages below usually auto-detect the right one.

-
-

⚠️ Choose a Stable Release (all methods & platforms). Whether you use the standalone -installer, conda, or uv, pick a Stable Release β€” the latest stable version (e.g. -Python 3.12.x or 3.13.x). Do not download or install anything marked Pre-release or -Development: those builds are for testing and may be unstable or break your packages.

-
- -

Best for beginners: one fast tool, local environments, minimal fuss.

-
    -
  1. Install uv. Open the uv website (docs.astral.sh/uv) in your browser, go to the - Installation page, and download the installer for your system (macOS, Windows, or - Linux). Run it and follow the on-screen prompts β€” pick the default options when asked. - When it finishes, uv is installed.
    2. -
-
-

πŸ“ After install, close the terminal and open a new one, then verify with uv --version.

-
-
    -
  1. Install a Python and create your first project:
    2. -
-
uv python install 3.12          # download CPython 3.12 (one time)
-uv init myproject               # create a project folder with a .venv
-cd myproject
-uv pip install pandas           # install a package into this project
-uv run main.py                  # run a script with this project's Python
-
-
    -
  • After closing the terminal, you do not need to "activate" β€” just run - uv run <script> from the project folder and uv uses the local .venv automatically.
    • -
  • To pin a pre-installed interpreter (avoid re-downloading), set it in - pyproject.toml: requires-python = "&gt;=3.12" and uv venv --python 3.12.
    • -
- -

Best if you will use data-science packages with non-Python system dependencies.

-
    -
  1. Install Miniconda. Open the Miniconda website (anaconda.com) in your browser, find the - Miniconda download for your system (macOS, Windows, or Linux), and download the - installer. Run it and follow the on-screen prompts β€” when asked whether to "Add Miniconda - to PATH" or "run conda init", you can leave the default; we explain conda init below. - When it finishes, Miniconda is installed.
    2. -
-
-

πŸ“ After install, close the terminal and open a new one so the conda command is -available. Then verify with conda --version. -2. Create and activate an environment:

-
-
conda create --name py312 python=3.12
-conda activate py312
-python --version
-
-
    -
  • After closing the terminal, the environment deactivates. Re-enter it with - conda activate py312 β€” the environment still exists globally, so you never recreate it.
    • -
  • To save disk space, point conda at a Python you already installed instead of letting - it download another copy: conda create --name py312 --clone base or use - conda create --name py312 python=$(python3 --version 2>&1 | cut -d' ' -f2).
    • -
-

What to do if you are asked to run conda init

-

The first time you open a terminal after installing conda, conda activate may fail with a -message like "To activate this environment, run conda init first." Here is why, and what -to do.

-

Why conda init is needed. conda activate only works if conda has hooked into your -shell's startup file. conda init writes a small block of code into that file so the shell -loads conda automatically every time you open a new terminal. Until you do this, the shell -doesn't know what conda activate means.

-

How to do it. Just run it once for your shell (the command is harmless to re-run):

-
conda init bash        # Linux default shell
-conda init zsh         # macOS default shell
-conda init powershell  # Windows (run in PowerShell)
-
-

Then close and reopen the terminal β€” the change only takes effect in new sessions.

-

Where does conda write the code? -- macOS / Linux (unix): into your shell's rc file in your home directory β€” - ~/.bashrc for bash, ~/.zshrc for zsh. Open a new terminal and conda is ready. -- Windows: into your PowerShell profile script (e.g. - C:\Users\<you>\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1), - not a .bashrc/.zshrc (those don't exist on Windows). If you use Git Bash on Windows, - conda instead writes to ~/.bashrc under your Git install.

-

After conda init, you get a permanent prompt prefix. Every new terminal will now show -your current conda environment in the prompt, e.g. (base) when no environment is active. -That (base) is a reminder of which environment your commands run in.

-
-

⚠️ Don't use base as your main environment. base is conda's built-in default env. -Keep it clean and instead conda activate py312 (or any env you create) for real work, -so packages for different projects don't clash. Tip: run conda config --set -auto_activate_base false to stop conda from auto-activating base every time you open a -terminal.

-
-

Method C Β· Standalone installer

-

Best if you want the official Python and nothing else.

-

Windows

-
    -
  1. Open the python.org Windows download page in your browser.
    2. -
  2. Download the Windows installer (64-bit) β€” the amd64 executable.
    3. -
  3. Important: on the first setup screen, tick "Add python.exe to PATH" before - clicking Install Now.
    4. -
  4. After install, reopen PowerShell and verify:
    5. -
-
python --version
-# Python 3.12.x   (on Windows the command is `python`, not `python3`)
-
-

Most Windows personal computers are amd64 architecture; if you have a Microsoft Surface, it may be arm64. -To be sure which one you have, run this in PowerShell and check the value it prints:

-
echo $env:PROCESSOR_ARCHITECTURE
-# ARM64  -> you have an Arm-based Surface; download the arm64 installer
-# AMD64  -> standard x64 PC; download the amd64 installer
-
-

Typical install path:

-
C:\Users\<you>\AppData\Local\Programs\Python\Python312\
-
-
-

⚠️\ -If python --version still says "command not found" or opens the Microsoft Store, you -forgot to tick Add to PATH. Re-run the installer and choose "Modify", then enable -"Add Python to environment variables".

-
-

macOS

-

Two routes:

-
    -
  • Official installer β€” open the python.org macOS download page in your browser and - always choose the "macOS 64-bit universal2" build. A universal2 installer works on - both Apple Silicon (arm64) and Intel Macs, so you don't need to figure out your chip. - Avoid the "macOS 64-bit Intel-only installer": it only supports Intel Macs and only exists - for older Python versions, so it's already outdated. Download the .pkg, double-click to - run, and follow the prompts. It may ask you to manually adjust PATH β€” see "after install" - below.
    • -
  • Homebrew (recommended if you already use it): open the Homebrew website (brew.sh), - install Homebrew first if you don't have it, then use it to install Python 3.12. It adds - itself to PATH automatically when brew is set up.
    • -
-

Typical paths:

-
# Official installer:
-/Library/Frameworks/Python.framework/Versions/3.12/bin/python3
-# Homebrew:
-/opt/homebrew/bin/python3        # Apple Silicon
-/usr/local/bin/python3           # Intel
-
-

Linux

-

Use your package manager, or build from source.

-
    -
  • Open your distro's software tool (or the package manager the system already uses) and - install python3 β€” e.g. on Debian/Ubuntu use apt, on Fedora use dnf, on Arch use - pacman. The package-manager Python is usually at /usr/bin/python3.
    • -
  • Or open the python.org source page in your browser, download the source tarball, then - compile it yourself (more advanced β€” skip unless you have a reason).
    • -
-
-

πŸ“ -On Linux, the system python3 (e.g. /usr/bin/python3) is used by the OS. For your -own projects, still create a virtual environment (Chapter 2) rather than installing -packages globally with sudo.

-
-

After install Β· test it works

-

Run this in your terminal. It prints the path of the Python that actually runs β€” this is -the one your commands use.

-
python3 -c "import sys; print(sys.executable)"
-
-

On macOS you might see something like:

-
/opt/homebrew/bin/python3        # good β€” the one you installed
-# or, if you forgot to set PATH:
-/Applications/Xcode.app/Contents/Developer/usr/bin/python3   # Apple's, not yours
-
-
-

⚠️ -If it points to Xcode's or the system Python instead of what you installed, your -PATH is wrong. Fix it by either activating your environment (conda activate … / -source .venv/bin/activate) or adding the install path to your shell config -(~/.zshrc on macOS, ~/.bashrc on Linux). Then reopen the terminal and re-test.

-
-

How to debug a broken install

-
    -
  1. Find the correct executable path with which python3 (macOS/Linux) or - Get-Command python (PowerShell).
    2. -
  2. Confirm PATH: echo $PATH (macOS/Linux) or $env:PATH (PowerShell) β€” your install - directory should appear before system paths.
    3. -
  3. Activate your environment (conda / .venv) β€” this is the easiest fix and avoids - touching PATH at all.
    4. -
  4. As a last resort, add the install path to your shell startup file and restart the - terminal.
    5. -
-

Run your first program

-

Now that Python is installed, let's run a real script. Create a file named -hello.py (any plain-text editor works) and paste the code below. Then run it with -python3 hello.py (or uv run hello.py if you used uv).

-

This example prints a friendly greeting and reports your machine's architecture -(platform.machine()), the Python version, and the operating system β€” a quick sanity -check that your install is alive and that you know which CPU it runs on.

-
import sys
-import platform
-
-def main():
-    # 1. The classic first program
-    print("Hello, world!")
-
-    # 2. Report the computer architecture and environment
-    print("\n--- Your machine ---")
-    print(f"OS        : {platform.system()} {platform.release()}")
-    print(f"Arch      : {platform.machine()}")   # e.g. arm64, x86_64, AMD64
-    print(f"Python    : {sys.version.splitlines()[0]}")
-    print(f"Executable: {sys.executable}")
-
-if __name__ == "__main__":
-    main()
-
-

Expected output (your numbers will differ):

-
Hello, world!
-
---- Your machine ---
-OS        : Darwin 24.0.0
-Arch      : arm64
-Python    : 3.12.4 (main, Jun  6 2024, 10:26:29) [Clang 15.0.0]
-Executable: /opt/homebrew/bin/python3
-
-
-

πŸ’‘ -The if __name__ == "__main__": line is a Python convention: it makes main() run -only when you execute the file directly (not when you import it as a module later). -Copy the block above β€” every code block on this site has a Copy button.

-

πŸ“ -About the shebang line (#!/usr/bin/env python3). It is not Python -syntax and does nothing when you run the file through an interpreter β€” it's only a -tip for the operating system.

-

```python

-

!/usr/bin/env python3

-

print("Hello, world!") -```

-

What it is / why write it. On macOS & Linux the #! (shebang) tells the OS which -program should run the file when you launch it directly. After chmod +x hello.py -you can run ./hello.py and the OS finds python3 for you. Using -/usr/bin/env python3 (not a hardcoded /usr/bin/python3) lets env search PATH, -so it picks up whatever Python you have active (conda / uv's .venv).

-

Why it "does nothing". The shebang only matters when the OS launches the file -itself. The moment you run it explicitly β€” python3 hello.py / uv run hello.py, -exactly what we used above β€” Python treats that line as an ordinary comment and -ignores it. So far it has had no effect at all.

- - - - - - - - - - - - - - - - - -
How you run itShebang used?
python3 hello.py / uv run hello.pyNo β€” ignored as a comment
./hello.py (after chmod +x)Yes β€” OS uses it to find the interpreter
-

Windows: the shebang is meaningless there β€” Windows picks the program from the -.py extension/association, not the first line, so you can leave it out.

-
-
-
-
- -
-

Python Setup Guide · Back to home

-

Content is a work in progress — see the project readme for status.

-
- - + + + + + +3 Β· Installing Python + + + +
Python Setup Guide
+
+ +
+ +
+

The detailed chapter. Three methods (standalone / conda / uv) Γ— three platforms (macOS +arm64, Windows amd64, Linux x86_64). Pick one method β€” we recommend uv for +beginners. You only need Python installed once per machine.

+

How to choose a version & architecture

+
    +
  • Version: pick a recent stable release β€” Python 3.12 or 3.13 are safe choices + in 2026. Not Python 2 (dead since 2020) and the very latest .0 release if a package + you need hasn't caught up yet.
    • +
  • Architecture (your CPU type):
    • +
  • macOS: Apple Silicon Macs (M1/M2/M3/M4) β†’ arm64. Intel Macs β†’ x86_64.
    • +
  • Windows: almost all modern PCs β†’ amd64 (also called x64).
    • +
  • Linux: most desktops/servers β†’ x86_64; newer ARM boards β†’ aarch64.
    • +
+

If you are unsure, the installer pages below usually auto-detect the right one.

+
+

⚠️ Choose a Stable Release (all methods & platforms). Whether you use the standalone +installer, conda, or uv, pick a Stable Release β€” the latest stable version (e.g. +Python 3.12.x or 3.13.x). Do not download or install anything marked Pre-release or +Development: those builds are for testing and may be unstable or break your packages.

+
+ +

Best for beginners: one fast tool, local environments, minimal fuss.

+
    +
  1. Install uv. Open the uv website (docs.astral.sh/uv) in your browser, go to the + Installation page, and download the installer for your system (macOS, Windows, or + Linux). Run it and follow the on-screen prompts β€” pick the default options when asked. + When it finishes, uv is installed.
    2. +
+
+

πŸ“ After install, close the terminal and open a new one, then verify with uv --version.

+
+
    +
  1. Install a Python and create your first project:
    2. +
+
uv python install 3.12          # download CPython 3.12 (one time)
+uv init myproject               # create a project folder with a .venv
+cd myproject
+uv pip install pandas           # install a package into this project
+uv run main.py                  # run a script with this project's Python
+
+
    +
  • After closing the terminal, you do not need to "activate" β€” just run + uv run <script> from the project folder and uv uses the local .venv automatically.
    • +
  • To pin a pre-installed interpreter (avoid re-downloading), set it in + pyproject.toml: requires-python = "&gt;=3.12" and uv venv --python 3.12.
    • +
+ +

Best if you will use data-science packages with non-Python system dependencies.

+
    +
  1. Install Miniconda. Open the Miniconda website (anaconda.com) in your browser, find the + Miniconda download for your system (macOS, Windows, or Linux), and download the + installer. Run it and follow the on-screen prompts β€” when asked whether to "Add Miniconda + to PATH" or "run conda init", you can leave the default; we explain conda init below. + When it finishes, Miniconda is installed.
    2. +
+
+

πŸ“ After install, close the terminal and open a new one so the conda command is +available. Then verify with conda --version. +2. Create and activate an environment:

+
+
conda create --name py312 python=3.12
+conda activate py312
+python --version
+
+
    +
  • After closing the terminal, the environment deactivates. Re-enter it with + conda activate py312 β€” the environment still exists globally, so you never recreate it.
    • +
  • To save disk space, point conda at a Python you already installed instead of letting + it download another copy: conda create --name py312 --clone base or use + conda create --name py312 python=$(python3 --version 2>&1 | cut -d' ' -f2).
    • +
+

What to do if you are asked to run conda init

+

The first time you open a terminal after installing conda, conda activate may fail with a +message like "To activate this environment, run conda init first." Here is why, and what +to do.

+

Why conda init is needed. conda activate only works if conda has hooked into your +shell's startup file. conda init writes a small block of code into that file so the shell +loads conda automatically every time you open a new terminal. Until you do this, the shell +doesn't know what conda activate means.

+

How to do it. Just run it once for your shell (the command is harmless to re-run):

+
conda init bash        # Linux default shell
+conda init zsh         # macOS default shell
+conda init powershell  # Windows (run in PowerShell)
+
+

Then close and reopen the terminal β€” the change only takes effect in new sessions.

+

Where does conda write the code? +- macOS / Linux (unix): into your shell's rc file in your home directory β€” + ~/.bashrc for bash, ~/.zshrc for zsh. Open a new terminal and conda is ready. +- Windows: into your PowerShell profile script (e.g. + C:\Users\<you>\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1), + not a .bashrc/.zshrc (those don't exist on Windows). If you use Git Bash on Windows, + conda instead writes to ~/.bashrc under your Git install.

+

After conda init, you get a permanent prompt prefix. Every new terminal will now show +your current conda environment in the prompt, e.g. (base) when no environment is active. +That (base) is a reminder of which environment your commands run in.

+
+

⚠️ Don't use base as your main environment. base is conda's built-in default env. +Keep it clean and instead conda activate py312 (or any env you create) for real work, +so packages for different projects don't clash. Tip: run conda config --set +auto_activate_base false to stop conda from auto-activating base every time you open a +terminal.

+
+

Method C Β· Standalone installer

+

Best if you want the official Python and nothing else.

+

Windows

+
    +
  1. Open the python.org Windows download page in your browser.
    2. +
  2. Download the Windows installer (64-bit) β€” the amd64 executable.
    3. +
  3. Important: on the first setup screen, tick "Add python.exe to PATH" before + clicking Install Now.
    4. +
  4. After install, reopen PowerShell and verify:
    5. +
+
python --version
+# Python 3.12.x   (on Windows the command is `python`, not `python3`)
+
+

Most Windows personal computers are amd64 architecture; if you have a Microsoft Surface, it may be arm64. +To be sure which one you have, run this in PowerShell and check the value it prints:

+
echo $env:PROCESSOR_ARCHITECTURE
+# ARM64  -> you have an Arm-based Surface; download the arm64 installer
+# AMD64  -> standard x64 PC; download the amd64 installer
+
+

Typical install path:

+
C:\Users\<you>\AppData\Local\Programs\Python\Python312\
+
+
+

⚠️\ +If python --version still says "command not found" or opens the Microsoft Store, you +forgot to tick Add to PATH. Re-run the installer and choose "Modify", then enable +"Add Python to environment variables".

+
+

macOS

+

Two routes:

+
    +
  • Official installer β€” open the python.org macOS download page in your browser and + always choose the "macOS 64-bit universal2" build. A universal2 installer works on + both Apple Silicon (arm64) and Intel Macs, so you don't need to figure out your chip. + Avoid the "macOS 64-bit Intel-only installer": it only supports Intel Macs and only exists + for older Python versions, so it's already outdated. Download the .pkg, double-click to + run, and follow the prompts. It may ask you to manually adjust PATH β€” see "after install" + below.
    • +
  • Homebrew (recommended if you already use it): open the Homebrew website (brew.sh), + install Homebrew first if you don't have it, then use it to install Python 3.12. It adds + itself to PATH automatically when brew is set up.
    • +
+

Typical paths:

+
# Official installer:
+/Library/Frameworks/Python.framework/Versions/3.12/bin/python3
+# Homebrew:
+/opt/homebrew/bin/python3        # Apple Silicon
+/usr/local/bin/python3           # Intel
+
+

Linux

+

Use your package manager, or build from source.

+
    +
  • Open your distro's software tool (or the package manager the system already uses) and + install python3 β€” e.g. on Debian/Ubuntu use apt, on Fedora use dnf, on Arch use + pacman. The package-manager Python is usually at /usr/bin/python3.
    • +
  • Or open the python.org source page in your browser, download the source tarball, then + compile it yourself (more advanced β€” skip unless you have a reason).
    • +
+
+

πŸ“ +On Linux, the system python3 (e.g. /usr/bin/python3) is used by the OS. For your +own projects, still create a virtual environment (Chapter 2) rather than installing +packages globally with sudo.

+
+

After install Β· test it works

+

Run this in your terminal. It prints the path of the Python that actually runs β€” this is +the one your commands use.

+
python3 -c "import sys; print(sys.executable)"
+
+

On macOS you might see something like:

+
/opt/homebrew/bin/python3        # good β€” the one you installed
+# or, if you forgot to set PATH:
+/Applications/Xcode.app/Contents/Developer/usr/bin/python3   # Apple's, not yours
+
+
+

⚠️ +If it points to Xcode's or the system Python instead of what you installed, your +PATH is wrong. Fix it by either activating your environment (conda activate … / +source .venv/bin/activate) or adding the install path to your shell config +(~/.zshrc on macOS, ~/.bashrc on Linux). Then reopen the terminal and re-test.

+
+

How to debug a broken install

+
    +
  1. Find the correct executable path with which python3 (macOS/Linux) or + Get-Command python (PowerShell).
    2. +
  2. Confirm PATH: echo $PATH (macOS/Linux) or $env:PATH (PowerShell) β€” your install + directory should appear before system paths.
    3. +
  3. Activate your environment (conda / .venv) β€” this is the easiest fix and avoids + touching PATH at all.
    4. +
  4. As a last resort, add the install path to your shell startup file and restart the + terminal.
    5. +
+

Run your first program

+

Now that Python is installed, let's run a real script. Create a file named +hello.py (any plain-text editor works) and paste the code below. Then run it with +python3 hello.py (or uv run hello.py if you used uv).

+

This example prints a friendly greeting and reports your machine's architecture +(platform.machine()), the Python version, and the operating system β€” a quick sanity +check that your install is alive and that you know which CPU it runs on.

+
import sys
+import platform
+
+def main():
+    # 1. The classic first program
+    print("Hello, world!")
+
+    # 2. Report the computer architecture and environment
+    print("\n--- Your machine ---")
+    print(f"OS        : {platform.system()} {platform.release()}")
+    print(f"Arch      : {platform.machine()}")   # e.g. arm64, x86_64, AMD64
+    print(f"Python    : {sys.version.splitlines()[0]}")
+    print(f"Executable: {sys.executable}")
+
+if __name__ == "__main__":
+    main()
+
+

Expected output (your numbers will differ):

+
Hello, world!
+
+--- Your machine ---
+OS        : Darwin 24.0.0
+Arch      : arm64
+Python    : 3.12.4 (main, Jun  6 2024, 10:26:29) [Clang 15.0.0]
+Executable: /opt/homebrew/bin/python3
+
+
+

πŸ’‘ +The if __name__ == "__main__": line is a Python convention: it makes main() run +only when you execute the file directly (not when you import it as a module later). +Copy the block above β€” every code block on this site has a Copy button.

+

πŸ“ +About the shebang line (#!/usr/bin/env python3). It is not Python +syntax and does nothing when you run the file through an interpreter β€” it's only a +tip for the operating system.

+

```python

+

!/usr/bin/env python3

+

print("Hello, world!") +```

+

What it is / why write it. On macOS & Linux the #! (shebang) tells the OS which +program should run the file when you launch it directly. After chmod +x hello.py +you can run ./hello.py and the OS finds python3 for you. Using +/usr/bin/env python3 (not a hardcoded /usr/bin/python3) lets env search PATH, +so it picks up whatever Python you have active (conda / uv's .venv).

+

Why it "does nothing". The shebang only matters when the OS launches the file +itself. The moment you run it explicitly β€” python3 hello.py / uv run hello.py, +exactly what we used above β€” Python treats that line as an ordinary comment and +ignores it. So far it has had no effect at all.

+ + + + + + + + + + + + + + + + + +
How you run itShebang used?
python3 hello.py / uv run hello.pyNo β€” ignored as a comment
./hello.py (after chmod +x)Yes β€” OS uses it to find the interpreter
+

Windows: the shebang is meaningless there β€” Windows picks the program from the +.py extension/association, not the first line, so you can leave it out.

+
+
+
+
+ +
+

Python Setup Guide · Back to home

+

Content is a work in progress — see the project readme for status.

+
+ + diff --git a/release/recommended-reading.html b/release/recommended-reading.html index 89bd5ba..428e2ea 100644 --- a/release/recommended-reading.html +++ b/release/recommended-reading.html @@ -1,419 +1,419 @@ - - - - - -5 Β· Recommended Reading - - - -
Python Setup Guide
-
- -
- -
-

A short, non-compulsory list to write cleaner Python and get editor features like -autocomplete and live error checking. All of these plug into the editors from Chapter 4.

-

PEP 8 β€” Style Guide for Python Code

-

PEP 8 is the official style convention for Python. You -do not need to memorize it β€” your editor can enforce it β€” but know the big ones:

-
    -
  • Indent with 4 spaces (never tabs).
    • -
  • Max line length 79 characters for code (99 is tolerated).
    • -
  • Naming: lowercase_with_underscores for functions/variables, - CapitalizedWords for classes, UPPER_CASE for constants.
    • -
  • Two blank lines between top-level definitions; one between methods.
    • -
-

Reading it once makes your code readable to TAs and teammates β€” and to the AI agents.

-

Language servers: ty and pyright

-

A Language Server Protocol (LSP) tool runs in the background and gives your editor -"brains": red squiggles for errors, hover docs, jump-to-definition, and safe rename.

-
    -
  • pyright β€” Microsoft's type checker for Python; fast, mature, the default in VS Code's - Python extension (via Pylance).
    • -
  • ty β€” Astral's (the uv makers) new type checker written in Rust; aims to be even - faster. Still young, but worth watching.
    • -
-

Enable in your editor: install the Python extension (pyright/ty come along), or run -the checker from the terminal:

-
uv pip install pyright
-pyright .            # type-check the project
-
-

Linters: ruff

-

ruff is an extremely fast all-in-one linter and -formatter (it replaces flake8, black, isort, and more in one tool). One command -cleans and formats your code:

-
uv pip install ruff
-ruff check .          # lint: report style/bug issues
-ruff check --fix .    # lint + auto-fix what it can
-ruff format .         # format: rewrite files to a consistent style
-
-

Drop a ruff.toml in your project to configure rules. Most teams adopt ruff because it -runs in milliseconds even on large codebases.

-
-

πŸ’‘ -Workflow: write code β†’ ruff format . β†’ ruff check . β†’ uv run main.py. Your -editor shows the same warnings live if you enable the Ruff extension.

-
-
-
-
- -
-

Python Setup Guide · Back to home

-

Content is a work in progress — see the project readme for status.

-
- - + + + + + +5 Β· Recommended Reading + + + +
Python Setup Guide
+
+ +
+ +
+

A short, non-compulsory list to write cleaner Python and get editor features like +autocomplete and live error checking. All of these plug into the editors from Chapter 4.

+

PEP 8 β€” Style Guide for Python Code

+

PEP 8 is the official style convention for Python. You +do not need to memorize it β€” your editor can enforce it β€” but know the big ones:

+
    +
  • Indent with 4 spaces (never tabs).
    • +
  • Max line length 79 characters for code (99 is tolerated).
    • +
  • Naming: lowercase_with_underscores for functions/variables, + CapitalizedWords for classes, UPPER_CASE for constants.
    • +
  • Two blank lines between top-level definitions; one between methods.
    • +
+

Reading it once makes your code readable to TAs and teammates β€” and to the AI agents.

+

Language servers: ty and pyright

+

A Language Server Protocol (LSP) tool runs in the background and gives your editor +"brains": red squiggles for errors, hover docs, jump-to-definition, and safe rename.

+
    +
  • pyright β€” Microsoft's type checker for Python; fast, mature, the default in VS Code's + Python extension (via Pylance).
    • +
  • ty β€” Astral's (the uv makers) new type checker written in Rust; aims to be even + faster. Still young, but worth watching.
    • +
+

Enable in your editor: install the Python extension (pyright/ty come along), or run +the checker from the terminal:

+
uv pip install pyright
+pyright .            # type-check the project
+
+

Linters: ruff

+

ruff is an extremely fast all-in-one linter and +formatter (it replaces flake8, black, isort, and more in one tool). One command +cleans and formats your code:

+
uv pip install ruff
+ruff check .          # lint: report style/bug issues
+ruff check --fix .    # lint + auto-fix what it can
+ruff format .         # format: rewrite files to a consistent style
+
+

Drop a ruff.toml in your project to configure rules. Most teams adopt ruff because it +runs in milliseconds even on large codebases.

+
+

πŸ’‘ +Workflow: write code β†’ ruff format . β†’ ruff check . β†’ uv run main.py. Your +editor shows the same warnings live if you enable the Ruff extension.

+
+
+
+
+ +
+

Python Setup Guide · Back to home

+

Content is a work in progress — see the project readme for status.

+
+ + diff --git a/release/unix-basics.html b/release/unix-basics.html index 8e6b1d8..f61b830 100644 --- a/release/unix-basics.html +++ b/release/unix-basics.html @@ -1,691 +1,691 @@ - - - - - -1 Β· Basic Unix-like Systems - - - -
Python Setup Guide
-
- -
- -
-

A very short, friendly introduction to the command line. If you already open a terminal -daily, you can skip this chapter β€” but a 5-minute read helps if terms like shell, PATH, -or sudo are new to you.

-

What is the command line?

-

The command line (also called the terminal or shell) is a text interface where you -type commands instead of clicking icons. You type a command, press Enter, and the computer -does exactly that.

-

The program that reads your commands is the shell. Different systems ship different -defaults:

-
    -
  • Linux β†’ bash (Bourne Again Shell), and increasingly zsh on newer distros.
    • -
  • macOS β†’ zsh since macOS Catalina (older versions used bash).
    • -
  • Windows β†’ PowerShell (pwsh) or the older cmd.exe. We recommend PowerShell.
    • -
-

You will see a prompt β€” something like you@Mbp ~ % β€” followed by a blinking cursor. -That prompt is the shell asking "what next?".

-
-

πŸ’‘ -In the code blocks below, the $ (or % on macOS zsh) at the start of a line is the -prompt, not something you type. Only type what comes after it.

-
-

How to find the terminal on your computer

-
    -
  • macOS: press Cmd + Space to open Spotlight, type Terminal, and press Enter. - (Or use a nicer terminal such as iTerm2 or the one built into VS Code β€” see Chapter 4.)
    • -
  • Linux (Ubuntu/GNOME): press Ctrl + Alt + T.
    • -
  • Windows: install Windows Terminal from the Microsoft Store, then open - PowerShell. Avoid the old cmd.exe β€” PowerShell understands more modern commands.
    • -
-

TODO: Screenshot of opening the terminal β€” macOS Spotlight β†’ Terminal, Windows Terminal β†’ PowerShell, or Linux Ctrl+Alt+T β†’ GNOME Terminal.

-

sudo and "run as administrator"

-

Some commands change system-level settings (installing software, editing protected files). -Those need elevated rights:

-
    -
  • macOS / Linux: prefix the command with sudo ("superuser do"). The first time, - macOS/Linux asks for your password.
    • -
  • Windows: right-click the terminal icon and choose Run as administrator, or use - Start-Process in PowerShell.
    • -
-
-

⚠️ -Your sudo password is usually your macOS/login password. macOS deliberately shows -nothing as you type β€” no dots, no asterisks. That is normal; just type and press Enter.

-
-
-⚠️ Use sudo with caution β€” it can damage your computer - -`sudo` grants full administrator (root) power, so a typo or a wrong command can -delete system files, break the operating system, or lock you out of your machine. -Before pressing Enter on a `sudo` command: - -1. Make sure you understand what it does β€” if you copy-pasted it from the internet, - know exactly why each part is there. -2. Never run `sudo` on a command you don't recognise, especially ones using `rm`, - `dd`, or wildcards like `*` on system folders. -3. Prefer `sudo` for the single command you need, not for opening a long-lived root - shell (`sudo -i` / `sudo su`). - -For this guide's Python setup you will rarely need `sudo` at all β€” virtual -environments and `uv` install things into your own home folder, not system-wide. - -
- -
sudo whoami
-# macOS/Linux: enter your login password when prompted
-# prints "root" β†’ you are now acting as the administrator
-
-

Using -h / --help

-

Almost every command accepts flags that change its behavior. A single dash (-) -introduces a short flag (one letter); a double dash (--) introduces a long, readable -flag.

-
ls -la          # short flags: -l (long format) + -a (include hidden files)
-python3 --help  # long flag: full help text
-
-

When stuck, append -h or --help to nearly any command to see its options.

-
ls -la
-python3 -h
-# zsh: command not found: python  β†’  we use python3 (see below)
-
-
-Why there is no python on macOS？ - -On macOS, the command is `python3`, not `python`. Apple stopped shipping a plain `python` -command (it pointed to an ancient Python 2). So always use `python3`. - -πŸ“ **Jump ahead:** See [Chapter 3 Β· Installing Python](installation.html) for how many -Pythons live on a Mac and which one you should actually use. The `python3` you get by -default may be Apple's, not the one you want for your projects. - -
- -

Difference between options and arguments

-

A command line has two kinds of inputs:

-
    -
  • Options / flags modify how the command runs (e.g. -l, --help). They usually - start with - or --.
    • -
  • Arguments are the targets the command acts on β€” file names, URLs, values.
    • -
-
  cp -r project backup
-#β””β”¬β”˜ β””β”¬β”˜  β””β”¬β”˜    β””β”¬β”˜
-# β”‚   β”‚    β”‚      └─ argument: destination
-# β”‚   β”‚    └──────── argument: source
-# β”‚   └───────────── option: recursive
-# └───────────────── command
-
-

How the shell finds a command: the PATH

-

When you type python3 and press Enter, the shell does not magically know what -python3 means. It is really just a name. The shell asks the operating system: -"where is the program called python3?" β€” and the OS answers by searching a list -of folders called the PATH.

-

PATH is an environment variable: a colon-separated (:) list of directories -on Unix/macOS, or semicolon-separated (;) on Windows. Think of it as a set of -"places to look". To find a command, the system walks the list in order and -opens the first folder that contains a matching executable.

-
$ echo $PATH
-/usr/local/bin:/usr/bin:/bin:/Users/you/.local/bin
-                 β”‚        β”‚      β”‚                 └─ searched last
-                 β””β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”˜β”€ searched first β†’ first match wins
-
-

So python3 is actually: the system takes the name python3 and looks through -every folder in PATH until it finds a file with that name it can run. The first -match wins β€” which is why, if you have several Pythons installed, the one found -earliest in PATH is the one that runs. -- Unix:

-
# Show the folders your shell searches, in order:
-echo $PATH                 # macOS / Linux
-which python3              # macOS / Linux  β†’ prints e.g. /usr/local/bin/python3
-
-
    -
  • Windows:
    • -
-
$env:PATH                  # Windows (PowerShell)
-Get-Command python3        # Windows (PowerShell)
-
-

This is also why a freshly installed Python sometimes "doesn't work" until you -reopen the terminal: installing it adds its folder to PATH, but already-open -shells loaded the old PATH. Close and reopen the terminal (or run the installer's -"add to PATH" step) so the new folder is included. We return to this in -Chapter 3 Β· Installing Python.

-
-

What is an "executable"? (and why python is one)

-

An executable is simply a file the operating system knows how to run directly β€” -as a program, not as data to be opened in another program. When you type python3 and -press Enter, you are asking the OS to launch the python3 executable; it then reads -your script and executes it line by line.

-

So Python itself is an executable (python.exe on Windows, python3 on macOS/Linux). -Your .py script is not an executable on its own β€” it is data that the Python -executable interprets. That is the key mental model:

-
python3  hello.py
-β”‚        β”‚
-β”‚        └─ your script = DATA (text the interpreter reads)
-└────────── the executable = PROGRAM (actually runs)
-
-
-How the OS knows a file is executable - -Different systems use different signals: - -- **Windows** decides by the file **extension** (`.exe`, `.msi`, …). Double-clicking - `python.exe` runs it; renaming it to `python.txt` makes Windows treat it as text. -- **Unix-like systems** (macOS/Linux) decide by a **permission bit** (the file is marked - *executable* with `chmod +x`) plus a **shebang** line (`#!/usr/bin/env python3`) at the - top that tells the shell which interpreter to use. So Unix programs often have **no - extension** at all. - -This is why you run `python.exe` on Windows but just `python3` on macOS/Linux β€” and why -your own `.py` files need `python3` in front of them (unless you add a shebang and make -them executable, as seen in Chapter 3). -
- -

PowerShell notes (Windows)

-

PowerShell ships convenience aliases that mimic Unix commands, but its native commands -are different (verb-noun cmdlets). We recommend PowerShell over cmd.exe.

-
# PowerShell alias   β‰ˆ   Unix command
-Get-Command          # β‰ˆ which   (locate a command)
-Get-ChildItem        # β‰ˆ ls      (list files)
-Get-Location         # β‰ˆ pwd     (print working directory)
-Set-Location         # β‰ˆ cd      (change directory)
-
-
-

πŸ’‘ -In PowerShell, the path separator is \ (back-slash) and environment variables use -$env:NAME (e.g. $env:PATH) instead of Unix $NAME.

-
-

Why Windows is less preferred (for this guide)

-

We recommend PowerShell over cmd.exe, but Unix-like shells (bash/zsh) are still -preferred over Windows overall, and here is the honest reason:

-
    -
  • A different command grammar. Windows uses verb-noun cmdlets (Get-ChildItem, - Set-Location) while Unix uses short names (ls, cd). Most tutorials, Stack - Overflow answers, and this guide's commands are written for Unix β€” on Windows you - must mentally translate them.
    • -
  • The backslash tax. Windows paths use \, which is an escape character in nearly - every programming language, so you constantly fight \\ or raw strings (see above). - Unix's / just works everywhere, including inside Python.
    • -
  • Case-insensitive filesystem. Readme.md and readme.md are the same file on - Windows but different on macOS/Linux. This silently breaks imports and git diffs - when code moves between systems.
    • -
  • Legacy split. Two shells (cmd.exe and PowerShell), two path styles, and - years of conflicting advice make Windows setups more error-prone for beginners.
    • -
-

None of this means Windows is "bad" β€” millions use it daily. It just means you will -meet more friction following Python tutorials written from a Unix point of view, so -expect to adapt commands rather than copy them verbatim.

-

Path separators: / (slash) vs \ (backslash)

-

A path tells the OS where a file lives. The character that separates folders -differs by system:

-
    -
  • macOS / Linux use the forward slash / β€” e.g. /Users/you/hello.py.
    • -
  • Windows traditionally uses the backslash \ β€” e.g. C:\Users\you\hello.py.
    • -
-
-

⚠️ -Inside most programming languages the backslash \ is an escape character (it -changes the meaning of the next character, e.g. \n = newline). So in Python you must -either double it ("C:\\Users\\you") or use a raw string (r"C:\Users\you"). -Forward slashes have no such problem and are safer in code.

-
-

In PowerShell you can use either

-

A nice surprise: PowerShell accepts both / and \ when you type a path, and it -normalises them automatically. So these all work:

-
cd C:\Users\you\Documents      # classic Windows backslash
-cd C:/Users/you/Documents      # forward slash β€” also fine in pwsh
-cd ~/Documents                 # ~ means your home folder
-Get-ChildItem C:/Users/you/hello.py
-
-

On macOS/Linux the shell only understands /; a \ there is an escaping character, -not a separator. So when you write cross-platform scripts or Python code, prefer / -everywhere.

-

Users and the home folder (~)

-

You may have noticed paths like C:\Users\you\hello.py (Windows) or -/Users/you/hello.py (macOS). That you is a username β€” every person who -logs into a computer gets their own account, and each account has its own private -space on disk.

-

What does <you> mean in C:\Users\<you>?

-

In tutorials you will often see a placeholder like C:\Users\<you> or -/home/<you>. The <you> is not literal text you type β€” it is a stand-in -for your own username on the machine. Replace it with whatever name you used -when you set up the computer.

-
    -
  • On Windows, your user folder is C:\Users\YourName. If your account is - named alice, your real path is C:\Users\alice β€” not C:\Users\<you>.
    • -
  • On macOS, it is /Users/YourName (e.g. /Users/you).
    • -
  • On Linux, it is /home/YourName (e.g. /home/you).
    • -
-

The angle brackets < > are a common notation meaning "fill in your own value -here". Whenever you copy a command, swap <you> for your actual username.

-

whoami β€” ask "who am I right now?"

-

The whoami command prints the username of the account you are currently logged -into the shell as. It is handy when you are unsure whose home folder a path -refers to.

-
# macOS / Linux (bash, zsh):
-whoami
-# prints e.g. "you"  β†’ that is the name that replaces <you> above
-
-
# Windows (PowerShell):
-whoami
-# prints e.g. "desktop-abc\alice"  β†’ the part after "\" is your username,
-# or use the shorter form:
-$env:USERNAME
-# prints just "alice"
-
-
-

πŸ“ -A small difference between systems. On macOS/Linux, whoami returns just -the short username (you). On Windows, the plain whoami command returns the -full account name including the machine/domain prefix (e.g. -DESKTOP-ABC\alice), because Windows accounts live inside a "domain". If you -only want the bare username on Windows, use $env:USERNAME instead β€” it -behaves like the Unix whoami.

-
-

What is ~ (tilde)?

-

~ is a shortcut for your home folder β€” the private directory the OS creates -for your account. Instead of typing the full /Users/you or -C:\Users\you every time, you can write ~ and the shell expands it.

-
    -
  • On macOS/Linux: ~ = /Users/you
    • -
  • On Windows (PowerShell): ~ = C:\Users\you
    • -
-
cd ~              # go straight to your home folder
-cd ~/Documents    # go to Documents inside your home folder
-echo ~            # print the full path your ~ resolves to
-
-
cd ~              # PowerShell also understands ~ as your home folder
-cd ~/Documents
-
-

So <you> in C:\Users\<you> is just "your username", and ~ is the fast way -to refer to C:\Users\<you> (or /Users/<you>) without writing it out.

-

Tab completion

-

You rarely have to type a long path or command name in full. Press Tab and the -shell finishes it for you; press Tab again to cycle through multiple matches.

-

Here is a real session in a project folder (the <you> part is your username, as -explained earlier β€” see Users and the home folder (~)):

-
# <you> at Mbp.lan in ~/PycharmProjects/python-setup-moodle on git:main x [11:17:03]
-$ ls
-AGENTS.md        assets           azure-api-key.py css              index.html       index.md         pages            readme.md        serve.py
-
-# <you> at Mbp.lan in ~/PycharmProjects/python-setup-moodle on git:main x [11:17:04]
-$ vim AGENT<Tab>
-# β†’ shell auto-completes to: vim AGENTS.md
-
-# <you> at Mbp.lan in ~/PycharmProjects/python-setup-moodle on git:main x [11:17:29]
-$ vim AGENTS.md
-# β†’ opens the file; no need to type the rest of the name by hand
-
-
# In PowerShell the same Tab key works:
-cd ~/Doc<Tab>      # β†’ ~/Documents/
-Get-Command pyth<Tab>   # β†’ fills in the matching command name
-
-
-

πŸ’‘ -If Tab does nothing, you may have typed a wrong starting letter β€” the shell only -completes from what it can uniquely match. Tab is your best friend for avoiding -typos in long paths.

-
-
-
-
- -
-

Python Setup Guide · Back to home

-

Content is a work in progress — see the project readme for status.

-
- - + + + + + +1 Β· Basic Unix-like Systems + + + +
Python Setup Guide
+
+ +
+ +
+

A very short, friendly introduction to the command line. If you already open a terminal +daily, you can skip this chapter β€” but a 5-minute read helps if terms like shell, PATH, +or sudo are new to you.

+

What is the command line?

+

The command line (also called the terminal or shell) is a text interface where you +type commands instead of clicking icons. You type a command, press Enter, and the computer +does exactly that.

+

The program that reads your commands is the shell. Different systems ship different +defaults:

+
    +
  • Linux β†’ bash (Bourne Again Shell), and increasingly zsh on newer distros.
    • +
  • macOS β†’ zsh since macOS Catalina (older versions used bash).
    • +
  • Windows β†’ PowerShell (pwsh) or the older cmd.exe. We recommend PowerShell.
    • +
+

You will see a prompt β€” something like you@Mbp ~ % β€” followed by a blinking cursor. +That prompt is the shell asking "what next?".

+
+

πŸ’‘ +In the code blocks below, the $ (or % on macOS zsh) at the start of a line is the +prompt, not something you type. Only type what comes after it.

+
+

How to find the terminal on your computer

+
    +
  • macOS: press Cmd + Space to open Spotlight, type Terminal, and press Enter. + (Or use a nicer terminal such as iTerm2 or the one built into VS Code β€” see Chapter 4.)
    • +
  • Linux (Ubuntu/GNOME): press Ctrl + Alt + T.
    • +
  • Windows: install Windows Terminal from the Microsoft Store, then open + PowerShell. Avoid the old cmd.exe β€” PowerShell understands more modern commands.
    • +
+

TODO: Screenshot of opening the terminal β€” macOS Spotlight β†’ Terminal, Windows Terminal β†’ PowerShell, or Linux Ctrl+Alt+T β†’ GNOME Terminal.

+

sudo and "run as administrator"

+

Some commands change system-level settings (installing software, editing protected files). +Those need elevated rights:

+
    +
  • macOS / Linux: prefix the command with sudo ("superuser do"). The first time, + macOS/Linux asks for your password.
    • +
  • Windows: right-click the terminal icon and choose Run as administrator, or use + Start-Process in PowerShell.
    • +
+
+

⚠️ +Your sudo password is usually your macOS/login password. macOS deliberately shows +nothing as you type β€” no dots, no asterisks. That is normal; just type and press Enter.

+
+
+⚠️ Use sudo with caution β€” it can damage your computer + +`sudo` grants full administrator (root) power, so a typo or a wrong command can +delete system files, break the operating system, or lock you out of your machine. +Before pressing Enter on a `sudo` command: + +1. Make sure you understand what it does β€” if you copy-pasted it from the internet, + know exactly why each part is there. +2. Never run `sudo` on a command you don't recognise, especially ones using `rm`, + `dd`, or wildcards like `*` on system folders. +3. Prefer `sudo` for the single command you need, not for opening a long-lived root + shell (`sudo -i` / `sudo su`). + +For this guide's Python setup you will rarely need `sudo` at all β€” virtual +environments and `uv` install things into your own home folder, not system-wide. + +
+ +
sudo whoami
+# macOS/Linux: enter your login password when prompted
+# prints "root" β†’ you are now acting as the administrator
+
+

Using -h / --help

+

Almost every command accepts flags that change its behavior. A single dash (-) +introduces a short flag (one letter); a double dash (--) introduces a long, readable +flag.

+
ls -la          # short flags: -l (long format) + -a (include hidden files)
+python3 --help  # long flag: full help text
+
+

When stuck, append -h or --help to nearly any command to see its options.

+
ls -la
+python3 -h
+# zsh: command not found: python  β†’  we use python3 (see below)
+
+
+Why there is no python on macOS？ + +On macOS, the command is `python3`, not `python`. Apple stopped shipping a plain `python` +command (it pointed to an ancient Python 2). So always use `python3`. + +πŸ“ **Jump ahead:** See [Chapter 3 Β· Installing Python](installation.html) for how many +Pythons live on a Mac and which one you should actually use. The `python3` you get by +default may be Apple's, not the one you want for your projects. + +
+ +

Difference between options and arguments

+

A command line has two kinds of inputs:

+
    +
  • Options / flags modify how the command runs (e.g. -l, --help). They usually + start with - or --.
    • +
  • Arguments are the targets the command acts on β€” file names, URLs, values.
    • +
+
  cp -r project backup
+#β””β”¬β”˜ β””β”¬β”˜  β””β”¬β”˜    β””β”¬β”˜
+# β”‚   β”‚    β”‚      └─ argument: destination
+# β”‚   β”‚    └──────── argument: source
+# β”‚   └───────────── option: recursive
+# └───────────────── command
+
+

How the shell finds a command: the PATH

+

When you type python3 and press Enter, the shell does not magically know what +python3 means. It is really just a name. The shell asks the operating system: +"where is the program called python3?" β€” and the OS answers by searching a list +of folders called the PATH.

+

PATH is an environment variable: a colon-separated (:) list of directories +on Unix/macOS, or semicolon-separated (;) on Windows. Think of it as a set of +"places to look". To find a command, the system walks the list in order and +opens the first folder that contains a matching executable.

+
$ echo $PATH
+/usr/local/bin:/usr/bin:/bin:/Users/you/.local/bin
+                 β”‚        β”‚      β”‚                 └─ searched last
+                 β””β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”˜β”€ searched first β†’ first match wins
+
+

So python3 is actually: the system takes the name python3 and looks through +every folder in PATH until it finds a file with that name it can run. The first +match wins β€” which is why, if you have several Pythons installed, the one found +earliest in PATH is the one that runs. +- Unix:

+
# Show the folders your shell searches, in order:
+echo $PATH                 # macOS / Linux
+which python3              # macOS / Linux  β†’ prints e.g. /usr/local/bin/python3
+
+
    +
  • Windows:
    • +
+
$env:PATH                  # Windows (PowerShell)
+Get-Command python3        # Windows (PowerShell)
+
+

This is also why a freshly installed Python sometimes "doesn't work" until you +reopen the terminal: installing it adds its folder to PATH, but already-open +shells loaded the old PATH. Close and reopen the terminal (or run the installer's +"add to PATH" step) so the new folder is included. We return to this in +Chapter 3 Β· Installing Python.

+
+

What is an "executable"? (and why python is one)

+

An executable is simply a file the operating system knows how to run directly β€” +as a program, not as data to be opened in another program. When you type python3 and +press Enter, you are asking the OS to launch the python3 executable; it then reads +your script and executes it line by line.

+

So Python itself is an executable (python.exe on Windows, python3 on macOS/Linux). +Your .py script is not an executable on its own β€” it is data that the Python +executable interprets. That is the key mental model:

+
python3  hello.py
+β”‚        β”‚
+β”‚        └─ your script = DATA (text the interpreter reads)
+└────────── the executable = PROGRAM (actually runs)
+
+
+How the OS knows a file is executable + +Different systems use different signals: + +- **Windows** decides by the file **extension** (`.exe`, `.msi`, …). Double-clicking + `python.exe` runs it; renaming it to `python.txt` makes Windows treat it as text. +- **Unix-like systems** (macOS/Linux) decide by a **permission bit** (the file is marked + *executable* with `chmod +x`) plus a **shebang** line (`#!/usr/bin/env python3`) at the + top that tells the shell which interpreter to use. So Unix programs often have **no + extension** at all. + +This is why you run `python.exe` on Windows but just `python3` on macOS/Linux β€” and why +your own `.py` files need `python3` in front of them (unless you add a shebang and make +them executable, as seen in Chapter 3). +
+ +

PowerShell notes (Windows)

+

PowerShell ships convenience aliases that mimic Unix commands, but its native commands +are different (verb-noun cmdlets). We recommend PowerShell over cmd.exe.

+
# PowerShell alias   β‰ˆ   Unix command
+Get-Command          # β‰ˆ which   (locate a command)
+Get-ChildItem        # β‰ˆ ls      (list files)
+Get-Location         # β‰ˆ pwd     (print working directory)
+Set-Location         # β‰ˆ cd      (change directory)
+
+
+

πŸ’‘ +In PowerShell, the path separator is \ (back-slash) and environment variables use +$env:NAME (e.g. $env:PATH) instead of Unix $NAME.

+
+

Why Windows is less preferred (for this guide)

+

We recommend PowerShell over cmd.exe, but Unix-like shells (bash/zsh) are still +preferred over Windows overall, and here is the honest reason:

+
    +
  • A different command grammar. Windows uses verb-noun cmdlets (Get-ChildItem, + Set-Location) while Unix uses short names (ls, cd). Most tutorials, Stack + Overflow answers, and this guide's commands are written for Unix β€” on Windows you + must mentally translate them.
    • +
  • The backslash tax. Windows paths use \, which is an escape character in nearly + every programming language, so you constantly fight \\ or raw strings (see above). + Unix's / just works everywhere, including inside Python.
    • +
  • Case-insensitive filesystem. Readme.md and readme.md are the same file on + Windows but different on macOS/Linux. This silently breaks imports and git diffs + when code moves between systems.
    • +
  • Legacy split. Two shells (cmd.exe and PowerShell), two path styles, and + years of conflicting advice make Windows setups more error-prone for beginners.
    • +
+

None of this means Windows is "bad" β€” millions use it daily. It just means you will +meet more friction following Python tutorials written from a Unix point of view, so +expect to adapt commands rather than copy them verbatim.

+

Path separators: / (slash) vs \ (backslash)

+

A path tells the OS where a file lives. The character that separates folders +differs by system:

+
    +
  • macOS / Linux use the forward slash / β€” e.g. /Users/you/hello.py.
    • +
  • Windows traditionally uses the backslash \ β€” e.g. C:\Users\you\hello.py.
    • +
+
+

⚠️ +Inside most programming languages the backslash \ is an escape character (it +changes the meaning of the next character, e.g. \n = newline). So in Python you must +either double it ("C:\\Users\\you") or use a raw string (r"C:\Users\you"). +Forward slashes have no such problem and are safer in code.

+
+

In PowerShell you can use either

+

A nice surprise: PowerShell accepts both / and \ when you type a path, and it +normalises them automatically. So these all work:

+
cd C:\Users\you\Documents      # classic Windows backslash
+cd C:/Users/you/Documents      # forward slash β€” also fine in pwsh
+cd ~/Documents                 # ~ means your home folder
+Get-ChildItem C:/Users/you/hello.py
+
+

On macOS/Linux the shell only understands /; a \ there is an escaping character, +not a separator. So when you write cross-platform scripts or Python code, prefer / +everywhere.

+

Users and the home folder (~)

+

You may have noticed paths like C:\Users\you\hello.py (Windows) or +/Users/you/hello.py (macOS). That you is a username β€” every person who +logs into a computer gets their own account, and each account has its own private +space on disk.

+

What does <you> mean in C:\Users\<you>?

+

In tutorials you will often see a placeholder like C:\Users\<you> or +/home/<you>. The <you> is not literal text you type β€” it is a stand-in +for your own username on the machine. Replace it with whatever name you used +when you set up the computer.

+
    +
  • On Windows, your user folder is C:\Users\YourName. If your account is + named alice, your real path is C:\Users\alice β€” not C:\Users\<you>.
    • +
  • On macOS, it is /Users/YourName (e.g. /Users/you).
    • +
  • On Linux, it is /home/YourName (e.g. /home/you).
    • +
+

The angle brackets < > are a common notation meaning "fill in your own value +here". Whenever you copy a command, swap <you> for your actual username.

+

whoami β€” ask "who am I right now?"

+

The whoami command prints the username of the account you are currently logged +into the shell as. It is handy when you are unsure whose home folder a path +refers to.

+
# macOS / Linux (bash, zsh):
+whoami
+# prints e.g. "you"  β†’ that is the name that replaces <you> above
+
+
# Windows (PowerShell):
+whoami
+# prints e.g. "desktop-abc\alice"  β†’ the part after "\" is your username,
+# or use the shorter form:
+$env:USERNAME
+# prints just "alice"
+
+
+

πŸ“ +A small difference between systems. On macOS/Linux, whoami returns just +the short username (you). On Windows, the plain whoami command returns the +full account name including the machine/domain prefix (e.g. +DESKTOP-ABC\alice), because Windows accounts live inside a "domain". If you +only want the bare username on Windows, use $env:USERNAME instead β€” it +behaves like the Unix whoami.

+
+

What is ~ (tilde)?

+

~ is a shortcut for your home folder β€” the private directory the OS creates +for your account. Instead of typing the full /Users/you or +C:\Users\you every time, you can write ~ and the shell expands it.

+
    +
  • On macOS/Linux: ~ = /Users/you
    • +
  • On Windows (PowerShell): ~ = C:\Users\you
    • +
+
cd ~              # go straight to your home folder
+cd ~/Documents    # go to Documents inside your home folder
+echo ~            # print the full path your ~ resolves to
+
+
cd ~              # PowerShell also understands ~ as your home folder
+cd ~/Documents
+
+

So <you> in C:\Users\<you> is just "your username", and ~ is the fast way +to refer to C:\Users\<you> (or /Users/<you>) without writing it out.

+

Tab completion

+

You rarely have to type a long path or command name in full. Press Tab and the +shell finishes it for you; press Tab again to cycle through multiple matches.

+

Here is a real session in a project folder (the <you> part is your username, as +explained earlier β€” see Users and the home folder (~)):

+
# <you> at Mbp.lan in ~/PycharmProjects/python-setup-moodle on git:main x [11:17:03]
+$ ls
+AGENTS.md        assets           azure-api-key.py css              index.html       index.md         pages            readme.md        serve.py
+
+# <you> at Mbp.lan in ~/PycharmProjects/python-setup-moodle on git:main x [11:17:04]
+$ vim AGENT<Tab>
+# β†’ shell auto-completes to: vim AGENTS.md
+
+# <you> at Mbp.lan in ~/PycharmProjects/python-setup-moodle on git:main x [11:17:29]
+$ vim AGENTS.md
+# β†’ opens the file; no need to type the rest of the name by hand
+
+
# In PowerShell the same Tab key works:
+cd ~/Doc<Tab>      # β†’ ~/Documents/
+Get-Command pyth<Tab>   # β†’ fills in the matching command name
+
+
+

πŸ’‘ +If Tab does nothing, you may have typed a wrong starting letter β€” the shell only +completes from what it can uniquely match. Tab is your best friend for avoiding +typos in long paths.

+
+
+
+
+ +
+

Python Setup Guide · Back to home

+

Content is a work in progress — see the project readme for status.

+
+ + diff --git a/release/virtual-environment.html b/release/virtual-environment.html index d823a80..ee7ff8d 100644 --- a/release/virtual-environment.html +++ b/release/virtual-environment.html @@ -1,558 +1,558 @@ - - - - - -2 Β· Virtual Environments - - - -
Python Setup Guide
-
- -
- -
-

A short, non-compulsory concept chapter. Understanding this now saves real pain later, when -two projects need different versions of the same package.

-

Why you need a virtual environment

-

A Python environment is a private, isolated copy of the interpreter plus its installed -packages. Without one, every package you install lands in a single global location, and -versions collide:

-
    -
  • Project A needs pandas 1.x; Project B needs pandas 2.x β†’ one of them breaks.
    • -
  • You install packages into the system Python (/usr/bin/python3 on macOS/Linux), which - the operating system itself relies on. Upgrading or removing something there can break - system tools.
    • -
-

A virtual environment keeps each project's dependencies in its own folder, so projects -never step on each other β€” and never touch the system Python.

-
-

⚠️ -On macOS/Linux, /usr/bin/python3 is managed by the system. Installing packages into it -with sudo pip install … can break OS tools. Always work inside a project environment.

-
-

uv

-

uv is a modern, extremely fast Python package and -environment manager written in Rust. It replaces pip, virtualenv, and parts of -conda. We recommend it for beginners because:

-
    -
  • One tool does everything (install Python, create envs, install packages, run scripts).
    • -
  • It is 10–100Γ— faster than pip.
    • -
  • Environments are created in a local .venv folder β€” no global state to manage.
    • -
-
uv init myproject      # create a new project with a .venv
-cd myproject
-uv pip install pandas  # install a package into this project's env
-uv run main.py         # run a script using this project's Python
-
-

Locking & recording dependencies: uv lock and requirements.txt

-

Installing packages is only half the story. To make your project reproducible β€” -so someone else (or future you) can rebuild the exact same environment β€” you record -what you installed.

-

requirements.txt (the classic, pip-style list)

-

A plain text file listing every package (and version) your project needs:

-
pandas==2.2.2
-numpy>=1.26.0
-requests
-
-
    -
  • Generate it from your current env with pip/uv:
    • -
-
uv pip freeze > requirements.txt     # uv
-pip freeze    > requirements.txt     # plain pip
-
-
    -
  • Rebuild an env from it on another machine:
    • -
-
uv pip install -r requirements.txt
-
-

The catch: requirements.txt only pins top-level packages. If pandas silently -pulls in a specific numpy, that sub-dependency version is not fixed β€” two people -can end up with different environments.

-

uv lock (the modern, exact solution)

-

uv goes further with a lockfile β€” uv.lock β€” that pins every package, -including all transitive dependencies, to exact versions and hashes:

-
uv add pandas          # adds pandas AND writes/updates uv.lock + pyproject.toml
-uv lock                # (re)resolve and write uv.lock without installing
-uv sync                # install exactly what uv.lock specifies
-
-

uv.lock guarantees that everyone who runs uv sync gets a byte-for-byte identical -set of packages. Think of it as requirements.txt on steroids.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
requirements.txtuv.lock
Pins top-level packagesYes (if you use ==)Yes
Pins transitive depsNoYes β€” exact versions + hashes
Human-readableYesMachine-generated (don't edit by hand)
Toolpip / uvuv only
-
-

πŸ’‘ -For coursework, requirements.txt is enough and easier to read. Once a project -matters (a real app, a paper's analysis), switch to uv.lock so results stay -reproducible. Either way, keep the file alongside your project so the environment -travels with your code.

-
-

conda / Anaconda / Miniconda

-

conda is an older, very popular environment manager, especially in data science. The -naming is confusing, so here is the split:

-
    -
  • Anaconda β€” the full distribution: conda plus 250+ pre-installed packages. Large - (~3 GB). Good if you want everything out of the box.
    • -
  • Miniconda β€” conda with no pre-installed packages. Small and clean. We recommend - Miniconda if you go the conda route.
    • -
  • conda-forge β€” a community channel (see below) of packages; usually more up to date - than the default defaults channel.
    • -
-

Unlike uv/pip, conda can also install non-Python dependencies (e.g. CUDA, R), which is -why many scientists like it.

-
conda create --name py312 python=3.12   # create a named environment
-conda activate py312                     # switch into it
-
-

Channels: conda-forge and others

-

A channel is a repository conda downloads packages from. The two you will meet:

-
    -
  • defaults β€” Anaconda's official, curated channel.
    • -
  • conda-forge β€” a community-run channel with broader, faster-updated packages.
    • -
-

We recommend preferring conda-forge:

-
conda create -n py312 python=3.12 -c conda-forge
-
-

This differs from PyPI (the Python Package Index), which is what pip and uv use. -conda packages and PyPI packages are not always interchangeable β€” generally, inside an -environment, prefer uv pip/pip for Python packages and let conda handle only what it -does best.

-

conda vs uv: global vs local

-

A quick comparison to help you choose.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Topicconda (Miniconda)uv
Environment scopeglobal β€” named envs stored in one place (~/miniconda3/envs)local β€” a .venv folder inside each project
Activate commandconda activate <name>source .venv/bin/activate (macOS/Linux) / .venv\Scripts\activate (Windows)
Re-activate after restartconda activate <name> again (env still exists globally)source .venv/bin/activate again β€” or just uv run (no activate needed)
Non-Python depsYes (CUDA, R, …)No (Python only)
SpeedSlowerVery fast
Best forData-science stacks needing system libsEveryday Python projects
-
-

πŸ’‘ -Our default recommendation: uv. Create one .venv per project, and use uv run -so you rarely have to activate manually. Switch to conda only if a package you need -ships non-Python system libraries.

-
-
-
-
- -
-

Python Setup Guide · Back to home

-

Content is a work in progress — see the project readme for status.

-
- - + + + + + +2 Β· Virtual Environments + + + +
Python Setup Guide
+
+ +
+ +
+

A short, non-compulsory concept chapter. Understanding this now saves real pain later, when +two projects need different versions of the same package.

+

Why you need a virtual environment

+

A Python environment is a private, isolated copy of the interpreter plus its installed +packages. Without one, every package you install lands in a single global location, and +versions collide:

+
    +
  • Project A needs pandas 1.x; Project B needs pandas 2.x β†’ one of them breaks.
    • +
  • You install packages into the system Python (/usr/bin/python3 on macOS/Linux), which + the operating system itself relies on. Upgrading or removing something there can break + system tools.
    • +
+

A virtual environment keeps each project's dependencies in its own folder, so projects +never step on each other β€” and never touch the system Python.

+
+

⚠️ +On macOS/Linux, /usr/bin/python3 is managed by the system. Installing packages into it +with sudo pip install … can break OS tools. Always work inside a project environment.

+
+

uv

+

uv is a modern, extremely fast Python package and +environment manager written in Rust. It replaces pip, virtualenv, and parts of +conda. We recommend it for beginners because:

+
    +
  • One tool does everything (install Python, create envs, install packages, run scripts).
    • +
  • It is 10–100Γ— faster than pip.
    • +
  • Environments are created in a local .venv folder β€” no global state to manage.
    • +
+
uv init myproject      # create a new project with a .venv
+cd myproject
+uv pip install pandas  # install a package into this project's env
+uv run main.py         # run a script using this project's Python
+
+

Locking & recording dependencies: uv lock and requirements.txt

+

Installing packages is only half the story. To make your project reproducible β€” +so someone else (or future you) can rebuild the exact same environment β€” you record +what you installed.

+

requirements.txt (the classic, pip-style list)

+

A plain text file listing every package (and version) your project needs:

+
pandas==2.2.2
+numpy>=1.26.0
+requests
+
+
    +
  • Generate it from your current env with pip/uv:
    • +
+
uv pip freeze > requirements.txt     # uv
+pip freeze    > requirements.txt     # plain pip
+
+
    +
  • Rebuild an env from it on another machine:
    • +
+
uv pip install -r requirements.txt
+
+

The catch: requirements.txt only pins top-level packages. If pandas silently +pulls in a specific numpy, that sub-dependency version is not fixed β€” two people +can end up with different environments.

+

uv lock (the modern, exact solution)

+

uv goes further with a lockfile β€” uv.lock β€” that pins every package, +including all transitive dependencies, to exact versions and hashes:

+
uv add pandas          # adds pandas AND writes/updates uv.lock + pyproject.toml
+uv lock                # (re)resolve and write uv.lock without installing
+uv sync                # install exactly what uv.lock specifies
+
+

uv.lock guarantees that everyone who runs uv sync gets a byte-for-byte identical +set of packages. Think of it as requirements.txt on steroids.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
requirements.txtuv.lock
Pins top-level packagesYes (if you use ==)Yes
Pins transitive depsNoYes β€” exact versions + hashes
Human-readableYesMachine-generated (don't edit by hand)
Toolpip / uvuv only
+
+

πŸ’‘ +For coursework, requirements.txt is enough and easier to read. Once a project +matters (a real app, a paper's analysis), switch to uv.lock so results stay +reproducible. Either way, keep the file alongside your project so the environment +travels with your code.

+
+

conda / Anaconda / Miniconda

+

conda is an older, very popular environment manager, especially in data science. The +naming is confusing, so here is the split:

+
    +
  • Anaconda β€” the full distribution: conda plus 250+ pre-installed packages. Large + (~3 GB). Good if you want everything out of the box.
    • +
  • Miniconda β€” conda with no pre-installed packages. Small and clean. We recommend + Miniconda if you go the conda route.
    • +
  • conda-forge β€” a community channel (see below) of packages; usually more up to date + than the default defaults channel.
    • +
+

Unlike uv/pip, conda can also install non-Python dependencies (e.g. CUDA, R), which is +why many scientists like it.

+
conda create --name py312 python=3.12   # create a named environment
+conda activate py312                     # switch into it
+
+

Channels: conda-forge and others

+

A channel is a repository conda downloads packages from. The two you will meet:

+
    +
  • defaults β€” Anaconda's official, curated channel.
    • +
  • conda-forge β€” a community-run channel with broader, faster-updated packages.
    • +
+

We recommend preferring conda-forge:

+
conda create -n py312 python=3.12 -c conda-forge
+
+

This differs from PyPI (the Python Package Index), which is what pip and uv use. +conda packages and PyPI packages are not always interchangeable β€” generally, inside an +environment, prefer uv pip/pip for Python packages and let conda handle only what it +does best.

+

conda vs uv: global vs local

+

A quick comparison to help you choose.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Topicconda (Miniconda)uv
Environment scopeglobal β€” named envs stored in one place (~/miniconda3/envs)local β€” a .venv folder inside each project
Activate commandconda activate <name>source .venv/bin/activate (macOS/Linux) / .venv\Scripts\activate (Windows)
Re-activate after restartconda activate <name> again (env still exists globally)source .venv/bin/activate again β€” or just uv run (no activate needed)
Non-Python depsYes (CUDA, R, …)No (Python only)
SpeedSlowerVery fast
Best forData-science stacks needing system libsEveryday Python projects
+
+

πŸ’‘ +Our default recommendation: uv. Create one .venv per project, and use uv run +so you rarely have to activate manually. Switch to conda only if a package you need +ships non-Python system libraries.

+
+
+
+
+ +
+

Python Setup Guide · Back to home

+

Content is a work in progress — see the project readme for status.

+
+ + From b3ffbc4910859412136b3969b70d20eaf8b365b4 Mon Sep 17 00:00:00 2001 From: anin Date: Mon, 10 Aug 2026 22:42:55 +0800 Subject: [PATCH 2/6] docs: rewrite image paths to jsDelivr CDN, add VS Code setup screenshots - build_release.py: rewrite ../assets/img/ paths to jsDelivr CDN URLs - pages/ide-setup.md: add VS Code interpreter screenshot, CDN image links - release/*.html: regenerate with CDN-hosted images - pages\installation.md according to project requirement --- .workbuddy/memory/2026-08-10.md | 43 + AGENTS.md | 29 +- build_release.py | 11 +- pages/ide-setup.md | 4 +- pages/installation.md | 195 +++-- pages/virtual-environment.md | 113 ++- release/ide-setup.html | 848 +++++++++--------- release/index.html | 804 ++++++++--------- release/installation.html | 1292 ++++++++++++++-------------- release/recommended-reading.html | 838 +++++++++--------- release/unix-basics.html | 1382 +++++++++++++++--------------- release/virtual-environment.html | 1116 ++++++++++++------------ 12 files changed, 3423 insertions(+), 3252 deletions(-) create mode 100644 .workbuddy/memory/2026-08-10.md diff --git a/.workbuddy/memory/2026-08-10.md b/.workbuddy/memory/2026-08-10.md new file mode 100644 index 0000000..8bfe2fe --- /dev/null +++ b/.workbuddy/memory/2026-08-10.md @@ -0,0 +1,43 @@ +# 2026-08-10 β€” conda-first install guide + git recovery incident + +## Project +`python-setup-moodle` β€” beginner Python install tutorial (English prose, Chinese UI chat). +Convention (AGENTS.md): emoji callouts (πŸ“πŸ’‘βš οΈβ—) instead of GitHub alert syntax; no authoring +instructions in reader-facing `.md`; commands split per OS, no copyable `$`. + +## install guide content decisions (this session) +- Reorder: **conda first (Method A, most recommended)**, **uv second (Method B)**, standalone third. +- Anaconda vs Miniconda: documented as two conda distributions (differ only in pre-installed + packages; full Anaconda ~3GB, Miniconda minimal). "conda" command identical for both. +- Install now requires **concrete versions** (not "latest"). Anaconda example Anaconda3-2026.07-1. +- Course env = **`mffintech`** (cloned from base): out-of-box Python 3.14.6 / NumPy 2.4.6 / + pandas 3.0.3 / PyArrow 23.0.1 / pytest 9.0.3 / JupyterLab 4.5.9. Extra: duckdb=1.5.4, + polars=1.43.2, yfinance=1.5.2. +- **conda rule:** prefer `conda install` over `pip` inside conda envs (pip pkgs invisible to conda). +- uv: must `cd` into project before `uv pip install`/`uv run` or it pollutes `~/.venv` in home. +- Section order: test β†’ Run your first program β†’ **How to debug** (debug moved to very end). + +## ⚠️ GIT REPO IS FRAGILE β€” read before any git op +- During a PR attempt the repo got corrupted. `main` ref now = `08aa301` (origin/base, the + published Aug-5 version). `HEAD` currently points to branch `docs/ide-setup-cdn-images`. +- A dangling root commit `0235d60` exists but its tree is broken at the `pages` subtree + (object `ad15a881` missing) β†’ cannot extract files from it. +- Loose blob `477f05` = an *intermediate* installation.md (has conda-first + πŸ“ note, but + missing mffintech/pkg-table/conda-install/Miniconda-links/heading-restructure/uv-warning). +- **Do NOT run `git commit`/`checkout -f`/`switch` casually here** β€” earlier a `checkout -f main` + reverted installation.md, virtual-environment.md AND AGENTS.md to base (lost all our edits). + +## Recovery status (end of session) +- `pages/installation.md`: **REBUILT** (conda-first, mffintech env, pkg table, conda-install + pref, Miniconda links, heading restructure, uv cd warning, debug-at-end). NOT touched again. +- `pages/virtual-environment.md`: **REBUILT this turn** (full Write). Re-ordered conda+Channels + BEFORE uv; added Anaconda vs Miniconda comparison table; fixed Channels to "prefer conda + install over pip"; added uv `requirements.txt` 2nd method + cd warning; ending πŸ’‘ now + recommends **conda (Miniconda)**. +- `AGENTS.md`: **REBUILT this turn** (3 Edits). "why conda is preferred (uv as fast + alternative)"; conda listed before uv; "specific, concrete versions" (no "latest"); with + conda split into **Anaconda + Miniconda** two distributions, each with verified install-doc + URLs (mac-cli-install / windows-cli-install / linux-install). +- Verified Anaconda install-doc URLs via WebFetch: mac-cli-install βœ“, windows-cli-install βœ“, + linux-install βœ“. (mac-os-install / mac-install / windows-install all 404.) +- Temp/backup files created during recovery were deleted; `.bak.tar.gz` removed. diff --git a/AGENTS.md b/AGENTS.md index 2f83111..ccd9489 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -70,14 +70,13 @@ Options and arguments (and corresponding environment variables): - why executables on windows has `exe` extension and why unix does not have - pwsh commands: unix-like aliases and its original commands and why windows is not prefered. e.g. `Get-Command` = `which` ### (short, non-compulsory)concept of virtual enviroment -- why need virtual env rather than standalone python, why uv is prefered. why /usr/bin/python3 cannot be used directly -- uv +- why need virtual env rather than standalone python, why conda is preferred (uv as a fast alternative). why /usr/bin/python3 cannot be used directly - conda:https://www.anaconda.com/docs/getting-started/concepts/anaconda-or-miniconda -- anaconda -- miniconda, difference of channels, conda-forge and others +- anaconda (full distribution: conda + 250+ pre-installed packages, ~3 GB) and miniconda (minimal installer: conda only, ~100 MB), difference of channels, conda-forge and others +- uv:https://docs.astral.sh/uv/ (fast alternative) - difference of `conda` and `uv`, `conda activate` vs `source .venv/bin/activate`, global vs local enviroment ### (very detail) How to installation python executable -- how to choose version (amd64, arm64, x86_64, exe) and how to set up first python enviroment +- how to choose **specific, concrete versions** β€” a fixed Python version (e.g. 3.12), the exact CPU arch (amd64, arm64, x86_64, aarch64), and the exact installer version number for Anaconda/Miniconda. Never write "latest" or leave the version blank. Then how to set up first python enviroment - standalone installation, double click exe to install - win: - https://www.python.org/downloads/windows/ @@ -91,14 +90,18 @@ Options and arguments (and corresponding environment variables): - with standalone installer:https://www.python.org/downloads/source/ - typecially it will be installed under the path of -- with conda: - - url: - - macos:https://www.anaconda.com/docs/getting-started/miniconda/install/mac-cli-install#using-miniconda-in-a-commercial-setting - - windows:https://www.anaconda.com/docs/getting-started/miniconda/install/windows-cli-install#powershell - - linux:https://www.anaconda.com/docs/getting-started/miniconda/install/linux-install#installation-steps - - how to install - - introduce cli reference`conda create --name py310 python=3.12` - - `conda activate ` condaand how to re-activate after close terminal +- with conda (two distributions β€” pick one): + - **Anaconda** (full distribution: conda + 250+ pre-installed packages, ~3 GB) β€” official install docs: + - macos: https://www.anaconda.com/docs/getting-started/anaconda/install/mac-cli-install + - windows: https://www.anaconda.com/docs/getting-started/anaconda/install/windows-cli-install + - linux: https://www.anaconda.com/docs/getting-started/anaconda/install/linux-install + - **Miniconda** (minimal installer: conda only, no pre-installed packages β€” recommended) β€” official install docs: + - macos: https://www.anaconda.com/docs/getting-started/miniconda/install/mac-cli-install + - windows: https://www.anaconda.com/docs/getting-started/miniconda/install/windows-cli-install + - linux: https://www.anaconda.com/docs/getting-started/miniconda/install/linux-install + - how to install (same for both distributions) + - introduce cli reference `conda create --name py310 python=3.12` + - `conda activate ` and how to re-activate after close terminal - how to set specific pre-installed python executable for new env to save space - with uv: - url: https://docs.astral.sh/uv/getting-started/installation/#pypi diff --git a/build_release.py b/build_release.py index fc6503a..b24fb6e 100644 --- a/build_release.py +++ b/build_release.py @@ -76,8 +76,15 @@ def slugify(s): def render_body(md_text): """Render markdown to HTML and add heading ids / collect a TOC.""" html = _md.markdown(md_text, extensions=MD_EXTENSIONS) - # TODO: image src still uses the local relative path (`../assets/img/...`). - # Rewrite to a GitHub permalink before publishing (see file header). + # Rewrite local image paths (../assets/img/...) to GitHub permalink + # via jsDelivr CDN, so the release HTML is fully self-contained and + # needs no bundled assets/ folder. + GITHUB_CDN = "https://cdn.jsdelivr.net/gh/fyq163/python-setup-moodle@main" + html = re.sub( + r'src="\.\./assets/img/([^"]+)"', + lambda mo: 'src="%s/assets/img/%s"' % (GITHUB_CDN, mo.group(1)), + html, + ) # Turn any leftover GitHub-style alert markers into emoji callouts. html = re.sub( r'
\s*

\s*\[!(NOTE|TIP|WARNING|IMPORTANT|CAUTION)\]\s*', diff --git a/pages/ide-setup.md b/pages/ide-setup.md index aef3a88..0ba6511 100644 --- a/pages/ide-setup.md +++ b/pages/ide-setup.md @@ -18,10 +18,11 @@ identical: 4. Select the interpreter: press `Ctrl/Cmd + Shift + P`, type **"Python: Select Interpreter"**, and choose the environment you made in Chapter 3 (the `.venv` or conda env). The bottom-right status bar then shows that Python. + ![vscode plugin marketplace](https://cdn.jsdelivr.net/gh/fyq163/python-setup-moodle@main/assets/img/vscode-extension-python.png) 5. Use the built-in terminal (`Ctrl/Cmd + `` `) to run `uv run main.py` or `python main.py`. -![TODO: Screenshot of VS Code β€” the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.](../assets/img/placeholder.svg) +![Screenshot of VS Code β€” the "Python: Select Interpreter" picker, highlighting the virtual environment created in Chapter 3.](https://cdn.jsdelivr.net/gh/fyq163/python-setup-moodle@main/assets/img/vscode-interpreter-selection.png) > πŸ’‘ > Once the interpreter is selected, the play button (β–Ά) and the terminal both use *your* @@ -57,4 +58,3 @@ Python your shell currently has active. GitHub Copilot is an AI pair-programmer that suggests code as you type. **Students get it free** (and many other developer tools) through the [GitHub Copilot - Information Technology Services - HKU](https://its.hku.hk/software/github-copilot/) -pack with a school email. \ No newline at end of file diff --git a/pages/installation.md b/pages/installation.md index 93563fc..a1c3ab7 100644 --- a/pages/installation.md +++ b/pages/installation.md @@ -3,8 +3,8 @@ title: 3 Β· Installing Python tag: Required --- -The detailed chapter. Three methods (standalone / conda / uv) Γ— three platforms (macOS -arm64, Windows amd64, Linux x86_64). **Pick one method** β€” we recommend **uv** for +The detailed chapter. Three methods (conda / uv / standalone) Γ— three platforms (macOS +arm64, Windows amd64, Linux x86_64). **Pick one method** β€” we recommend **conda** for beginners. You only need Python installed once per machine. ## How to choose a version & architecture @@ -16,65 +16,116 @@ beginners. You only need Python installed once per machine. - **macOS:** Apple Silicon Macs (M1/M2/M3/M4) β†’ **arm64**. Intel Macs β†’ **x86_64**. - **Windows:** almost all modern PCs β†’ **amd64** (also called x64). - **Linux:** most desktops/servers β†’ **x86_64**; newer ARM boards β†’ **aarch64**. +> πŸ“ The guide below shows one standard installation. This course will teach using this +> version as the reference, but you are always free to choose your own way to install +> based on your needs. -If you are unsure, the installer pages below usually auto-detect the right one. +## Method A Β· With conda (most recommended) -> **⚠️ Choose a Stable Release (all methods & platforms).** Whether you use the standalone -> installer, conda, or uv, pick a **Stable Release** β€” the latest stable version (e.g. -> Python 3.12.x or 3.13.x). **Do not** download or install anything marked *Pre-release* or -> *Development*: those builds are for testing and may be unstable or break your packages. +Best for beginners: one environment manager that also handles data-science and +non-Python system dependencies (CUDA, R, …). -## Method A Β· With uv (most recommended) +### Install Conda. -Best for beginners: one fast tool, local environments, minimal fuss. +#### Standard Anaconda Installation -1. Install uv. Open the uv website (docs.astral.sh/uv) in your browser, go to the - **Installation** page, and download the installer for your system (macOS, Windows, or - Linux). Run it and follow the on-screen prompts β€” pick the default options when asked. - When it finishes, uv is installed. +##### Windows: Anaconda Windows 64-bit -> πŸ“ After install, **close the terminal and open a new one**, then verify with `uv --version`. +1. download the installer + ```powershell + Invoke-WebRequest -Uri "https://repo.anaconda.com/archive/Anaconda3-2026.07-1-Windows-x86_64.exe" -OutFile ".\Anaconda3-2026.07-1-Windows-x86_64.exe" + ``` + **Alternatively**, download the installer from the url and change directory to the location where it was downloaded, then double click it to run. +2. Then **double click it to run installation**. -2. Install a Python and create your first project: +##### macOS -```bash -uv python install 3.12 # download CPython 3.12 (one time) -uv init myproject # create a project folder with a .venv -cd myproject -uv pip install pandas # install a package into this project -uv run main.py # run a script with this project's Python -``` + ```bash + curl -O https://repo.anaconda.com/archive/Anaconda3-2026.07-1-MacOSX-arm64.sh + bash ./Anaconda3-2026.07-1-MacOSX-arm64.sh + ``` + > **Alternatively**, download the installer from the url and change directory to the location where it was downloaded, then paste it's path in the terminal and run it with `bash `. + > ⚠️ If you have an *Intel Mac*, see below for miniconda option, anaconda has stopped supporting Intel Macs. -- **After closing the terminal**, you do **not** need to "activate" β€” just run - `uv run