F01 — Python and NumPy
← Diagnostic & learning path · F02 — Tensors & shapes → · Glossary
Learning outcome
You will turn a small data transformation into a tested NumPy program and explain every value it produces. This block is required when the diagnostic marked Python and development as Required.
If you already write Python, skim the steps before the Build; the Build takes 45–60 minutes. If programming is new, plan about 60–90 minutes for everything before the Build (including the testing step) and another 60–120 minutes for the Build, spread across several sessions. These times are guides, not deadlines.
If this is your first Python program
Finish setup first. Create artifacts/my-work with your file manager,
then save a plain-text file named hello.py there (not hello.py.txt). Put this
Python code in the file:
name = "tiny model"
print("Hello", name)Run python artifacts/my-work/hello.py in the terminal from the course root.
Expected output: Hello tiny model. = assigns a value to a name, quoted text
is a string, and print(...) displays its arguments. # starts a comment.
Errors name a file and line: fix the first relevant error before continuing.
Lists, positions, and slices
One idea at a time. Each block below asks you to predict one thing before you
run it; the comment on each line is the answer, so cover it first. Collect the
blocks up to “Naming a calculation” in one file, artifacts/my-work/lists.py,
each below the previous one, and run python artifacts/my-work/lists.py after
adding each.
tokens = ["a", "b", "c", "d"]
print(tokens[0]) # a: Python positions start at zero
print(tokens[1:3]) # ['b', 'c']: start included, stop excluded
print(tokens[:-1]) # ['a', 'b', 'c']: omit the final item
print(tokens[1:]) # ['b', 'c', 'd']: omit the first itemSquare brackets construct a list or select from it. A single number selects one
position. A colon selects a slice: the start is included, the stop is
excluded, and -1 counts from the end. Leaving a side empty means “from the
beginning” or “to the end”. Predict the four printed lines, then run the file.
Repeating for each item
for token in tokens:
print(token)for repeats the indented lines once per item, with token holding the current
one. It uses tokens from the first block, so keep that block above it. Predict
how many lines print, then check.
Pairing two lists
zip walks two lists side by side and hands you one item from each:
pairs = list(zip(["a", "b", "c"], ["b", "c", "d"], strict=True))
print(pairs) # [('a', 'b'), ('b', 'c'), ('c', 'd')]list(...) collects the pairs so you can print them. Each pair sits in
parentheses: a tuple, a fixed sequence that does not change. strict=True
makes zip stop with an error if the lists differ in length, instead of quietly
dropping the leftover items. Now line up the two slices from above and zip
them:
left = tokens[:-1] # ['a', 'b', 'c']
right = tokens[1:] # ['b', 'c', 'd']
print(list(zip(left, right, strict=True)))Predict the pairs before running. Each pair is a character and the character that follows it — which is exactly what a bigram model counts. You have just written the idea behind T01 in two lines.
Interactive · Slices and pairs
tokens = ["a", "b", "c", "d"]
Which positions does a slice select?
The list from the lesson. Type a slice or pick one, then predict which boxes light up before you look.
- 'a'
- 'b'
- 'c'
- 'd'
Selected: ['b', 'c']
Naming a calculation
A function gives a calculation a name so you can reuse it:
def next_item_pairs(sequence):
if len(sequence) < 2:
return []
return list(zip(sequence[:-1], sequence[1:], strict=True))def defines the function and sequence is its input. return hands a result
back. if runs its indented branch only when the condition is true; <
compares numbers. Predict what next_item_pairs(["a"]) returns, then add the
function and print(next_item_pairs(["a"])) to lists.py and run it. Then
predict: if you removed the if line and the return [] below it, would the
function still be correct for ["a"] and []?
Answer
Yes. For ["a"] and for [], both sequence[:-1] and sequence[1:] are
empty, so zip finds no pairs and the function returns [] anyway. The if
only makes the short-input rule visible to a reader.
Checking it
Save the function and a test together as artifacts/my-work/test_pairs.py:
def next_item_pairs(sequence):
if len(sequence) < 2:
return []
return list(zip(sequence[:-1], sequence[1:], strict=True))
def test_pairs():
assert next_item_pairs(["a", "b", "c"]) == [("a", "b"), ("b", "c")]
assert next_item_pairs([]) == []
assert next_item_pairs(["a"]) == []== checks equality; it does not assign. assert stops with an
AssertionError when its condition is false, and does nothing when it is true.
pytest runs every function whose name starts with test_ in files whose names
start with test_. Run python -m pytest artifacts/my-work/test_pairs.py; the
last line shows 1 passed, framed by = signs and followed by the time taken.
A green result means the assertions passed; it does not prove untested inputs
work.
Change one expected pair to see that the assertion really catches a mistake — predict which line fails first — then change it back.
Two things you will see in course code but do not need yet: type hints such as
sequence: list[str] describe the expected type for readers and tools, and
Python does not enforce them; a docstring is a triple-quoted explanation just
inside a function.
NumPy terms before the next exercise
import numpy as np loads the numerical library with the short name np.
An array holds values with a shared numeric type (dtype): integers for
IDs, floating-point numbers for probabilities. shape counts items along each
axis. For [[1,4,2],[3,0,2]], the shape (2,3) means two rows of three numbers.
np.all(condition) checks that every element satisfies a condition. A function
can raise ValueError("reason") to explain invalid input instead of calculating
with it. Start with the concrete example below, then build the validator.
Predict → Trace → Build → Break → Measure → Explain
Start with adjacent next-item pairs:
tokens = ["a", "b", "c", "d"]
pairs = list(zip(tokens[:-1], tokens[1:], strict=True))
assert pairs == [("a", "b"), ("b", "c"), ("c", "d")]Predict the three pairs before running the code. Trace the two slices. Then wrap the transformation in a function and test empty, one-item, and normal inputs. The loop visits each item at most once, so runtime and output storage grow linearly with input length.
NumPy makes numerical contracts visible
import numpy as np
token_ids = np.array([[1, 4, 2], [3, 0, 2]], dtype=np.int64)
assert token_ids.shape == (2, 3)
assert token_ids.dtype == np.int64
assert np.all(token_ids >= 0)The shape says two examples with three positions each. Save the block as
artifacts/my-work/contract.py and run python artifacts/my-work/contract.py;
it prints nothing because every assertion holds. Break the contract by replacing
one ID with -1 (for example [[1, -1, 2], [3, 0, 2]]), predict which assertion
fails, and run it again: the np.all line raises AssertionError. Then repair
the data rather than removing the assertion.
Testing that bad input is rejected
The Build asks for error messages that name the failing value and for tests that prove bad input is rejected. Two tools do that; allow about 15 minutes.
An f-string puts values into text. Save this as artifacts/my-work/fstring.py
and run it:
token_id = -1
message = f"negative ID: {token_id}"
print(message) # negative ID: -1The f before the opening quote tells Python to replace each {...} with the
value of the name inside.
A test normally fails when an error happens. Inside with pytest.raises(ValueError):
the opposite holds: the test passes only if the indented code raises a
ValueError. Save this as artifacts/my-work/test_raises.py:
import pytest
def check_id(token_id):
if token_id < 0:
raise ValueError(f"negative ID: {token_id}")
def test_check_id_rejects_negative():
with pytest.raises(ValueError) as error:
check_id(-1)
assert "-1" in str(error.value)import pytest loads the test library. as error keeps the caught error,
str(error.value) is its message, and in checks that "-1" appears inside it.
Run python -m pytest artifacts/my-work/test_raises.py; the last line shows
1 passed. Now change check_id(-1) to check_id(1), predict what pytest
reports, then run it. Expected: Failed: DID NOT RAISE <class 'ValueError'> —
nothing was rejected, so the test fails. Change it back.
Every invalid-input test in the Build has the same four parts: bad input,
pytest.raises, the call, and the message check.
def test_rejects_negative_ids():
batch = np.array([[1, -1, 2]], dtype=np.int64)
with pytest.raises(ValueError) as error:
validate_token_batch(batch)
assert "-1" in str(error.value)It needs import numpy as np and import pytest at the top of the file. Copy it
once per invalid case, changing its name, the bad input and the text you expect
in the message. Two tests with the same name make ruff report F811, and only the
last one runs.
Build
Work in one file, artifacts/my-work/test_f01.py: imports at the top, then your
functions, then the tests, as in test_pairs.py. Implement
next_item_pairs(sequence) without importing course code. Add type hints, a
short docstring, and three tests: empty, one item, normal. Then implement
validate_token_batch(array) that raises ValueError for non-integer, negative,
or non-2D inputs. Each error message includes the failing value, and each of the
three rejections gets its own test built from the skeleton above. Stuck? Open
the Validator hint at the bottom.
Completion evidence
- tests cover empty, one-item, normal, and invalid inputs;
- output order is deterministic;
- you can explain slicing, iteration, dtype, and each assertion;
ruff check artifacts/my-workandpython -m pytest artifacts/my-workpass. Name the folder: plainruff check .andpytestcheck the course’s code, not yours.
What’s next
Continue with F02 — Tensors and shapes. Re-enter F01 whenever Python control flow, tests, exceptions, or NumPy dtypes hide the behaviour you need to inspect.
Validator hint
Check array.ndim != 2, np.issubdtype(array.dtype, np.integer) and
np.any(array < 0). These answer independent questions: rank, type, values.
Reference validator
import numpy as np
def validate_token_batch(array):
if array.ndim != 2:
raise ValueError(f"expected 2D, got shape {array.shape}")
if not np.issubdtype(array.dtype, np.integer):
raise ValueError(f"expected integer IDs, got {array.dtype}")
if np.any(array < 0):
raise ValueError(f"negative IDs: {array[array < 0].tolist()}")← Diagnostic & learning path · F02 — Tensors & shapes → · Glossary