💵 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
- 📦 Requirements and installation
- 🚀 Quick start
- 🧮 How the calculations work
- 🛠️ Calculator API reference
- 🖥️ Desktop GUI
- 📊 CPI data, coverage, and freshness
- 🗂️ Advanced usage and reproducible data
- 🩺 Errors and troubleshooting
- ⚠️ Interpretation and limitations
- 🕰️ Historical migration to quantsumore
- 👨💻 Development and contributions
- 📚 Project links and license
🔍 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.15requirement. 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_yearsshould be a positive integer. The calculation starts atcurrent_year - n_yearsand ends atcurrent_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=Truealso 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_valueuses 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.
📚 Project links and license
- 🧑💻 Source repository
- 📦 PyPI package
- 🐛 Issue tracker
- 🏷️ Releases
- 🤝 Contribution guide
- 🔐 Security policy
- ⚖️ MIT License, copyright DOYDL Technologies
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.