FI

FI is a Python library of functions for the financial independence (FI, FIRE) community. Functions can be run as standalone utilities on the command line or used in Python code. The FI library powers the auto-generated site FI Widgets, a GUI representation of the library. It powers FI MCP and FI API. It's also used in MMM Savings Rate.

Installation

This package is pip installable. To get the newest code use one of the commands below. FI requires python3. Use pip to install it if you're installing into a Virtualenv otherwise install with pip3. If you're a developer and you wish to contribute, see the installation instructions in the Developers section.

pip install git+https://github.com/bbusenius/FI.git#egg=FI

or

pip3 install -e git+https://github.com/bbusenius/FI.git#egg=FI

Pass the -e flag to retain the editable source.

Using

The following functions are packaged in this library:

• annual_cost
• average_daily_spend
• buy_a_day_of_freedom
• cap_rate
• coast_fi
• cost_of_costs
• cost_per_use
• days_covered_by_fi
• expected_gross_return
• fi_age
• fi_number
• future_value
• get_percentage
• hours_of_life_energy
• likely_real_return
• monthly_investment_income
• monthly_payment
• net_operating_income
• opportunity_cost
• percent_decrease
• percent_increase
• percent_return_for_percent
• pot_score
• price_to_rent
• real_hourly_wage
• redeem_points
• redeem_chase_points
• remaining_life_expectancy
• rule_of_72
• savings_rate
• spending_from_savings
• stock_returns
• take_home_pay
• total_interest
• turnover_costs

All functions can be run from the command-line or used in Python directly.

Full API

Running from the command-line

List available functions:

FI --help

To see how to run a function from the command-line, just open a terminal and invoke the command with --help options, e.g.:

coast_fi -h or coast_fi --help

This will display instructions on how to run the command.

Running the coast_fi command might look something like this:

coast_fi 800000 .07 62 40

Other functions are run in a similar way. Use -h or --help to see all the options.

Advanced use from the command-line

By using variables and backticks, commands can be combined to produce more robust output. The following example shows how to calculate savings rate from money saved rather than money spent.

THP="$(take_home_pay 5215.71 417.27 514.09)"
savings_rate "${THP}" `spending_from_savings "${THP}" 2600`

Another useful example might be to calculate CoastFI using your "retire today" number, a projected inflation rate and a future value calculation.

coast_fi `future_value 800000 .03 1 22` .07 62 40

Developers

FI is written with type hints and relies on the built in typing module. This allows FI to be used more robustly in third party applications. Docstrings are considered forward facing since they are sometimes exposed to the public as on FI Widgets.

Docstring Format

FI uses markdown-formatted docstrings to serve two audiences:

1. End users viewing documentation on FI Widgets (rendered as HTML)
2. Developers using Python's help() function (displayed as plain text)

Format Requirements

All function docstrings must follow this format:

def function_name(param1: float, param2: float) -> Money:
    """Brief description of what the function does.
    Credit: [Source Title](https://example.com) (if applicable)

    ### Args:
    - **param1**: description of the first parameter.
    - **param2**: description of the second parameter.

    ### Returns:
    Return description.
    """

Style Guidelines

• Headers: Use ### Args: and ### Returns: (h3 headers with colons)
• Parameters: Use list format: - **param_name**: (dash, space, bold name, colon outside bold)
• Links: Use [Link Text](https://url) for all URLs
• Indentation: Use base indentation (4 spaces) for all docstring content for Python readability
• Citations: Include book/article links when crediting sources
• Lists: Parameters render as bulleted lists (<ul> with <li> tags) on the website

Why Markdown?

• Clean rendering: Markdown converts to semantic HTML for the website (proper lists, headers, links)
• Readable as text: Still looks good in terminal help() output
• Standard format: Widely recognized by developers
• Consistent: One format serves multiple contexts (web, CLI, docs, MCP tools)
• Simple processing: Parsed with inspect.cleandoc() + markdown.markdown() - no complex transformations

The docstrings are parsed by FI-API using Python's markdown library and displayed on FI Widgets. This approach provides rich formatting on the web while maintaining readability for developers.

Installation for developers

To install for development run the following command from the root of the cloned directory:

pip3 install -e .

Run unit tests

python -m unittest tests.test_fi

Documentation

Documentation is automatically generated from docstrings using Sphinx.

cd docs/
sphinx-apidoc -o source/ ../fi
make html