Metadata-Version: 2.4
Name: dollarwave
Version: 2.0.7
Summary: Retired U.S. CPI inflation adjustment library with a desktop calculator, preserved for legacy use.
Author: DOYDL Technologies
License: MIT
Project-URL: Homepage, https://github.com/doydl-technologies/dollarwave
Project-URL: Documentation, https://github.com/doydl-technologies/dollarwave#readme
Project-URL: Issues, https://github.com/doydl-technologies/dollarwave/issues
Project-URL: Releases, https://github.com/doydl-technologies/dollarwave/releases
Project-URL: Source, https://github.com/doydl-technologies/dollarwave
Keywords: cpi,economics,inflation,finance,retired,deprecated
Classifier: Development Status :: 7 - Inactive
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: pillow
Requires-Dist: requests
Provides-Extra: test
Requires-Dist: build; extra == "test"
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: twine; extra == "test"
Dynamic: license-file

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/doydl-technologies/dollarwave/v2.0.7/assets/png/dollarwave-endorsed-lockup-v03-stacked-light-733x533-384dpi.png">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/doydl-technologies/dollarwave/v2.0.7/assets/png/dollarwave-endorsed-lockup-v03-stacked-dark-733x533-384dpi.png">
    <img src="https://raw.githubusercontent.com/doydl-technologies/dollarwave/v2.0.7/assets/png/dollarwave-endorsed-lockup-v03-stacked-dark-733x533-384dpi.png" alt="Dollarwave — powered by DOYDL Technologies" width="700">
  </picture>
</p>

# 💵 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.

> [!WARNING]
> **🛑 Deprecated package.** Dollarwave is a legacy library. This guide documents the **2.0.7 source release** for existing users, evaluation, and reproducibility. The repository's [contribution policy](CONTRIBUTING.md) permits focused maintenance; this does not remove the deprecation notice.

> [!IMPORTANT]
> **⚠️ Previous migration guidance is outdated.** Earlier documentation directed users to `quantsumore` as an actively developed successor. That project was also retired. Its [retirement policy](https://github.com/doydl-technologies/quantsumore/blob/main/ARCHIVED.md) states that it remains unsupported. The [historical migration notes](#historical-migration-to-quantsumore) below preserve context without recommending it for new projects.

<a id="contents"></a>

## 🧭 Contents

- [🔍 What Dollarwave does](#what-dollarwave-does)
- [📦 Requirements and installation](#requirements-and-installation)
- [🚀 Quick start](#quick-start)
- [🧮 How the calculations work](#how-the-calculations-work)
- [🛠️ Calculator API reference](#calculator-api-reference)
- [🖥️ Desktop GUI](#desktop-gui)
- [📊 CPI data, coverage, and freshness](#cpi-data-coverage-and-freshness)
- [🗂️ Advanced usage and reproducible data](#advanced-usage-and-reproducible-data)
- [🩺 Errors and troubleshooting](#errors-and-troubleshooting)
- [⚠️ Interpretation and limitations](#interpretation-and-limitations)
- [🕰️ Historical migration to quantsumore](#historical-migration-to-quantsumore)
- [👨‍💻 Development and contributions](#development-and-contributions)
- [📚 Project links and license](#project-links-and-license)

<a id="what-dollarwave-does"></a>

## 🔍 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.

<a id="requirements-and-installation"></a>

## 📦 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

```bash
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

```bash
python -m pip install --upgrade pip
python -m pip install dollarwave
```

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

```bash
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`:

```bash
python -m pip install .
```

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

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

For an editable development installation, see [Development and contributions](#development-and-contributions).

<a id="quick-start"></a>

## 🚀 Quick start

### 💵 Adjust a historical amount

```python
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:

```text
$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](https://www.usinflationcalculator.com/inflation/consumer-price-index-and-annual-percent-changes-from-1913-to-2008/). 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

```python
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

```python
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](#errors-and-troubleshooting).

<a id="how-the-calculations-work"></a>

## 🧮 How the calculations work

**📐 Annual CPI adjustment formula**

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

```text
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](https://www.bls.gov/cpi/questions-and-answers.htm) explains CPI concepts and the difference between annual-average and particular-month comparisons. Choose the same time basis when checking results against another calculator.

<a id="calculator-api-reference"></a>

## 🛠️ Calculator API reference

Import the shared, lazily loaded calculator:

```python
from dollarwave import inflation_calculator
```

### 💰 `inflation_calculator(amount, original_year, target_year)`

Equivalent to:

```python
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**.

```python
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:

```text
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**:

```python
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`.

```text
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

```python
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.

<a id="desktop-gui"></a>

## 🖥️ Desktop GUI

```python
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:

```bash
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.

<a id="cpi-data-coverage-and-freshness"></a>

## 📊 CPI data, coverage, and freshness

### 🌐 Source and coverage

The default loader downloads an HTML table from [US Inflation Calculator's historical CPI page](https://www.usinflationcalculator.com/inflation/consumer-price-index-and-annual-percent-changes-from-1913-to-2008/). 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:

```text
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.

<a id="advanced-usage-and-reproducible-data"></a>

## 🗂️ 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.

<details>
<summary><strong>🔬 Show advanced data workflows and offline examples</strong></summary>

### 💾 Inspect and save the loaded table

```python
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

```python
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:

```python
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:

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

### ⚙️ Customize loading and timeout

```python
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.

<a id="errors-and-troubleshooting"></a>

</details>

## 🩺 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.

<a id="interpretation-and-limitations"></a>

## ⚠️ 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](https://www.bls.gov/cpi/questions-and-answers.htm).
- 💵 **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.

<a id="historical-migration-to-quantsumore"></a>

## 🕰️ Historical migration to quantsumore

Earlier versions of this README recommended `quantsumore` as Dollarwave's successor. Its [retirement policy](https://github.com/doydl-technologies/quantsumore/blob/main/ARCHIVED.md) 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.

<details>
<summary><strong>🕰️ Show archived migration notes (not a current recommendation)</strong></summary>

| 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:

```python
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](https://pypi.org/project/quantsumore/) 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.

<a id="development-and-contributions"></a>

</details>

## 👨‍💻 Development and contributions

The [contribution guide](CONTRIBUTING.md) 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:

```bash
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:

```bash
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:

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

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

<a id="project-links-and-license"></a>

## 📚 Project links and license

- 🧑‍💻 [Source repository](https://github.com/doydl-technologies/dollarwave)
- 📦 [PyPI package](https://pypi.org/project/dollarwave/)
- 🐛 [Issue tracker](https://github.com/doydl-technologies/dollarwave/issues)
- 🏷️ [Releases](https://github.com/doydl-technologies/dollarwave/releases)
- 🤝 [Contribution guide](CONTRIBUTING.md)
- 🔐 [Security policy](SECURITY.md)
- ⚖️ [MIT License](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.
