Python and pandas offer another approach: represent the project as structured data, align every financial event to a timeline, and calculate the resulting cash flows programmatically.

In this tutorial, we'll build a simple monthly cash flow engine for a real estate development project. It will distribute construction costs across a project timeline, record sales receipts in their expected months, calculate net and cumulative cash flow, and estimate the project's peak funding requirement.

The example is intentionally focused on the data model and calculation logic. It does not attempt to implement a complete development appraisal, financing model, or investment-return engine.

1. Define the project assumptions

Assume a development project has a construction budget of $1.2 million and a 12-month construction program. Costs are incurred at different rates throughout the project rather than being distributed evenly.

The project is also expected to receive three sales payments during the timeline:

The construction allocations add up to 100% of the budget. The expected sales receipts total $1.55 million.

These are illustrative assumptions, not market estimates. For this first version, we'll exclude land acquisition, taxes, financing costs, operating expenses, and other cash flows. Those items can be added as separate components later.

The objective is to convert these assumptions into a monthly schedule that the application can calculate and inspect consistently.

2. Set up the Python environment

Install pandas if it is not already available:

python -m pip install pandas

Create a Python file named cash_flow_engine.py.

We'll use pandas to manage the timeline and combine the construction and sales schedules. Python's standard library will handle input validation and numerical checks.

from math import isclose

import pandas as pd

Using a date-based index is preferable to relying on labels such as Month 1, Month 2, and Month 3. Actual month-start dates make it easier to combine schedules, filter periods, and eventually connect the model to other time-based data.

3. Generate the project timeline

The first component creates the monthly periods for the development.

def create_timeline(start_month, periods):
    if periods <= 0:
        raise ValueError("periods must be positive")

    start = pd.Timestamp(start_month)

    # Normalize the start date to the first day of its month.
    start = start.to_period("M").to_timestamp()

    return pd.date_range(
        start=start,
        periods=periods,
        freq="MS",
    )

The MS frequency represents month start. If the supplied start date is February 15, for example, the timeline begins on February 1.

Normalizing dates at the beginning prevents mismatches when one schedule uses the first day of a month and another uses a date later in the same month.

For this project, the timeline is generated as follows:

timeline = create_timeline(
    start_month="2027-01-01",
    periods=12,
)

print(timeline)

The result is a sequence of 12 monthly timestamps, from January through December 2027.

This function does not decide when construction or sales occur. It only defines the periods into which the model will place those events.

4. Allocate construction costs across the timeline

Construction expenditure rarely follows a perfectly uniform pattern. Early periods may involve site preparation and foundations, while later periods may include structural work, finishes, and final completion activities.

Rather than hard-coding a cost for every month, we'll represent the construction schedule using allocation weights.

def build_construction_schedule(
    timeline,
    construction_budget,
    monthly_weights,
):
    if construction_budget < 0:
        raise ValueError(
            "construction_budget cannot be negative"
        )

    if len(timeline) != len(monthly_weights):
        raise ValueError(
            "Each timeline period needs one cost weight"
        )

    if not monthly_weights:
        raise ValueError(
            "monthly_weights cannot be empty"
        )

    if any(
        not isinstance(weight, (int, float))
        or not pd.notna(weight)
        or weight < 0
        for weight in monthly_weights
    ):
        raise ValueError(
            "Cost weights must be finite, non-negative numbers"
        )

    if not isclose(
        sum(monthly_weights),
        1.0,
        rel_tol=1e-9,
        abs_tol=1e-9,
    ):
        raise ValueError(
            "Monthly cost weights must add up to 1"
        )

    return pd.DataFrame(
        {
            "month": timeline,
            "construction_cost": [
                construction_budget * weight
                for weight in monthly_weights
            ],
        }
    )

The validation matters because an incorrect allocation can silently change the total construction budget represented in the model. If the weights add up to 95%, the schedule will allocate only 95% of the intended budget. If they add up to 110%, it will allocate too much.

We can now define the project's construction assumptions:

construction_budget = 1_200_000

monthly_weights = [
    0.05,
    0.05,
    0.07,
    0.08,
    0.10,
    0.12,
    0.12,
    0.10,
    0.10,
    0.08,
    0.07,
    0.06,
]

timeline = create_timeline(
    start_month="2027-01-01",
    periods=12,
)

construction = build_construction_schedule(
    timeline,
    construction_budget,
    monthly_weights,
)

print(construction)

Each weight is multiplied by the total construction budget. A 5% allocation therefore represents $60,000, while a 12% allocation represents $144,000.

The output is a table containing one row per month and a positive construction-cost amount. We'll treat costs as positive values in the component schedule and subtract them when calculating net cash flow.

This convention makes individual components easier to read. The sign convention for the combined cash flow will be applied in one place rather than being mixed into every input.

5. Represent sales receipts as dated events

Sales receipts have a different structure from construction costs. A construction schedule may allocate costs across every month, while sales revenue may arrive in only a few periods.

We can represent receipts as a sequence of dated events and aggregate them by month.

def build_sales_schedule(timeline, sales_receipts):
    if any(
        not isinstance(amount, (int, float))
        or not pd.notna(amount)
        or amount < 0
        for amount in sales_receipts.values()
    ):
        raise ValueError(
            "Sales receipts must be finite, non-negative numbers"
        )

    sales = pd.DataFrame(
        [
            {
                "month": pd.Timestamp(date)
                .to_period("M")
                .to_timestamp(),
                "sales_revenue": amount,
            }
            for date, amount in sales_receipts.items()
        ],
        columns=["month", "sales_revenue"],
    )

    if sales.empty:
        return pd.DataFrame(
            {
                "month": timeline,
                "sales_revenue": 0.0,
            }
        )

    valid_months = set(timeline)

    if not sales["month"].isin(valid_months).all():
        raise ValueError(
            "Every sales receipt must fall within the timeline"
        )

    sales = (
        sales.groupby("month", as_index=False)["sales_revenue"]
        .sum()
    )

    return pd.DataFrame(
        {"month": timeline}
    ).merge(
        sales,
        on="month",
        how="left",
    ).fillna(
        {"sales_revenue": 0.0}
    )

This function allows the input dates to fall on any day of a month. Each date is normalized to the first day of its month before being matched to the timeline.

For example, a receipt dated September 18 is assigned to September. This is a monthly modeling convention, not a claim that the money is received on September 1.

Let's define the sales assumptions:

sales_receipts = {
    "2027-09-18": 450_000,
    "2027-11-12": 500_000,
    "2027-12-20": 600_000,
}

sales = build_sales_schedule(
    timeline,
    sales_receipts,
)

print(sales)

The resulting schedule contains all 12 months. Months without receipts receive a value of zero, which means the construction and sales schedules can be combined without losing periods.

6. Combine the schedules into one cash flow model

We now have two independent components:

• A construction schedule containing monthly expenditure.
• A sales schedule containing monthly receipts.

The next step is to combine them into a single project timeline.

def build_project_cash_flow(construction, sales):
    cash_flow = construction.merge(
        sales,
        on="month",
        how="outer",
        validate="one_to_one",
    )

    cash_flow = cash_flow.fillna(
        {
            "construction_cost": 0.0,
            "sales_revenue": 0.0,
        }
    )

    cash_flow = cash_flow.sort_values(
        "month"
    ).reset_index(drop=True)

    cash_flow["net_cash_flow"] = (
        cash_flow["sales_revenue"]
        - cash_flow["construction_cost"]
    )

    cash_flow["cumulative_cash_flow"] = (
        cash_flow["net_cash_flow"].cumsum()
    )

    return cash_flow

The validate="one_to_one" argument checks that each input contains no more than one row for a given month. This helps detect duplicate monthly records rather than allowing an accidental many-to-many merge to multiply rows.

The net cash flow formula is:

[ \text{Net Cash Flow}_t

\text{Sales Revenue}_t

\text{Construction Cost}_t ]

Cumulative cash flow is the running total of net cash flow through the current period:

[ \text{Cumulative Cash Flow}_t

\sum_{i=0}^{t}\text{Net Cash Flow}_i ]

Let's create the complete schedule:

project_cash_flow = build_project_cash_flow(
    construction,
    sales,
)

print(
    project_cash_flow[
        [
            "month",
            "construction_cost",
            "sales_revenue",
            "net_cash_flow",
            "cumulative_cash_flow",
        ]
    ].to_string(index=False)
)

The result brings the cost and revenue assumptions together. Each row represents one month, and every calculated amount can be traced back to the component schedules.

This is an important architectural separation. The construction-cost logic does not need to know how sales receipts are generated, and the sales schedule does not need to calculate cumulative project cash flow.

Each component has one responsibility, while the combined model handles the relationship between them.

7. Calculate the peak funding requirement

A project can have positive total cash flow over its entire timeline and still require substantial funding before receipts arrive.

For example, construction expenditure may accumulate for several months before the first major sales payment. Looking only at the final project balance would hide that interim cash requirement.

A simple estimate of peak funding need can be derived from the lowest cumulative cash flow:

[ \text{Peak Funding Need}

\max\left(0,-\min_t(\text{Cumulative Cash Flow}_t)\right) ]

We can implement this as a separate function:

def calculate_peak_funding_need(project_cash_flow):
    if project_cash_flow.empty:
        raise ValueError(
            "project_cash_flow cannot be empty"
        )

    lowest_balance = (
        project_cash_flow["cumulative_cash_flow"].min()
    )

    return max(0.0, -lowest_balance)

Now calculate the result:

peak_funding = calculate_peak_funding_need(
    project_cash_flow
)

print(f"Peak funding need: ${peak_funding:,.2f}")

With the assumptions in this example, the cumulative cash flow reaches its lowest point in August, at negative $828,000. The estimated peak funding need is therefore $828,000.

This is a simplified project cash requirement, not a financing recommendation. The calculation excludes land costs, financing charges, taxes, working capital, and any other items that were not included in the input schedules. If those costs or receipts are relevant, they must be added before the result can represent the broader project.

It also assumes that the modeled receipts arrive as scheduled. Delayed collections could increase the actual funding requirement.

8. Add a basic consistency check

Before using the model in a larger application, we should verify that the generated schedule reconciles to the assumptions.

For this example, total construction expenditure should equal the original construction budget, total sales receipts should equal the sum of the input receipts, and the final cumulative cash flow should equal total receipts less total construction costs.

assert isclose(
    project_cash_flow["construction_cost"].sum(),
    construction_budget,
    rel_tol=1e-9,
    abs_tol=1e-6,
)

assert isclose(
    project_cash_flow["sales_revenue"].sum(),
    sum(sales_receipts.values()),
    rel_tol=1e-9,
    abs_tol=1e-6,
)

expected_final_cash_flow = (
    sum(sales_receipts.values())
    - construction_budget
)

assert isclose(
    project_cash_flow["cumulative_cash_flow"].iloc[-1],
    expected_final_cash_flow,
    rel_tol=1e-9,
    abs_tol=1e-6,
)

print("Cash flow schedule reconciles to the input assumptions.")

The assertions check the relationship between the input data and the generated output. They do not prove that the assumptions are economically realistic, but they help detect common implementation errors such as missing periods, incorrect allocations, or duplicated amounts.

For a production system, these checks should be incorporated into automated tests rather than left as temporary statements in the execution script.

9. Understand what this model does not calculate

A monthly cash flow engine is a foundation for financial analysis, but it is not a complete feasibility model.

The current implementation assumes that construction expenditure is represented by monthly allocation weights and that sales receipts occur in specified months. It does not generate construction schedules from milestones, model individual unit sales, calculate installment collections, or forecast financing drawdowns.

It also does not calculate NPV or IRR. Those metrics require additional assumptions about discount rates, timing conventions, and the cash flow definition being evaluated.

One important extension would be to distinguish the date of a sale from the date cash is collected. A unit might be contracted in one month, generate installment payments in later months, and produce a final receipt at handover. Modeling these events separately would make the revenue schedule more useful for projects with staged collections.

Another extension would be to add financing as its own component. The model could then represent debt drawdowns, interest, principal repayments, and equity contributions as separate cash flow events instead of mixing them into construction expenditure.

These additions should build on the same structure: separate assumptions, transform them into dated schedules, combine the schedules, and validate the resulting cash flows.

Conclusion

Python and pandas make it possible to represent a development project's financial timeline as structured, reproducible data. By separating construction expenditure from sales receipts, combining the schedules by month, and calculating cumulative cash flow, we have built a small cash flow engine that can be extended without putting every rule into one large function.

The most useful part of this approach is not the final number. It is the structure behind the calculation. Each input schedule has a defined purpose, each transformation can be inspected, and the final output can be reconciled to the original assumptions.

From here, the same architecture can support more detailed construction schedules, staged sales collections, financing events, scenario analysis, and investment-return calculations. Each addition introduces new modeling requirements, but the underlying principle remains the same: keep the assumptions explicit, the transformations traceable, and the calculations reproducible.

These problems are particularly important in applications that generate financial projections. A small error in a calculation can propagate through reports, dashboards, scenario comparisons, and downstream decisions.

The usual response is to write unit tests for a few known inputs and outputs. That is a useful starting point, but financial software benefits from a broader testing strategy: test known results, verify mathematical properties, exercise edge cases, and check whether the output satisfies the assumptions of the calculation.

This tutorial uses Python and pytest to build a testing strategy for a net present value (NPV) function. The same approach can be applied to loan calculators, investment tools, pricing engines, accounting systems, and other applications that depend on numerical calculations.

1. Start with a Small Financial Function

Consider an NPV function that accepts a sequence of equally spaced cash flows. The first value represents the cash flow at period zero, so the initial investment is included in the sequence rather than supplied separately.

For cash flows (CF_0, CF_1, \ldots, CF_n), NPV is defined as:

[ NPV(r)=\sum_{t=0}^{n}\frac{CF_t}{(1+r)^t} ]

The implementation is straightforward:

def npv(cash_flows, discount_rate):
    """Calculate NPV for equally spaced cash flows."""
    if not cash_flows:
        raise ValueError("cash_flows cannot be empty")

    if discount_rate <= -1:
        raise ValueError(
            "discount_rate must be greater than -1"
        )

    total = 0.0

    for period, cash_flow in enumerate(cash_flows):
        total += (
            cash_flow / (1 + discount_rate) ** period
        )

    return total

This function has a deliberately narrow contract. It expects equally spaced cash flows and a discount rate greater than -100%. It does not handle irregular dates, currency conversion, or project-specific assumptions.

Keeping that contract explicit makes testing easier because each test can focus on a clearly defined behavior.

Save the function in financial_metrics.py. The following examples assume that the tests are stored separately in test_financial_metrics.py.

2. Test Known Results First

The first layer of testing checks whether the function produces the expected result for inputs that can be calculated independently.

At a zero discount rate, every cash flow retains its original value. Therefore, NPV equals the sum of all cash flows.

from financial_metrics import npv


def test_npv_with_zero_discount_rate():
    cash_flows = [-100, 60, 60]

    assert npv(cash_flows, 0) == 20

A second test uses a cash flow sequence with a known break-even rate.

An initial investment of 100 followed by a receipt of 110 after one period has an NPV of zero at a 10% discount rate.

def test_npv_at_break_even_rate():
    cash_flows = [-100, 110]

    result = npv(cash_flows, 0.10)

    assert abs(result) < 1e-10

Using a tolerance is important when comparing floating-point calculations. Decimal values such as 0.1 cannot always be represented exactly in binary floating-point arithmetic, so an exact equality comparison can fail even when the numerical result is effectively correct.

The tolerance should reflect the scale and requirements of the calculation. A very small tolerance may be appropriate for a simple calculation with small inputs, but larger financial models may require scale-aware comparisons.

3. Test Mathematical Invariants

Known examples test specific cases. Invariants test relationships that should remain true across many valid inputs.

This is a powerful technique because it checks the mathematical behavior of a function without requiring a manually calculated expected answer for every input.

Invariant 1: Scaling cash flows scales NPV

If every cash flow is multiplied by a constant (k), the resulting NPV should also be multiplied by (k), provided the discount rate remains unchanged.

[ NPV(k \cdot CF,r)=k \cdot NPV(CF,r) ]

This follows directly from the linearity of the NPV formula.

A test can verify that relationship:

def test_npv_scales_with_cash_flows():
    cash_flows = [-1000, 300, 400, 500]
    scale = 3

    original = npv(cash_flows, 0.08)

    scaled = npv(
        [cash_flow * scale for cash_flow in cash_flows],
        0.08,
    )

    assert abs(scaled - original * scale) < 1e-8

This test would catch certain implementation errors that ordinary example-based tests might miss, such as accidentally applying a fixed adjustment to the final result.

Invariant 2: Adding a zero cash flow at the beginning shifts the schedule

Suppose a zero cash flow is inserted before the original sequence. Every original cash flow moves one period later, so each amount receives one additional period of discounting.

For a discount rate (r), the relationship is:

[ NPV([0,CF_0,\ldots,CF_n],r) =\frac{NPV([CF_0,\ldots,CF_n],r)}{1+r} ]

This provides another useful test:

def test_npv_when_schedule_is_shifted():
    cash_flows = [-1000, 400, 500, 600]
    rate = 0.10

    original = npv(cash_flows, rate)
    shifted = npv([0, *cash_flows], rate)

    expected = original / (1 + rate)

    assert abs(shifted - expected) < 1e-8

The test verifies that the implementation respects period positions rather than simply discounting each cash flow according to its value.

4. Test Invalid Inputs Explicitly

A reliable calculation function should define how it responds to invalid input. Silently accepting an invalid discount rate or an empty schedule can allow errors to propagate into other parts of an application.

The function already rejects empty cash flow sequences and discount rates at or below -100%. Those behaviors should be tested directly.

import pytest

from financial_metrics import npv


def test_npv_rejects_empty_cash_flows():
    with pytest.raises(ValueError):
        npv([], 0.10)


def test_npv_rejects_discount_rate_of_minus_one():
    with pytest.raises(ValueError):
        npv([-100, 110], -1)


def test_npv_rejects_discount_rate_below_minus_one():
    with pytest.raises(ValueError):
        npv([-100, 110], -1.1)

These tests document the function's input contract. If someone changes the implementation later, the tests help prevent accidental changes to its error-handling behavior.

There is also a distinction between validating the mathematical domain and validating the data type. The current implementation does not explicitly reject NaN, infinity, or non-numeric cash flows. A production implementation should decide how to handle those values and add tests for the chosen behavior.

For example, if the application requires all inputs to be finite numbers, that requirement should be enforced explicitly rather than left to incidental Python behavior.

5. Use Parameterized Tests for More Coverage

Several tests may differ only in their inputs. Pytest's parameterization feature lets developers express these cases without duplicating the test logic.

import pytest

from financial_metrics import npv


@pytest.mark.parametrize(
    "cash_flows, rate, expected",
    [
        ([-100, 110], 0.10, 0.0),
        ([-100, 50, 50], 0.0, 0.0),
        ([100, 0, 0], 0.10, 100.0),
        ([-100, 0, 121], 0.10, 0.0),
    ],
)
def test_npv_known_cases(cash_flows, rate, expected):
    result = npv(cash_flows, rate)

    assert abs(result - expected) < 1e-8

Each row describes a separate test case. The same assertion is executed against all four inputs.

The third case verifies that a cash flow at period zero is not discounted. The fourth checks that a receipt of 121 after two periods offsets an initial investment of 100 at a 10% rate.

Parameterization is especially useful when a calculation has many meaningful boundary cases. It keeps the test suite compact while making the coverage easier to inspect.

6. Add Property-Based Testing

When the number of possible inputs becomes large, manually selecting test cases is not enough. Property-based testing generates many inputs and verifies that defined properties hold for them.

The Hypothesis library can generate cash flow sequences and discount rates automatically.

Install the dependencies:

python -m pip install pytest hypothesis

The following example tests the scaling property across generated cash flow sequences and discount rates.

import pytest
from hypothesis import given, strategies as st

from financial_metrics import npv


@given(
    cash_flows=st.lists(
        st.floats(
            min_value=-1_000_000,
            max_value=1_000_000,
            allow_nan=False,
            allow_infinity=False,
        ),
        min_size=1,
        max_size=12,
    ),
    rate=st.floats(
        min_value=0,
        max_value=1,
        allow_nan=False,
        allow_infinity=False,
    ),
    scale=st.integers(min_value=1, max_value=10),
)
def test_npv_scaling_property(cash_flows, rate, scale):
    original = npv(cash_flows, rate)

    scaled_cash_flows = [
        cash_flow * scale
        for cash_flow in cash_flows
    ]

    scaled = npv(scaled_cash_flows, rate)

    assert scaled == pytest.approx(
        original * scale,
        rel=1e-9,
        abs=1e-7,
    )

Hypothesis generates different schedules, rates, and scaling factors. If it discovers a failing input, it attempts to reduce that input to a smaller example that still demonstrates the failure.

This can reveal defects that were not anticipated when the test suite was first written.

The example deliberately restricts discount rates to the range from zero to one and uses finite cash flows. Those bounds keep the generated cases focused on ordinary discounting behavior. Broader input ranges should be introduced only when the implementation is designed to support them.

7. Test IRR Against the Original Equation

Numerical solvers require a different kind of validation. A solver can return a rate, but the important question is whether that rate satisfies the equation it is supposed to solve.

For a conventional cash flow sequence with a unique IRR in the selected interval, the NPV evaluated at the calculated IRR should be close to zero.

Assuming an irr() function is available in financial_metrics.py, a test can verify that property:

from financial_metrics import npv, irr


def test_irr_produces_near_zero_npv():
    cash_flows = [-1000, 300, 400, 500]

    rate = irr(cash_flows)

    assert abs(npv(cash_flows, rate)) < 1e-5

The tolerance depends on the stopping criteria used by the solver and the magnitude of the cash flows. The threshold above is illustrative and should be adjusted to match the implementation's numerical guarantees.

This test is more general than checking whether IRR equals a hard-coded percentage. It verifies that the returned rate satisfies the defining equation.

However, it does not prove that the returned IRR is unique. Cash flow sequences with multiple sign changes can have multiple valid IRRs. Tests should account for that behavior rather than assuming every project has exactly one solution.

8. Run the Test Suite in a Repeatable Environment

A useful test suite should be easy to run locally and in continuous integration.

With the calculation module and test file in the same directory, execute:

python -m pytest -v

For a larger project, organize the tests by responsibility. Keep basic calculation tests separate from validation tests, numerical-solver tests, and integration tests that verify how the financial model assembles its cash flows.

It is also useful to run tests automatically whenever code changes. A continuous integration workflow can install the project's dependencies, run the test suite, and report failures before a change is merged.

The goal is not to test every possible number. It is to establish confidence that the implementation respects its mathematical contract, handles expected invalid inputs, and behaves consistently as the code evolves.

Conclusion

Testing financial calculations requires more than confirming that a few examples return the expected numbers. Known-result tests establish a baseline, mathematical invariants verify deeper relationships, parameterized tests expand coverage, and property-based tests explore a wider range of inputs.

For numerical solvers such as IRR, the result should also be checked against the original equation. This helps detect incorrect outputs even when the returned value looks reasonable.

These techniques are useful wherever software turns financial assumptions into calculated results. By making mathematical properties and input contracts executable as tests, developers can detect errors earlier and make financial calculation code easier to maintain.

A real estate development project makes the distinction particularly clear. Construction costs may occur over several years, revenue may arrive in stages, and the initial investment may be followed by additional capital requirements before the project generates positive cash flow. A useful implementation must preserve the timing and sign of each cash flow, handle invalid inputs, and make its assumptions explicit.

This tutorial implements NPV and IRR using Python's standard library. We will build a small cash flow model, calculate both metrics, test the results, and examine limitations that matter when these functions become part of a larger financial application.

1. Define the cash flow model

Suppose a development project requires an initial investment of $1,000,000. The project is expected to generate the following net cash flows over the next five years.

These figures are illustrative. They represent net project cash flows rather than gross property revenue. Depending on the model's purpose, cash flows might incorporate construction costs, operating expenses, sale proceeds, financing, taxes, or other project-specific items.

The negative initial cash flow represents capital invested at the beginning of the analysis. The positive amounts represent subsequent cash received by the investor.

We can represent the schedule as a Python list:

cash_flows = [
    -1_000_000,
    250_000,
    300_000,
    350_000,
    400_000,
    450_000,
]

Each position corresponds to a period. Index 0 represents the initial investment, index 1 represents the first year's cash flow, and so on.

This representation assumes equally spaced periods. It is suitable for a basic annual model, but it is not sufficient when cash flows occur on irregular dates. We will return to that distinction later.

2. Implement net present value

NPV measures the present value of future cash flows after accounting for the initial investment. It discounts each cash flow according to the required rate of return.

For equally spaced periods, the formula is:

[ NPV(r)=\sum_{t=0}^{n}\frac{CF_t}{(1+r)^t} ]

Here, (CF_t) is the cash flow at period (t), (r) is the discount rate per period, and (n) is the final period.

The discount rate reflects the return required for the investment or the rate used to evaluate its cash flows. It should be chosen consistently with the cash flow definition and the period length.

For example, if the model uses annual cash flows, the discount rate should also be annual.

Build the function

def npv(cash_flows, discount_rate):
    """Calculate NPV for equally spaced cash flows.

    The first cash flow occurs at period 0.
    """
    if not cash_flows:
        raise ValueError("cash_flows cannot be empty")

    if discount_rate <= -1:
        raise ValueError("discount_rate must be greater than -1")

    total = 0.0

    for period, cash_flow in enumerate(cash_flows):
        total += cash_flow / (1 + discount_rate) ** period

    return total

The function iterates through the cash flow schedule and discounts each amount according to its position. Because the first cash flow occurs at period zero, it is not discounted.

That detail is important. Some spreadsheet functions use a convention in which the initial investment is supplied separately from the sequence of future cash flows. Our Python function instead accepts the complete schedule, including the initial investment. Mixing these conventions can produce incorrect results.

We can calculate the project's NPV using a 10% annual discount rate:

cash_flows = [
    -1_000_000,
    250_000,
    300_000,
    350_000,
    400_000,
    450_000,
]

project_npv = npv(cash_flows, 0.10)

print(f"NPV: ${project_npv:,.2f}")

A positive NPV means the discounted value of the modeled cash flows exceeds the initial investment at the selected discount rate. A negative NPV means the modeled cash flows fall short of that threshold.

NPV is therefore conditional on the assumptions in the model. Changing the discount rate, development costs, sale values, or timing of receipts can change the result.

3. Implement internal rate of return

IRR is the discount rate at which NPV equals zero.

[ 0=\sum_{t=0}^{n}\frac{CF_t}{(1+IRR)^t} ]

Unlike NPV, IRR is not calculated by supplying a discount rate. The rate must be found by solving an equation.

For a general cash flow schedule, there may not be a convenient closed-form solution. A numerical method is often used instead.

We will implement the bisection method. It repeatedly narrows a range of possible rates until the NPV is sufficiently close to zero.

Why use bisection?

Bisection is straightforward to implement and does not require derivatives. It works when the chosen interval brackets a root and the NPV function is continuous over that interval.

For a conventional project with one initial outflow followed by positive inflows, this can be a practical approach. However, bisection does not automatically find every possible IRR. The interval must contain a root, and cash flows with multiple sign changes may have multiple IRRs.

Build the function

def irr(
    cash_flows,
    low=-0.9999,
    high=1.0,
    tolerance=1e-7,
    max_iterations=1_000,
):
    """Estimate IRR for equally spaced cash flows using bisection.

    The selected interval must bracket an IRR.
    """
    if len(cash_flows) < 2:
        raise ValueError("At least two cash flows are required")

    if not any(cf < 0 for cf in cash_flows):
        raise ValueError("Cash flows must include a negative value")

    if not any(cf > 0 for cf in cash_flows):
        raise ValueError("Cash flows must include a positive value")

    if low <= -1:
        raise ValueError("low must be greater than -1")

    if high <= low:
        raise ValueError("high must be greater than low")

    if tolerance <= 0:
        raise ValueError("tolerance must be positive")

    if max_iterations <= 0:
        raise ValueError("max_iterations must be positive")

    npv_low = npv(cash_flows, low)
    npv_high = npv(cash_flows, high)

    if npv_low == 0:
        return low

    if npv_high == 0:
        return high

    if npv_low * npv_high > 0:
        raise ValueError(
            "The interval does not bracket an IRR. "
            "Try a different low/high range."
        )

    for _ in range(max_iterations):
        midpoint = (low + high) / 2
        npv_midpoint = npv(cash_flows, midpoint)

        if abs(npv_midpoint) < tolerance:
            return midpoint

        if npv_low * npv_midpoint < 0:
            high = midpoint
            npv_high = npv_midpoint
        else:
            low = midpoint
            npv_low = npv_midpoint

        if high - low < tolerance:
            return (low + high) / 2

    raise RuntimeError("IRR calculation did not converge")

The lower bound must be greater than -1, because a discount rate of -100% makes the discounting denominator zero for periods after the initial period.

The upper bound is a search parameter, not a statement about the project's expected return. If the interval does not bracket a root, the function raises an error rather than silently returning an unreliable value.

The function also checks for both positive and negative cash flows. This is a basic validity check, not proof that a unique IRR exists.

4. Calculate NPV and IRR for the project

We can now calculate both metrics from the same cash flow schedule.

cash_flows = [
    -1_000_000,
    250_000,
    300_000,
    350_000,
    400_000,
    450_000,
]

discount_rate = 0.10

project_npv = npv(cash_flows, discount_rate)
project_irr = irr(cash_flows)

print(f"NPV at {discount_rate:.0%}: ${project_npv:,.2f}")
print(f"IRR: {project_irr:.2%}")

The NPV tells us how much value the modeled project creates or loses in present-value terms at the selected 10% discount rate. The IRR identifies the rate at which the modeled NPV is zero.

These measures answer different questions. NPV evaluates the cash flows against a specified return threshold, while IRR expresses the break-even discount rate implied by those cash flows.

Neither metric should be interpreted without examining the assumptions behind the schedule. In a development model, a delayed completion date, higher construction costs, lower sale proceeds, or slower collections can materially affect the results.

5. Test the implementation

Financial calculations should be tested independently of the user interface or the larger application. A function that produces a plausible number is not necessarily correct.

The following tests use Python's built-in unittest module. They cover a known NPV result, a simple IRR case, and invalid input conditions.

Save the calculation functions in a file named financial_metrics.py. Then create a file named test_financial_metrics.py with the following code:

import unittest

from financial_metrics import npv, irr


class TestFinancialMetrics(unittest.TestCase):

    def test_npv_with_zero_discount_rate(self):
        cash_flows = [-100, 60, 60]

        self.assertAlmostEqual(
            npv(cash_flows, 0),
            20.0,
        )

    def test_npv_discounting(self):
        cash_flows = [-100, 110]

        self.assertAlmostEqual(
            npv(cash_flows, 0.10),
            0.0,
            places=8,
        )

    def test_irr_simple_project(self):
        cash_flows = [-100, 110]

        self.assertAlmostEqual(
            irr(cash_flows),
            0.10,
            places=6,
        )

    def test_npv_rejects_empty_cash_flows(self):
        with self.assertRaises(ValueError):
            npv([], 0.10)

    def test_npv_rejects_invalid_discount_rate(self):
        with self.assertRaises(ValueError):
            npv([-100, 110], -1)

    def test_irr_rejects_missing_sign_change(self):
        with self.assertRaises(ValueError):
            irr([-100, -50])

    def test_irr_rejects_unbracketed_root(self):
        with self.assertRaises(ValueError):
            irr([-100, 110], low=0.20, high=0.50)


if __name__ == "__main__":
    unittest.main()

Run the tests from the directory containing both files:

python -m unittest -v

The tests verify that a zero discount rate returns the sum of the cash flows, that a 10% return makes the NPV of [-100, 110] equal to zero, and that invalid inputs raise errors.

The test suite should pass before the functions are integrated into a larger application. Additional tests are appropriate for extreme values, multiple sign changes, and the specific cash flow patterns supported by the model.

6. Understand the limitations of IRR

IRR is useful, but it has limitations that matter when implementing financial software.

Multiple IRRs

Consider a cash flow schedule that changes sign more than once:

cash_flows = [-100, 230, -132]

Its NPV equation can have more than one valid rate. In this case, the equation has roots at 10% and 20%.

A bisection function can return a root only when its chosen interval brackets one. It cannot establish that the root is unique, and different intervals can produce different answers.

For projects with irregular patterns of capital expenditure, operating cash flow, and later investment, a single IRR may not communicate the economics clearly. NPV at a justified discount rate is often easier to interpret alongside the full cash flow schedule.

No IRR

Some cash flow schedules have no IRR within the valid rate range. For example, cash flows that are all negative cannot produce an NPV of zero at a conventional finite discount rate greater than -100%.

The implementation rejects schedules without both positive and negative values, but that check is not sufficient to prove that a root exists. The interval check provides another safeguard.

Periodic cash flows versus dated cash flows

The functions in this tutorial assume equal intervals between cash flows. That is reasonable for a basic annual projection in which all amounts are assigned to year-end periods.

Real estate development cash flows can be more complicated. A construction payment may occur in March, a buyer installment may arrive in September, and a final sale receipt may be collected several months later. Treating these events as if they occurred at evenly spaced annual intervals can distort the results.

For actual-date calculations, use a dated cash flow model and a method designed for irregular timing, such as XIRR. A dated implementation must define its day-count convention and the treatment of the initial date explicitly.

7. Keep calculation logic separate from project assumptions

A financial model becomes easier to maintain when its calculation engine is separated from the data that describes the project.

The npv() and irr() functions above do not know whether a cash flow comes from land acquisition, construction, financing, rent, or a property sale. They operate only on the cash flow sequence.

A separate model layer can generate that sequence from project assumptions. For example, it could combine monthly construction costs, scheduled unit sales, collection percentages, operating expenses, and financing flows into a consolidated schedule. The calculation layer can then evaluate the resulting cash flows without duplicating project-specific rules.

This separation also makes testing more effective. You can test the cost schedule independently, test revenue collection logic separately, and verify that the final cash flow schedule produces the expected financial metrics.

For a larger application, it is useful to define a clear contract for the calculation functions: what the inputs represent, which periods they use, which cash flow conventions apply, and which errors are raised. That contract prevents different parts of the application from quietly using incompatible assumptions.

Conclusion

Implementing NPV and IRR in Python requires more than writing two formulas. The functions must handle period timing consistently, reject invalid inputs, expose numerical limitations, and be tested against known results.

For a real estate development model, these calculations are only as reliable as the cash flows supplied to them. Construction timing, revenue collection, project costs, and the chosen discount rate all influence the result. A well-structured calculation engine makes these relationships easier to test and maintain, but it cannot compensate for incorrect project assumptions.

The next step is to extend the example from a fixed list of cash flows into a project schedule that generates cash flows from dated construction costs, sales, collections, and financing events. That is where the calculation functions become part of a more complete financial modeling system.