Revising Inventory Proposals
Introduction
Welcome back to The Complete Review Cycle. We are now in lesson 3, switching back to the author’s side to resolve the review we wrote in lesson 2. We will turn each finding into a concrete change or test, keep the rules the proposal already got right, and finish with an author response that shows the reviewer exactly where each finding was addressed. Three practices follow: add the stock guard, write regression tests for it, and then cover the value cases and record the author response.
From Review Findings to a Revision Plan
In REVIEW.md, the review contains one blocking issue and three non-blocking suggestions. The blocker says stock can drop below zero and asks for a test proving that a rejected adjustment leaves the quantity unchanged. The suggestions ask for a zero-quantity value test, a fractional Decimal price test, and an inventory-specific error for stock shortages. Before writing code, we map each finding to the change and the evidence that will resolve it:
| Finding | Planned change | Evidence |
|---|---|---|
| issue (blocking): negative stock | Reject the adjustment before changing the quantity | Rejection and zero-boundary tests |
| suggestion: zero-quantity value | None; the behavior is already correct | Zero-quantity test |
| suggestion: fractional price | Keep prices as Decimal | 3 items at Decimal("0.10") test |
| suggestion: shortage error | Add InsufficientStockError; keep ValueError | Rejection test (InsufficientStockError) and fractional-adjustment test (ValueError) |
The review also told us what must not change. The proposal already rejects fractional adjustments and stores prices as exact Decimal values. A good revision fixes the findings without undoing the contract the reviewer relied on. As you may recall from earlier review work, rechecking each finding against the revision is how we confirm that the requested behavior is actually covered.
Designing InsufficientStockError
The review suggested an inventory-specific exception so callers can distinguish a stock shortage from invalid input. In app/inventory.py, the class can inherit from Python’s built-in Exception. Its docstring states exactly when the error is used, making the purpose clear to someone reading the code or catching the exception.
The new error covers only one failure: a valid whole-number adjustment that asks for more stock than the item has. Half an item is still an input error, so it keeps raising ValueError. Two different problems get two different names.
Guarding Against Negative Stock
The revised adjust_stock runs two checks before it changes anything. First, it keeps the existing whole-number check. Second, it computes the prospective quantity, the current quantity plus the requested adjustment, and raises InsufficientStockError if that result would be negative. Only when both checks pass does the method update self.quantity.
For an item with a quantity of 5, an adjustment of -6 raises the new error and the stored quantity stays 5, because the assignment comes after the check. An adjustment of -0.5 still raises ValueError. An adjustment of -5 is allowed: reaching zero is valid, not an error.
Why the Price Stays a Decimal
The value calculation itself needs no change: total_value still multiplies the current quantity by the unit price, and the constructor still defaults the price to Decimal("0"). It can be tempting to "simplify" the model with plain floats, but floats store most decimal fractions approximately, and that error shows up in money.
Three pencils at ten cents each must be worth exactly thirty cents. Keeping Decimal is what makes that true, and the fractional-price test the reviewer asked for is what will catch anyone who changes it later.
Reading the Test Suite as Contract Documentation
In tests/test_inventory.py, the original two tests stay in place, and five new tests describe the behavior the revision must maintain. The first three protect the stock guard: a rejected adjustment leaves the quantity unchanged, reducing stock exactly to zero is allowed, and a fractional adjustment is still rejected without changing anything. The last two add the value cases the reviewer requested.
The follow-up equality assertions matter: they would catch a method that raises the right error but changes the quantity first. As we learned when reviewing tests, strong coverage checks observable behavior, not just whether a line of code ran.
Running the Suite
As in lesson 2, solution.py discovers the tests in the tests directory and runs them with the standard library’s unittest. It returns 0 when the suite succeeds and 1 when it fails, so it works as a simple pass-or-fail gate.
With the revision in place, all seven tests pass:
The same tests also run under pytest -q, which we will use alongside flake8 as part of the full gate in the next lesson. The empty tests/__init__.py file lets pytest find the app package from the project root.
Responding to the Review
The last step is to tell the reviewer what happened to each finding. Instead of a vague "addressed all comments," we add an Author Response section to REVIEW.md that maps every finding to its change and the test that proves it. The reviewer can then check each claim directly.
Notice that the zero-quantity row says "no code change needed." Accepting a suggestion sometimes means adding evidence, not changing behavior, and saying so plainly is part of an honest response. Notice also that the shortage row cites two tests: the rejection test proves InsufficientStockError is raised, and the fractional-adjustment test proves ValueError is kept for non-whole numbers.
Conclusion and Next Steps
We resolved the review one finding at a time: a guard that rejects negative stock before changing the quantity, a named error for shortages, unchanged whole-number and Decimal rules, five new tests, and an author response that links every finding to its evidence. Next, we will practice the revision in three steps: add the stock guard, write its regression tests, and then add the value tests and complete the author response. In the final lesson, we will switch sides again and re-review this exact revision.
