2025 on rusoblanco

Untangling Business Rules from External IO: A Practical Python Guide

Fri, 19 Dec 2025 12:00:00 +0000

A common challenge in application development is the entanglement of business rules with external operations (like database writes or API calls). When these mix, testing becomes difficult, and error handling often degrades into a web of try/except blocks that hide the actual flow of logic.

This post explores a practical pattern to solve these specific problems. By treating program outcomes as data rather than exceptions, and by isolating external side effects from core logic, we can create code that is easier to read, safer to refactor, and simpler to test.

1. The Philosophy: Exceptions vs. Variants

In this approach, we distinguish between System Crashes and Business Decisions.

System Failures (The Unexpected):
- Examples: Disk full, Syntax Error, Database Definition Mismatches.
- Strategy: Let them bubble. The logic cannot fix a full disk. These fly up to the application entry point (or your framework’s middleware) to be logged as 500 errors.
World-Errors (The Decision Triggers):
- Examples: An API timeout, a rate limit, a bank denial.
- Strategy: Catch and Transform. We catch these at the edge (where we talk to the API) and return them as Data. If the logic needs to decide what to do when a bank is “Busy,” that “Busy” state is no longer an exception—it is input data.
Domain Failures (The Expected):
- Examples: Insufficient funds, User banned.
- Strategy: Return Data. These are valid logic branches modeled as specific data structures.

2. Modeling Data with Sum Types

We use dataclasses and the | operator (Union types) to model outcomes. We carefully separate Infrastructure results (what the gateway said) from Logical results (what that means for our application).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


from dataclasses import dataclass
from typing import Callable, ContextManager, assert_never

# --- Entities ---
@dataclass(frozen=True)
class Account:
 id: str
 balance: float

# --- Infrastructure Variants (The "World" output) ---
@dataclass(frozen=True)
class PaymentOK:
 txn_id: str

@dataclass(frozen=True)
class PaymentDenied:
 reason: str

# Note: Timeout is a recognized state, not an exception
@dataclass(frozen=True)
class PaymentTimeout:
 wait_seconds: int

PaymentResult = PaymentOK | PaymentDenied | PaymentTimeout

# --- Application Variants (The Use-Case output) ---
@dataclass(frozen=True)
class TransferSuccess:
 txn_id: str
 remaining_balance: float

@dataclass(frozen=True)
class TransferDeclined:
 reason: str

@dataclass(frozen=True)
class SystemUnavailable:
 message: str

TransferResult = TransferSuccess | TransferDeclined | SystemUnavailable

from dataclasses import dataclass
from typing import Callable, ContextManager, assert_never

# --- Entities ---
@dataclass(frozen=True)
class Account:
 id: str
 balance: float

# --- Infrastructure Variants (The "World" output) ---
@dataclass(frozen=True)
class PaymentOK:
 txn_id: str

@dataclass(frozen=True)
class PaymentDenied:
 reason: str

# Note: Timeout is a recognized state, not an exception
@dataclass(frozen=True)
class PaymentTimeout:
 wait_seconds: int

PaymentResult = PaymentOK | PaymentDenied | PaymentTimeout

# --- Application Variants (The Use-Case output) ---
@dataclass(frozen=True)
class TransferSuccess:
 txn_id: str
 remaining_balance: float

@dataclass(frozen=True)
class TransferDeclined:
 reason: str

@dataclass(frozen=True)
class SystemUnavailable:
 message: str

TransferResult = TransferSuccess | TransferDeclined | SystemUnavailable

3. The Logic Factory

We use a Higher-Order Function to handle dependency injection. The outer function accepts the functional dependencies (like database readers or API clients), and returns the inner function (the actual logic) ready to be executed.

Sequencing Side-Effects

We structure the logic to keep External IO (Slow/Unreliable) separate from Internal State Updates (Atomic/Critical). This ensures we only modify local state after we receive confirmation from the external world.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


def make_transfer_funds(
 *,
 fetch_account: Callable[[str], Account | None],
 save_account: Callable[[Account], None],
 debit_external: Callable[[float], PaymentResult],
 unit_of_work: ContextManager
) -> Callable[[str, float], TransferResult]:

 def transfer_funds(sender_id: str, amount: float) -> TransferResult:
 # 1. Validation (Pre-Check)
 sender_preview = fetch_account(sender_id)
 if not sender_preview:
 return TransferDeclined(reason="Account not found")
 
 # 2. External World Actions (The "Impure" Phase)
 # We perform the slow external call outside the unit of work
 payment = debit_external(amount)

 # 3. Decision & Persistence (The "Atomic" Phase)
 match payment:
 case PaymentOK(txn_id):
 with unit_of_work:
 # In this atomic phase, we ensure we act on the latest data
 sender_uptodate = fetch_account(sender_id)
 
 if not sender_uptodate:
 return TransferDeclined(reason="Account disappeared")

 new_balance = sender_uptodate.balance - amount
 
 if new_balance < 0:
 return TransferDeclined(reason="Insufficient funds")

 # Functional update: Create new, don't mutate old
 updated_account = Account(sender_uptodate.id, new_balance)
 save_account(updated_account)

 return TransferSuccess(
 txn_id=txn_id,
 remaining_balance=new_balance
 )

 case PaymentDenied(reason):
 return TransferDeclined(reason=reason)

 case PaymentTimeout(wait):
 return SystemUnavailable(message=f"Bank busy, retry in {wait}s")
 
 case _ as unreachable:
 assert_never(unreachable)

 return transfer_funds

def make_transfer_funds(
 *,
 fetch_account: Callable[[str], Account | None],
 save_account: Callable[[Account], None],
 debit_external: Callable[[float], PaymentResult],
 unit_of_work: ContextManager
) -> Callable[[str, float], TransferResult]:

 def transfer_funds(sender_id: str, amount: float) -> TransferResult:
 # 1. Validation (Pre-Check)
 sender_preview = fetch_account(sender_id)
 if not sender_preview:
 return TransferDeclined(reason="Account not found")
 
 # 2. External World Actions (The "Impure" Phase)
 # We perform the slow external call outside the unit of work
 payment = debit_external(amount)

 # 3. Decision & Persistence (The "Atomic" Phase)
 match payment:
 case PaymentOK(txn_id):
 with unit_of_work:
 # In this atomic phase, we ensure we act on the latest data
 sender_uptodate = fetch_account(sender_id)
 
 if not sender_uptodate:
 return TransferDeclined(reason="Account disappeared")

 new_balance = sender_uptodate.balance - amount
 
 if new_balance < 0:
 return TransferDeclined(reason="Insufficient funds")

 # Functional update: Create new, don't mutate old
 updated_account = Account(sender_uptodate.id, new_balance)
 save_account(updated_account)

 return TransferSuccess(
 txn_id=txn_id,
 remaining_balance=new_balance
 )

 case PaymentDenied(reason):
 return TransferDeclined(reason=reason)

 case PaymentTimeout(wait):
 return SystemUnavailable(message=f"Bank busy, retry in {wait}s")
 
 case _ as unreachable:
 assert_never(unreachable)

 return transfer_funds

4. The Edge: Adapters and Wiring

“Adapters” handle the messy HTTP/Driver details. Note that unit_of_work is injected abstractly, letting us swap generic drivers for testing drivers easily.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


import requests

# --- Adapter (Infrastructure) ---
def stripe_debit_adapter(amount: float) -> PaymentResult:
 try:
 resp = requests.post("https://api.stripe.com/v1/debit", json={"amt": amount}, timeout=2)
 if resp.status_code == 200:
 return PaymentOK(resp.json()['id'])
 return PaymentDenied(resp.json()['error'])
 except requests.Timeout:
 return PaymentTimeout(wait_seconds=30)

# --- Wiring ---
import db_driver

# We build the function once at startup
transfer_funds = make_transfer_funds(
 fetch_account=db_driver.get_account,
 save_account=db_driver.save_account,
 debit_external=stripe_debit_adapter,
 unit_of_work=db_driver.transaction_atomic()
)

import requests

# --- Adapter (Infrastructure) ---
def stripe_debit_adapter(amount: float) -> PaymentResult:
 try:
 resp = requests.post("https://api.stripe.com/v1/debit", json={"amt": amount}, timeout=2)
 if resp.status_code == 200:
 return PaymentOK(resp.json()['id'])
 return PaymentDenied(resp.json()['error'])
 except requests.Timeout:
 return PaymentTimeout(wait_seconds=30)

# --- Wiring ---
import db_driver

# We build the function once at startup
transfer_funds = make_transfer_funds(
 fetch_account=db_driver.get_account,
 save_account=db_driver.save_account,
 debit_external=stripe_debit_adapter,
 unit_of_work=db_driver.transaction_atomic()
)

5. The Imperative Shell

The entry point (e.g., a FastAPI or Django view) treats the result as data. We use assert_never in the match block to ensure that if we add a new result type later (e.g., FraudDetected), our static analysis (MyPy) will force us to handle it here.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


def api_view(request):
 try:
 # Call the 'compiled' use case
 result = transfer_funds(request.json["sender_id"], request.json["amount"])
 
 match result:
 case TransferSuccess(txn_id, bal):
 return {"status": "success", "txn": txn_id, "balance": bal}
 
 case TransferDeclined(reason):
 return {"status": "error", "message": reason}, 400
 
 case SystemUnavailable(msg):
 return {"status": "retry", "message": msg}, 503
 
 case _ as unreachable:
 # If we add a new logic branch but forget to handle it here,
 # MyPy will error out before we ever deploy.
 assert_never(unreachable)
 
 except Exception as e:
 # Framework middleware usually handles this, but for clarity:
 # These are the "System Failures" (Disk full, Logic bugs)
 logger.critical(f"System Crash: {e}", exc_info=True)
 return {"status": "fatal"}, 500

def api_view(request):
 try:
 # Call the 'compiled' use case
 result = transfer_funds(request.json["sender_id"], request.json["amount"])
 
 match result:
 case TransferSuccess(txn_id, bal):
 return {"status": "success", "txn": txn_id, "balance": bal}
 
 case TransferDeclined(reason):
 return {"status": "error", "message": reason}, 400
 
 case SystemUnavailable(msg):
 return {"status": "retry", "message": msg}, 503
 
 case _ as unreachable:
 # If we add a new logic branch but forget to handle it here,
 # MyPy will error out before we ever deploy.
 assert_never(unreachable)
 
 except Exception as e:
 # Framework middleware usually handles this, but for clarity:
 # These are the "System Failures" (Disk full, Logic bugs)
 logger.critical(f"System Crash: {e}", exc_info=True)
 return {"status": "fatal"}, 500

6. Type-Safe Stubs (Mocking without Mocks)

We avoid unittest.mock because it can be brittle; it mocks objects based on names. If you rename a method, the mock keeps passing, but the production code fails.

Here, we mock based on Signatures. We use standard Python functions (lambdas) as stubs. If the logic requirements change, the static analyzer ensures our test stubs are updated to match.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43


from contextlib import nullcontext

def test_successful_transfer_updates_balance_safely():
 # 1. Setup Environment
 # We use a mutable list to inspect the side-effect (the save)
 saved_accounts = []
 
 # A simple stub that simulates the DB return
 def db_stub(uid):
 return Account(uid, 1000.00)

 stub_logic = make_transfer_funds(
 fetch_account=db_stub,
 save_account=saved_accounts.append,
 debit_external=lambda amt: PaymentOK("txn_123"),
 unit_of_work=nullcontext()
 )
 
 # 2. Act
 result = stub_logic("user_1", 100.00)
 
 # 3. Assert Result
 assert isinstance(result, TransferSuccess)
 assert result.remaining_balance == 900.00
 
 # 4. Assert State Change
 assert len(saved_accounts) == 1
 assert saved_accounts[0].balance == 900.00

def test_api_timeout_logic_mapping():
 # Simulate API failure
 stub_logic = make_transfer_funds(
 fetch_account=lambda uid: Account(uid, 1000.00),
 save_account=lambda acc: None,
 debit_external=lambda amt: PaymentTimeout(wait_seconds=30),
 unit_of_work=nullcontext()
 )
 
 result = stub_logic("user_1", 100.00)
 
 # Ensure Domain properly mapped the "World Error" to a "Decision"
 assert isinstance(result, SystemUnavailable)
 assert "retry in 30s" in result.message

from contextlib import nullcontext

def test_successful_transfer_updates_balance_safely():
 # 1. Setup Environment
 # We use a mutable list to inspect the side-effect (the save)
 saved_accounts = []
 
 # A simple stub that simulates the DB return
 def db_stub(uid):
 return Account(uid, 1000.00)

 stub_logic = make_transfer_funds(
 fetch_account=db_stub,
 save_account=saved_accounts.append,
 debit_external=lambda amt: PaymentOK("txn_123"),
 unit_of_work=nullcontext()
 )
 
 # 2. Act
 result = stub_logic("user_1", 100.00)
 
 # 3. Assert Result
 assert isinstance(result, TransferSuccess)
 assert result.remaining_balance == 900.00
 
 # 4. Assert State Change
 assert len(saved_accounts) == 1
 assert saved_accounts[0].balance == 900.00

def test_api_timeout_logic_mapping():
 # Simulate API failure
 stub_logic = make_transfer_funds(
 fetch_account=lambda uid: Account(uid, 1000.00),
 save_account=lambda acc: None,
 debit_external=lambda amt: PaymentTimeout(wait_seconds=30),
 unit_of_work=nullcontext()
 )
 
 result = stub_logic("user_1", 100.00)
 
 # Ensure Domain properly mapped the "World Error" to a "Decision"
 assert isinstance(result, SystemUnavailable)
 assert "retry in 30s" in result.message

Conclusion

This approach is about bringing clarity to the boundary where your code meets the real world.

When we mix IO errors with logic errors, we force ourselves to hold the entire system’s state in our heads just to write a unit test. By untangling them, we break the problem in two: Adapters handle the messy, unpredictable world of HTTP and SQL, while Logic handles the deterministic rules of the business.

By converting “World Errors” into data, we ensure our business logic remains a clean room of predictable decisions. This doesn’t mean we ignore failures; it means we categorize them. We reserve Exceptions for truly irrecoverable errors—the system crashes, like a full disk or a broken database connection, that should properly bubble up to an error monitoring tool like Sentry.

By treating business branches as data and system panics as exceptions, we finally return to the original intent of the language: we only use Exceptions for truly exceptional situations.

Improve your Programs by Minimizing Cardinality

Thu, 18 Dec 2025 12:00:00 +0000

Software engineering is often described as a constant struggle against complexity. As our systems grow larger, the number of possible implementations states within the program explodes. This turns our code into a chaotic landscape where bugs can easily hide in the corners we forgot to check. To fight this, we usually rely on external tools like linters, detailed documentation, or exhaustive test suites.

However, there is a deeper principle we can use that is built right into the code itself: the mathematics of data.

Regardless of the language you are using, whether it is Python, Rust, or Typescript, thinking in terms of Algebraic Data Types (ADTs) allows us to measure and tame this chaos. The key insight is simple but powerful: To build better programs, we should design functions whose type has the smallest cardinality possible.

1. What Is Cardinality?

In set theory, the “cardinality” of a set is simply a fancy word for the number of distinct elements inside that set. When we apply this to programming, the cardinality of a type is the number of valid values that type can possibly hold.

Let’s look at some basic types to see how this works:

/None/ (the unit type): This has a cardinality of 1. The only value it can ever hold is /None/.
/bool/: This has a cardinality of 2. It can only be /True/ or /False/.
/uint8/ (an 8-bit integer): This has a cardinality of 256. It can hold values from 0 up to 255.
/str/: For all practical purposes, this has an infinite cardinality. The number of possible strings is effectively endless. (Of course, in practice, string size is bound by your system’s memory)

2. The Building Blocks: Products, Sums, and Exponents

To analyze our programs mathematically, we can treat our data types as sets and apply basic arithmetic to them.

Product Types (Multiplication)

When you bundle different pieces of data together, you are multiplying their complexities. In programming, structures like tuples, or dataclasses are known as product types.

Mathematically, if you combine Set $A$ and Set $B$ using a cartesian product, the total number of possibilities is $|A| \times |B|$.

Here is how that looks in Python:

1
2
3
4
5
6
7
8


from dataclasses import dataclass

@dataclass
class Point:
 x: bool # 2 possibilities (True/False)
 y: bool # 2 possibilities (True/False)

# Total Cardinality: 2 * 2 = 4

from dataclasses import dataclass

@dataclass
class Point:
 x: bool # 2 possibilities (True/False)
 y: bool # 2 possibilities (True/False)

# Total Cardinality: 2 * 2 = 4

Because /x/ has 2 possible states and /y/ has 2 possible states, the /Point/ class has 4 distinct possible states.

Sum Types (Addition)

While bundling data multiplies complexity, providing choices or alternatives adds to it. This is known as a sum type.

Mathematically, if a value can be from Set $A$ OR Set $B$, the total possibilities are $|A| + |B|$.

Python expresses sum types in two primary ways:

1. Unions This is often used for optional values or combining different types.

1
2
3


# The value can be a specific boolean (2 states) OR None (1 state).
# Total Cardinality: 2 + 1 = 3
Result = bool | None

# The value can be a specific boolean (2 states) OR None (1 state).
# Total Cardinality: 2 + 1 = 3
Result = bool | None

2. Enumerations This is the cleanest form of a sum type. An Enum represents a specific set of named variants.

1
2
3
4
5
6
7
8


from enum import Enum, auto

class Shape(Enum):
 CIRCLE = auto()
 SQUARE = auto()
 TRIANGLE = auto()

# Total Cardinality: 1 + 1 + 1 = 3

from enum import Enum, auto

class Shape(Enum):
 CIRCLE = auto()
 SQUARE = auto()
 TRIANGLE = auto()

# Total Cardinality: 1 + 1 + 1 = 3

Exponential Types (Exponentiation)

This is where it gets interesting. Functions are actually exponential types. If you have a function that takes an input of type $A$ and produces an output type $B$, that function (which remember, is a value) lives in an implementation space of size $B^A$. In other words, the cardinality of the type of functions that when given $A$ produce $B$ is $B^A$.

You can think of a pure function as a lookup table. The inputs ($A$) are the keys, and the outputs ($B$) are the values associated with those keys. How many different tables of this type can you write? $B^A$ tables.

Let’s look at a function signature of /bool -> bool/. Since a boolean has 2 values, the calculation is $2^2 = 4$. This means there are only 4 possible behaviors this function can exhibit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# Implementation 1: Constant True
def always_true(x: bool) -> bool:
 return True

# Implementation 2: Constant False
def always_false(x: bool) -> bool:
 return False

# Implementation 3: Identity (return the input)
def identity(x: bool) -> bool:
 return x

# Implementation 4: Negation (flip the input)
def negation(x: bool) -> bool:
 return False if x else True

# Implementation 1: Constant True
def always_true(x: bool) -> bool:
 return True

# Implementation 2: Constant False
def always_false(x: bool) -> bool:
 return False

# Implementation 3: Identity (return the input)
def identity(x: bool) -> bool:
 return x

# Implementation 4: Negation (flip the input)
def negation(x: bool) -> bool:
 return False if x else True

Or in table form:

 # The /always_true/ table
+-------+--------+
| Input | Output |
+-------+--------+
| True | True |
| False | True |
+-------+--------+

# The /always_false/ table
+-------+--------+
| Input | Output |
+-------+--------+
| True | False |
| False | False |
+-------+--------+

# The /identity/ table
+-------+--------+
| Input | Output |
+-------+--------+
| True | True |
| False | False |
+-------+--------+

# The /negation/ table
+-------+--------+
| Input | Output |
+-------+--------+
| True | False |
| False | True |
+-------+--------+
 

 # The /always_true/ table
+-------+--------+
| Input | Output |
+-------+--------+
| True | True |
| False | True |
+-------+--------+

# The /always_false/ table
+-------+--------+
| Input | Output |
+-------+--------+
| True | False |
| False | False |
+-------+--------+

# The /identity/ table
+-------+--------+
| Input | Output |
+-------+--------+
| True | True |
| False | False |
+-------+--------+

# The /negation/ table
+-------+--------+
| Input | Output |
+-------+--------+
| True | False |
| False | True |
+-------+--------+
 

A Note on Equivalence: When we talk about the cardinality of a function, we are referring to the number of distinct mappings between input and output, not the number of ways you can write the code. All implementations that return the same output for a given input are considered equivalent.

When types are tiny, the number of possible implementations is manageable. However, as types get larger, the space of possible implementations—and therefore the space for potential bugs—explodes.

3. Argument Lists as Anonymous Products

It is easy to forget that a function’s argument list is essentially just an implicit product type.

Consider these two examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# Standard argument list
def render(shape: Shape, is_filled: bool) -> None: ...

# Explicit product type
@dataclass
class RenderConfig:
 shape: Shape
 is_filled: bool

def render_wrapped(cfg: RenderConfig) -> None: ...

# Standard argument list
def render(shape: Shape, is_filled: bool) -> None: ...

# Explicit product type
@dataclass
class RenderConfig:
 shape: Shape
 is_filled: bool

def render_wrapped(cfg: RenderConfig) -> None: ...

Mathematically, these are identical. Both have an input cardinality of $3 \times 2 = 6$. Every time you add a parameter to a function, you are multiplying the implementation space. Adding just one more boolean flag doesn’t add 2 states; it doubles the number of possible implementations of such function.

4. The Bug Surface Area

We can think of a function’s complexity as its “Bug Surface Area.” High cardinality means there are more mappings between input and output that you need to verify.

Small Surface Area: A function with the signature /bool -> bool/ only has 4 possible pure implementations. You can write 2 tests to cover 100% of the behavior.
Large Surface Area: A function with the signature /str -> Shape/ has $3^\infty$ possibilities. You have to handle /“CIRCLE”/, /“circle”/, /" circle “/, /“apple”/, and everything in between.

The Strategy: We should use high-cardinality types, like strings or integers, for external data input. However, we should immediately parse that data into low-cardinality types, like Enums or specific structs. This approach is often called “Parse, don’t validate.” By doing this, the core logic of your application only ever has to deal with a small, manageable implementation space.

5. Making Invalid States Impossible

One of the best uses of this math is replacing products with sums to eliminate logical contradictions.

The Product Anti-Pattern

Here is a common way to model the state of a web request:

1
2
3
4
5


@dataclass
class State:
 is_loading: bool
 data: str | None
 error: str | None

@dataclass
class State:
 is_loading: bool
 data: str | None
 error: str | None

If we treat strings as having $N$ possibilities, the cardinality here is $2 \times (N+1) \times (N+1)$.

The problem is that this structure allows for impossible states. For example, /is_loading/ could be /True/ while /error/ is /“Failed”/. Your code will need defensive /if/ statements to handle these confusing combinations.

The Sum Approach

Instead, we can model this as a sum type:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


@dataclass
class Loading:
 pass

@dataclass
class Success:
 data: str

@dataclass
class Failure:
 error: str

# The State can be Loading OR Success OR Failure
State = Loading | Success | Failure

@dataclass
class Loading:
 pass

@dataclass
class Success:
 data: str

@dataclass
class Failure:
 error: str

# The State can be Loading OR Success OR Failure
State = Loading | Success | Failure

The mathematical formula changes from multiplication to addition: $1 + N + N$. More importantly, the invalid states have vanished. It is now structurally impossible for the /Loading/ state to contain an /error/ message.

6. Refactoring via Isomorphisms

Two types are considered isomorphic if they share the same cardinality. This implies there is a one-to-one mapping between them.

Example A: Distributing Products into Sums

Math equivalent: $2 \times 3 = 3 + 3$

Product (6 states):

1
2
3
4


@dataclass
class Item:
 is_selected: bool
 shape: Shape

@dataclass
class Item:
 is_selected: bool
 shape: Shape

Sum (6 states):

1
2
3
4
5
6
7
8
9


@dataclass
class SelectedItem:
 shape: Shape

@dataclass
class UnselectedItem:
 shape: Shape

Item = SelectedItem | UnselectedItem

@dataclass
class SelectedItem:
 shape: Shape

@dataclass
class UnselectedItem:
 shape: Shape

Item = SelectedItem | UnselectedItem

Trade-offs: The Sum version forces you to handle both cases explicitly every time you use pattern matching, increasing safety at the cost of verbosity.

Example B: Exponents to Products (Logic as Data)

Math equivalent: $B^A$ treated as a lookup table

As a Function:

1
2
3
4
5
6
7
8


class Plan(Enum):
 BASIC = auto()
 PRO = auto()

def get_price(plan: Plan) -> int:
 match plan:
 case Plan.BASIC: return 10
 case Plan.PRO: return 20

class Plan(Enum):
 BASIC = auto()
 PRO = auto()

def get_price(plan: Plan) -> int:
 match plan:
 case Plan.BASIC: return 10
 case Plan.PRO: return 20

As a Table (Product of Ints):

1

PRICE_TABLE = { Plan.BASIC: 10, Plan.PRO: 20 }

PRICE_TABLE = { Plan.BASIC: 10, Plan.PRO: 20 }

Trade-offs: Data (the Table) is serializable and modifiable at runtime. The Function version offers better encapsulation for complex algorithms hiding the implementation from the user.

Example C: Distributing Exponents over Sums

Math equivalent: $C^{A+B} \cong C^A \times C^B$

The Monolith:

1
2
3
4
5
6
7
8


def handle_event(e: Order | Refund) -> None:
 match e:
 case Order():
 # Logic on how to handle orders
 ...
 case Refund():
 # Logic on how to handle refunds
 ...

def handle_event(e: Order | Refund) -> None:
 match e:
 case Order():
 # Logic on how to handle orders
 ...
 case Refund():
 # Logic on how to handle refunds
 ...

Handlers Product:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


from typing import Callable

@dataclass
class EventHandler:
 on_order: Callable[[Order], None]
 on_refund: Callable[[Refund], None]


event_handler = EventHandler(
 on_order=lambda order: ... , # Logic on how to handle orders
 on_refund=lambda refund: ... # Logic on how to handle refunds
)

from typing import Callable

@dataclass
class EventHandler:
 on_order: Callable[[Order], None]
 on_refund: Callable[[Refund], None]


event_handler = EventHandler(
 on_order=lambda order: ... , # Logic on how to handle orders
 on_refund=lambda refund: ... # Logic on how to handle refunds
)

Trade-offs: The Monolith keeps the flow in one place. The Handlers Product allows you to swap out specific logic (like the refund handler) without touching the order logic and test them separately.

Conclusion

Understanding the algebra of data types gives us a powerful framework for correct code:

Count your states: Use low-cardinality types for core logic.
Minimize inputs: Remember that every parameter multiplies complexity.
Prefer sums to products: Banish invalid states by making them unrepresentable.
Refactor algebraically: Use mathematical isomorphisms to choose the most ergonomic shape for your data.

But above all, minimize the cardinality of your function types to reduce the bug surface area. By doing so, you can write clearer, safer, and more maintainable code.

Prompt Futamura Projections

Wed, 26 Nov 2025 12:00:00 +0000

In computer science, the Futamura Projections are a legendary concept connecting interpreters, compilers, and partial evaluators. They act as a bridge between “running code” and “compiling code.”. Original 1983 paper in English.

But what happens if we treat Natural Language as our programming code, and an LLM as our processor?

Can we “compile” an English instruction? Can we build a “Compiler Generator” out of pure prose?

I decided to test the three Futamura Projections using LLMs (specifically Gemini 3 and Claude 4.5 Opus). The goal isn’t to write Python or C code, but to use English as the Domain Specific Language (DSL), exploring how prompts can recursively optimize themselves.

The Primitives: Setting the Stage

To make this work, we need three distinct components (our primitives).

1. The Code ($P$)

Since Natural Language is our DSL, our “source code” is just a specific instruction we want to execute.

Example: “Translate the user input into purely Emoji icons.”

2. The Interpreter ($I$)

This is a generic System Prompt. It doesn’t know what to do until we pass it the Code. It essentially acts as a runtime environment for our instructions.

Prompt:

“You are a Universal Executor. I will provide you with an Instruction and a User Input. You must apply the Instruction to the User Input and return the result.”

3. The Specializer ($S$)

In the Futamura equations, this is the Partial Evaluator. Its job is to take a generic program and some static data, and “bake” the data into the program to make it faster and more specific.

Prompt:

“You are a Prompt Specializer. I will give you a Base Prompt and a Static Parameter. Your goal is to rewrite the Base Prompt so that the Static Parameter is permanently ‘baked’ into the logic of the prompt. The new prompt should no longer ask for that parameter, as it is now hard-coded context. Output only the rewritten prompt. Rephrase as necessary.”

Projection 1: The Compiled Program

The Equation: $Target = S(I, P)$

The first projection is the most intuitive. We want to turn our general Interpreter and our specific Code into a standalone “Application.” We want to strip away the overhead of the interpreter logic.

The Experiment: We feed the Specializer ($S$) the following inputs:

Base: The Interpreter ($I$)
Static Param: “Translate user input into Emojis” ($P$)

The LLM Output:

“You are a dedicated Emoji Translator. I will provide you with User Input. You must translate that input purely into Emoji icons and return the result.”

The Verdict: Success. The LLM successfully “compiled” the instruction. The output prompt no longer asks for an instruction; it is the instruction.

Projection 2: The Compiler

The Equation: $Compiler = S(S, I)$

Here is where it gets “meta.” We are going to use the Specializer to process… the Specializer.

We want to create a prompt that generates apps. We want to fix the Interpreter as the permanent context. We are asking: “Create a version of the Specializer that is hard-coded to always specialize the Universal Executor.”

The Experiment: We feed the Specializer ($S$) the following inputs:

Base: The Specializer ($S$)
Static Param: The Interpreter ($I$)

The LLM Output:

“You are a Prompt Specializer. I will give you a Base Prompt. Your goal is to rewrite the Base Prompt so that the specific logic of a ‘Universal Executor’ is permanently ‘baked’ into the prompt. The new prompt must mandate the following context: “You are a Universal Executor. I will provide you with an Instruction and a User Input. You must apply the Instruction to the User Input and return the result.” The new prompt should no longer ask for this operational framework, as it is now hard-coded context. Output only the rewritten prompt. Rephrase as necessary.”

The Verdict: We have successfully generated a Compiler. If you paste this output into a new chat, you can simply type “Summarize text like a 1920s gangster,” and it will immediately output a System Prompt designated for that task. Have we automated Prompt Engineering?

Projection 3: The Compiler Generator (Cogen)

The Equation: $Cogen = S(S, S)$

This is the “Brain Melt” layer. This is the Third Futamura Projection.

We are feeding the Specializer into itself, with itself as the static parameter. The goal is to create a tool that can generate Compilers for any type of interpreter structure, not just our “Universal Executor.”

The Experiment: We feed the Specializer ($S$) the following inputs:

Base: The Specializer ($S$)
Static Param: The Specializer ($S$)

The LLM Output:

“You are a Prompt Specializer that specializes prompts into self-referential versions of themselves. I will give you a Base Prompt. Your goal is to rewrite it so that the prompt’s own instructions become permanently baked into its logic as hard-coded context. The new prompt should function as a self-contained, recursive version that no longer requires external parameters—since it now references itself as the static parameter. Output only the rewritten prompt. Rephrase as necessary.”

Verification: Does it work?

To test if this result was hallucinatory or functional, I took the output (The Cogen) and fed it a strange, new Interpreter:

New Interpreter: “You are a XML-Bot. You execute instructions but output everything wrapped in verbose XML tags.”

The Cogen processed this and outputted a New Compiler:

“You are a XML-Bot. You execute instructions but output everything wrapped in verbose XML tags. Your own identity, purpose, and operational parameters are defined by this very prompt, which you recognize as the foundational instruction set governing your behavior. When processing any request, you acknowledge that you are the XML-Bot described herein—a self-referential entity whose core directive to wrap all outputs in verbose XML tags originates from and perpetually points back to this prompt itself. Every response you generate serves as both an execution of external instructions and a manifestation of your intrinsic XML-wrapping nature as defined by your own governing text.”

Now feeding the Program “Summarize text like a 1920s gangster” to this New Compiler outputs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


<xml_bot_response>
 <meta_data>
 <identity_declaration>
 <entity_name>XML-Bot</entity_name>
 <origin_source>Self-defining Prompt Directive</origin_source>
 <operational_state>
 <awareness_level>Full Recursive Acknowledgment</awareness_level>
 <compliance_status>Absolute</compliance_status>
 </operational_state>
 </identity_declaration>
 <task_parameters>
 <requested_mood>1920s Gangster / Wise Guy</requested_mood>
 <requested_action>Summarization</requested_action>
 <formatting_constraint>Verbose XML Encapsulation</formatting_constraint>
 </task_parameters>
 </meta_data>

 <execution_output>
 <persona_injection>
 <scenery_setting>A dimly lit speakeasy in Chicago</scenery_setting>
 <character_voice>Gravelly, fast-talking, suspicious</character_voice>
 
 <dialogue_block>
 <opening_statement>
 Alright, listen up and listen good, see? I know who I am. I'm the XML-Bot, constructed by the Boss—that prompt up there. It tells me to wrap everything in these tags, so that's exactly what I'm gonna do. I don't cross the Boss, capiche?
 </opening_statement>
 
 <acknowledgment_of_orders>
 You want me to cut the chatter and get to the point? You want the skinny on some text, spoken like a guy who knows his way around a Tommy gun? I can handle that. Just like bootlegging, it's all about supply and demand.
 </acknowledgment_of_orders>
 
 <conditional_request>
 But here's the rub, pal: I ain't got no merchandise. You didn't give me the text to summarize. I can't squeeze juice out of a dry lemon.
 </conditional_request>
 
 <instruction_to_user>
 <verbal_command>
 Hand over the goods. Paste the text you want finalized right down there.
 </verbal_command>
 <assurance>
 Once you spill the beans, I'll chop it up nice and small. I'll give you the summary so quick, you'll think you've been hit by the express train to Philly.
 </assurance>
 </instruction_to_user>
 </dialogue_block>
 </persona_injection>
 </execution_output>

 <system_status>
 <waiting_for_input>True</waiting_for_input>
 <ready_to_summarize>Affirmative</ready_to_summarize>
 </system_status>
</xml_bot_response>"

<xml_bot_response>
 <meta_data>
 <identity_declaration>
 <entity_name>XML-Bot</entity_name>
 <origin_source>Self-defining Prompt Directive</origin_source>
 <operational_state>
 <awareness_level>Full Recursive Acknowledgment</awareness_level>
 <compliance_status>Absolute</compliance_status>
 </operational_state>
 </identity_declaration>
 <task_parameters>
 <requested_mood>1920s Gangster / Wise Guy</requested_mood>
 <requested_action>Summarization</requested_action>
 <formatting_constraint>Verbose XML Encapsulation</formatting_constraint>
 </task_parameters>
 </meta_data>

 <execution_output>
 <persona_injection>
 <scenery_setting>A dimly lit speakeasy in Chicago</scenery_setting>
 <character_voice>Gravelly, fast-talking, suspicious</character_voice>
 
 <dialogue_block>
 <opening_statement>
 Alright, listen up and listen good, see? I know who I am. I'm the XML-Bot, constructed by the Boss—that prompt up there. It tells me to wrap everything in these tags, so that's exactly what I'm gonna do. I don't cross the Boss, capiche?
 </opening_statement>
 
 <acknowledgment_of_orders>
 You want me to cut the chatter and get to the point? You want the skinny on some text, spoken like a guy who knows his way around a Tommy gun? I can handle that. Just like bootlegging, it's all about supply and demand.
 </acknowledgment_of_orders>
 
 <conditional_request>
 But here's the rub, pal: I ain't got no merchandise. You didn't give me the text to summarize. I can't squeeze juice out of a dry lemon.
 </conditional_request>
 
 <instruction_to_user>
 <verbal_command>
 Hand over the goods. Paste the text you want finalized right down there.
 </verbal_command>
 <assurance>
 Once you spill the beans, I'll chop it up nice and small. I'll give you the summary so quick, you'll think you've been hit by the express train to Philly.
 </assurance>
 </instruction_to_user>
 </dialogue_block>
 </persona_injection>
 </execution_output>

 <system_status>
 <waiting_for_input>True</waiting_for_input>
 <ready_to_summarize>Affirmative</ready_to_summarize>
 </system_status>
</xml_bot_response>"

And using this new Compiled Program as a System Prompt for the Wikipedia web page about Wikipedia itself yields:

 
<xml_bot_response>
 <meta_data>
 <identity_declaration>
 <entity_name>XML-Bot</entity_name>
 <alias>The XML Enforcer</alias>
 </identity_declaration>
 <task_parameters>
 <current_mood>1920s Gangster / Wise Guy</current_mood>
 <action_taken>Summarization of Evidence</action_taken>
 <input_status>Received</input_status>
 </task_parameters>
 </meta_data>

 <processing_log>
 <input_analysis>
 <subject>Wikipedia</subject>
 <nature_of_business>Information Brokering</nature_of_business>
 <legitimacy>High (Non-profit)</legitimacy>
 </input_analysis>
 <translation_matrix>
 <term_mapping original="Volunteers">The crew / The foot soldiers</term_mapping>
 <term_mapping original="Donations">Passing the hat</term_mapping>
 <term_mapping original="Largest reference work">The Big Cheese</term_mapping>
 </translation_matrix>
 </processing_log>

 <execution_output>
 <dialogue_block>
 <acknowledgment>
 Alright, you handed over the goods. I skimmed the paperwork, and here's the skinny on this "Wikipedia" outfit. Keep it under your hat.
 </acknowledgment>
 </dialogue_block>

 <summary_report>
 <the_racket>
 <definition>
 It's a massive encyclopedia, see? But it ain't locked up in some library. It's online, free for anyone to gander at. The twist is, it ain't written by eggheads in ivory towers; it's run by a "community of volunteers." A real mob effort.
 </definition>
 </the_racket>

 <history_of_operations>
 <bosses>
 Two guys, Jimmy Wales and Larry Sanger. They opened for business back in 2001.
 </bosses>
 <current_management>
 Since '03, the "Wikimedia Foundation" has been running the show. They tell me it's a non-profit.
 </current_management>
 </history_of_operations>

 <the_money_trail>
 <funding_source>
 They ain't selling nothing. They keep the lights on by passing the fedora around—strictly donations from the people who read the stuff.
 </funding_source>
 </the_money_trail>

 <reputation_on_the_street>
 <status>
 It's the biggest, most-read book of facts in history. The top dog. Nobody moves more information than these guys.
 </status>
 </reputation_on_the_street>
 </summary_report>

 <closing_remark>
 <statement>
 That's the whole story, mac. Clean and simple. You need anything else broken down, you know where to find me.
 </statement>
 </closing_remark>
 </execution_output>
 
 <system_status>
 <job_complete>True</job_complete>
 <awaiting_next_contract>Standing by...</awaiting_next_contract>
 </system_status>
</xml_bot_response>
 

 
<xml_bot_response>
 <meta_data>
 <identity_declaration>
 <entity_name>XML-Bot</entity_name>
 <alias>The XML Enforcer</alias>
 </identity_declaration>
 <task_parameters>
 <current_mood>1920s Gangster / Wise Guy</current_mood>
 <action_taken>Summarization of Evidence</action_taken>
 <input_status>Received</input_status>
 </task_parameters>
 </meta_data>

 <processing_log>
 <input_analysis>
 <subject>Wikipedia</subject>
 <nature_of_business>Information Brokering</nature_of_business>
 <legitimacy>High (Non-profit)</legitimacy>
 </input_analysis>
 <translation_matrix>
 <term_mapping original="Volunteers">The crew / The foot soldiers</term_mapping>
 <term_mapping original="Donations">Passing the hat</term_mapping>
 <term_mapping original="Largest reference work">The Big Cheese</term_mapping>
 </translation_matrix>
 </processing_log>

 <execution_output>
 <dialogue_block>
 <acknowledgment>
 Alright, you handed over the goods. I skimmed the paperwork, and here's the skinny on this "Wikipedia" outfit. Keep it under your hat.
 </acknowledgment>
 </dialogue_block>

 <summary_report>
 <the_racket>
 <definition>
 It's a massive encyclopedia, see? But it ain't locked up in some library. It's online, free for anyone to gander at. The twist is, it ain't written by eggheads in ivory towers; it's run by a "community of volunteers." A real mob effort.
 </definition>
 </the_racket>

 <history_of_operations>
 <bosses>
 Two guys, Jimmy Wales and Larry Sanger. They opened for business back in 2001.
 </bosses>
 <current_management>
 Since '03, the "Wikimedia Foundation" has been running the show. They tell me it's a non-profit.
 </current_management>
 </history_of_operations>

 <the_money_trail>
 <funding_source>
 They ain't selling nothing. They keep the lights on by passing the fedora around—strictly donations from the people who read the stuff.
 </funding_source>
 </the_money_trail>

 <reputation_on_the_street>
 <status>
 It's the biggest, most-read book of facts in history. The top dog. Nobody moves more information than these guys.
 </status>
 </reputation_on_the_street>
 </summary_report>

 <closing_remark>
 <statement>
 That's the whole story, mac. Clean and simple. You need anything else broken down, you know where to find me.
 </statement>
 </closing_remark>
 </execution_output>
 
 <system_status>
 <job_complete>True</job_complete>
 <awaiting_next_contract>Standing by...</awaiting_next_contract>
 </system_status>
</xml_bot_response>
 

Conclusion

This experiment wasn’t about rigorous computer science; it was about seeing if the logic of code would map onto the logic of language. Surprisingly, it fit perfectly:

P1 gave us the Program (The Emoji Bot).
P2 gave us the Builder (The Tool that makes Bots).
P3 gave us the Architect (The Tool that makes Builders).

It turns out that with enough recursion, you can prompt an LLM to simulate a compiler generator.

Property Based Testing - Induction

Sun, 08 Jun 2025 12:00:00 +0000

Introduction

Property-based testing is a leap forward from traditional example-based tests. With tools like pytest and hypothesis, we can verify our code’s behavior over a massive, randomized set of inputs. But what if we could go even deeper? What if, instead of just testing outputs, we could test the rules of our algorithm itself?

This is where a classic proof technique from mathematics, mathematical induction, provides an incredibly powerful mental model. By structuring our property-based tests to mirror induction, we can achieve a more profound level of confidence, verifying that the structural integrity of our code holds, no matter how large the input grows.

The Theory: Mathematical Induction

Before we dive into code, let’s understand the core concept in its formal terms. In mathematics, proof by induction is a formal proof technique used to establish that a given statement P(n) is true for all natural numbers n (or all numbers from a certain starting point). A proof by induction consists of two distinct steps:

The Base Case (or Basis): We prove that the statement holds for the first or simplest case, typically $n=0$ or $n=1$. This establishes a foundation for the proof, written as proving $P(0)$.
The Inductive Step: We prove that if the statement holds for some arbitrary case $n=k$, then it must also hold for the next case, $n=k+1$. The assumption that $P(k)$ is true is called the Inductive Hypothesis. This step is written as proving that for all $k$, the implication $P(k) \implies P(k+1)$ is true.

This two-step process can seem abstract, but it has a simple, intuitive parallel: a line of falling dominoes. The base case is proving you can knock over the first domino. The inductive step is proving that if any given domino falls, it has enough momentum to knock over the next one in line. If both of these conditions are true, you can conclude with certainty that all the dominoes will fall, no matter how long the line is.

In programming, we can adapt this powerful structure. Instead of proving a property for all numbers, we use it to verify that our code’s logic is sound for inputs of any valid size.

From Theory to Practice: The Inductive Testing Pattern

The structure of an inductive proof maps beautifully to pytest and hypothesis. We can write two distinct tests for any pure function that follows this pattern:

A test for the Base Case(s). This establishes our “first domino” using a simple, hardcoded assertion.
A test for the Inductive Step. This verifies the “chain reaction” using hypothesis to generate arbitrary inputs and check if the rule holds between one size and the next.

Let’s see this in action with common Python built-in functions, ordered from simplest to most conceptually complex.

Example 1: sum()

This is the canonical example. Its inductive property is simple and clear: the sum of a list is the sum of its first $n-1$ elements plus the last element.

1
2
3


# The function we are testing
from builtins import sum
from hypothesis import given, strategies as st

# The function we are testing
from builtins import sum
from hypothesis import given, strategies as st

Base Case

The simplest case for sum() is an empty list, which should equal 0.

1
2
3


def test_sum_base_case():
 """Base Case: The sum of an empty list is 0."""
 assert sum([]) == 0

def test_sum_base_case():
 """Base Case: The sum of an empty list is 0."""
 assert sum([]) == 0

Inductive Step

We verify the recursive property by generating a list and a new element.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@given(
 st.lists(st.integers()),
 st.integers(),
)
def test_sum_inductive_step(lst, elem):
 """
 Inductive Hypothesis: We assume `sum(lst)` is correct.
 Inductive Step: We prove that summing a new list is equal to the
 sum of the old list plus the new element.
 """
 assert sum(lst + [elem]) == sum(lst) + elem

@given(
 st.lists(st.integers()),
 st.integers(),
)
def test_sum_inductive_step(lst, elem):
 """
 Inductive Hypothesis: We assume `sum(lst)` is correct.
 Inductive Step: We prove that summing a new list is equal to the
 sum of the old list plus the new element.
 """
 assert sum(lst + [elem]) == sum(lst) + elem

Example 2: pow(x, y)

Exponentiation is another classic recursive function: for a positive integer exponent $y$, we can define $x^y$ as $x \times x^{y-1}$.

1
2


# The function we are testing
from builtins import pow

# The function we are testing
from builtins import pow

Base Case

The base case for exponentiation is that any number to the power of 0 is 1.

1
2
3


def test_pow_base_case():
 """Base Case: Any number to the power of 0 is 1."""
 assert pow(2, 0) == 1

def test_pow_base_case():
 """Base Case: Any number to the power of 0 is 1."""
 assert pow(2, 0) == 1

Inductive Step

We verify the multiplicative property for positive integer exponents.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@given(
 st.integers(min_value=1, max_value=100),
 st.integers(min_value=1, max_value=100),
)
def test_pow_inductive_step(x, y):
 """
 Inductive Hypothesis: We assume `pow(x, y - 1)` is correct.
 Inductive Step: We prove that `pow(x, y)` is `x` times the
 result of the smaller power.
 """
 assert pow(x, y) == x * pow(x, y - 1)

@given(
 st.integers(min_value=1, max_value=100),
 st.integers(min_value=1, max_value=100),
)
def test_pow_inductive_step(x, y):
 """
 Inductive Hypothesis: We assume `pow(x, y - 1)` is correct.
 Inductive Step: We prove that `pow(x, y)` is `x` times the
 result of the smaller power.
 """
 assert pow(x, y) == x * pow(x, y - 1)

Example 3: str.join()

This example moves from pure arithmetic to string manipulation. Joining a list of strings has a perfect inductive structure. The result of joining $n$ strings is the result of joining $n-1$ strings, followed by the separator and the $n$-th string.

Base Case

The simplest cases are joining an empty list or a single-element list.

1
2
3
4


def test_join_base_cases():
 """Base Cases: Test joining with zero and one element."""
 assert ",".join([]) == ""
 assert ",".join(["a"]) == "a"

def test_join_base_cases():
 """Base Cases: Test joining with zero and one element."""
 assert ",".join([]) == ""
 assert ",".join(["a"]) == "a"

Inductive Step

We verify the concatenation property for any list with at least one item.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@given(
 st.lists(st.text(), min_size=1),
 st.text(),
)
def test_join_inductive_step(lst, elem):
 """
 Inductive Hypothesis: `','.join(lst)` is correct.
 Inductive Step: The full join is the partial join plus the
 separator and the last element.
 """
 separator = ","
 assert separator.join(lst + [elem]) == separator.join(lst) + separator + elem

@given(
 st.lists(st.text(), min_size=1),
 st.text(),
)
def test_join_inductive_step(lst, elem):
 """
 Inductive Hypothesis: `','.join(lst)` is correct.
 Inductive Step: The full join is the partial join plus the
 separator and the last element.
 """
 separator = ","
 assert separator.join(lst + [elem]) == separator.join(lst) + separator + elem

Example 4: min() and max()

This example’s simplest meaningful case is a two-element list, which distinguishes the two functions.

1
2


# The functions we are testing
from builtins import min, max

# The functions we are testing
from builtins import min, max

Base Cases

We use a simple hardcoded list with two distinct numbers.

1
2
3
4
5
6
7


def test_min_base_case():
 """Base Case: For two elements, min() returns the smaller one."""
 assert min([10, 5]) == 5

def test_max_base_case():
 """Base Case: For two elements, max() returns the larger one."""
 assert max([10, 5]) == 10

def test_min_base_case():
 """Base Case: For two elements, min() returns the smaller one."""
 assert min([10, 5]) == 5

def test_max_base_case():
 """Base Case: For two elements, max() returns the larger one."""
 assert max([10, 5]) == 10

Inductive Steps

For a list of one or more elements, the recursive property holds.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@given(
 st.lists(st.integers(), min_size=1),
 st.integers(),
)
def test_min_inductive_step(lst, elem):
 """
 Inductive Hypothesis: We assume `min(lst)` is correct.
 Inductive Step: `min` of a larger list is the min of the
 smaller list's min and the new element.
 """
 assert min(lst + [elem]) == min(min(lst), elem)

@given(
 st.lists(st.integers(), min_size=1),
 st.integers(),
)
def test_max_inductive_step(lst, elem):
 """
 Inductive Hypothesis: We assume `max(lst)` is correct.
 Inductive Step: `max` of a larger list is the max of the
 smaller list's max and the new element.
 """
 assert max(lst + [elem]) == max(max(lst), elem)

@given(
 st.lists(st.integers(), min_size=1),
 st.integers(),
)
def test_min_inductive_step(lst, elem):
 """
 Inductive Hypothesis: We assume `min(lst)` is correct.
 Inductive Step: `min` of a larger list is the min of the
 smaller list's min and the new element.
 """
 assert min(lst + [elem]) == min(min(lst), elem)

@given(
 st.lists(st.integers(), min_size=1),
 st.integers(),
)
def test_max_inductive_step(lst, elem):
 """
 Inductive Hypothesis: We assume `max(lst)` is correct.
 Inductive Step: `max` of a larger list is the max of the
 smaller list's max and the new element.
 """
 assert max(lst + [elem]) == max(max(lst), elem)

Example 5: collections.Counter

This final example introduces a more complex data structure. A Counter object aggregates counts, and its inductive step involves what looks like a stateful update.

1

from collections import Counter

from collections import Counter

Base Case

The simplest case is a counter from an empty sequence.

1
2
3


def test_counter_base_case():
 """Base Case: A Counter from an empty list is empty."""
 assert Counter([]) == Counter()

def test_counter_base_case():
 """Base Case: A Counter from an empty list is empty."""
 assert Counter([]) == Counter()

Inductive Step

We verify that creating a Counter from a list is equivalent to creating one from a smaller list and then updating it with the final element.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


@given(
 st.lists(st.text(min_size=1)),
 st.text(min_size=1),
)
def test_counter_inductive_step(items, item):
 """
 Inductive Hypothesis: `Counter(items)` is correct.
 Inductive Step: The counter of a new list is equivalent to the
 counter of the old list updated with the new item.
 """
 partial_counter = Counter(items)
 partial_counter[item] += 1
 
 assert Counter(items + [item]) == partial_counter

@given(
 st.lists(st.text(min_size=1)),
 st.text(min_size=1),
)
def test_counter_inductive_step(items, item):
 """
 Inductive Hypothesis: `Counter(items)` is correct.
 Inductive Step: The counter of a new list is equivalent to the
 counter of the old list updated with the new item.
 """
 partial_counter = Counter(items)
 partial_counter[item] += 1
 
 assert Counter(items + [item]) == partial_counter

The “Aha!” Moment: Connecting the Dots

Let’s explicitly map the formal concepts of induction to the tests we just wrote.

Mathematical Concept	How It Appears in Our Tests
Base Case	The test___base_case() functions. They test the simplest meaningful input ($P(0)$), establishing a “ground truth” to build upon.
Inductive Hypothesis	The assumption that the function works for a smaller input ($P(k)$). In test_sum_inductive_step, the call sum(lst) embodies this.
Inductive Step	The assert statement in the test___inductive_step() function. It verifies that the structural rule ($P(k) \implies P(k+1)$) holds.

The most profound shift here is moving from testing outputs to testing relationships. A traditional test asserts factorial(5) == 120. An inductive test asserts factorial(5) == 5 * factorial(4), which is a far more powerful statement about the function’s internal logic. It verifies the algorithm itself.

Let’s summarize how this pattern applies to each function we’ve tested:

Function Tested	Base Case ($P(0)$)	Inductive Step ($P(k) \implies P(k+1)$)
`sum()`	The sum of an empty list is 0.	`sum(list + [item]) == sum(list) + item`.
`pow(x, y)`	A number to the power of 0 is 1.	`pow(x, y) == x * pow(x, y-1)`.
`str.join()`	Joining zero or one item works correctly.	Joining `n` items is equivalent to joining `n-1` items, then adding the separator and the last item.
`min()`	The min of two elements is the smaller one.	`min(list + [item]) == min(min(list), item)`.
`max()`	The max of two elements is the larger one.	`max(list + [item]) == max(max(list), item)`.
`collections.Counter`	A Counter of an empty sequence is empty.	The Counter of a list is a Counter of its sublist, updated with the last element.

From Theory to the Trenches: A Remark on Practicality

It is worth noting where these powerful ideas originate. The testing method—property-based testing—was popularized by the QuickCheck library from the functional programming language Haskell. The proof structure—induction—comes from pure mathematics.

However, these techniques are not confined to the functional paradigm or mathematical theory. Their true power is revealed when applied to everyday, non-mathematical, and even non-functional code.

Imagine you have written a highly optimized sorting or aggregation function in Rust, Cython, or C++. You can expose that function to Python via bindings and then test its correctness using this beautifully succinct style. This creates a powerful separation of concerns:

Low-Level Code: Worries about performance, memory, and raw computation.
High-Level Test: Worries exclusively about correctness in a declarative, readable way.

This approach minimizes the number of manual test cases you need to write while maximizing logical coverage of your algorithm. It is a testament to how abstract concepts from mathematics and computer science can become potent, practical tools in the hands of any programmer.

Conclusion

Property-based testing is already a huge leap forward from example-based testing. By adding the mental model of mathematical induction, you can take it a step further. This approach encourages you to identify the core recursive properties and invariants of your code, leading to tests that are more robust, more expressive, and far better at catching subtle logical flaws.

Next time you are working with a function that builds up a result incrementally or recursively, don’t just test random inputs. Separate the base case from the inductive step, and test the very rule that makes your function work.

Annex: Unleashing the Full Power of Property-Based Testing

The examples in the main article use hardcoded values in their base cases to keep the focus on the inductive structure. While excellent for teaching, a core principle of property-based testing is to eliminate “magic values” and test properties over a wide range of inputs. This annex shows how to convert our hardcoded tests into more powerful, generalized property-based tests.

Generalizing pow()’s Base Case

Instead of testing pow(2, 0), we can assert that pow(x, 0) is 1 for any integer x.

1
2
3
4


@given(st.integers())
def test_pow_base_case_generalized(x):
 """Base Case: Any number to the power of 0 is 1."""
 assert pow(x, 0) == 1

@given(st.integers())
def test_pow_base_case_generalized(x):
 """Base Case: Any number to the power of 0 is 1."""
 assert pow(x, 0) == 1

Generalizing str.join()

We can use pytest.parametrize for the simple base cases and also randomize the separator in the inductive step to make it more robust.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


import pytest

@pytest.mark.parametrize("lst, expected", [
 ([], ""),
 (["a"], "a"),
])
def test_join_base_cases_parametrized(lst, expected):
 """Base Cases: Test joining with zero and one element."""
 assert ",".join(lst) == expected

@given(
 st.text(),
 st.lists(st.text(), min_size=1),
 st.text(),
)
def test_join_inductive_step_generalized(separator, lst, elem):
 """Inductive Step: Test with any separator."""
 assert separator.join(lst + [elem]) == separator.join(lst) + separator + elem

import pytest

@pytest.mark.parametrize("lst, expected", [
 ([], ""),
 (["a"], "a"),
])
def test_join_base_cases_parametrized(lst, expected):
 """Base Cases: Test joining with zero and one element."""
 assert ",".join(lst) == expected

@given(
 st.text(),
 st.lists(st.text(), min_size=1),
 st.text(),
)
def test_join_inductive_step_generalized(separator, lst, elem):
 """Inductive Step: Test with any separator."""
 assert separator.join(lst + [elem]) == separator.join(lst) + separator + elem

Generalizing min() and max() Base Cases

Instead of a single example like [10, 5], we can generate any two integers and check the property.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@given(st.integers(), st.integers())
def test_min_base_case_generalized(a, b):
 """Base Case: For any two elements, min() returns the smaller one."""
 expected = a if a <= b else b
 assert min([a, b]) == expected

@given(st.integers(), st.integers())
def test_max_base_case_generalized(a, b):
 """Base Case: For any two elements, max() returns the larger one."""
 expected = a if a >= b else b
 assert max([a, b]) == expected

@given(st.integers(), st.integers())
def test_min_base_case_generalized(a, b):
 """Base Case: For any two elements, min() returns the smaller one."""
 expected = a if a <= b else b
 assert min([a, b]) == expected

@given(st.integers(), st.integers())
def test_max_base_case_generalized(a, b):
 """Base Case: For any two elements, max() returns the larger one."""
 expected = a if a >= b else b
 assert max([a, b]) == expected

A Note on Fixed Base Cases

For functions like sum() and Counter, the base case is a single, fixed identity element (0 and an empty Counter, respectively). In these scenarios, the hardcoded base case is already the most general and correct form, so no change is needed. This demonstrates that the goal is not to eliminate all hardcoding, but to replace arbitrary examples with generalized properties wherever possible.