Intermediate Python for Research

Python · Reliable building blocks · Section 1 of 2

Design functions with explicit contracts

A research function should state its inputs, output, units, and invalid cases. A type annotation such as list[float] documents intent and helps tools, but Python does not automatically enforce it at runtime. A docstring can explain conventions such as fractional returns and cost per traded dollar.

Keyword-only parameters follow * in a signature. They make calls such as net_return(0.02, turnover=0.5, cost=0.001) easier to review than a row of unexplained numbers. A pure calculation returns a result without changing external state or its input containers.

Avoid mutable default arguments such as history=[] because the default object is shared across calls. Use None and create a new container inside the function. Validate nonfinite or out-of-domain inputs deliberately instead of silently converting them into apparently valid output.

import math

def net_return(gross: float, *, turnover: float, cost: float) -> float:
    """Return gross minus traded-notional costs, in fractional units."""
    if not all(math.isfinite(x) for x in (gross, turnover, cost)):
        raise ValueError("inputs must be finite")
    if turnover < 0 or cost < 0:
        raise ValueError("turnover and cost must be nonnegative")
    return gross - turnover * cost

print(f"{net_return(0.02, turnover=0.5, cost=0.001):.4f}")

0.0195

Keep in mind: A small explicit function is easier to test and review than a hidden calculation.