Skip to main content

Referential Transparency and Pure Functions: A Complete Guide

· 12 min read

1. Core Concepts: The Pillars of Functional Programming​

Visual Metaphor: Mathematical Functions​

┌─────────────────────────────────────────────────────────────┐
│ PURE FUNCTION vs IMPURE FUNCTION │
├─────────────────────────────────────────────────────────────┤
│ │
│ PURE FUNCTION (Mathematical) │
│ f(x) = x² + 3 │
│ │
│ Input: 5 → Always Output: 28 │
│ Input: 5 → Always Output: 28 │
│ Input: 5 → Always Output: 28 │
│ (1000 times later...) │
│ Input: 5 → Still Output: 28 │
│ │
│ IMPURE FUNCTION (Real World) │
│ get_time() │
│ │
│ Call 1: "10:30:15" │
│ Call 2: "10:30:16" │
│ Call 3: "10:30:17" │
│ (Same input, different outputs every time!) │
└─────────────────────────────────────────────────────────────┘

2. Pure Functions​

2.1 Definition​

A pure function is a function that:

  1. Always returns the same output for the same input
  2. Has no side effects (doesn't modify anything outside itself)

2.2 The Two Rules of Pure Functions​

Rule 1: Deterministic (Same Input → Same Output)​

# PURE
def add(a, b):
return a + b

print(add(2, 3)) # Always 5
print(add(2, 3)) # Always 5
print(add(2, 3)) # Always 5

# IMPURE
import random
def roll_dice():
return random.randint(1, 6)

print(roll_dice()) # Could be 3
print(roll_dice()) # Could be 5
print(roll_dice()) # Could be 1
# Same input (no parameters), different outputs!

Rule 2: No Side Effects​

# PURE (no side effects)
def square(x):
return x * x

# IMPURE (has side effects)
total = 0
def add_to_total(x):
global total # Modifies external state
total += x
return total

# IMPURE (modifies input)
def add_item(list_, item):
list_.append(item) # Modifies input argument
return list_

2.3 Pure Function Characteristics​

# Characteristics of pure functions:

# 1. They only depend on their inputs
def pure_multiply(a, b):
return a * b # Only uses inputs

# 2. They don't modify anything outside
def impure_print_and_add(a, b):
print(f"Adding {a} and {b}") # Side effect: prints to console
return a + b

# 3. They don't rely on external state
external_state = 10

def pure_add(a, b):
return a + b # Doesn't use external_state

def impure_add(a):
return a + external_state # Depends on external state

# 4. They don't perform I/O operations
def pure_calculate(a, b):
return (a + b) * (a - b)

def impure_read_file():
with open('data.txt') as f: # I/O operation
return f.read()

2.4 Real Examples: Pure vs Impure​

# ---------- PURE EXAMPLES ----------
# Mathematical operations
def calculate_tax(income, rate):
return income * rate

# String transformations
def format_name(first, last):
return f"{last.upper()}, {first.capitalize()}"

# Data transformations
def process_data(data):
return [x * 2 for x in data if x > 0]

# ---------- IMPURE EXAMPLES ----------
# File operations
def read_config():
with open('config.json') as f: # I/O
return json.load(f)

# Database operations
def save_user(user):
database.insert(user) # Modifies external state

# Random operations
def generate_id():
return uuid.uuid4() # Non-deterministic

# Time-dependent operations
def get_current_time():
return datetime.now() # Different each time

# Modifying global state
counter = 0
def increment_counter():
global counter
counter += 1
return counter

3. Referential Transparency​

3.1 Definition​

Referential Transparency is a property of expressions (not just functions) where you can replace an expression with its value without changing the program's behavior.

3.2 Simple Explanation​

If you have an expression E that evaluates to value V, you can replace E with V anywhere in your code, and the program will behave exactly the same.

3.3 Visual Metaphor: Algebraic Substitution​

┌─────────────────────────────────────────────────────────────┐
│ REFERENTIAL TRANSPARENCY DEMO │
├─────────────────────────────────────────────────────────────┤
│ │
│ Expression: 2 + 3 │
│ Value: 5 │
│ │
│ Program A: │
│ x = (2 + 3) * 4 │
│ Result: 5 * 4 = 20 │
│ │
│ Program B: │
│ x = 5 * 4 ← Replaced (2+3) with 5 │
│ Result: 20 │
│ │
│ Programs A and B are EQUIVALENT! │
│ The expression (2+3) is referentially transparent. │
└─────────────────────────────────────────────────────────────┘

3.4 Python Examples​

# REFERENTIALLY TRANSPARENT EXPRESSIONS

# Example 1: Simple arithmetic
result = (2 + 3) * 4
# Can replace (2 + 3) with 5:
result = 5 * 4 # Same result!

# Example 2: Pure function calls
def add(a, b):
return a + b

x = add(2, 3) * 4
# Can replace add(2, 3) with 5:
x = 5 * 4 # Same result!

# Example 3: Complex but pure expression
def calculate_discounted_price(price, discount):
return price * (1 - discount)

total = calculate_discounted_price(100, 0.1) + 20
# Can replace calculate_discounted_price(100, 0.1) with 90:
total = 90 + 20 # Same result!

# NOT REFERENTIALLY TRANSPARENT
import random

def get_random_number():
return random.randint(1, 100)

x = get_random_number() * 2
# CANNOT replace get_random_number() with a value!
# Because it returns different values each time

3.5 Test for Referential Transparency​

The Substitution Test: Can you replace the function call with its result without changing the program's behavior?

# Test Case 1: Pure Function (PASSES)
def square(x):
return x * x

# Original
result1 = square(5) + 10
# After substitution (square(5) → 25)
result2 = 25 + 10
print(result1 == result2) # True - Referentially Transparent!

# Test Case 2: Impure Function (FAILS)
count = 0
def increment():
global count
count += 1
return count

# Original
value1 = increment() + increment()
print(f"Original: {value1}, count: {count}")

# Reset
count = 0

# Try substitution (WRONG!)
# increment() returns 1 first time, 2 second time
# But we can't know this without executing!
value2 = 1 + 2 # This assumes both calls return same value!
print(f"Substituted: {value2}, count: {count}")
# Different results! Not Referentially Transparent!

4. Relationship Between Pure Functions and Referential Transparency​

4.1 The Connection​

┌─────────────────────────────────────────────────────────────┐
│ THE RELATIONSHIP: PURE → REFERENTIALLY TRANSPARENT │
├─────────────────────────────────────────────────────────────┤
│ │
│ Pure Function │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 1. Same input → Same output │ │
│ │ 2. No side effects │ │
│ └─────────────────────────────────────────────────────┘ │
│ ⇓ guarantees │
│ │
│ Referentially Transparent Expression │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Can replace expression with its value │ │
│ │ without changing program behavior │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ All pure functions are referentially transparent! │
│ But not all referentially transparent expressions are │
│ functions (e.g., 2 + 3 is RT but not a function). │
└─────────────────────────────────────────────────────────────┘

4.2 Pure Function ⇒ Referentially Transparent​

# Pure function → Referentially transparent
def multiply(a, b):
return a * b

# In this expression:
result = multiply(3, 4) + 5
# We can safely replace multiply(3, 4) with 12:
result = 12 + 5 # Same result!

# Proof:
print(multiply(3, 4) + 5) # 17
print(12 + 5) # 17

4.3 Referentially Transparent ≠ Pure Function​

# Constants are referentially transparent but not functions
PI = 3.14159
# PI is referentially transparent (can replace with 3.14159)
# But it's not a function

# Literal values are referentially transparent
x = 42 # 42 is referentially transparent
# But 42 is not a function

5. Benefits and Advantages​

5.1 Benefits of Pure Functions & Referential Transparency​

1. Predictability​

# Pure: Always know what you get
def calculate_area(radius):
return 3.14159 * radius * radius

# Can trust this completely
area = calculate_area(5) # Always ~78.53975

# Impure: Unexpected results possible
def get_user_input():
return input("Enter value: ") # Who knows what user will enter?

2. Testability​

# Pure functions are easy to test
def add(a, b):
return a + b

# Simple test
assert add(2, 3) == 5
assert add(-1, 1) == 0
assert add(0, 0) == 0

# Impure functions are hard to test
def save_to_database(data):
# How to test without actual database?
# Need mocks, fixtures, setup/teardown
database.save(data)

3. Parallelization & Concurrency​

# Pure: Safe to run in parallel
def process_chunk(data):
return [x * 2 for x in data]

# Can process chunks independently
chunk1 = [1, 2, 3]
chunk2 = [4, 5, 6]

import concurrent.futures
with concurrent.futures.ThreadPoolExecutor() as executor:
future1 = executor.submit(process_chunk, chunk1)
future2 = executor.submit(process_chunk, chunk2)
# No race conditions!

# Impure: Dangerous in parallel
counter = 0
def increment():
global counter
counter += 1 # Race condition in parallel!

4. Caching & Memoization​

# Pure functions can be cached
from functools import lru_cache

@lru_cache(maxsize=None)
def fibonacci(n):
if n < 2:
return n
return fibonacci(n-1) + fibonacci(n-2)

# First call computes
print(fibonacci(30)) # Computes
# Second call uses cache (same input → same output)
print(fibonacci(30)) # Instantly from cache!

# Impure functions can't be cached
def get_current_stock_price(symbol):
# Different every minute!
return api.get_price(symbol)

5. Reasoning & Refactoring​

# With pure functions, you can reason locally
def calculate_total(items, tax_rate):
subtotal = sum(item['price'] for item in items)
tax = subtotal * tax_rate
return subtotal + tax

# Easy to understand: depends ONLY on inputs
# Easy to refactor: won't break other code

# With impure functions, need to consider global state
def process_order(order_id):
order = database.get_order(order_id) # What's in DB?
inventory.update(order.items) # Affects other orders
log_activity(order) # Side effect
send_email(order.customer) # Side effect
# Hard to reason about all effects!

5.2 The "Functional Core, Imperative Shell" Pattern​

# IMPURE SHELL (handles I/O, side effects)
def process_user_registration(user_data):
# 1. Validate input (pure)
errors = validate_user_data(user_data)
if errors:
return {"success": False, "errors": errors}

# 2. Process data (pure)
user = create_user_object(user_data)
hashed_password = hash_password(user.password)

# 3. Save to database (impure)
user_id = database.save_user(user, hashed_password)

# 4. Send notification (impure)
send_welcome_email(user.email)

return {"success": True, "user_id": user_id}

# PURE CORE (easy to test, reason about)
def validate_user_data(data):
errors = []
if len(data.get('username', '')) < 3:
errors.append("Username too short")
if '@' not in data.get('email', ''):
errors.append("Invalid email")
return errors

def create_user_object(data):
return {
'username': data['username'].strip(),
'email': data['email'].lower(),
'password': data['password']
}

def hash_password(password):
import hashlib
return hashlib.sha256(password.encode()).hexdigest()

6. Your Tax Calculation Example Analysis​

Let's analyze the code you provided:

def _process_operation(
acc: tuple[PortfolioState, list[TaxResult]],
operation: Operation
) -> tuple[PortfolioState, list[TaxResult]]:
"""
Process a single operation and return updated state and results.

This is a PURE FUNCTION used by calculate_taxes for functional composition
with reduce().
"""
state, results = acc

match operation.operation:
case "buy":
new_state = state.buy(operation.quantity, operation.unit_cost)
new_results = results + [TaxResult(tax=Decimal("0"))]
return new_state, new_results
case "sell":
new_state, tax = state.sell(
operation.quantity,
operation.unit_cost,
TAX_EXEMPT_THRESHOLD
)
new_results = results + [TaxResult(tax=tax)]
return new_state, new_results

def calculate_taxes(operations: list[Operation]) -> list[TaxResult]:
"""
Calculate capital gains taxes for a sequence of stock operations.

This is a PURE FUNCTION - given the same list of operations, it always
returns the same tax results with no side effects.
"""
initial_state = (PortfolioState(), [])
_, results = reduce(_process_operation, operations, initial_state)
return results

Why This is Pure and Referentially Transparent:​

1. No Side Effects:​

  • Doesn't modify global state
  • Doesn't perform I/O (no printing, file operations, network calls)
  • Doesn't mutate input parameters (creates new objects)

2. Deterministic:​

  • Same operations input → Same TaxResult output
  • Depends only on inputs
  • No randomness or external state

3. Referentially Transparent:​

# Given:
operations = [Operation("buy", 100, Decimal("50"))]

# This expression:
results = calculate_taxes(operations)

# Can be replaced with its value (if we know what it computes to)
# For example, if we know calculate_taxes returns [TaxResult(tax=Decimal("0"))]
# We could write:
results = [TaxResult(tax=Decimal("0"))]

# The program behavior would be the same!

4. Immutable Data Flow:​

# Note how it creates NEW objects instead of modifying:
new_results = results + [TaxResult(tax=tax)] # New list
return new_state, new_results # New tuple

# Not modifying: results.append(TaxResult(tax=tax)) # This would be impure!

7. Practical Examples: Converting Impure to Pure​

Example 1: Making a Function Pure​

# IMPURE VERSION
user_database = [] # Global state

def add_user_impure(name, email):
"""Impure: Modifies global state"""
user = {"name": name, "email": email, "id": len(user_database)}
user_database.append(user) # Side effect!
return user

# PURE VERSION
def add_user_pure(users, name, email):
"""Pure: Returns new state instead of modifying"""
new_user = {"name": name, "email": email, "id": len(users)}
new_users = users + [new_user] # Create new list
return new_users, new_user # Return new state

# Usage comparison
users = []
# Impure
user1 = add_user_impure("Alice", "alice@example.com")
print(user_database) # Modified!

# Pure
users, user1 = add_user_pure(users, "Alice", "alice@example.com")
print(users) # New list with user

Example 2: Separating I/O from Logic​

# MIXED (Impure)
def process_order_impure(order_data):
# Business logic mixed with I/O
total = sum(item['price'] for item in order_data['items'])

if total > 1000:
discount = total * 0.1
else:
discount = 0

# I/O operations (impure)
save_to_database(order_data)
send_receipt_email(order_data['email'], total - discount)

return total - discount

# PURE CORE + IMPURE SHELL
def calculate_order_total(items):
"""Pure: Business logic only"""
total = sum(item['price'] for item in items)
discount = total * 0.1 if total > 1000 else 0
return total - discount

def process_order_pure(order_data):
"""Impure shell: Handles I/O"""
# Pure calculation
final_total = calculate_order_total(order_data['items'])

# Impure operations
save_to_database(order_data)
send_receipt_email(order_data['email'], final_total)

return final_total

8. Testing Pure vs Impure Functions​

Testing Pure Functions (Easy)​

import pytest

def test_pure_function():
# Pure functions are deterministic
assert add(2, 3) == 5
assert add(0, 0) == 0
assert add(-5, 10) == 5

# No setup/teardown needed
# No mocks needed
# Can run in any order
# Fast (no I/O)

# Property-based testing
from hypothesis import given, strategies as st

@given(st.integers(), st.integers())
def test_add_commutative(a, b):
assert add(a, b) == add(b, a) # Always true for pure add

Testing Impure Functions (Hard)​

def test_impure_function():
# Need to setup state
global counter
counter = 0

# Test
assert increment() == 1
assert increment() == 2 # Depends on previous call!

# Need to cleanup
counter = 0

# May need mocks for I/O
with patch('database.save') as mock_save:
save_user({"name": "Alice"})
mock_save.assert_called_once()

9. Common Pitfalls and Misconceptions​

Pitfall 1: Not All "Mathematical" Functions are Pure​

# Looks pure but isn't!
import time

def get_timestamp():
return int(time.time()) # Different each call!

def random_id():
return id(object()) # Different each call!

Pitfall 2: Hidden Side Effects​

# Subtle side effect
def process_data(data):
data.sort() # MODIFIES INPUT! Side effect!
return sum(data)

# Better (pure)
def process_data_pure(data):
sorted_data = sorted(data) # Creates new list
return sum(sorted_data)

Pitfall 3: Depending on Mutable Defaults​

# IMPURE (shared mutable default)
def add_to_list(item, lst=[]): # Default list is shared!
lst.append(item) # Modifies default
return lst

print(add_to_list(1)) # [1]
print(add_to_list(2)) # [1, 2] - Oops!

# PURE
def add_to_list_pure(item, lst=None):
if lst is None:
lst = [] # New list each time
return lst + [item] # New list

10. When Impure is Necessary (and OK!)​

Necessary Impure Operations:​

# 1. I/O Operations
def read_file(path):
with open(path) as f:
return f.read()

def call_api(url):
import requests
return requests.get(url).json()

# 2. Randomness
def generate_token():
import secrets
return secrets.token_hex(16)

# 3. System Interactions
def get_env_variable(name):
import os
return os.getenv(name)

# 4. Time
def log_with_timestamp(message):
from datetime import datetime
print(f"[{datetime.now()}] {message}")

Strategy: Isolate Impurity​

# Keep impure code at boundaries
def application():
# 1. Read input (impure)
user_input = input("Enter data: ")

# 2. Process (pure)
result = process_data(user_input)

# 3. Output (impure)
print(f"Result: {result}")
save_to_file(result)

return result

# Now you can test the pure part easily
def test_process_data():
assert process_data("test") == expected_value

11. Summary​

Pure Functions:​

  • ✅ Same input → Same output (deterministic)
  • ✅ No side effects (doesn't modify external state)
  • ✅ Easy to test, reason about, parallelize
  • ✅ Cacheable (memoization)
  • ❌ Cannot do I/O, randomness, or depend on time

Referential Transparency:​

  • ✅ Expression can be replaced with its value
  • ✅ Enables equational reasoning
  • ✅ All pure functions are referentially transparent
  • ✅ But not all RT expressions are functions

Key Takeaways:​

  1. Pure functions are the building blocks of reliable, testable code

  2. Referential transparency enables substitution and mathematical reasoning

  3. Your tax calculation example is pure because:

    • It only depends on inputs
    • Creates new data instead of modifying
    • No I/O or side effects
    • Same operations → Same results always
  4. In practice: Aim for pure core logic with impure I/O at boundaries

  5. Benefits: Better testing, debugging, concurrency, and reasoning

The functional programming approach in your tax calculation (reduce with pure functions) ensures correctness and maintainability by leveraging these principles!