---
title: "F01 — Python and NumPy"
sidebar:
  label: "F01 — Python & NumPy"
---

<span id="f01-python-and-numpy" />


[← Diagnostic & learning path](/diagnostic) · [F02 — Tensors & shapes →](/foundations-02-shapes) · [Glossary](/glossary)

## Learning outcome [#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 [#if-this-is-your-first-python-program]

Finish [setup](/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:

```python
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 [#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.

```python
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 item
```

Square 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 [#repeating-for-each-item]

```python
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 [#pairing-two-lists]

`zip` walks two lists side by side and hands you one item from each:

```python
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*:

```python
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

**Interactive slice visualizer.** `tokens = ["a", "b", "c", "d"]`: `tokens[1:3]` → ['b', 'c']; `tokens[:-1]` → ['a', 'b', 'c']; `tokens[1:]` → ['b', 'c', 'd']. A slice `[start:stop]` includes the start and excludes the stop; `-1` counts from the end. `zip(tokens[:-1], tokens[1:])` gives [('a', 'b'), ('b', 'c'), ('c', 'd')] — each character with the one that follows it. In the browser you type your own slice and see which positions light up.

### Naming a calculation [#naming-a-calculation]

A **function** gives a calculation a name so you can reuse it:

```python
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 `[]`?

<details>
<summary>Answer</summary>

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.


</details>

### Checking it [#checking-it]

Save the function and a test together as `artifacts/my-work/test_pairs.py`:

```python
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 [#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 [#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 [#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 [#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:

```python
token_id = -1
message = f"negative ID: {token_id}"
print(message)   # negative ID: -1
```

The `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`:

```python
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.

```python
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 [#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 [#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-work` and `python -m pytest artifacts/my-work` pass.
  Name the folder: plain `ruff check .` and `pytest` check the course's code,
  not yours.

## What's next [#whats-next]

Continue with [F02 — Tensors and shapes](/foundations-02-shapes). Re-enter F01
whenever Python control flow, tests, exceptions, or NumPy dtypes hide the
behaviour you need to inspect.

[← Diagnostic](/diagnostic) · [→ F02](/foundations-02-shapes)

<details>
<summary>Validator hint</summary>

Check `array.ndim != 2`, `np.issubdtype(array.dtype, np.integer)` and
`np.any(array < 0)`. These answer independent questions: rank, type, values.


</details>

<details>
<summary>Reference validator</summary>

```python
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()}")
```


</details>

[← Diagnostic & learning path](/diagnostic) · [F02 — Tensors & shapes →](/foundations-02-shapes) · [Glossary](/glossary)
