Python Language Levels (PLL)
PLL is a VS Code extension for learning Python. It runs your programs
inside the editor and shows the results in an interactions panel —
output, errors, images, tables, and a prompt where you can try extra
Python after a run.
It works in vscode.dev (in the browser) and in
desktop VS Code. You do not need to install Python on your computer.
Install
PLL needs VS Code 1.101 (June 2025) or newer. If you are installing VS
Code now, you have it; if yours is older, update it first.
- Open VS Code (desktop or vscode.dev).
- Open the Extensions view (the four squares in the left sidebar).
- Search for Python Language Levels.
- Click Install. If you are asked to trust the publisher, do that.
You do not need Microsoft's Python extension. If VS Code offers
to install it, you can skip it. PLL is enough.
Run a program
Create a file whose name ends in .py, for example hello.py.
Type a small program:
print("hello")
Look at the top right of the editor, on the same bar as the file name.
Click PLL: Run Python File.
If you do not see that text, open the Command Palette
(Ctrl+Shift+P on Windows, Cmd+Shift+P on a Mac) and run
PLL: Run Python File. Ctrl+Enter (Cmd+Enter on a Mac) in the
editor does the same.
The first run can take a little while: PLL is starting Python in the
editor. Later runs are faster.
A file with no #level line runs as plain Python, without PLL's
assistance, so every run of one asks first: Choose a Level opens the
list of levels, and Run as Plain Python runs it as it is. To run plain
Python without being asked, give the file #level raw. See
Language levels.
Your file stays a normal editor. Results appear in the PLL panel at
the bottom of the window (near Problems and Terminal). If that panel is
hidden, run PLL: Show Interactions from the Command Palette.
Before you have a file
With no Python file open, the PLL panel has a session of its own, called
No file: type Python at its prompt and press Enter. It is for the very
first things you try - on vscode.dev, before you have a repository to make
a file in. It always uses #level beginner. It has no folder, so it cannot
read files next to a program (a table or picture from a URL still works),
and a file it writes is not saved.
Once you open a Python file, the panel shows that file's session instead.
PLL: Start REPL switches back to the session with no file, which keeps
what you typed in it until the window closes - or until you clear it
(Ctrl+L, or the Clear button), which starts it afresh: nothing typed in
it before is defined any more.
Try things after a run
The interactions panel has a prompt at the bottom. After a file has
run, you can type extra Python there and press Enter. Names you defined
in the file are still available. The prompt uses the same language
level as that run (the one shown in the header).
- Enter runs what you typed.
- Shift+Enter adds another line (for a longer snippet).
- If Python is waiting for more input (for example after
if True:),
PLL will keep prompting until the snippet is complete.
- Up and Down move through things you typed earlier.
- Ctrl+L (Windows) or Cmd+L (Mac) clears the interactions panel.
You can also run PLL: Clear Interactions.
Stopping a program
If a program runs longer than you expect - a loop that never ends, say -
click Stop in the interactions panel. Ctrl+C (with nothing selected)
and PLL: Stop Program in the Command Palette do the same thing. The
program stops with a KeyboardInterrupt, and anything it printed first is
kept.
Stop works the same way while your tests run. The test that was running is
marked as stopped, and the rest of the tests do not run.
This works for ordinary Python code. If your program is stuck inside a
library (a very long pandas operation, for example), or if it catches
KeyboardInterrupt itself, PLL will tell you it could not stop it - reload
the window in that case.
Language levels
The first non-blank line of a file chooses how strict PLL is. The level
the panel's prompt is at is shown in the interactions header (for example
hello.py [beginner]).
#level beginner
Write it exactly like that, in lower case, as the first line that is not
blank.
| Line in your file |
What it does |
#level raw |
Nothing is checked. Your program runs exactly as plain Python would, with PLL's built-in libraries (images, tables) and the interactions panel still available. This is what you get if you leave the line out. |
#level beginner |
Strictest. PLL warns about reassigning a variable, reusing a name that hides another name (a built-in like list, or one of PLL's own like circle), the global / nonlocal keywords, removing a name with del, and is, which asks whether two values are the same object: x == None, not x is None. If it finds a problem, it does not run the file. Type annotations are checked as the program runs, and so are bitwise operators: ^, &, \|, <<, >> and ~ stop the program when used on numbers (^ is not a power). So does changing a list, a dictionary, a set or a dataclass in place - xs.append(4), d[key] = 1, del xs[0], p.age = 5 - and the message shows how to make a new one instead (xs + [4]). |
#level intermediate |
Same rules about hiding names, global / nonlocal, del and is, but you may reassign variables inside a function. That is useful for introducing for loops, where you need accumulators: total = total + n, or found = found + [n] for a list. Reassigning at the top of the file is still flagged. Annotations, bitwise operators and changes in place are checked. |
#level advanced |
Reassigning, hiding names, global / nonlocal, del, is, bitwise operators and changing a value in place are all allowed. Annotations are still checked as the program runs, but by Python's own rules (so True counts as 1). |
At beginner, intermediate and advanced PLL also looks, before the
file runs, for a name used where it has no value: a misspelling, a
function called above its def, a variable read before it is set, or a
call that runs a function before a name the function uses is set. Python
would stop there with a NameError; PLL says so, the same way, without
running the file.
At those three levels every file also starts with dataclass and
Callable, as it does with PLL's image and table functions, so neither
needs an import; at beginner and intermediate an import of either is
reported, with what to delete. At #level raw, as in Python, they are
from dataclasses import dataclass and from collections.abc import Callable.
A ... stops the program when it runs, at those three levels: there it
holds the place of code still to be written, so a function whose body is
... can be defined, and its tests written, but stops when it is called.
A ... in a type (tuple[int, ...]) is left alone. At #level raw, as in
Python, ... is a value that does nothing.
The level is the only thing that decides what gets checked — there is no
separate setting to keep in sync with it.
The #level line in the editor
PLL keeps a file's #level line where it is, so it is not lost by accident.
The line is tinted, with a lock beside it, and hovering over it says where to
change it: the status bar, which shows the level — PLL: beginner, or
PLL: raw for a file with no line. Clicking that opens a list of the levels,
where you can also remove the line, or give a file with no line one; so does
PLL: Change Level in the Command Palette.
Editing the line itself does nothing to it. Select All selects everything
below it, so Select All and Delete empties the file but keeps the line.
Typing into the line puts what you typed on the line below, and deleting the
line puts it back. Pasting in a whole program with its own #level line
gives the file that program's level. Undo works as usual.
Each file keeps its own level when another file imports it. If main.py
does from helper import half and helper.py starts with #level beginner, then helper.py is checked as a beginner file, whatever level
main.py has: if the checks find a problem in it, the import stops with a
ChecksFailed error that lists each problem, and its annotations are
checked as it runs. (So a grading script can import a student's file and
get the student's level.)
If your course sets pll.newFileLevel, every new .py file you create
starts with that level line already written in, so you do not have to
remember it. You can always change or delete the line.
The prompt at the bottom of the interactions panel uses the same
level as the last run. If you have not run the file yet, it uses the level
the file's #level line names, as it is now. Either way, the header shows
it.
Type annotations are checked as your program runs
If you write annotations, PLL checks them while the program runs and stops
with an explanation the moment a value does not match:
def book_cost(num_books: int, hardcover: bool) -> float:
if hardcover:
return num_books * 25
return num_books * 12
book_cost("three", True)
book_cost expects num_books to be a whole number (int), but got a
string (str).
You do not need to import anything, and it works at every level except
#level raw. What is checked:
- the arguments you pass to a function, checked at the call
- the value a function returns, including a function that ends without
returning anything when it says it returns something
- variables you annotate, like
total: int = 0
- every item in an annotated
list, dict, set, or tuple
- the fields of a dataclass, when one is made and when a field is changed
- a type with its type filled in, like
BinTree[float], all the way down
Functions without annotations are left completely alone. A whole number is
accepted wherever a float is expected, as it is in normal Python.
An annotation has to name a type. -> 12345, or a variable that holds a
number or a string, is an error as soon as the def runs.
An annotation may name a type defined further down the file, so a type that
refers to itself needs no quotes:
@dataclass
class Node:
first: int
rest: Chain
type Chain = Node | None
At the student levels, annotations are read when they are needed, as they
are with from __future__ import annotations. At #level raw, which is
plain Python, they are read as the file runs, so rest would need the
quotes: rest: "Chain".
Functions passed to functions
A Callable annotation is a promise about a function that is handed over,
and PLL checks it each time that function is called - then says who broke
the promise. At the student levels Callable needs no import (at #level raw, as in Python, it is from collections.abc import Callable):
#level beginner
def shout(word: str) -> str:
return word.upper() + "!"
def apply_to_42(f: Callable[[int], str]) -> str:
return f(42)
apply_to_42(shout)
shout expects word to be a string (str), but it was handed over on
line 9 and then called by apply_to_42 with a whole number (int).
apply_to_42 kept its promise - it calls f with a whole number - so the
line that handed shout over is the mistake. Had apply_to_42 called f
with a string instead, it would be the one blamed: its annotation says f
is given whole numbers. A function handed over only has to take the right
number of arguments; the rest is checked when it is called. The same goes
for a function another one returns.
Generic functions
A function with a type variable, def first[T](https://github.com/dbp/pll/blob/HEAD/lst: list[T]) -> T, promises
to work for every type, and at #level beginner and #level intermediate
PLL holds it to that, as LSL's All does. A value it is given as a T can
only be passed along - to a function, into a list or a dataclass, or back:
adding one, comparing one (even with ==), printing one or testing it with
isinstance stops. And what it gives back as a T must be one of those:
#level intermediate
def wrong_first[T](https://github.com/dbp/pll/blob/HEAD/lst: list[T], default: T) -> T:
return 5
wrong_first(["oak"], "none")
wrong_first says it returns a T, but this line returns 5, which it
wasn't given as a T.
A T | None can still be told from None, with is None or == None.
To seal the Ts in a list or a dataclass, PLL hands the function a copy,
so #level advanced, where a list can be changed, leaves type variables
unchecked. So does a T in a set, among a dictionary's keys or in an
Iterable, which cannot be copied that way; one with a bound or
constraints (T: (int, float)) is checked as them.
At #level beginner and #level intermediate, True and False are
not accepted where int or float is annotated:
#level beginner
shelf_count: int = True # error: True is not a whole number here
Python itself counts True as 1, so this is a rule PLL adds rather than
one Python enforces — a value that is really a yes/no answer should be
annotated bool. At #level advanced this follows Python's own rule and is
allowed.
To turn annotation checking off entirely, write #level raw at the top of
the file (or leave the level line out).
Tests
You can put tests in the same file as the code they check. A test is
a function whose name starts with test_. Use assert to check that
something is true:
def add(x, y):
return x + y
def test_add():
assert add(2, 3) == 5
When you click PLL: Run Python File, PLL runs your file, and then its
tests, and shows a pass/fail card in the interactions panel after what the
program printed. The tests see everything the file defined. If a test
fails, you can click it to jump to that test. If the program stops with an
error, or ends itself with sys.exit(), the tests are not run, and PLL
says so.
A test takes no parameters: PLL calls it with nothing. One written with
parameters - def test_add(x): - is not run, and PLL says what is wrong
with it above the card, apart from the tests that ran.
You do not need a separate test file, and you do not need to run
pytest in a terminal.
For decimal (floating-point) numbers, exact == can be unreliable.
Import pytest and use pytest.approx:
import pytest
def test_cost():
assert 0.1 + 0.2 == pytest.approx(0.3)
Checking your tests against your course's code
Some assignments ask you to write the tests first, before the code. There
is nothing of your own to run them against yet — so PLL can run them against
code your course wrote: implementations known to be correct, and
implementations known to contain a bug.
Your course gives you a line to put at the top of the file:
#examplar https://example.edu/hw3.json
After that, every run adds a card for each function the assignment asks for:
total Examplar
Against correct implementations: all 3 of your tests pass.
Against buggy implementations: caught 4 of 6 - missed [#2](https://github.com/dbp/pll/issues/2), [#5](https://github.com/dbp/pll/issues/5).
The first line asks whether your tests are right — do they agree with
code that works? The second asks whether they are thorough — how many of
the deliberately broken versions did they notice? One test_ function is
enough to start; you do not need to have written any of the assignment.
It will not tell you the answer. If a test expects the wrong thing you
are told which test, never what it should have said — otherwise you could
read the assignment straight off the card, one deliberately-wrong test at a
time. A buggy version you missed gives up its number and nothing else.
Working out what you failed to check is the exercise.
Coverage only appears once every test of that function passes, because a
wrong test fails on the buggy versions too and would look as though it had
caught them. Each function is scored on its own, and one you have not
started says simply "No tests yet."
Two things to know. Your program does not run during the check — only your
definitions are loaded, so a print at the end of your file still happens
once, right afterwards. And files next to your program are not available
during it, so a test that opens data.csv cannot run there; the card says
so rather than calling that test wrong.
None of this is a grade. It shows you where your tests are thin while you
still have time to do something about it.
Using your course's code
An assignment can give you functions to use without showing you their code:
to work out what they do, say. Your course gives you a line for your file,
naming the bundle they come in:
#level beginner
#bundle mystery https://example.edu/lab5.json
mystery.shuffle([1, 2, 3])
The line gives your file the name mystery, with no import, and its
functions are mystery.shuffle and the rest. The bundle is fetched when the
file runs, and kept, so a run without a network uses the copy it got last.
An error inside one of its functions is shown at your line that called it,
and says which function it was in, as "Inside shuffle: ...". The code is
your course's, so what you can change is what you give it.
A bundle's code runs as your own does, with nothing checking it, so only use
#bundle lines your course gives you. Courses make bundles with the command
line, pll bundle build: see pll-python on
npm.
Images
You can make pictures with built-in functions. You do not need to
import anything. If a line in your file produces an image, PLL shows
it in the interactions panel, in order with any print output.
#level beginner
circle(50, "solid", "red")
beside(
triangle(60, "solid", "gold"),
square(60, "outline", "navy"),
)
Each picture has a Save SVG button if you want to keep it.
In print("Area:", picture), the text is a line of its own, above the
picture. At #level raw, print is Python's, and prints <Image 20x20>.
Shapes: circle, square, rectangle, ellipse, triangle,
right_triangle, regular_polygon, star, star_polygon, line,
text.
Combining and transforming: beside, above, overlay, underlay,
rotate, scale, flip_horizontal, flip_vertical.
Placing things exactly: overlay_xy and underlay_xy move the second
image by an offset — overlay_xy(a, 20, 10, b) puts b 20 to the right and
10 down from a. Negative offsets move it left or up, and the picture grows
that way rather than cutting anything off.
Choosing which edges line up: beside_align("top", ...),
above_align("left", ...), overlay_align("right", "bottom", ...), and
underlay_align. Horizontal positions are "left", "center", "right";
vertical are "top", "center", "bottom".
Scenes: empty_scene(width, height) is a fixed-size canvas, and
place_image(image, x, y, scene) puts an image's center at that point
on it, cropping anything past the edge. crop(x, y, width, height, image)
takes a piece out of an image, and frame(image) outlines its edges.
Size: image_width, image_height, empty_image.
The shapes are drawn as 2htdp/image draws them: an outline is a 1-pixel
pen just inside the shape, a rotated picture's box is the box of the turned
shapes (so a circle turned is as wide as it was), star and
star_polygon are true star polygons, and right_triangle's right angle
is at the bottom left. text is set in a monospace font, so its size is
exact and its spaces are kept.
Two pictures are == when they draw the same shapes in the same places in
the same colours, however they were built - so a test can compare what a
function draws with what it should:
def test_dot():
assert dot(3) == circle(3, "solid", "red")
Colors can be names ("red"), hex ("#ff0000" or "#f00"),
"rgb(255, 0, 0)" or "hsl(0, 100%, 50%)", or tuples (red, green, blue)
with values from 0 to 255. A fourth number is how solid it is: in a tuple, a
whole number from 0 to 255, or a fraction from 0.0 to 1.0, so
(255, 0, 0, 128) and (255, 0, 0, 0.5) are both half see-through; in
"rgba(255, 0, 0, 0.5)" and "hsla(...)", a fraction. Names are checked against the CSS colours, which are
the names a browser understands, so a misspelling is an error that suggests
what you meant ("rd" → "Did you mean red?", "light blue" → "Did you
mean lightblue?") rather than an invisible shape. "transparent" works
too.
Loading a picture
load_image reads a picture from a file next to your program or from an
address, working out which from what you give it:
cat = load_image("cat.png")
cat = load_image("https://example.edu/cat.png")
It gives you an ordinary picture, so everything above works on it —
scale, rotate, beside, place_image and the rest. PNG, JPEG, GIF,
WebP and SVG files are understood, up to 2 MB each, from a file or an
address — these are for the graphics a program draws with, not for
photographs.
Tables and charts
PLL also includes a table type (again, no import). Tables do not
change in place: each operation returns a new table.
people = table(
["name", "age"],
[
["Ada", 36],
["Grace", 85],
],
)
people
people.bar_chart("name", "age", title="Age")
Tables show up as a card you can scroll, with a Save CSV button, which
saves the whole table, every row and every digit. A number is shown as
Python prints it (12999.99, 2.0), and columns of numbers line up on the
right - so a column of numbers that is still text, from a CSV, can be seen
to be. Charts are pictures: they show up as images, and beside, above
and the rest work on them.
Loading a CSV
load_table reads a CSV, either from a file next to your program or from
an address — it works out which from what you give it:
cars = load_table("cars.csv")
cars = load_table("https://example.edu/cars.csv")
The first row names the columns, and every value arrives as text —
including the ones that look like numbers. An empty cell is "". A file
saved by Excel is read either way: "CSV UTF-8", and a plain "CSV" in
Windows-1252, which PLL says it has done. Convert a column when you want to
chart it or average it:
cars = load_table("cars.csv").transform_column("mpg", float)
cars.histogram("mpg")
That is one more line than guessing which columns are numbers, and it is
the line that says what you meant: a column of years or postcodes is not
something to do arithmetic on, and one stray n/a would otherwise change
what the whole column holds.
Methods
Useful ones include filter, transform_column, add_column,
add_row, order_by, select_columns, head, columns, length,
row, column, sum, mean, min, and max. For a median, a standard
deviation or anything else of that sort, use a column with Python's own
statistics module. A row is a Row, which is a dict.
sum of whole numbers is a whole number. At beginner and intermediate,
True and False are not numbers to a table: sum, mean, the charts,
linear_regression and function_plot refuse them, and min, max and
order_by put them after the numbers. min, max and
order_by refuse a column of numbers that is still text when comparing it
as text would give a different answer ("9" comes after "100"), and say
to convert it first.
Two tables are == when they have the same columns, in the same order,
holding the same values — so you can test a function that builds a table
by comparing it with the table you expect. When such a test fails, it says
which row is the first to differ.
Charts
| Chart |
What it shows |
bar_chart(labels, values) |
one bar per row |
freq_bar_chart(column) |
one bar per distinct value, counting the rows |
pie_chart(labels, values) |
each row's share of the total |
scatter_plot(x, y) |
one point per row |
line_chart(x, y) |
points joined in order of x |
dot_plot(column) |
one dot per row, stacked where rows share a value |
box_plot(column) |
quartiles, whiskers and outliers |
histogram(column) |
counts per bucket — bins= how many, or bin_width= how wide |
lr_plot(x, y) |
a scatter plot with the line of best fit, and r² in the title |
labeled_scatter_plot, labeled_dot_plot and labeled_lr_plot take an
extra first argument: a column to colour the points by, with a key. Every
chart takes an optional title=, and needs a table with at least one row; a
histogram has at most 1,000 bars. linear_regression(x, y) gives you the
slope, intercept and r² as numbers instead of a picture.
To draw a function rather than a table, function_plot takes the function
and the range to draw it over:
function_plot(lambda x: x * x, -3, 3)
If you already know pandas, my_table.to_pandas() gives you a DataFrame.
You can also import pandas as pd and read a CSV from a URL with
pd.read_csv("https://..."), and urllib and requests work too. That
works in desktop VS Code, on the command line and in the browser. An
address that answers with an error (a 404) raises HTTPError, as in
Python; one that does not answer at all gives up after 60 seconds, or the
timeout a program gives, and Stop ends the wait. In the browser, the site
must allow cross-origin requests (CORS) — the same goes for load_table
with an address.
Charts with matplotlib
import matplotlib.pyplot as plt works too: plt.show() shows each figure
in the panel as a picture, and so does a figure on a line of its own at a
student level. The text and lines plt.title(...) or plt.plot(...) give
back are not printed.
Packages
A program can import any package Pyodide has - numpy, pandas, matplotlib,
requests, scipy and many more. PLL finds them before the program runs, from
its imports wherever they are, and from those of the files of yours it
imports; the first time, it downloads them, which needs the network. A
package Pyodide does not have (flask) is said to be one, rather than
left as No module named 'flask'.
Animations and interactive programs
A reactor is an interactive program: a starting state, a function that
draws it, and functions that change it when something happens. It shows up
as a card right in the interactions panel.
The quickest way in is animate, where the state is just a frame counter:
scene = empty_scene(320, 140)
animate(lambda n: place_image(circle(14, "solid", "crimson"), (n * 4) % 320, 70, scene))
The long form names each handler:
reactor(
init=(160, 70),
to_draw=lambda spot: place_image(star(18, "solid", "gold"), spot[0], spot[1], scene),
on_key=move, # def move(spot: tuple[int, int], key: str) -> tuple[int, int]
title="Arrow keys",
).interact()
| Handler |
When |
to_draw |
every frame |
on_tick |
on the clock |
on_key |
a key press — "left", "a", " ", … |
on_mouse |
"button-down", "button-up", "drag", "move", "enter", "leave" |
stop_when |
after each change; True ends it |
on_receive |
a message from a server (see below) |
Their signatures are below, where State stands for the type of the state
and Message for the type of a server's messages. The names are yours to
choose.
def draw(state: State) -> Image: ... # to_draw
def tick(state: State) -> State: ... # on_tick
def press(state: State, key: str) -> State: ... # on_key
def mouse(state: State, x: int, y: int, event: str) -> State: ... # on_mouse
def done(state: State) -> bool: ... # stop_when
def receive(state: State, message: Message) -> State: ... # on_receive
Also tick_rate (seconds between ticks, default about 1/28) and title.
Each handler returns the new state. Click the picture before using the
keyboard, so the keys go to the reactor and not the prompt.
Playing, pausing, and rewinding
The card has play / pause, a single-step button, and a slider. Every state
the reactor passes through is recorded, so you can drag the slider back to
watch what happened and then play forward again from there.
big_bang(init, ...) is the same as reactor(...).interact().
Testing a reactor without watching it
A reactor is a value, so you can run it without any of the animation:
countdown = reactor(init=10, to_draw=..., on_tick=lambda n: n - 1,
stop_when=lambda n: n <= 0)
countdown.simulate_trace(20).get_trace() # [10, 9, 8, ..., 0]
countdown.get_value() # 10 — the original is unchanged
countdown.react({"kind": "tick"}).get_value() # 9
react returns a new reactor, so this works in tests and at the prompt.
Talking to a universe server
A reactor with a register address is a world: it connects to a server
and can send and receive messages.
reactor(
init=...,
to_draw=...,
on_key=lambda state, key: package(new_state, {"at": [x, y]}),
on_receive=lambda state, message: ...,
register="ws://localhost:8080",
).interact()
package(state, message) returns the new state and sends a message.
Whatever the server sends back arrives at on_receive. The card shows
whether it is connected.
You write worlds; the server is a separate program your course runs, in
whatever language they like. Messages are JSON, one value per message, in
each direction — so a conforming server is small, and your course will give
you one to run.
In the browser, a page served over https (including vscode.dev) can only
reach a wss:// address — except on localhost, which is allowed either
way.
input() asks for a line in the interactions panel, in desktop VS Code
and in the browser. The prompt string prints first, then you type a
reply and press Enter. Stop - or Ctrl+C with nothing selected -
stops the program there with a KeyboardInterrupt, as Ctrl+C does in a
terminal.
name = input("What is your name? ")
print("Hello,", name)
Files next to your program
open("data.csv") and pd.read_csv("data.csv") read files that sit in
the same folder as the .py file you ran, or in a folder inside it:
open("data/2024.csv"). That works in desktop VS Code and in the browser
(including vscode.dev). Files are read exactly as they are on disk, so a
CSV saved in another encoding, or a picture, arrives intact.
After the program finishes, files it wrote or changed — for example
to_csv("out.csv") or open("results/out.csv", "w") — show up in that
folder, and a file it deleted is deleted. You can open them in the editor.
Some are never saved, and the panel names each one and why ("Not saved:
..."):
- your
.py files, which PLL never overwrites or deletes;
- a file the program was not given (too big, say) — saving what it wrote
would replace a file it never saw;
- a file that changed while the program ran, or that is open in the
editor with changes you have not saved.
Untitled editors (not yet saved to a folder) have no files around them to
load or save.
There are limits: at most 100 files are loaded, each at most 50 MB and 100
MB in all - those nearest the program first - and the same for the files
saved afterwards. Hidden folders (.git) and tools' folders (venv,
node_modules, __pycache__) are left out. A file left out by a limit is
named in the panel ("Not loaded: ... - each file can be at most 50 MB."),
so a program that cannot open or import it is not left failing for no
reason you can see.
Friendlier errors
If you use a name that is not defined, PLL rewrites Python's NameError
into a short explanation of what went wrong and how to fix it. At every
level but raw, most of these are found before the file runs. The
message appears in the interactions panel and as a mark in the editor.
Click the location in the message to jump to that line. The marks go as
soon as you edit the file, since its lines may have moved; the panel keeps
the message, and the next run marks whatever is still wrong.
Commands
All of these are available from the Command Palette. PLL: Run Python File
also appears in the editor title bar when a .py file is open, and
Ctrl+Enter (Cmd+Enter on a Mac) in the editor runs it; in a Python file,
that takes the place of VS Code's Insert Line Below.
| Command |
What it does |
| PLL: Run Python File |
Run the file, then its tests (if any). |
| PLL: Show Interactions |
Open the interactions panel. |
| PLL: Start REPL |
Show the session with no file, at #level beginner, whatever file is open. |
| PLL: Stop Program |
Stop the program that is running. |
| PLL: Clear Interactions |
Clear the panel. |
Copy and paste
Ctrl/Cmd+C, X, and V work as usual, both in the editor and in the
interactions panel, in the browser and on the desktop. Right-click also
works.
If the shortcuts do nothing in the browser and you use a layout other
than QWERTY (Dvorak, Colemak, …), add this to your user settings
(Command Palette → Preferences: Open User Settings (JSON)) — a
.vscode/settings.json in the folder will not work:
{
"keyboard.dispatch": "keyCode"
}
Otherwise, check whether something in your own Keyboard Shortcuts
has taken over Ctrl/Cmd+C or V. PLL: Editor Copy/Cut/Paste in the
Command Palette also work as a fallback.
A quieter editor
PLL turns off many extra Python tools (autocomplete popups, extra
linters, and similar) so the editor stays simple while you are learning.
Settings you choose yourself still win over PLL's defaults.
PLL also turns off VS Code's pop-ups recommending extensions, so opening a
.py file does not ask you to install Microsoft's Python extension. That
holds for every kind of file while PLL is installed; unticking
Extensions: Ignore Recommendations in Settings brings them back.
PLL also turns off the AI features built into VS Code, GitHub Copilot's
chat and suggestions, for every kind of file while PLL is installed.
Unticking Chat: Disable AI Features in Settings brings them back;
suggestions still stay out of Python files.
If another Python extension is installed and might add confusing
messages, PLL may ask whether to disable it for this workspace. That
does not uninstall the extension.
Running programs without the editor
The same language levels are available as a command-line tool, so a program
behaves the same on a terminal as it does in the panel:
npx pll-python hw.py
The level still comes from the file's own #level line, an #examplar line
still checks your tests, a #bundle line still gives the file its bundle,
tests still run after the program, and errors are worded the same way. Pictures cannot be drawn in a
terminal (each prints a note, or use --save-images) and reactors do not
animate, but tables print as text and everything else is the same code.
Exit codes make it usable for marking: 0 ran and tests passed, 1 the
program raised or was stopped, 2 level checks blocked it, 3 a test
failed. A program that ends itself with sys.exit(n) exits with n, as
under python.
Course staff can also build Examplar bundles and bundles with it. See
pll-python on npm for that and
the full list of options.
For course staff and contributors
How PLL is built, how to run it from source, how to author Examplar
bundles, and how the editor defaults work are documented in the
repository.