Skip to main content

Dollarwave — powered by DOYDL Technologies

💵 Dollarwave: U.S. CPI Inflation Adjustment

Calculate the equivalent purchasing power of a U.S. dollar amount across years, explore historical and monthly CPI comparisons, and use a desktop inflation calculator.

🧭 Contents

🔍 What Dollarwave does

Dollarwave uses Consumer Price Index data to express an amount from one year in another year's dollars. Typical uses include putting historical prices into a common year's dollars and comparing the purchasing power of amounts recorded at different times.

Feature Entry point Result
💵 Adjust between two years inflation_calculator(amount, original_year, target_year) Amount calculated from annual average CPI
🔄 Call the same operation by name inflation_calculator.adjusted_value(...) Same calculation and result
📈 Compare a current-year amount with preceding years inflation_calculator.comparison(amount, n_years, plot=False) Dictionary keyed by historical year
📅 Compare available months within the current year inflation_calculator.current_year_change(amount, plot=False) Dictionary keyed by month name
🖥️ Open the desktop calculator GUI.run() Tkinter application with three tabs
💾 Work with your own CPI table CPIDataTool and InflationCalculator Calculator backed by a supplied pandas DataFrame

Imports do not download CPI data or construct the GUI in this release. The default calculator downloads data when first used, then reuses its loaded dataset.

📦 Requirements and installation

📋 Requirements

  • 🐍 Python 3.8 through 3.14, as declared by this release's >=3.8,<3.15 requirement. An older interpreter may also need older dependency versions that still support it.
  • 📦 pip for installation.
  • 🌐 Internet access for the default calculator's initial CPI download. No API key is required.
  • 🖥️ Tkinter/Tcl/Tk and a graphical desktop to launch the GUI.
  • 📈 A working Matplotlib display backend to show plots with plot=True.

The package declares pandas, requests, matplotlib, and pillow as dependencies. pip installs compatible dependencies automatically. Tkinter is supplied by the Python installation or operating system rather than this package's pip dependencies.

1️⃣ Create an isolated environment

python -m venv .venv

Activate it using the command for your environment:

Environment Activation command
Windows, MSYS2 UCRT64 with a standard Windows Python environment source .venv/Scripts/activate
Linux or macOS, bash/zsh source .venv/bin/activate

The activation path depends on the Python distribution that created the environment. Use python -m pip so installation targets that interpreter.

2️⃣ Install a published package

python -m pip install --upgrade pip
python -m pip install dollarwave

🔎 Check the installed version before following this release's examples:

python -c "import dollarwave; print(dollarwave.__version__)"

This README describes 2.0.7. A package index may offer an earlier release with different import behavior, dependencies, or error handling. If 2.0.7 is unavailable from your index, install this source release instead of assuming the published package matches it.

3️⃣ Install this source release

From the directory containing this README and pyproject.toml:

python -m pip install .

If you received a built 2.0.7 wheel, install that file from its containing directory:

python -m pip install ./dollarwave-2.0.7-py3-none-any.whl

For an editable development installation, see Development and contributions.

🚀 Quick start

💵 Adjust a historical amount

from dollarwave import inflation_calculator

adjusted_amount = inflation_calculator(
    amount=1,
    original_year=1970,
    target_year=2024,
)

# The calculator prints its own explanation and also returns the value.
print(f"Returned amount: ${adjusted_amount:.2f}")

With annual average CPI values of 38.8 for 1970 and 313.689 for 2024:

$1 from 1970 is equivalent to $8.08 in 2024 dollars.
Returned amount: $8.08

These are the annual values in the source CPI table. Results depend on the loaded dataset. The older README's $8.04 example does not match this annual-average calculation.

🔄 Adjust in the opposite direction

from dollarwave import inflation_calculator

# Express a 2024 amount in 1970 dollars.
historical_amount = inflation_calculator(100, 2024, 1970)
print(f"1970 purchasing-power equivalent: ${historical_amount:.2f}")

Both directions are supported. The two years must be distinct and present in the dataset.

🛡️ Handle a failed calculation

import math

from dollarwave import CPIDataError, inflation_calculator

try:
    adjusted_amount = inflation_calculator(100, 2000, 2024)
    if adjusted_amount is None or not math.isfinite(adjusted_amount):
        raise ValueError("The CPI data did not produce a finite result.")
except CPIDataError as exc:
    print(f"CPI data could not be loaded: {exc}")
except (ValueError, KeyError, TypeError) as exc:
    print(f"Check the amount, years, and available CPI values: {exc}")
else:
    print(f"Adjusted amount: ${adjusted_amount:.2f}")

CPIDataError covers the default loader's download and table-validation failures. Invalid inputs or missing table entries may produce other exceptions, as described in Errors and troubleshooting.

🧮 How the calculations work

📐 Annual CPI adjustment formula

For an amount expressed in the original year's dollars:

adjusted amount = original amount × (target-year average CPI / original-year average CPI)

For example, if one year's CPI is 100 and another year's CPI is 150, an amount of $100 in the first year corresponds to $150 in the second. Reversing the years gives approximately $66.67 for an original amount of $100.

Dollarwave's annual adjustment uses the table's Avg column. If that value is missing, the data tool calculates an average from the available monthly entries. An incomplete year's average can therefore change as additional months become available.

The result is a built-in Python float, rounded to two decimal places using Python's round. Calculations use floating-point arithmetic. Format with :.2f for a two-decimal display.

The BLS CPI FAQ explains CPI concepts and the difference between annual-average and particular-month comparisons. Choose the same time basis when checking results against another calculator.

🛠️ Calculator API reference

Import the shared, lazily loaded calculator:

from dollarwave import inflation_calculator

💰 inflation_calculator(amount, original_year, target_year)

Equivalent to:

inflation_calculator.adjusted_value(amount, original_year, target_year)
Parameter Recommended input Meaning
amount Finite int or float Dollar amount in the original year's purchasing power
original_year Four-digit integer Year in which the amount is expressed
target_year Four-digit integer Year whose dollars you want to use

Returns: the rounded adjusted amount. Side effect: prints a sentence explaining the adjustment.

Year strings such as "2000" can also work because the data tool stores year labels as strings. Prefer integers; do not pass fractional years or date objects. Equal years raise ValueError, including when the amount is zero.

Amounts must be finite numeric values; booleans, strings, NaN, and infinities raise ValueError. Years must be integers or integer strings. Missing years raise ValueError, and unusable CPI values raise CPIDataError. A zero amount produces zero when the years and CPI values are valid; negative amounts follow the same arithmetic.

📈 inflation_calculator.comparison(amount, n_years, plot=False)

Return historical purchasing-power equivalents of an amount expressed in current-year dollars.

from dollarwave import inflation_calculator

historical_values = inflation_calculator.comparison(
    amount=100,
    n_years=5,
    plot=False,
)

for year, value in historical_values.items():
    print(f"$100 in current-year dollars corresponds to ${value:.2f} in {year} dollars.")
  • n_years should be a positive integer. The calculation starts at current_year - n_years and ends at current_year - 1; the current year is excluded from the returned dictionary.
  • The current year comes from the machine's local clock when the data tool is constructed.
  • Every requested year, including the current-year baseline, must have usable data. This method does not automatically substitute the latest available year.
  • plot=True also calls Matplotlib to display a chart.

The actual calculation for each historical year is:

historical equivalent = amount × (historical-year average CPI / current-year average CPI)

The printed sentences and chart labels describe current-year dollars converted to each historical year's dollars. To convert a historical amount forward instead, call adjusted_value(amount, historical_year, current_year).

📅 inflation_calculator.current_year_change(amount, plot=False)

Compare each available monthly CPI value with the same year's average CPI:

from dollarwave import inflation_calculator

monthly_values = inflation_calculator.current_year_change(100, plot=False)

for month, value in monthly_values.items():
    print(f"{month}: ${value:.2f}")

Returns: a dictionary such as {"January": ..., "February": ...}, with one rounded amount for each available month. Missing monthly values are skipped. Unlike the annual adjustment and historical comparison, this method does not print results itself when plot=False.

monthly amount = amount × (monthly CPI / current-year average CPI)

Despite the method's name, its values are dollar amounts relative to an annual-average baseline. They are not monthly percentage inflation rates, year-over-year rates, or a January-to-latest-month cumulative change. For an incomplete year, the baseline may be an average of only the available months.

Set plot=True to display the returned monthly values in a Matplotlib chart. The current-year row must be present in the dataset.

🔎 Availability and loaded data

from dollarwave import inflation_calculator

# This property attempts to load CPI data; it is not an offline status check.
if inflation_calculator.is_available:
    tool = inflation_calculator.cpi_data_tool
    print(f"Available CPI years: {tool.min}–{tool.max}")
    print(tool.df.tail())
else:
    print("The CPI download or table validation failed.")

For the default calculator, is_available returns False when loading raises CPIDataError. It does not establish that every CPI cell or requested operation is valid. Accessing cpi_data_tool also triggers loading if necessary.

🖥️ Desktop GUI

from dollarwave import GUI

GUI.run()

Run this in a local Python session with desktop access. GUI.run() opens the application and runs Tk's event loop until the window closes. Importing GUI alone does not open a window or import the GUI implementation.

Tab Inputs Operation
💵 Adjusted Value Dollar amount, original year, target year Annual-average adjustment between two years
📅 Current Year Change Dollar amount Available monthly amounts relative to the current year's average CPI
📊 Dollar Comparison Dollar amount, number of years Historical equivalents of a current-year amount

Enter plain numbers, such as 1000.50, 1970, and 2024. Currency symbols and thousands separators are not accepted by the GUI's direct numeric conversion. Click Calculate in the selected tab. Switching tabs clears the other tabs' inputs and results.

The monthly and historical result panes scroll so longer comparisons and all available months remain accessible at the minimum window size.

The GUI uses the same shared calculator and data-loading behavior as the Python API. Its calculation callbacks display errors in dialogs. The historical-comparison interpretation described above also applies to the Dollar Comparison tab.

To check whether your interpreter can open Tkinter:

python -m tkinter

If that fails, add Tcl/Tk support for the same Python distribution you use to run Dollarwave. A standard Windows CPython installation and MSYS2's UCRT64 Python are separate installations; installing Tk for one does not configure the other. A remote or headless environment can use the calculation API with plot=False without opening the GUI.

📊 CPI data, coverage, and freshness

🌐 Source and coverage

The default loader downloads an HTML table from US Inflation Calculator's historical CPI page. The provider identifies it as CPI-U data published by the U.S. Bureau of Labor Statistics and supplies monthly values and annual averages beginning in 1913. The 1913-to-2008 text in the URL is historical; it does not define the table's current end year.

Dollarwave retrieves the third-party page; it does not call the BLS API. Actual coverage is determined by the successfully loaded table. Inspect cpi_data_tool.min, cpi_data_tool.max, and the relevant rows before choosing a comparison period.

✅ What the loader checks

The HTML parser requires the following column names:

Year, Jan, Feb, Mar, Apr, May, June, July, Aug, Sep, Oct, Nov, Dec, Avg

It requires annual data rows and rejects a table whose latest year is earlier than the previous local calendar year. The data tool then converts non-year cells to numeric values, converts unparseable values to NaN, fills missing annual averages from available months, and indexes the table by year strings.

These checks establish table structure and basic freshness. The data tool rejects missing required columns, duplicate or invalid years, and zero, negative, or infinite CPI values. Missing monthly values are allowed, and missing annual averages are calculated from available months. Calculations reject missing requested years and unusable CPI values. These checks do not verify the source's numbers against BLS or require all months to exist.

🔁 Download and reuse behavior

  • The default request uses a Requests session with a timeout value of 20 seconds. This is not a guarantee of a 20-second total wall-clock limit.
  • Successful loading is reused by the shared calculator in the running process. Subsequent calculations do not automatically re-download the table.
  • There is no built-in persistent disk cache, scheduled refresh, or bundled offline CPI history.
  • A failed initialization is not stored as a successful calculator; a later call can attempt loading again. There is no explicit application-level retry loop.
  • The current year is captured when the data tool is created. For a long-running process crossing a year boundary, create a fresh calculator to update both the clock-based baseline and the dataset.

The freshness check can accept a table ending in the previous year. Annual adjustments between available historical years can still work, while the two methods requiring the current year can fail until that year's row is published.

🗂️ Advanced usage and reproducible data

The following classes are imported from dollarwave.calculate; they are lower-level tools rather than replacements for the simple public API.

🔬 Show advanced data workflows and offline examples

💾 Inspect and save the loaded table

from dollarwave import inflation_calculator

tool = inflation_calculator.cpi_data_tool  # Downloads on first access.

print(tool.get_value(2024, "Avg"))
print(tool.get_value(2024, "January"))  # Full English month name or table abbreviation.

# Export the prepared table, restoring Year as a regular column.
snapshot = tool.df.reset_index()
snapshot.to_csv("cpi_snapshot.csv", index=False)

The prepared DataFrame has year strings as its index, monthly CPI columns, and Avg. Saving it preserves the values used at that point, including any annual averages calculated from incomplete monthly data. Record the source URL, retrieval date, package version, and whether the chosen year was complete alongside your snapshot.

Treat the shared tool.df as read-only unless you intentionally want to change later calculations. To experiment, use tool.df.copy(deep=True) and a separate calculator.

📂 Calculate from a saved table without downloading

import pandas as pd

from dollarwave.calculate import CPIDataTool, InflationCalculator

frame = pd.read_csv("cpi_snapshot.csv", dtype={"Year": str})
calculator = InflationCalculator(CPIDataTool(frame))

result = calculator(100, 2000, 2024)

This path bypasses the HTML parser and its freshness check. You are responsible for the table's provenance and validity. Supply one row per year, a Year column, all 12 monthly columns with the exact spellings above, and an Avg column. Use numeric CPI values or missing values; ensure the CPI values needed by your operation are finite and positive. A complete Avg value is sufficient for annual adjustment even if monthly cells are missing.

🧪 Fully offline demonstration with illustrative data

This example uses synthetic CPI values to demonstrate the formula. It makes no network request and does not represent actual U.S. inflation:

import pandas as pd

from dollarwave.calculate import CPIDataTool, InflationCalculator

months = [
    "Jan", "Feb", "Mar", "Apr", "May", "June",
    "July", "Aug", "Sep", "Oct", "Nov", "Dec",
]
rows = []
for year, average in [(2000, 100.0), (2020, 150.0)]:
    row = {"Year": str(year), "Avg": average}
    row.update({month: average for month in months})
    rows.append(row)

calculator = InflationCalculator(CPIDataTool(pd.DataFrame(rows)))
result = calculator(100, 2000, 2020)
assert result == 150.0

Output:

$100 from 2000 is equivalent to $150.00 in 2020 dollars.

⚙️ Customize loading and timeout

from dollarwave.calculate import CPIDataTool, CPIHTMLTableParser, InflationCalculator

parser = CPIHTMLTableParser(timeout=30)
frame = parser.fetch_data()
calculator = InflationCalculator(CPIDataTool(frame))

result = calculator(100, 2000, 2024)

CPIHTMLTableParser(url=..., timeout=..., session=...) also accepts a custom URL and a Requests-compatible session. A replacement page must retain the expected table structure. parse_data(html) parses a supplied HTML string and applies the same structural and freshness checks without making a request itself. fetch_data() reuses its parsed DataFrame after successful loading.

🩺 Errors and troubleshooting

Symptom Explanation and next step
ModuleNotFoundError: dollarwave Install into the interpreter running your script with python -m pip. Confirm the environment is activated.
Installed behavior differs from this README Check dollarwave.__version__ and dollarwave.__file__. This guide targets 2.0.7; an older distribution or a local file named dollarwave.py can resolve differently.
CPIDataError: Unable to download CPI data. The request failed, including HTTP errors, connectivity problems, certificate errors, or a timeout. Check access to the source page and the underlying exception available through exc.__cause__.
CPI header, rows, or required columns not found The provider may have changed the HTML, or an intermediary returned a different page. Inspect the response rather than treating it as valid CPI data.
Downloaded table is reported as stale The newest year is older than the previous local calendar year. Check the machine's date and source table. A saved table can be loaded explicitly when reproducing an older dataset.
ValueError about equal years Use different years. If your application's desired same-year result is the unchanged amount, handle that case before calling Dollarwave.
ValueError about the available range Choose years within the loaded table's coverage. Future-year projections are not supported.
ValueError about unavailable years or an unknown column A required row or column is absent. A year can fall between the minimum and maximum yet still be missing. Current-year operations require the actual current-year row.
ValueError about an amount, year, or comparison range Pass a finite numeric amount, integer years, and a positive integer n_years. Convert form input before calling the API.
CPIDataError about CPI values The requested data is missing or contains zero, negative, or infinite CPI values. Inspect the source table or saved dataset.
A calculation returns None A lower-level calculator constructed with the legacy Fail object prints an unavailable message and returns None. Default download failures raise CPIDataError instead.
Tkinter import, Tcl/Tk, or display error Verify python -m tkinter using the same interpreter. Install matching Tcl/Tk support and run with desktop access.
A chart does not appear or waits until closed Check the Matplotlib backend and display availability. plot=True calls plt.show(), which may block depending on the backend. Use plot=False to obtain data without a chart.

When reporting a reproducible issue, include the Dollarwave version, Python version, operating system, minimal code, complete exception traceback, affected years, and whether you used live or saved CPI data. Avoid including private environment details or credentials.

⚠️ Interpretation and limitations

  • 🧺 CPI scope: CPI describes changes in a representative consumer basket. A person's expenses or a particular product's price may move differently. See the BLS explanation of CPI coverage.
  • 💵 U.S. dollar purchasing power: the default source is U.S. CPI. The package does not convert currencies or select country-specific, regional, or expenditure-category indexes.
  • 📅 Annual versus monthly basis: adjusted_value uses annual averages. The public adjustment call does not accept a month argument. A calculator using a particular month can legitimately return a different result.
  • ⏳ Incomplete years: an average calculated from available months is not a completed full-year average. New data can change results involving that year.
  • 🔢 Numerical precision: results are rounded floating-point values. Reversing a rounded conversion may not recover the starting amount exactly. The package does not provide decimal-accounting arithmetic.
  • 🔍 Source validation: the library checks structure and numeric validity; applications should still verify the provenance and suitability of source data.
  • 🕰️ Historical data only: the package does not forecast inflation, calculate investment returns, include interest or taxes, or model individual spending patterns.
  • 🌐 External availability: the default workflow depends on a third-party HTML page and its format. Saving a verified dataset is the documented way to reproduce a calculation without that live dependency.

🕰️ Historical migration to quantsumore

Earlier versions of this README recommended quantsumore as Dollarwave's successor. Its retirement policy now states that it is retired and unsupported. These notes are retained for understanding existing code; they do not establish current compatibility or endpoint availability.

🕰️ Show archived migration notes (not a current recommendation)
Dollarwave code Historical quantsumore counterpart
from dollarwave import inflation_calculator from quantsumore.api import cpi
inflation_calculator(amount, original_year, target_year) cpi.CPI_U.InflationAdjustment.select(amount, original_year, target_year)
from dollarwave import GUI from quantsumore.gui import GUI
GUI.run() GUI.run()

The historical CPI call was:

from quantsumore.api import cpi

adjusted_amount = cpi.CPI_U.InflationAdjustment.select(
    original_amount=100,
    original_year=2000,
    target_year=2024,
)

The published quantsumore documentation includes a month_input parameter. Do not assume the two libraries use the same month or annual-average basis, return identical results, or have matching error behavior. For an existing migration, compare against a known dataset, record the exact package versions, and validate the requested workflow independently. Dollarwave and quantsumore remain separate installations and imports.

👨‍💻 Development and contributions

The contribution guide welcomes focused bug fixes, compatibility updates, documentation improvements, and data-source maintenance for existing Dollarwave users. Broad API redesigns are outside that policy. It applies to Dollarwave; it is not a contribution guide for quantsumore.

To obtain a checkout using SSH:

git clone git@github.com:doydl-technologies/dollarwave.git
cd dollarwave

The default branch may differ from this 2.0.7 source snapshot. From the checkout or supplied release directory you intend to work on:

python -m venv .venv
# Windows/MSYS2 with standard Windows Python; see the installation table for other environments.
source .venv/Scripts/activate
python -m pip install --upgrade pip
python -m pip install -e ".[test]"
python -m pytest -q

The test extra installs the build and test tools. Existing tests use generated HTML and in-memory CPI data so their results do not depend on a live website. They cover public imports, lazy loading, table parsing, annual calculations, monthly results, and legacy failure behavior. Automated tests do not establish that the live source or every GUI behavior works on every platform.

Before opening a pull request, also verify the source and wheel distributions as requested by the contribution guide:

python -m build
python -m twine check dist/*

For suspected vulnerabilities, follow SECURITY.md and use the repository's private vulnerability-reporting feature rather than a public issue.

The MIT License covers Dollarwave's software. Consult the data provider's terms separately when obtaining, using, or redistributing CPI data.

Metadata

Release files for dollarwave 2.0.7

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dollarwave 2.0.7
File Size Uploaded Provenance Actions
dollarwave-2.0.7.tar.gz 431.1 kB Without provenance Details for dollarwave-2.0.7.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dollarwave 2.0.7
File Interpreter ABI Platform Actions
dollarwave-2.0.7-py3-none-any.whl Python 3 none any Details for dollarwave-2.0.7-py3-none-any.whl

Total release size: 845.9 kB

Release files / dollarwave-2.0.7.tar.gz

Download URL dollarwave-2.0.7.tar.gz
Size 431.1 kB
Tags Source
SHA-256 checksum
How to use checksums
a2946bfa448aae2214f7ebe719872233c723e37eae50c248a95c70ec447f0c01
BLAKE2b-256 checksum
How to use checksums
71ff2f1f2c5381d38118cc5133363ba6cb65c73f7fae0e46c6c85f3d538b11b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / dollarwave-2.0.7-py3-none-any.whl

Download URL dollarwave-2.0.7-py3-none-any.whl
Size 414.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7e6c9c77d562e6f10b2664328af5b42584facf85d67dd0e2efbdb53fe921d759
BLAKE2b-256 checksum
How to use checksums
eebd2f55db0001651b3e6d0d4f7d16acdd569d959f87c27ebba8d2962d90a2da
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for dollarwave 2.0.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page