Hands-on lab — Day 76: Linting and Formatting with Ruff

# Reference Ruff configuration for this lab.
#
# `pyproject.toml` is the standard place a Python project keeps its
# settings. Ruff looks for the closest one above the file it is checking,
# which is why running `ruff check .` from THIS directory picks these rules
# up automatically and running it from `examples/messy/` does not.
#
# Read this file top to bottom. Every line is a decision, and the comment
# next to it is the reason for the decision — which is the part a config
# file usually forgets to record.

[tool.ruff]
# 88 columns is Black's default and therefore Ruff's. The number matters
# far less than everyone using the same one.
line-length = 88

# The oldest Python this code must run on. `UP` rules use this: they will
# not rewrite something into syntax your target cannot parse.
target-version = "py39"

# Directories the tools should never look at. A virtual environment is full
# of other people's code and none of its style is your business.
extend-exclude = [".venv", "build", "dist"]

[tool.ruff.lint]
# The rule families this project has decided to enforce, smallest useful
# set first. Adding a family is a deliberate act with a reason:
#   E, W  pycodestyle  — PEP 8 layout and whitespace complaints
#   F     pyflakes     — real errors: unused imports, undefined names
#   I     isort        — import order
#   B     bugbear      — suspicious patterns that are usually bugs
#   SIM   simplify     — code that says something the long way round
#   UP    pyupgrade    — syntax made obsolete by the target version
#   N     pep8-naming  — snake_case, CapWords, UPPER_CASE
#   S     bandit       — common security mistakes
select = ["E", "W", "F", "I", "B", "SIM", "UP", "N", "S"]

ignore = [
  # The formatter owns line length. Once `ruff format` has run, E501 can
  # only fire on something the formatter is not allowed to split — a long
  # URL in a comment, a long string literal — and breaking those by hand
  # makes them worse, not better. Ruff's own documentation recommends
  # disabling E501 when the formatter is in use.
  "E501",
]

[tool.ruff.lint.per-file-ignores]
# `assert` is the entire point of a test, so the security rule that
# distrusts it (S101, "assert can be stripped by python -O") is noise
# here and only here. This is the classic per-file ignore: relax a rule
# in the one place where it is wrong, rather than switching it off
# everywhere.
"test_*.py" = ["S101"]

[tool.ruff.format]
# The formatter has almost nothing to configure, on purpose. These two
# lines are the defaults, written out so nobody has to go and look them up.
quote-style = "double"
indent-style = "space"

"""Price a small shop receipt.

This is the same module as `examples/messy/receipts.py`, after the tools
and one human decision have been through it. Compare the two files side by
side with `diff -u ../messy/receipts.py receipts.py`.

Almost every difference was made mechanically: `ruff check --fix` removed
the two unused imports and the unread local, `ruff check --fix
--unsafe-fixes` rewrote the two `== None` comparisons, collapsed the
if/else into a ternary and replaced the mutable default, and `ruff format`
re-quoted, re-spaced and re-wrapped everything. Only the percent-format
strings at the end were rewritten by hand, because the nested formatting
was beyond what the fix could see.

The behaviour is byte-for-byte identical to the messy version, with one
deliberate exception: `add_item` no longer shares a default basket between
calls. That was a real bug, `B006` found it, and fixing it is a decision a
person has to make and a test has to record.
"""

import re
from decimal import Decimal

TAX_RATE = Decimal("0.20")
LINE_PATTERN = re.compile(r"^(.+?)\s+([0-9]+)$")


def add_item(name, price_cents, basket=None):
    if basket is None:
        basket = []
    basket.append({"name": name, "price_cents": price_cents})
    return basket


def parse_line(line):
    match = LINE_PATTERN.match(line.strip())
    if match is None:
        return None
    return {"name": match.group(1), "price_cents": int(match.group(2))}


def load_basket(lines):
    basket = []
    for line in lines:
        item = parse_line(line)
        if item is None:
            continue
        add_item(item["name"], item["price_cents"], basket)
    return basket


def subtotal_cents(basket):
    total = 0
    for item in basket:
        total += item["price_cents"]
    return total


def tax_cents(basket):
    return int(Decimal(subtotal_cents(basket)) * TAX_RATE)


def total_cents(basket):
    return subtotal_cents(basket) + tax_cents(basket)


def describe(basket, name):
    hits = 0
    for item in basket:
        if item["name"] == name:
            hits += 1
    label = "found" if hits else "missing"
    return f"{name}: {label} x{hits}"


def format_receipt(basket, shop="Corner Shop"):
    rows = [shop]
    for item in basket:
        rows.append(f"{item['name']:<20}{item['price_cents'] / 100:>8.2f}")
    rows.append(f"{'TOTAL':<20}{total_cents(basket) / 100:>8.2f}")
    return "\n".join(rows)

"""Behaviour tests for the cleaned receipts module.

Every test below is character-for-character the same as the one in
`examples/messy/test_receipts.py`, except the last one. That is the whole
argument of this lab: the formatter and the linter rewrote the module
substantially and not one assertion about its behaviour had to change.

The last test changed because a person changed the behaviour on purpose,
after `B006` pointed at the bug.
"""

import receipts


def test_parse_line_reads_a_name_and_a_price():
    assert receipts.parse_line("apple 120") == {"name": "apple", "price_cents": 120}


def test_parse_line_keeps_multi_word_names():
    assert receipts.parse_line("brown bread 240") == {
        "name": "brown bread",
        "price_cents": 240,
    }


def test_parse_line_returns_none_for_junk():
    assert receipts.parse_line("nonsense") is None
    assert receipts.parse_line("") is None


def test_load_basket_skips_unparseable_lines():
    basket = receipts.load_basket(["apple 120", "nonsense", "pear 95"])
    assert [item["name"] for item in basket] == ["apple", "pear"]


def test_subtotal_adds_every_price():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    assert receipts.subtotal_cents(basket) == 215


def test_tax_is_twenty_percent_of_the_subtotal():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    assert receipts.tax_cents(basket) == 43


def test_total_is_subtotal_plus_tax():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    assert receipts.total_cents(basket) == 258


def test_describe_counts_matching_items():
    basket = receipts.load_basket(["apple 120", "apple 130", "pear 95"])
    assert receipts.describe(basket, "apple") == "apple: found x2"
    assert receipts.describe(basket, "plum") == "plum: missing x0"


def test_format_receipt_has_a_header_and_a_total_row():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    rows = receipts.format_receipt(basket).splitlines()
    assert rows[0] == "Corner Shop"
    assert rows[-1] == "TOTAL                   2.58"
    assert len(rows) == 4


def test_default_basket_is_fresh_on_every_call():
    """The fixed version of the B006 test.

    Two calls that omit `basket` must get two independent baskets. In the
    messy version they got the same one, and `first is second` was true.
    """
    first = receipts.add_item("apple", 120)
    second = receipts.add_item("pear", 95)
    assert first is not second
    assert first == [{"name": "apple", "price_cents": 120}]
    assert second == [{"name": "pear", "price_cents": 95}]

"""Price a small shop receipt.

This module WORKS. Every function does what its name says, and the test
suite next door passes. It is also written badly on purpose: unsorted
imports, an import nobody uses, a local variable nobody reads, a line far
too long, two comparisons to None written the wrong way, string formatting
from an older era of Python, and one mutable default argument that is a
genuine bug rather than a cosmetic complaint.

Nothing here is exaggerated. Every one of these appears in real code
written by people in a hurry.
"""
import json
from collections import Counter
import re
from decimal import Decimal

TAX_RATE = Decimal('0.20')
LINE_PATTERN = re.compile(r'^(.+?)\s+([0-9]+)$')


def add_item(name, price_cents, basket = []):
    basket.append({'name': name, 'price_cents': price_cents})
    return basket


def parse_line(line):
    match = LINE_PATTERN.match(line.strip())
    if match == None:
        return None
    return {'name': match.group(1), 'price_cents': int(match.group(2))}


def load_basket(lines):
    basket = []
    skipped = 0
    for line in lines:
        item = parse_line(line)
        if item == None:
            continue
        add_item(item['name'], item['price_cents'], basket)
    return basket


def subtotal_cents(basket):
    total = 0
    for item in basket:
        total += item['price_cents']
    return total


def tax_cents(basket):
    return int(Decimal(subtotal_cents(basket)) * TAX_RATE)


def total_cents(basket):
    return subtotal_cents(basket) + tax_cents(basket)


def describe(basket, name):
    hits = 0
    for item in basket:
        if item['name'] == name:
            hits += 1
    if hits:
        label = 'found'
    else:
        label = 'missing'
    return '%s: %s x%d' % (name, label, hits)


def format_receipt(basket, shop = 'Corner Shop'):
    rows = [shop]
    for item in basket:
        rows.append('{:<20}{:>8}'.format(item['name'], '%.2f' % (item['price_cents'] / 100)))
    rows.append('{:<20}{:>8}'.format('TOTAL', '%.2f' % (total_cents(basket) / 100)))
    return '\n'.join(rows)

"""Behaviour tests for the messy receipts module.

These tests exist to PIN CURRENT BEHAVIOUR. Their whole job is to be green
before you touch the file and green after the formatter and the linter have
rewritten it, so that you can see with your own eyes that neither tool
changed what the code does.

One test below deliberately asserts a bug. It is labelled.
"""

import receipts


def test_parse_line_reads_a_name_and_a_price():
    assert receipts.parse_line("apple 120") == {"name": "apple", "price_cents": 120}


def test_parse_line_keeps_multi_word_names():
    assert receipts.parse_line("brown bread 240") == {
        "name": "brown bread",
        "price_cents": 240,
    }


def test_parse_line_returns_none_for_junk():
    assert receipts.parse_line("nonsense") is None
    assert receipts.parse_line("") is None


def test_load_basket_skips_unparseable_lines():
    basket = receipts.load_basket(["apple 120", "nonsense", "pear 95"])
    assert [item["name"] for item in basket] == ["apple", "pear"]


def test_subtotal_adds_every_price():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    assert receipts.subtotal_cents(basket) == 215


def test_tax_is_twenty_percent_of_the_subtotal():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    assert receipts.tax_cents(basket) == 43


def test_total_is_subtotal_plus_tax():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    assert receipts.total_cents(basket) == 258


def test_describe_counts_matching_items():
    basket = receipts.load_basket(["apple 120", "apple 130", "pear 95"])
    assert receipts.describe(basket, "apple") == "apple: found x2"
    assert receipts.describe(basket, "plum") == "plum: missing x0"


def test_format_receipt_has_a_header_and_a_total_row():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    rows = receipts.format_receipt(basket).splitlines()
    assert rows[0] == "Corner Shop"
    assert rows[-1] == "TOTAL                   2.58"
    assert len(rows) == 4


def test_default_basket_is_shared_between_calls():
    """THIS TEST DOCUMENTS A BUG, NOT A FEATURE.

    `add_item`'s default `basket = []` is one list, created once when the
    `def` line ran. Every call that omits `basket` appends to that same
    list, so two unrelated shoppers end up sharing a trolley. The linter
    rule B006 flags exactly this. Exercise 6 fixes it, and this test is
    then rewritten to assert the correct behaviour instead.
    """
    first = receipts.add_item("apple", 120)
    second = receipts.add_item("pear", 95)
    assert first is second
    assert [item["name"] for item in second][-2:] == ["apple", "pear"]

lesson_id: D076
day: 76
kind: python-program
languages: [python]
setup_commands:
  - cd labs/sections/programming-with-python/day-076-linting-and-formatting-with-ruff
  - python3 -m venv .venv
  - .venv/bin/pip install -r requirements/requirements.txt
  - .venv/bin/ruff --version
  - .venv/bin/pytest --version
run_commands:
  - cat starter/EXERCISES.md
  - cd starter && pytest -q
  - ruff check --isolated receipts.py
  - ruff check --isolated --select E,F,I,B,SIM,UP receipts.py
  - ruff rule B006
  - ruff format --isolated --diff receipts.py
  - ruff format --isolated receipts.py
  - ruff check --isolated --select E,F,I,B,SIM,UP --fix receipts.py
  - ruff check --isolated --select E,F,I,B,SIM,UP --diff --unsafe-fixes receipts.py
  - ruff check --isolated --select E,F,I,B,SIM,UP --fix --unsafe-fixes receipts.py
  - ruff check .
  - ruff format --check .
test_commands:
  - bash tests/run_tests.sh
cleanup_commands:
  - 'find . -type d -name ".ruff_cache" -prune -exec rm -rf -- {} +'
  - 'find . -type d -name ".pytest_cache" -prune -exec rm -rf -- {} +'
  - 'find . -type d -name "__pycache__" -prune -exec rm -rf -- {} +'
  - 'git checkout -- starter/  # optional: reset your work'
  - 'rm -rf .venv  # optional: remove the lab virtual environment'
requires_network: true
requires_api_key: false
estimated_minutes: 30
last_executed: '2026-07-19'
executed_on: 'macOS 26.5.1 (Apple Silicon), Python 3.14.0, Ruff 0.15.22, pytest 9.1.1, bash 3.2.57 — bash tests/run_tests.sh -> 37 checks, 0 failure(s), exit 0'

# Requirements for the Day 076 lab

Two dependencies, both free and open source, both pinned to an exact
version so that your output matches the captures in `expected-output/`.

| Package | Pinned version | Why this lab needs it |
| --- | --- | --- |
| `ruff` | `0.15.22` | The subject of the lesson: a linter and a formatter in one binary. Provides `ruff check`, `ruff format` and `ruff rule`. |
| `pytest` | `9.1.1` | The evidence. The whole argument of this lab is that the tools change how code reads without changing what it does, and a green test suite before and after is how you prove that. Introduced on Day 71. |

Both projects are distributed under the MIT licence. Ruff is developed by
Astral; its documentation is at `https://docs.astral.sh/ruff/`. pytest is
developed by the pytest project; its documentation is at
`https://docs.pytest.org/en/stable/`. Neither asks for an account, a
licence key, or a paid tier to do anything in this lab.

## One-time install

From the lab directory:

```bash
cd labs/sections/programming-with-python/day-076-linting-and-formatting-with-ruff
python3 -m venv .venv
.venv/bin/pip install -r requirements/requirements.txt
.venv/bin/ruff --version
.venv/bin/pytest --version
```

You should see `ruff 0.15.22` and `pytest 9.1.1`.

`python3 -m venv` is the tool from Day 43. `.venv/` is ignored by this
repository's `.gitignore` and must never be committed.

## Network

Installing needs the network, once. After that the lab runs entirely
offline: neither Ruff nor pytest contacts anything, and `ruff rule <code>`
prints rule documentation that is compiled into the binary rather than
fetched.

## If you would rather not create a virtual environment

The test suite resolves its tools in this order: an explicit environment
variable, then `.venv/bin/` inside this lab, then whatever is on your
`PATH`. So if you already have Ruff and pytest installed somewhere, either
of these works:

```bash
bash tests/run_tests.sh                                   # uses PATH
RUFF=/path/to/ruff PYTEST=/path/to/pytest bash tests/run_tests.sh
```

If neither is found the suite stops with an install message rather than
quietly reporting success on checks it never ran.

## Caches

Ruff writes a `.ruff_cache/` directory next to the files it checks, and
pytest can write `__pycache__/` and `.pytest_cache/`. All three are ignored
by this repository. The `## Cleanup` section of the lab README removes
them.

ruff==0.15.22
pytest==9.1.1

# Exercises — from messy to clean, mechanically

Work through these in order, **from inside this `starter/` directory**:

```bash
cd labs/sections/programming-with-python/day-076-linting-and-formatting-with-ruff/starter
```

Everywhere below, `ruff` and `pytest` mean the ones you installed for this
lab. If you made a lab-local virtual environment, write `../.venv/bin/ruff`
and `../.venv/bin/pytest` instead, or activate the environment first.

The rule this whole exercise is built to prove: **the tools change how the
code reads, not what it does.** The test suite is your evidence. Run it
before, run it after, and watch it stay green.

---

## Exercise 1 — Establish the ground truth

Before changing anything, prove the module works.

```bash
pytest -q
```

You should see `10 passed`. Those ten tests pin every behaviour that
matters: parsing, skipping junk lines, the subtotal, the 20% tax, the
total, the description string, the receipt layout, and — the interesting
one — the fact that `add_item` currently shares a basket between calls.

Read `test_receipts.py`. The last test is labelled as documenting a bug
rather than a feature. Keep that in mind; you will come back to it.

**Write down the exact output line.** It is the number you are protecting.

## Exercise 2 — Look at what the default rule set finds

```bash
ruff check --isolated receipts.py
```

`--isolated` means "ignore any configuration file you might find" — use it
until Exercise 7, so that you are always seeing the rules you asked for and
not rules you inherited from somewhere up the directory tree.

Ruff's default selection is deliberately small: `E4`, `E7`, `E9` and `F`.
Count the findings. Note which of the problems you can see in the file it
did **not** mention.

## Exercise 3 — Ask for more rules

```bash
ruff check --isolated --select E,F,I,B,SIM,UP receipts.py
```

Now you should see **ten** findings across **eight** distinct rule codes.
Write each code down with one sentence in your own words about what it
means. If a code is unfamiliar, ask the tool:

```bash
ruff rule B006
ruff rule F841
```

`ruff rule <code>` prints the rule's full documentation, including why it
exists and what the fix does. It is the fastest way to learn the rule set,
and it needs no network.

Then look at the last line of the output. It tells you how many findings
are fixable safely, and how many more become fixable if you opt in to
unsafe fixes. Those two numbers are the subject of Exercise 5.

## Exercise 4 — Preview the formatter without running it

```bash
ruff format --isolated --diff receipts.py
```

`--diff` prints what the formatter *would* do and changes nothing. Read the
diff carefully. Every single line of it is about appearance: quotes,
spacing around `=` in a default argument, where a long call gets wrapped.
Not one line changes a value, a condition, or a name.

Now run it for real, and then run it again:

```bash
ruff format --isolated receipts.py
ruff format --isolated receipts.py
```

The second run must report `1 file left unchanged`. That property is called
**idempotence**: formatting formatted code is a no-op. It is what makes a
formatter safe to put in a commit hook.

**Re-run the tests: `pytest -q`. Still `10 passed`.** The file looks
different and behaves identically.

## Exercise 5 — Apply the fixes the linter is confident about

```bash
ruff check --isolated --select E,F,I,B,SIM,UP --fix receipts.py
```

Ruff applies only its **safe** fixes: ones it can prove do not change what
the program does and do not throw away a comment. Watch which findings
disappear and which survive.

`pytest -q` — still `10 passed`.

Now look at what is left and read the summary line. The remaining fixes are
marked **unsafe**, which does not mean "wrong" — it means "this fix may
change behaviour, so a human has to say yes." Preview them before applying:

```bash
ruff check --isolated --select E,F,I,B,SIM,UP --diff --unsafe-fixes receipts.py
```

Read that diff and decide, one hunk at a time, whether you agree. Then
apply it:

```bash
ruff check --isolated --select E,F,I,B,SIM,UP --fix --unsafe-fixes receipts.py
ruff format --isolated receipts.py
```

## Exercise 6 — The one the tools could not decide for you

Run the tests again.

```bash
pytest -q
```

This time one test **fails**, and it is the test labelled as documenting a
bug. Read the failure carefully before you do anything else.

What happened: `B006` found a real defect — `basket = []` in the signature
of `add_item` creates one list when the `def` line runs, and every call
that omits `basket` shares it. Two shoppers, one trolley. The unsafe fix
rewrote it to `basket=None` plus an `if basket is None:` guard, which is
the correct shape. Correct code, failing test — because the test was
written to record the broken behaviour.

Your job now is a judgement no tool can make for you:

1. Confirm the new behaviour is the behaviour you want. (It is. Read
   `add_item` and convince yourself.)
2. Rewrite the last test so it asserts the **correct** behaviour: two calls
   that omit `basket` return two independent lists. `assert first is not
   second`, and each list holds exactly one item.
3. Update the test's docstring so it no longer claims to document a bug.
4. `pytest -q` → `10 passed`.

If the unsafe fix did not run for you, make the same change by hand:

```python
def add_item(name, price_cents, basket=None):
    if basket is None:
        basket = []
    ...
```

This is the moment the lab is built around. Nine of the ten findings were
about how the code reads. One was a bug that would have shipped, and the
linter is the only thing in the room that noticed.

## Exercise 7 — Write the configuration

Nobody wants to type `--select E,F,I,B,SIM,UP` forever. Create a file
called `pyproject.toml` **in this `starter/` directory** with at least:

- a `[tool.ruff]` table setting `line-length` and `target-version`;
- a `[tool.ruff.lint]` table with a `select` list naming the rule families
  your project enforces, and an `ignore` list with a **comment explaining
  why** for each entry;
- a `[tool.ruff.lint.per-file-ignores]` table relaxing at least one rule
  for `test_*.py`.

Then check that it works with no flags at all:

```bash
ruff check .
ruff format --check .
pytest -q
```

All three must succeed. `ruff check .` printing `All checks passed!` with
no `--select` in sight means the configuration, not your memory, is now
carrying the rules.

Compare yours with `../examples/clean/pyproject.toml`. It does not have to
match — it has to be *defensible*. Every `ignore` entry you cannot justify
in one sentence is a rule you should either obey or remove from `select`.

## Exercise 8 — Confirm you arrived

```bash
diff -u ../examples/clean/receipts.py receipts.py
```

Differences in the module docstring are expected and fine — the reference
file explains itself. Differences in the *code* are worth reading: either
you found a better answer than the reference, or you missed a step.

Finally, from the lab directory:

```bash
cd .. && bash tests/run_tests.sh
```

## Exercise 9 (optional) — Measure the speed claim yourself

Do not take anybody's benchmark on trust, including this course's. Measure:

```bash
time ruff check --isolated --select E,F,I,B,SIM,UP ../examples/messy/receipts.py
```

Record the `real` figure. It is one small file, so most of what you are
measuring is process start-up — which is exactly the number that decides
whether a tool is tolerable in an editor on every keystroke. Try it again
against a large directory of Python you have lying around and watch how
little the number moves.

## Reset

To start over:

```bash
git checkout -- starter/
```

"""Price a small shop receipt.

This module WORKS. Every function does what its name says, and the test
suite next door passes. It is also written badly on purpose: unsorted
imports, an import nobody uses, a local variable nobody reads, a line far
too long, two comparisons to None written the wrong way, string formatting
from an older era of Python, and one mutable default argument that is a
genuine bug rather than a cosmetic complaint.

Nothing here is exaggerated. Every one of these appears in real code
written by people in a hurry.
"""
import json
from collections import Counter
import re
from decimal import Decimal

TAX_RATE = Decimal('0.20')
LINE_PATTERN = re.compile(r'^(.+?)\s+([0-9]+)$')


def add_item(name, price_cents, basket = []):
    basket.append({'name': name, 'price_cents': price_cents})
    return basket


def parse_line(line):
    match = LINE_PATTERN.match(line.strip())
    if match == None:
        return None
    return {'name': match.group(1), 'price_cents': int(match.group(2))}


def load_basket(lines):
    basket = []
    skipped = 0
    for line in lines:
        item = parse_line(line)
        if item == None:
            continue
        add_item(item['name'], item['price_cents'], basket)
    return basket


def subtotal_cents(basket):
    total = 0
    for item in basket:
        total += item['price_cents']
    return total


def tax_cents(basket):
    return int(Decimal(subtotal_cents(basket)) * TAX_RATE)


def total_cents(basket):
    return subtotal_cents(basket) + tax_cents(basket)


def describe(basket, name):
    hits = 0
    for item in basket:
        if item['name'] == name:
            hits += 1
    if hits:
        label = 'found'
    else:
        label = 'missing'
    return '%s: %s x%d' % (name, label, hits)


def format_receipt(basket, shop = 'Corner Shop'):
    rows = [shop]
    for item in basket:
        rows.append('{:<20}{:>8}'.format(item['name'], '%.2f' % (item['price_cents'] / 100)))
    rows.append('{:<20}{:>8}'.format('TOTAL', '%.2f' % (total_cents(basket) / 100)))
    return '\n'.join(rows)

"""Behaviour tests for the messy receipts module.

These tests exist to PIN CURRENT BEHAVIOUR. Their whole job is to be green
before you touch the file and green after the formatter and the linter have
rewritten it, so that you can see with your own eyes that neither tool
changed what the code does.

One test below deliberately asserts a bug. It is labelled.
"""

import receipts


def test_parse_line_reads_a_name_and_a_price():
    assert receipts.parse_line("apple 120") == {"name": "apple", "price_cents": 120}


def test_parse_line_keeps_multi_word_names():
    assert receipts.parse_line("brown bread 240") == {
        "name": "brown bread",
        "price_cents": 240,
    }


def test_parse_line_returns_none_for_junk():
    assert receipts.parse_line("nonsense") is None
    assert receipts.parse_line("") is None


def test_load_basket_skips_unparseable_lines():
    basket = receipts.load_basket(["apple 120", "nonsense", "pear 95"])
    assert [item["name"] for item in basket] == ["apple", "pear"]


def test_subtotal_adds_every_price():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    assert receipts.subtotal_cents(basket) == 215


def test_tax_is_twenty_percent_of_the_subtotal():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    assert receipts.tax_cents(basket) == 43


def test_total_is_subtotal_plus_tax():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    assert receipts.total_cents(basket) == 258


def test_describe_counts_matching_items():
    basket = receipts.load_basket(["apple 120", "apple 130", "pear 95"])
    assert receipts.describe(basket, "apple") == "apple: found x2"
    assert receipts.describe(basket, "plum") == "plum: missing x0"


def test_format_receipt_has_a_header_and_a_total_row():
    basket = receipts.load_basket(["apple 120", "pear 95"])
    rows = receipts.format_receipt(basket).splitlines()
    assert rows[0] == "Corner Shop"
    assert rows[-1] == "TOTAL                   2.58"
    assert len(rows) == 4


def test_default_basket_is_shared_between_calls():
    """THIS TEST DOCUMENTS A BUG, NOT A FEATURE.

    `add_item`'s default `basket = []` is one list, created once when the
    `def` line ran. Every call that omits `basket` appends to that same
    list, so two unrelated shoppers end up sharing a trolley. The linter
    rule B006 flags exactly this. Exercise 6 fixes it, and this test is
    then rewritten to assert the correct behaviour instead.
    """
    first = receipts.add_item("apple", 120)
    second = receipts.add_item("pear", 95)
    assert first is second
    assert [item["name"] for item in second][-2:] == ["apple", "pear"]

#!/usr/bin/env bash
# Tests for the Day 076 lab. Run from the lab directory:
#   bash tests/run_tests.sh
#
# What this suite proves, in order:
#
#   * the messy module WORKS — its pytest suite is green before anything
#     touches it, so we have a ground truth to protect;
#   * `ruff format` changes how it reads and NOT what it does — the same
#     suite is still green on a formatted copy, and formatting a second
#     time changes nothing (idempotence);
#   * `ruff check` finds the eight rule codes this lab is built around,
#     asserted by CODE rather than by the wording of the message;
#   * the safe autofix refuses to touch the real bug (B006) and the unsafe
#     autofix does fix it — the distinction the lesson turns on;
#   * the cleaned module is clean under the project's own configuration,
#     passes the same behaviour tests, and no longer shares a basket;
#   * `--check` mode fails on the messy file and passes on the clean one,
#     which is the shape both tools take in continuous integration;
#   * a `# noqa` comment with a specific code suppresses exactly that code.
#
# No network at test time, non-interactive, deterministic. Exits 0 only if
# every check passes.
set -u

export PYTHONDONTWRITEBYTECODE=1

lab_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
failures=0
checks=0

# The rule families this lab teaches. Kept in one variable so the harness
# and the exercises can never drift apart.
SELECT="E,F,I,B,SIM,UP"

check() {
  local label="$1" ok="$2"
  checks=$((checks + 1))
  if [ "${ok}" = "yes" ]; then
    echo "  ok: ${label}"
  else
    echo "  FAIL: ${label}"
    failures=$((failures + 1))
  fi
}

# Resolve a tool: an explicit override, then this lab's .venv, then whatever
# is on PATH. Fails loudly with instructions rather than silently skipping.
resolve_tool() {
  local tool="$1" override="$2"
  if [ -n "${override}" ] && [ -x "${override}" ]; then echo "${override}"; return 0; fi
  if [ -x "${lab_dir}/.venv/bin/${tool}" ]; then echo "${lab_dir}/.venv/bin/${tool}"; return 0; fi
  if command -v "${tool}" >/dev/null 2>&1; then command -v "${tool}"; return 0; fi
  return 1
}

install_hint() {
  echo "  Install it with:" >&2
  echo "    python3 -m venv .venv" >&2
  echo "    .venv/bin/pip install -r requirements/requirements.txt" >&2
}

pytest_bin="$(resolve_tool pytest "${PYTEST:-}")" || {
  echo "FAIL: pytest not found." >&2
  install_hint
  echo "  Or point this suite at an existing pytest: PYTEST=/path/to/pytest bash tests/run_tests.sh" >&2
  exit 1
}

ruff_bin="$(resolve_tool ruff "${RUFF:-}")" || {
  echo "FAIL: ruff not found." >&2
  install_hint
  echo "  Or point this suite at an existing ruff: RUFF=/path/to/ruff bash tests/run_tests.sh" >&2
  exit 1
}

# run_pytest <dir> — runs the suite in <dir>, quiet, leaving no cache behind.
run_pytest() {
  (cd "$1" && "${pytest_bin}" -q -p no:cacheprovider >/dev/null 2>&1)
}

# scratch_copy <src_dir> — copies a directory's .py files to a fresh temp
# directory and echoes its path. The caller removes it.
scratch_copy() {
  local src="$1" dest
  dest="$(mktemp -d "${TMPDIR:-/tmp}/ruff-lab.XXXXXX")"
  cp "${src}"/*.py "${dest}/"
  echo "${dest}"
}

echo "Day 076 — Linting and Formatting with Ruff"
echo "  ruff:   $("${ruff_bin}" --version)"
echo "  pytest: $("${pytest_bin}" --version 2>&1 | head -1)"
echo

# --------------------------------------------------------------------------
echo "Ground truth: the messy module works"
# --------------------------------------------------------------------------

if run_pytest "${lab_dir}/examples/messy"; then
  check "the messy module's pytest suite passes before any tool touches it" "yes"
else
  check "the messy module's pytest suite passes before any tool touches it" "no"
fi

messy_count="$(cd "${lab_dir}/examples/messy" && "${pytest_bin}" -q -p no:cacheprovider 2>/dev/null | grep -cE '^[.]+ +\[100%\]$')"
if [ "${messy_count}" = "1" ]; then
  check "the messy suite reports a single all-passing line" "yes"
else
  check "the messy suite reports a single all-passing line" "no"
fi

# The bug the linter is going to find, demonstrated at runtime.
if (cd "${lab_dir}/examples/messy" && python3 -c "
import receipts
first = receipts.add_item('apple', 120)
second = receipts.add_item('pear', 95)
raise SystemExit(0 if first is second else 1)
" >/dev/null 2>&1); then
  check "the messy add_item really does share one basket between calls (the B006 bug)" "yes"
else
  check "the messy add_item really does share one basket between calls (the B006 bug)" "no"
fi

# --------------------------------------------------------------------------
echo
echo "The linter: what it finds, by rule code"
# --------------------------------------------------------------------------

lint_report="$(cd "${lab_dir}/examples/messy" && "${ruff_bin}" check --isolated --select "${SELECT}" --output-format concise receipts.py 2>&1)"
lint_status=$?

if [ "${lint_status}" -ne 0 ]; then
  check "ruff check exits non-zero on the messy module" "yes"
else
  check "ruff check exits non-zero on the messy module" "no"
fi

for code in I001 F401 B006 E711 F841 SIM108 UP031 E501; do
  if printf '%s\n' "${lint_report}" | grep -q " ${code} "; then
    check "ruff check reports ${code} on the messy module" "yes"
  else
    check "ruff check reports ${code} on the messy module" "no"
  fi
done

if printf '%s\n' "${lint_report}" | grep -q "^Found 10 errors\.$"; then
  check "ruff check reports exactly 10 findings under --select ${SELECT}" "yes"
else
  check "ruff check reports exactly 10 findings under --select ${SELECT}" "no"
fi

# The default selection is deliberately smaller than the one above.
default_report="$(cd "${lab_dir}/examples/messy" && "${ruff_bin}" check --isolated --output-format concise receipts.py 2>&1)"
if printf '%s\n' "${default_report}" | grep -q "^Found 5 errors\.$" \
  && ! printf '%s\n' "${default_report}" | grep -q " B006 "; then
  check "ruff's default rule set is smaller and misses B006 until you select it" "yes"
else
  check "ruff's default rule set is smaller and misses B006 until you select it" "no"
fi

# --------------------------------------------------------------------------
echo
echo "The formatter: appearance only, and idempotent"
# --------------------------------------------------------------------------

if (cd "${lab_dir}/examples/messy" && "${ruff_bin}" format --isolated --check receipts.py >/dev/null 2>&1); then
  check "ruff format --check FAILS on the messy module (the CI form)" "no"
else
  check "ruff format --check FAILS on the messy module (the CI form)" "yes"
fi

scratch="$(scratch_copy "${lab_dir}/examples/messy")"
"${ruff_bin}" format --isolated "${scratch}/receipts.py" >/dev/null 2>&1
if run_pytest "${scratch}"; then
  check "the behaviour suite is STILL green after ruff format rewrote the module" "yes"
else
  check "the behaviour suite is STILL green after ruff format rewrote the module" "no"
fi

second_pass="$("${ruff_bin}" format --isolated "${scratch}/receipts.py" 2>&1)"
if printf '%s\n' "${second_pass}" | grep -q "1 file left unchanged"; then
  check "formatting is idempotent — the second run changes nothing" "yes"
else
  check "formatting is idempotent — the second run changes nothing" "no"
fi

if "${ruff_bin}" format --isolated --check "${scratch}/receipts.py" >/dev/null 2>&1; then
  check "ruff format --check now PASSES on the formatted copy" "yes"
else
  check "ruff format --check now PASSES on the formatted copy" "no"
fi
rm -rf "${scratch}"

# A formatter is not a linter: formatting alone leaves every real finding.
scratch="$(scratch_copy "${lab_dir}/examples/messy")"
"${ruff_bin}" format --isolated "${scratch}/receipts.py" >/dev/null 2>&1
after_format="$("${ruff_bin}" check --isolated --select "${SELECT}" --output-format concise "${scratch}/receipts.py" 2>&1)"
if printf '%s\n' "${after_format}" | grep -q " B006 " \
  && printf '%s\n' "${after_format}" | grep -q " F401 "; then
  check "formatting fixes no lint findings — B006 and F401 both survive it" "yes"
else
  check "formatting fixes no lint findings — B006 and F401 both survive it" "no"
fi
rm -rf "${scratch}"

# --------------------------------------------------------------------------
echo
echo "Autofix: safe, unsafe, and the line between them"
# --------------------------------------------------------------------------

scratch="$(scratch_copy "${lab_dir}/examples/messy")"
"${ruff_bin}" check --isolated --select "${SELECT}" --fix "${scratch}/receipts.py" >/dev/null 2>&1
safe_left="$("${ruff_bin}" check --isolated --select "${SELECT}" --output-format concise "${scratch}/receipts.py" 2>&1)"

if ! printf '%s\n' "${safe_left}" | grep -q " F401 "; then
  check "the SAFE autofix removes the unused imports (F401)" "yes"
else
  check "the SAFE autofix removes the unused imports (F401)" "no"
fi

if printf '%s\n' "${safe_left}" | grep -q " B006 "; then
  check "the SAFE autofix refuses to touch B006 — behaviour is a human decision" "yes"
else
  check "the SAFE autofix refuses to touch B006 — behaviour is a human decision" "no"
fi

if run_pytest "${scratch}"; then
  check "the behaviour suite is still green after the safe autofix" "yes"
else
  check "the behaviour suite is still green after the safe autofix" "no"
fi

"${ruff_bin}" check --isolated --select "${SELECT}" --fix --unsafe-fixes "${scratch}/receipts.py" >/dev/null 2>&1
unsafe_left="$("${ruff_bin}" check --isolated --select "${SELECT}" --output-format concise "${scratch}/receipts.py" 2>&1)"
if ! printf '%s\n' "${unsafe_left}" | grep -q " B006 "; then
  check "the UNSAFE autofix does rewrite the mutable default" "yes"
else
  check "the UNSAFE autofix does rewrite the mutable default" "no"
fi

# ...and that rewrite genuinely CHANGES BEHAVIOUR, which is why it is
# opt-in: the test that recorded the bug now fails.
if run_pytest "${scratch}"; then
  check "the unsafe fix changes behaviour, so the test that recorded the bug now fails" "no"
else
  check "the unsafe fix changes behaviour, so the test that recorded the bug now fails" "yes"
fi
rm -rf "${scratch}"

# --------------------------------------------------------------------------
echo
echo "Suppression: noqa with a code, not a bare noqa"
# --------------------------------------------------------------------------

scratch="$(mktemp -d "${TMPDIR:-/tmp}/ruff-lab.XXXXXX")"
{
  printf 'import json  # noqa: F401\n'
  printf 'import re\n\n\n'
  printf 'def first_digit(value):\n'
  printf '    if value == None:\n'
  printf '        return None\n'
  printf '    return re.search("[0-9]", value)\n'
} >"${scratch}/suppressed.py"
noqa_report="$("${ruff_bin}" check --isolated --select F,E --output-format concise "${scratch}/suppressed.py" 2>&1)"
if ! printf '%s\n' "${noqa_report}" | grep -q " F401 "; then
  check "# noqa: F401 suppresses exactly that rule on that line" "yes"
else
  check "# noqa: F401 suppresses exactly that rule on that line" "no"
fi
if printf '%s\n' "${noqa_report}" | grep -q " E711 "; then
  check "# noqa: F401 suppresses nothing else — E711 elsewhere still fires" "yes"
else
  check "# noqa: F401 suppresses nothing else — E711 elsewhere still fires" "no"
fi
rm -rf "${scratch}"

# --------------------------------------------------------------------------
echo
echo "The cleaned module and its configuration"
# --------------------------------------------------------------------------

if (cd "${lab_dir}/examples/clean" && "${ruff_bin}" check . >/dev/null 2>&1); then
  check "ruff check exits 0 on examples/clean using its own pyproject.toml" "yes"
else
  check "ruff check exits 0 on examples/clean using its own pyproject.toml" "no"
fi

if (cd "${lab_dir}/examples/clean" && "${ruff_bin}" format --check . >/dev/null 2>&1); then
  check "ruff format --check exits 0 on examples/clean" "yes"
else
  check "ruff format --check exits 0 on examples/clean" "no"
fi

if run_pytest "${lab_dir}/examples/clean"; then
  check "the cleaned module passes the same behaviour suite" "yes"
else
  check "the cleaned module passes the same behaviour suite" "no"
fi

if (cd "${lab_dir}/examples/clean" && python3 -c "
import receipts
first = receipts.add_item('apple', 120)
second = receipts.add_item('pear', 95)
assert first is not second
assert first == [{'name': 'apple', 'price_cents': 120}]
assert second == [{'name': 'pear', 'price_cents': 95}]
" >/dev/null 2>&1); then
  check "the cleaned add_item gives every caller a fresh basket — the bug is gone" "yes"
else
  check "the cleaned add_item gives every caller a fresh basket — the bug is gone" "no"
fi

# The two modules must still agree on everything that is not the bug.
if (cd "${lab_dir}" && python3 -c "
import importlib.util, sys

def load(name, path):
    spec = importlib.util.spec_from_file_location(name, path)
    module = importlib.util.module_from_spec(spec)
    sys.modules[name] = module
    spec.loader.exec_module(module)
    return module

messy = load('messy_receipts', 'examples/messy/receipts.py')
clean = load('clean_receipts', 'examples/clean/receipts.py')
lines = ['apple 120', 'nonsense', 'brown bread 240', 'pear 95']
for mod in (messy, clean):
    basket = mod.load_basket(lines)
    assert mod.subtotal_cents(basket) == 455, mod
    assert mod.tax_cents(basket) == 91, mod
    assert mod.total_cents(basket) == 546, mod
    assert mod.describe(basket, 'apple') == 'apple: found x1', mod
    assert mod.format_receipt(basket) == messy.format_receipt(basket), mod
" >/dev/null 2>&1); then
  check "messy and clean agree on every price, description and receipt line" "yes"
else
  check "messy and clean agree on every price, description and receipt line" "no"
fi

# The per-file ignore is doing real work: S101 fires on the tests without
# the configuration and is silent with it.
s101_isolated="$(cd "${lab_dir}/examples/clean" && "${ruff_bin}" check --isolated --select S --output-format concise test_receipts.py 2>&1)"
if printf '%s\n' "${s101_isolated}" | grep -q " S101 "; then
  check "S101 fires on the test file when the configuration is ignored" "yes"
else
  check "S101 fires on the test file when the configuration is ignored" "no"
fi

s101_configured="$(cd "${lab_dir}/examples/clean" && "${ruff_bin}" check --output-format concise test_receipts.py 2>&1)"
if ! printf '%s\n' "${s101_configured}" | grep -q " S101 "; then
  check "the per-file ignore silences S101 for test_*.py and nowhere else" "yes"
else
  check "the per-file ignore silences S101 for test_*.py and nowhere else" "no"
fi

if python3 -c "
import tomllib, pathlib
config = tomllib.loads(pathlib.Path('${lab_dir}/examples/clean/pyproject.toml').read_text())
lint = config['tool']['ruff']['lint']
assert config['tool']['ruff']['line-length'] == 88
assert {'E', 'F', 'I', 'B', 'SIM', 'UP'} <= set(lint['select'])
assert lint['ignore'] == ['E501']
assert lint['per-file-ignores']['test_*.py'] == ['S101']
" >/dev/null 2>&1; then
  check "the reference pyproject.toml parses and declares select, ignore and a per-file ignore" "yes"
else
  check "the reference pyproject.toml parses and declares select, ignore and a per-file ignore" "no"
fi

# --------------------------------------------------------------------------
echo
echo "Your starter files"
# --------------------------------------------------------------------------

if python3 -c "import ast, pathlib; ast.parse(pathlib.Path('${lab_dir}/starter/receipts.py').read_text())" >/dev/null 2>&1; then
  check "starter/receipts.py is valid Python" "yes"
else
  check "starter/receipts.py is valid Python" "no"
fi

if run_pytest "${lab_dir}/starter"; then
  check "starter/ still passes its own behaviour suite (whatever stage you are at)" "yes"
else
  check "starter/ still passes its own behaviour suite — if this fails, finish exercise 6" "no"
fi

if (cd "${lab_dir}/starter" && python3 -c "
import receipts
for name in ('add_item', 'parse_line', 'load_basket', 'subtotal_cents',
             'tax_cents', 'total_cents', 'describe', 'format_receipt'):
    assert hasattr(receipts, name), name
" >/dev/null 2>&1); then
  check "starter/receipts.py still defines all eight public functions" "yes"
else
  check "starter/receipts.py still defines all eight public functions" "no"
fi

echo
echo "${checks} checks, ${failures} failure(s)."
[ "${failures}" -eq 0 ] || exit 1
exit 0