Skip to content
This repository was archived by the owner on Oct 15, 2026. It is now read-only.

Latest commit

 

History

History
140 lines (131 loc) · 8.16 KB

AGENTS.md

File metadata and controls

140 lines (131 loc) · 8.16 KB
target python-beginner installation guide
target-audience new entrance post-graduate students with mixed background
target-Language English
target-platform arm64-macos, amd64-windows, x86_64-linux

python-beginner installation guide

This repo serves as tutorial for beginners to learn how to use install a python environment and use it to learn simple python lession.

what will be covered:

  1. basic unix-alike system introduction, path, command line (bash, zsh)
  2. basic python distribution and installation on different system, virtual environment etc
  3. how to run codes
  4. how to what to put in place of --config
  5. never include any instructions to site developer other than "TODO"
    • The reader is a beginner student, NOT the repo maintainer. Never put any authoring/dev-operations instructions into the tutorial text (.md chapters that render to reader-facing pages). This includes, but is not limited to:
      • "edit a .md / refresh the page to update" type hints
      • "commit/push the file to git", "run serve.py", "reload the page" instructions
      • any mention of the build/watch/reload workflow or repo internals
    • Authoring notes belong only in ![TODO: ...] image placeholders or HTML comments (<!-- TODO: ... -->), which are hidden from the rendered page. readme.md and serve.py are maintainer docs and are exempt from this rule.
  6. use emoji callouts, not GitHub-style alert syntax. Never write GitHub-style alert blocks (> [!NOTE], > [!TIP], > [!WARNING], > [!IMPORTANT]) in any reader-facing .md. Replace them with a leading emoji on the blockquote instead:
    • > [!NOTE] → > 📝
    • > [!TIP] → > 💡
    • > [!WARNING] → > ⚠️
    • > [!IMPORTANT]→ > ❗
    • > [!CAUTION] → > ⚠️ This keeps callouts visible without relying on GitHub-only rendering.

development phase

  • phase1: in html format, pure html for github page and paste to html previewer
  • phase2: tutorials in markdown format, with code snippets

your work step

  • plan for structure, ready to distribute github page
  • write first part
  • write second part
  • write third part

how to write this repo

welcome page

show welcome to hku students, and give a brief introduction to the repo. To better facilitate programming bootcamp students, we will provide a series of tutorials to help them learn how to install python on their pc and use it to learn simple python lessons. There are secions that can be skipped for those who have already learned the basics of programming. e.g. basic unix-alike system introduction. And why it's necessary to learn this while agents can do it for you. Also mention difference with pypy and cpython and state we use cpython

basic unix-alike system introduction (very basic )

  • (very short) what is command line, bash for linux, zsh for macos, recommand pwsh for windows, hot to find them on computer; how to invoke
  • sudo and run as administrator, sudo password is usually your macos login password
  • (short) useage of -h,--help, with example of (very short) difference of - and --
# fyq at Mbp.lan in ~/.pi [11:06:42]
$ ls -la

# fyq at Mbp.lan in ~/.pi [11:38:03]
$ python -h                    
zsh: command not found: python

# fyq at Mbp.lan in ~/.pi [11:38:15]
$ python3 -h
usage: /Applications/Xcode.app/Contents/Developer/usr/bin/python3 [option] ... [-c cmd | -m mod | file | -] [arg] ...
Options and arguments (and corresponding environment variables):
  • why there is no python on macos (with link jump to how many pythons are there on macos)
  • difference of Options and arguments
  • 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 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 (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

after install, test if it works

copy this command to your terminal and run it

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

it might return /Applications/Xcode.app/Contents/Developer/usr/bin/python3 which differs from what you have installed, explain why and how to fix it. might be path issue.

how to debug

  1. find the correct executable path
  2. put into .zshrc or activate virtual env

(short) code editor/IDE and how to configure

visual studio code series (vscode, cursor, codebuddy, trae etc)

pycharm community version

other poular coding cli

how to use can refer to command line part above

  • github copilot, student subscription:
  • opencode series: opencode, kilo, mimo

(very short; non-compulsory) recommand reading section

pep8

lsp: ty, pyright

lint tools: ruff

Design.md

  • commands should be seperated per system type, should be ready to paste and execute
  • so the code block should not have copyable $ which will mislead the reader