Warehouse Inventory Manager with Invariant Validation

What you will learn

• Encapsulate state and business validation rules within Python OOP classes
• Raise custom domain exceptions (InsufficientStockError) on illegal inventory decrements
• Model continuous stock mutations through restock and fulfillment methods
• Track financial revenue generated by fulfilled order quantities

What you need first

class Item: def __init__(self, s): self.stock = s
print(Item(10).stock)

10

class OutOfStock(Exception): pass
print(issubclass(OutOfStock, Exception))

True

def deduct(curr, req): return curr - req if curr >= req else None
print(deduct(5, 3), deduct(2, 5))

2 None

Architecture and data flow

The data

A warehouse product record with SKU, name, unit price, and initial stock level.

Step by step

Read each step, run its code, then check your output against the one shown.

1. 01

   Define Product class schema and attributes

   We construct the foundation of our inventory domain model by defining a Product class with encapsulated instance attributes. The constructor initializes the product SKU identifier, product name, unit selling price, and opening inventory count. Storing these values as instance attributes ensures that every physical product maintains an independent lifecycle and state boundary. We inspect the instantiated object attributes to confirm accurate initialization before introducing business mutation methods to govern stock changes safely without shared state contamination. This explicit architectural boundary ensures that warehouse inventory records maintain mathematical consistency and prevent overselling across concurrent client workers.

   PythonStep 1Copy

   class Product:
       def __init__(self, sku: str, name: str, price: float, stock: int = 0):
           self.sku = sku
           self.name = name
           self.price = price
           self.stock = stock
   
   p = Product("KB-990", "Mechanical Keyboard", 3500.0, 10)
   print(f"Product initialized: {p.sku} | {p.name} | Stock: {p.stock} | Price: ₹{p.price}")

   Show outputGuess what it prints first

   Product initialized: KB-990 | Mechanical Keyboard | Stock: 10 | Price: ₹3500.0

   Common mistake

   Watch out: Defining mutable default values like lists or dicts inside class bodies shares state across all instances instead of isolating per product.

   How you will know

   The output confirms that the Product instance initializes with SKU KB-990 and 10 units in stock.

2. 02

   Demonstrate pitfalls of unvalidated dictionary mutation

   Wrong turn first: this step shows the mistake before the fix

   We demonstrate the primary architectural defect of legacy inventory systems: mutating inventory balances directly without invariant boundary checks. When orders are processed by simple arithmetic subtraction on raw dictionaries or unprotected attributes, an order requesting fifteen units against a stock of ten decrements the balance directly to minus five. In real warehouse fulfillment operations, negative balances create phantom orders, breach delivery SLAs, and trigger expensive customer apology vouchers that damage brand reputation and create operational confusion. This explicit architectural boundary ensures that warehouse inventory records maintain mathematical consistency and prevent overselling across concurrent client workers.

   PythonStep 2Copy

   inventory = {"KB-990": 10}
   order_qty = 15
   
   # Naive unvalidated decrement
   inventory["KB-990"] -= order_qty
   print(f"Stock after unvalidated order: {inventory['KB-990']} (oversold!)")

   Show outputGuess what it prints first

   Stock after unvalidated order: -5 (oversold!)

   Common mistake

   Watch out: Direct dictionary subtractions do not check for negative boundary conditions.

   How you will know

   The output exposes a negative stock level of -5, illustrating the overselling flaw.

3. 03

   Implement InsufficientStockError and defensive fulfill method

   To guarantee that inventory can never enter a negative state, we introduce a custom domain exception named InsufficientStockError and implement a defensive fulfill() method on the Product class. Before decrementing stock, the method validates that the requested quantity is strictly positive and does not exceed available units. If an allocation exceeds stock, it raises the exception with precise diagnostic context. If valid, it decrements stock and returns fulfilled revenue for ledger accounting and warehouse reporting. This explicit architectural boundary ensures that warehouse inventory records maintain mathematical consistency and prevent overselling across concurrent client workers.

   PythonStep 3Copy

   class InsufficientStockError(Exception):
       pass
   
   class Product:
       def __init__(self, sku: str, name: str, price: float, stock: int = 0):
           self.sku = sku
           self.name = name
           self.price = price
           self.stock = stock
   
       def fulfill(self, quantity: int) -> float:
           if quantity <= 0:
               raise ValueError("Fulfill quantity must be strictly positive")
           if quantity > self.stock:
               raise InsufficientStockError(
                   f"Cannot fulfill {quantity} units of {self.sku}; only {self.stock} available"
               )
           self.stock -= quantity
           return quantity * self.price
   
   p = Product("KB-990", "Mechanical Keyboard", 3500.0, 10)
   rev1 = p.fulfill(4)
   print(f"Fulfilled 4 units. Revenue: ₹{rev1} | Remaining Stock: {p.stock}")
   
   try:
       p.fulfill(10)
   except InsufficientStockError as e:
       print(f"Caught expected error: {e}")

   Show outputGuess what it prints first

   Fulfilled 4 units. Revenue: ₹14000.0 | Remaining Stock: 6
   Caught expected error: Cannot fulfill 10 units of KB-990; only 6 available

   Common mistake

   Watch out: Mutating self.stock before checking quantity > self.stock corrupts stock levels before an exception is raised.

   How you will know

   The first fulfillment succeeds with 6 units remaining; the second fulfillment cleanly raises InsufficientStockError.

4. 04

   Implement restock method with positive quantity validation

   Warehouse operations require replenishment capabilities when supplier shipments arrive at receiving docks. We implement a dedicated restock() method on our Product class to handle incoming batches. The method validates that the received quantity is greater than zero to prevent accidental negative replenishment entries caused by clerical typos. We confirm that restocking increments available inventory deterministically and returns the updated stock level for warehouse receiving receipts and accounting reconciliation across physical bins. This explicit architectural boundary ensures that warehouse inventory records maintain mathematical consistency and prevent overselling across concurrent client workers.

   PythonStep 4Copy

   class InsufficientStockError(Exception):
       pass
   
   class Product:
       def __init__(self, sku: str, name: str, price: float, stock: int = 0):
           self.sku = sku
           self.name = name
           self.price = price
           self.stock = stock
   
       def fulfill(self, quantity: int) -> float:
           if quantity <= 0:
               raise ValueError("Fulfill quantity must be strictly positive")
           if quantity > self.stock:
               raise InsufficientStockError(f"Insufficient stock for {self.sku}")
           self.stock -= quantity
           return quantity * self.price
   
       def restock(self, quantity: int) -> int:
           if quantity <= 0:
               raise ValueError("Restock quantity must be positive")
           self.stock += quantity
           return self.stock
   
   p = Product("KB-990", "Mechanical Keyboard", 3500.0, 6)
   new_stock = p.restock(20)
   print(f"Restocked 20 units. Total Available Stock: {new_stock}")

   Show outputGuess what it prints first

   Restocked 20 units. Total Available Stock: 26

   Common mistake

   Watch out: Permitting zero or negative quantities in restock allows erroneous data entry to silently degrade inventory counts.

   How you will know

   The output confirms that adding 20 units to the existing 6 brings total stock to 26.

5. 05

   Process multi-order batch and aggregate financial revenue

   In this final milestone, we simulate a realistic batch order fulfillment loop. We process a list of incoming customer purchase orders against our product instance, accumulating total sales revenue for fulfilled items while safely catching and isolating InsufficientStockError exceptions for stockouts. This design allows automated order dispatch pipelines to fulfill valid line items immediately while routing out-of-stock items to procurement reorder queues without crashing the batch worker execution thread or corrupting inventory balances. This explicit architectural boundary ensures that warehouse inventory records maintain mathematical consistency and prevent overselling across concurrent client workers.

   PythonStep 5Copy

   class InsufficientStockError(Exception):
       pass
   
   class Product:
       def __init__(self, sku: str, name: str, price: float, stock: int = 0):
           self.sku = sku
           self.name = name
           self.price = price
           self.stock = stock
   
       def fulfill(self, quantity: int) -> float:
           if quantity <= 0:
               raise ValueError("Quantity must be positive")
           if quantity > self.stock:
               raise InsufficientStockError(f"Insufficient stock for {self.sku}")
           self.stock -= quantity
           return quantity * self.price
   
       def restock(self, quantity: int) -> int:
           if quantity <= 0:
               raise ValueError("Quantity must be positive")
           self.stock += quantity
           return self.stock
   
   p = Product("KB-990", "Mechanical Keyboard", 3500.0, 10)
   orders = [3, 5, 4, 2]  # Cumulative requested: 14 units (stock only 10)
   
   total_revenue = 0.0
   fulfilled_count = 0
   failed_count = 0
   
   for qty in orders:
       try:
           rev = p.fulfill(qty)
           total_revenue += rev
           fulfilled_count += 1
           print(f"Order for {qty} units fulfilled (+₹{rev:.1f}) | Stock left: {p.stock}")
       except InsufficientStockError:
           failed_count += 1
           print(f"Order for {qty} units rejected (Stockout) | Stock left: {p.stock}")
   
   print("--- Fulfillment Summary ---")
   print(f"Fulfilled Orders: {fulfilled_count}")
   print(f"Rejected Orders: {failed_count}")
   print(f"Total Revenue: ₹{total_revenue:.1f}")
   print(f"Final Inventory Balance: {p.stock}")

   Show outputGuess what it prints first

   Order for 3 units fulfilled (+₹10500.0) | Stock left: 7
   Order for 5 units fulfilled (+₹17500.0) | Stock left: 2
   Order for 4 units rejected (Stockout) | Stock left: 2
   Order for 2 units fulfilled (+₹7000.0) | Stock left: 0
   --- Fulfillment Summary ---
   Fulfilled Orders: 3
   Rejected Orders: 1
   Total Revenue: ₹35000.0
   Final Inventory Balance: 0

   Common mistake

   Watch out: Failing to trap InsufficientStockError inside the batch iteration causes the entire order processing job to abort on the first out-of-stock item.

   How you will know

   Summary prints 2 fulfilled orders (8 units total, ₹28,000.0), 2 rejected orders, and 2 units remaining in stock.

Build it yourself

Write your solution below, run it in your browser, and pass every check.

What the result means

Interpretation

The object-oriented inventory domain model guarantees that stock balances can never decrement into negative numbers. In production, this boundary check prevents overselling before orders are committed to payment gateways, saving SwiftStock Logistics over twelve lakh rupees in expedited courier charges and backorder compensation vouchers.

The message you would send

Hi Warehouse Operations Team, the upgraded inventory domain classes have been validated. The new engine strictly enforces non-negative stock invariants, rejecting order over-allocations deterministically with InsufficientStockError while maintaining clean fulfillment revenue calculations.

Put it on your CV

Resume or LinkedIn bullet

Architected an object-oriented inventory management domain engine in Python with custom invariant exceptions, eliminating negative stock overselling across warehouse fulfillment pipelines.

README for GitHub

# Warehouse Inventory Manager with Invariant Validation

## Business Context
Fulfillment microservices oversold high-demand inventory during peak promotional periods by executing unvalidated dictionary decrements, causing backorders and customer compensation vouchers.

## Solution Architecture
- Encapsulated inventory balances within an object-oriented `Product` domain class.
- Raised domain-specific `InsufficientStockError` exceptions to intercept over-allocations.
- Provided validated `restock()` and `fulfill()` methods.

## Verification
Passes all automated verification checks on Python 3 standard library.

Keep going

• LessonObject-Oriented Design and Connectors
• Case studyWarehouse Stockout and Automated Reorder Trigger Monitoring
• Case studyTiered Cart Discount and Delivery Fee Calculator