Skip to content

README.md

Latest commit

 

History

History
168 lines (120 loc) · 5.09 KB

README.md

File metadata and controls

168 lines (120 loc) · 5.09 KB

Python Learning Site

A small Vite/React site for teaching Python through short lesson modules, quizzes, runnable code exercises, and dataset challenges.

Running The Site

Install dependencies once:

npm install

Start the local dev server:

npm run dev

Deploying the site

run the following locally

export NVM_DIR="$HOME/.nvm" && . "$NVM_DIR/nvm.sh" && nvm use v20.20.2
npm run build
npx gh-pages -d dist -b gh-pages --repo https://github.com/neuroinformatics-unit/osss-python-prep

Where Content Lives

Course and lesson content is in src/data/curriculum/.

Each file is one module:

  • pythonFoundations.ts
  • collectionsIndexing.ts
  • functionsModules.ts
  • controlFlow.ts
  • packagesNumpy.ts
  • pandasPlotting.ts
  • errorsObjectsStructure.ts
  • assignmentsSupport.ts

The module order is controlled by src/data/curriculum.ts. That file imports each module and exports the final courses array used by the app.

Shared lesson helper functions live in src/data/lessonBuilders.ts.

Editing An Existing Lesson

Open the module file in src/data/curriculum/ and edit the relevant lesson entry.

Most lessons use one of these helper functions:

read(id, title, summary, concepts, body)
workshop(id, title, summary, concepts, body)
quiz(id, title, summary, concepts, body, prompt, options, answer, explanation)
code(id, title, summary, concepts, body, prompt, starterCode, expectedOutputContains, expectedIncludes, packages)
dataset(id, title, summary, concepts, body, datasetPath, mission, starterCode, expectedOutputContains, packages, hints)

The body field is an array of paragraphs. Inline Markdown-style links and inline code are supported in lesson text.

Keep lesson id values stable once published. Progress and exercise history are keyed by lesson id.

Adding A New Lesson

Add a new lesson object to the lessons array in the relevant module file.

Example read-only lesson:

read("reading-files", "Reading Files", "Use Python to open and inspect text files.", ["files", "open"], [
  "Python can read plain text files using `open()`.",
  "Use a `with` block so the file is closed automatically.",
])

Example code exercise:

code("average-two-values", "Practice: Average Two Values", "Calculate and print a mean.", ["operators", "print"], [
  "Store intermediate values with clear variable names.",
], "Calculate the average of `a` and `b`, then print it.", "a = 10\nb = 20\n\n# Calculate the average.\n", ["15"], ["print"])

For code exercises:

  • expectedOutputContains checks for strings in the program output.
  • expectedIncludes checks that the submitted code includes important syntax or function names.
  • packages lists Pyodide packages to load, such as ["numpy"] or ["pandas", "matplotlib"].
  • Use expectedPlotCount when the exercise should create plots.

Adding A New Module

Create a new file in src/data/curriculum/:

import type { Course } from "../types";
import { code, read } from "../lessonBuilders";

export const fileHandling: Course = {
  id: "file-handling",
  number: 9,
  title: "File Handling",
  theme: "Files",
  description: "Reading and writing local files with Python.",
  accent: "#111111",
  lessons: [
    read("file-paths", "File Paths", "Files live at paths.", ["files", "paths"], [
      "A path tells Python where to find a file.",
    ]),
  ],
};

Then import it and add it to courses in src/data/curriculum.ts.

Images And Data Files

Static files go in public/.

  • Put lesson images under public/images/....
  • Put CSV/XLSX files under public/data/....
  • Refer to public files with root-relative paths, for example /images/session1/slide09-01.png or /data/public_hospital_list.csv.

To add images to a lesson, spread a read() lesson and add an images array:

{
  ...read("terminal-basics", "The Terminal", "Use commands to run tools.", ["terminal"], [
    "The terminal is a text interface for running commands.",
  ]),
  images: [
    {
      src: "/images/session1/slide09-01.png",
      alt: "Terminal command typed into a command line",
      caption: "Commands are typed directly into the terminal.",
    },
  ],
}

For dataset lessons, use csvBase from lessonBuilders.ts:

dataset("hospital-mission", "Public Hospitals", "Analyse a hospital CSV.", ["pandas"], [
  "Load the data and answer a question from it.",
], `${csvBase}/public_hospital_list.csv`, "Print the number of rows.", "import pandas as pd\npath = '/data/public_hospital_list.csv'\n", ["100"], ["pandas"], ["Use `pd.read_csv(path)`."])

Code Examples

Longer display examples that appear inside lesson pages are kept in src/data/codeExamples.ts.

Use this when an example is reusable or too large to keep comfortably inside the lesson body. Match examples by lesson id.

Content Checklist

Before finishing a content change:

  1. Keep ids unique and descriptive.
  2. Check that any linked image or dataset exists in public/.
  3. For exercises, make the starter code valid Python.
  4. For exercises, make expected output specific enough to catch mistakes.
  5. Run npm test.
  6. Run npm run build before deploying.