cpi 2.1.0__py3-none-any.whl

cpi/__init__.py

@@ -0,0 +1,173 @@
+#! /usr/bin/env python
+"""
+Quickly adjust U.S. dollars for inflation using the Consumer Price Index (CPI)
+"""
+
+import logging
+import numbers
+import warnings
+from datetime import date, datetime
+from pathlib import Path
+
+from . import models
+from .defaults import DEFAULT_SERIES_ID, DEFAULTS_SERIES_ATTRS
+from .download import Downloader
+from .errors import StaleDataWarning
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+# Check if the cpi.db database exists, if not, download it.
+this_dir = Path(__file__).parent.absolute()
+db_path = this_dir / "cpi.db"
+if not db_path.exists():
+    warnings.warn(
+        "CPI database not found. Downloading... This may take a few minutes.",
+        stacklevel=2,
+    )
+    logger.info("CPI database not found. Downloading...")
+    Downloader().update()
+
+# Create a list of all available series, will be lazy loaded as we go
+series = models.SeriesList()
+
+# Set the default series to the CPI-U
+DEFAULT_SERIES = models.Series.get_by_id(DEFAULT_SERIES_ID)
+series.append(DEFAULT_SERIES)
+
+# Establish the range of data available
+LATEST_MONTH = DEFAULT_SERIES.latest_month
+LATEST_YEAR = DEFAULT_SERIES.latest_year
+
+# Figure out how out of date you are
+DAYS_SINCE_LATEST_MONTH = (date.today() - LATEST_MONTH).days
+DAYS_SINCE_LATEST_YEAR = (date.today() - date(LATEST_YEAR, 1, 1)).days
+
+# If it's more than two and a half years out of date, raise a warning.
+if DAYS_SINCE_LATEST_YEAR > (365 * 2.25) or DAYS_SINCE_LATEST_MONTH > 90:
+    warnings.warn(StaleDataWarning(), stacklevel=2)
+    logger.warning(
+        "CPI data is out of date. To accurately inflate to today's dollars, you must run `cpi.update()`."
+    )
+
+# Create aliases for accessing the other data tables
+areas = models.Area
+periods = models.Period
+periodicities = models.Periodicity
+items = models.Item
+
+
+def get(
+    year_or_month,
+    survey=DEFAULTS_SERIES_ATTRS["survey"],
+    seasonally_adjusted=DEFAULTS_SERIES_ATTRS["seasonally_adjusted"],
+    periodicity=DEFAULTS_SERIES_ATTRS["periodicity"],
+    area=DEFAULTS_SERIES_ATTRS["area"],
+    items=DEFAULTS_SERIES_ATTRS["items"],
+    series_id=None,
+):
+    """Returns the CPI value for a given year."""
+    # Pull the series
+    if series_id:
+        # If the user has provided an explicit series id, we are going to ignore the humanized options.
+        series_obj = series.get_by_id(series_id)
+    else:
+        # Otherwise, we build the series id using the more humanized options
+        series_obj = series.get(survey, seasonally_adjusted, periodicity, area, items)
+
+    # Prep the lookup value depending on the input type.
+    if isinstance(year_or_month, numbers.Integral):
+        year_or_month = date(year_or_month, 1, 1)
+        period_type = "annual"
+    elif isinstance(year_or_month, date):
+        period_type = "monthly"
+        # If it's not set to the first day of the month, we should do that now.
+        if year_or_month.day != 1:
+            year_or_month = year_or_month.replace(day=1)
+    else:
+        raise ValueError("Only integers and date objects are accepted.")
+
+    # Pull the value from the series by date
+    return series_obj.get_index_by_date(year_or_month, period_type=period_type).value
+
+
+def inflate(
+    value,
+    year_or_month,
+    to=None,
+    survey=DEFAULTS_SERIES_ATTRS["survey"],
+    seasonally_adjusted=DEFAULTS_SERIES_ATTRS["seasonally_adjusted"],
+    periodicity=DEFAULTS_SERIES_ATTRS["periodicity"],
+    area=DEFAULTS_SERIES_ATTRS["area"],
+    items=DEFAULTS_SERIES_ATTRS["items"],
+    series_id=None,
+):
+    """
+    Returns a dollar value adjusted for inflation.
+
+    You must submit the value, followed by the year or month its from.
+
+    Years should be submitted as integers. Months as datetime.date objects.
+
+    By default, the input is adjusted to the most recent year or month available from the CPI.
+
+    If you'd like to adjust to a different year or month, submit it to the optional `to` keyword argument.
+
+    Yearly data can only be updated to other years. Monthly data can only be updated to other months.
+    """
+    # If the two dates match, just return the value unadjusted
+    if year_or_month == to:
+        return value
+
+    # Figure out the 'to' date if it has not been provided
+    if not to:
+        if isinstance(year_or_month, (date, datetime)):
+            to = LATEST_MONTH
+        else:
+            to = LATEST_YEAR
+    # Otherwise sanitize it
+    else:
+        if isinstance(to, numbers.Integral):
+            to = int(to)
+        elif isinstance(to, datetime):
+            # We want dates not datetimes
+            to = to.date()
+
+    # Sanitize the year_or_month
+    if isinstance(year_or_month, numbers.Integral):
+        # We need to make sure that int64, int32 and other int-like objects
+        # are the same type for the comparison to come.
+        year_or_month = int(year_or_month)
+    # If a datetime has been provided, shave it down to a date.
+    elif isinstance(year_or_month, datetime):
+        year_or_month = year_or_month.date()
+
+    # Make sure the two dates are the same type
+    if type(year_or_month) is not type(to):
+        raise TypeError(
+            "Years can only be converted to other years. Months only to other months."
+        )
+
+    # Otherwise, let's do the math.
+    # The input value is multiplied by the CPI of the target year,
+    # then divided into the CPI from the source year.
+    kwargs = {
+        "survey": survey,
+        "seasonally_adjusted": seasonally_adjusted,
+        "periodicity": periodicity,
+        "area": area,
+        "items": items,
+        "series_id": series_id,
+    }
+    source_index = get(year_or_month, **kwargs)
+    target_index = get(to, **kwargs)
+    return (value * target_index) / float(source_index)
+
+
+def update():
+    """
+    Updates the Consumer Price Index dataset at the core of this library.
+
+    Requires an Internet connection.
+    """
+    Downloader().update()

cpi/cli.py

@@ -0,0 +1,76 @@
+#! /usr/bin/env python
+"""
+Command-line interface.
+"""
+
+import click
+from dateutil.parser import parse as dateparse
+
+import cpi
+
+
+@click.command()
+@click.argument(
+    "value",
+    nargs=1,
+    required=True,
+)
+@click.argument(
+    "year_or_month",
+    nargs=1,
+    required=True,
+)
+@click.option(
+    "--to", nargs=1, default=None, help="The year or month to adjust the value to."
+)
+@click.option(
+    "--series_id",
+    type=click.STRING,
+    nargs=1,
+    default=cpi.DEFAULT_SERIES_ID,
+    help="The CPI data series used for the conversion. The default is the CPI-U.",
+)
+def inflate(value, year_or_month, to=None, series_id=cpi.DEFAULT_SERIES):
+    """
+    Returns a dollar value adjusted for inflation.
+    """
+    # Sanitize the value
+    try:
+        value = float(value)
+    except ValueError:
+        click.ClickException("Dollar value must be an integer or float.")
+
+    # Sanitize the `from` date.
+    try:
+        year_or_month = _parse_date(year_or_month)
+    except ValueError:
+        click.ClickException(
+            "Source date must be a year as an integer or a month as a parseable date string."
+        )
+
+    # Sanitize the `to` date.
+    if to:
+        try:
+            to = _parse_date(to)
+        except ValueError:
+            click.ClickException(
+                "Source date must be a year as an integer or a month as a parseable date string."
+            )
+
+    # Run the command
+    result = cpi.inflate(value, year_or_month, to=to, series_id=series_id)
+
+    # Print out the result to the terminal
+    click.echo(result)
+
+
+def _parse_date(value):
+    """
+    Parse a date submitted to the CLIself.
+
+    Returns and integer if its a year. Returns a date object if its a month.
+    """
+    try:
+        return int(value)
+    except ValueError:
+        return dateparse(value).date()

cpi/cpi.db

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: cpi/cpi.db
+size: 63467520 bytes
+sha256: 28a3230316ae3f2a0566428f14d8d6402c25ab5702f63fab565d49e143276a1c

cpi/defaults.py

@@ -0,0 +1,23 @@
+"""Default values."""
+
+from typing import TypedDict
+
+
+class SeriesAttributes(TypedDict):
+    """Human-readable attributes identifying a CPI series."""
+
+    survey: str
+    seasonally_adjusted: bool
+    periodicity: str
+    area: str
+    items: str
+
+
+DEFAULT_SERIES_ID = "CUUR0000SA0"
+DEFAULTS_SERIES_ATTRS: SeriesAttributes = {
+    "survey": "All urban consumers",
+    "seasonally_adjusted": False,
+    "periodicity": "Monthly",
+    "area": "U.S. city average",
+    "items": "All items",
+}

cpi/download.py

@@ -0,0 +1,192 @@
+"""Download the latest annual Consumer Price Index (CPI) dataset."""
+
+import io
+import logging
+import sqlite3
+import typing
+from pathlib import Path
+
+import pandas as pd
+import requests
+
+from cpi import parsers
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+class Downloader:
+    """Download the latest data."""
+
+    THIS_DIR: Path = Path(__file__).parent.absolute()
+    FILE_LIST: typing.List[str] = [
+        "cu.area",
+        "cu.item",
+        "cu.period",
+        "cu.periodicity",
+        "cu.series",
+        "cu.data.0.Current",
+        "cu.data.1.AllItems",
+        "cu.data.2.Summaries",
+        "cu.data.3.AsizeNorthEast",
+        "cu.data.4.AsizeNorthCentral",
+        "cu.data.5.AsizeSouth",
+        "cu.data.6.AsizeWest",
+        "cu.data.7.OtherNorthEast",
+        "cu.data.8.OtherNorthCentral",
+        "cu.data.9.OtherSouth",
+        "cu.data.10.OtherWest",
+        "cu.data.11.USFoodBeverage",
+        "cu.data.12.USHousing",
+        "cu.data.13.USApparel",
+        "cu.data.14.USTransportation",
+        "cu.data.15.USMedical",
+        "cu.data.16.USRecreation",
+        "cu.data.17.USEducationAndCommunication",
+        "cu.data.18.USOtherGoodsAndServices",
+        "cu.data.19.PopulationSize",
+        "cu.data.20.USCommoditiesServicesSpecial",
+    ]
+
+    def rm(self) -> None:
+        """Remove any existing files."""
+        db_path = self.THIS_DIR / "cpi.db"
+        if db_path.exists():
+            logger.debug("Clearing database")
+            # Drop all tables in the database
+            conn = self.get_db_conn()
+            table_list = [
+                "areas",
+                "items",
+                "periods",
+                "periodicities",
+                "series",
+                "indexes",
+            ]
+            for t in table_list:
+                conn.execute(f"DROP TABLE IF EXISTS '{t}';")
+            conn.close()
+            self.vacuum()
+
+    def vacuum(self) -> None:
+        """Vacuum the database."""
+        conn = self.get_db_conn()
+        conn.execute("VACUUM;")
+        conn.close()
+
+    def update(self) -> None:
+        """Update the Consumer Price Index dataset that powers this library."""
+        # Delete existing files
+        self.rm()
+
+        # Load the default files
+        self.load_file_list(self.FILE_LIST)
+
+        # Process flat CSVs we can use in our API
+        self.process_files()
+
+        # Drop the raw files now that we don't need them
+        self.drop_file_list(self.FILE_LIST)
+
+    def get_db_conn(self) -> sqlite3.Connection:
+        """Connect to db."""
+        db_path = self.THIS_DIR / "cpi.db"
+        return sqlite3.connect(db_path)
+
+    def process_files(self) -> None:
+        """Process the raw data files into simplified tables."""
+        logger.info("Parsing data files from the BLS")
+        conn = self.get_db_conn()
+
+        areas = parsers.ParseArea().get_df()
+        areas.to_sql("areas", conn, if_exists="replace", index=False)
+
+        items = parsers.ParseItem().get_df()
+        items.to_sql("items", conn, if_exists="replace", index=False)
+
+        periods = parsers.ParsePeriod().get_df()
+        periods.to_sql("periods", conn, if_exists="replace", index=False)
+
+        periodicities = parsers.ParsePeriodicity().get_df()
+        periodicities.to_sql("periodicities", conn, if_exists="replace", index=False)
+
+        series = parsers.ParseSeries().get_df()
+        series.to_sql("series", conn, if_exists="replace", index=False)
+
+        index = parsers.ParseIndex().get_df()
+        index.to_sql("indexes", conn, if_exists="replace", index=False)
+
+        conn.close()
+
+    def load_file_list(self, file_list: typing.List[str]) -> None:
+        # Download the TSVs
+        logger.debug(f"Downloading {len(file_list)} files from the BLS")
+        df_list = {name: self.get_df(name) for name in file_list}
+
+        # Insert the TSVs
+        logger.debug("Loading data into SQLite database")
+        conn = self.get_db_conn()
+
+        # Load them one by one
+        for name, df in df_list.items():
+            logger.debug(f"- {name}")
+            df.to_sql(name, conn, if_exists="replace", index=False)
+
+        # Close connection
+        conn.close()
+
+    def drop_file_list(self, file_list: typing.List[str]) -> None:
+        """Drop the raw data from BLS."""
+        logger.debug("Dropping data from SQLite database")
+
+        # Connect
+        conn = self.get_db_conn()
+
+        # Do tables one by one
+        for name in file_list:
+            logger.debug(f"- {name}")
+            conn.execute(f"DROP TABLE '{name}';")
+
+        # Close the connection
+        conn.close()
+
+        # Vacuum the database.
+        self.vacuum()
+
+    def get_df(self, file: str) -> pd.DataFrame:
+        """Download TSV file from the BLS."""
+        # Download it
+        url = f"https://download.bls.gov/pub/time.series/cu/{file}"
+        logger.debug(f" - {url}")
+        headers = {
+            "User-Agent": "b@palewi.re",
+        }
+        response = requests.get(url, headers=headers, timeout=30)
+
+        # Make sure the response is legit
+        try:
+            assert response.ok
+        except AssertionError:
+            logger.error(f"Error downloading {url}")
+            logger.error(f"Response: {response.text}")
+            raise AssertionError(f"Error downloading {url} - {response.text}")
+
+        # Read in the contents as an io.StringIO object
+        df = pd.read_csv(io.StringIO(response.text), sep="\t")
+
+        # .strip() every value in the dataframe
+        df_obj = df.select_dtypes("object")
+        df[df_obj.columns] = df_obj.apply(lambda x: x.str.strip())
+
+        # .strip every column name
+        df.columns = [col.strip() for col in df.columns]
+
+        # Clean file
+        df.drop([None], axis=1, inplace=True, errors="ignore")
+
+        # Pass it back
+        return df
+
+
+if __name__ == "__main__":
+    Downloader().update()

cpi/errors.py

@@ -0,0 +1,21 @@
+#! /usr/bin/env python
+"""
+Custom errors.
+"""
+
+
+class CPIObjectDoesNotExist(Exception):
+    """
+    Error raised when a CPI object is requested that doesn't exist.
+    """
+
+    pass
+
+
+class StaleDataWarning(Warning):
+    """
+    The warning to raise when the local data are out of date.
+    """
+
+    def __str__(self):
+        return "CPI data is out of date. To accurately inflate to today's dollars, you must run `cpi.update()`."

cpi/models.py

@@ -0,0 +1,444 @@
+"""Python objects for modeling Consumer Price Index (CPI) data structures."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+from collections.abc import Sequence
+from datetime import date as Date
+from typing import Any
+from pathlib import Path
+
+from pandas import json_normalize
+
+from .defaults import DEFAULTS_SERIES_ATTRS
+
+# CPI tools
+from .errors import CPIObjectDoesNotExist
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+def query(sql: str, params: Sequence[Any] | None = None) -> list[dict[str, Any]]:
+    """Query the cpi.db database and return the result.
+
+    Args:
+        sql (str): The SQL query to execute.
+        params (list | tuple): The parameters to pass to the query.
+
+    Returns:
+        list[dict]: A list of dictionaries representing the result of the query.
+
+    Examples:
+        >>> query("SELECT * FROM 'areas';")
+        [{'id': '0000', 'code': 'US', 'name': 'United States'}, ...]
+    """
+    # Connect
+    this_dir = Path(__file__).parent.absolute()
+    conn = sqlite3.connect(this_dir / "cpi.db")
+    cursor = conn.cursor()
+
+    # Query the sql
+    if not params:
+        query = cursor.execute(sql)
+    else:
+        query = cursor.execute(sql, params)
+    columns = [d[0] for d in query.description]
+    result_list = [dict(zip(columns, r)) for r in query.fetchall()]
+
+    # Close
+    conn.close()
+
+    # Return the result
+    return result_list
+
+
+def queryone(sql: str, params: Sequence[Any] | None = None) -> dict[str, Any]:
+    """Query the cpi.db database and return a single result.
+
+    Args:
+        sql (str): The SQL query to execute.
+        params (list | tuple): The parameters to pass to the query.
+
+    Returns:
+        dict: A dictionary representing the result of the query.
+
+    Raises:
+        CPIObjectDoesNotExist: If the object does not exist.
+        ValueError: If more than one object exists.
+
+    Examples:
+        >>> queryone("SELECT * FROM 'areas' WHERE id=?", ('0000',))
+        {'id': '0000', 'code': 'US', 'name': 'United States'}
+    """
+    dict_list = query(sql, params)
+    try:
+        assert len(dict_list) == 1
+    except AssertionError:
+        if len(dict_list) == 0:
+            raise CPIObjectDoesNotExist("Object does not exist")
+        elif len(dict_list) > 1:
+            raise ValueError("More than one object exists")
+    return dict_list[0]
+
+
+class BaseObject:
+    """An abstract base class for all the models."""
+
+    table_name: str | None = None  #: The name of the table in the database.
+
+    def __repr__(self) -> str:
+        return f"<{self.__class__.__name__}: {self.__str__()}>"
+
+    def __eq__(self, other: object) -> bool:
+        return bool(
+            getattr(other, "id", None) is not None
+            and getattr(self, "id", None) == getattr(other, "id", None)
+        )
+
+    def __str__(self) -> str:
+        return str(getattr(self, "name"))
+
+    @classmethod
+    def get_by_id(cls, value: str) -> Any:
+        """Returns the object with the provided identifier code."""
+        d = queryone(f"SELECT * from '{cls.table_name}' WHERE id=?", (value,))
+        return cls(**d)
+
+    @classmethod
+    def get_by_name(cls, value: str) -> Any:
+        """Returns the object with the provided name."""
+        d = queryone(f"SELECT * from '{cls.table_name}' WHERE name=?", (value,))
+        return cls(**d)
+
+    @classmethod
+    def all(cls) -> list[Any]:
+        """Returns a list of all objects in the table."""
+        dict_list = query(f"SELECT * FROM '{cls.table_name}'")
+        return [cls(**d) for d in dict_list]
+
+
+class Area(BaseObject):
+    """A geographical area where prices are gathered monthly."""
+
+    table_name = "areas"
+
+    def __init__(self, id, code, name):
+        self.id = id
+        self.code = code
+        self.name = name
+
+    def __dict__(self):
+        return {"id": self.id, "code": self.code, "name": self.name}
+
+
+class Item(BaseObject):
+    """A type of consumer good or goods that has its price tracked."""
+
+    table_name = "items"
+
+    def __init__(self, id, code, name):
+        self.id = id
+        self.code = code
+        self.name = name
+
+    def __dict__(self):
+        return {"id": self.id, "code": self.code, "name": self.name}
+
+
+class Period(BaseObject):
+    """A time period tracked by the CPI."""
+
+    table_name = "periods"
+
+    def __init__(self, id, code, abbreviation, name):
+        self.id = id
+        self.code = code
+        self.abbreviation = abbreviation
+        self.name = name
+
+    def __dict__(self):
+        return {
+            "id": self.id,
+            "code": self.code,
+            "abbreviation": self.abbreviation,
+            "name": self.name,
+            "month": self.month,
+            "type": self.type,
+        }
+
+    @property
+    def month(self) -> int:
+        """
+        Returns the month integer for the period.
+        """
+        if self.id in ["M13", "S01", "S03"]:
+            return 1
+        elif self.id == "S02":
+            return 7
+        else:
+            return int(self.id.replace("M", ""))
+
+    @property
+    def type(self) -> str:
+        """
+        Returns a string classifying the period.
+        """
+        if self.id in ["M13", "S03"]:
+            return "annual"
+        elif self.id in ["S01", "S02"]:
+            return "semiannual"
+        else:
+            return "monthly"
+
+
+class Periodicity(BaseObject):
+    """A time interval tracked by the CPI."""
+
+    table_name = "periodicities"
+
+    def __init__(self, id, code, name):
+        self.id = code
+        self.code = code
+        self.name = name
+
+    def __dict__(self):
+        return {"id": self.id, "code": self.code, "name": self.name}
+
+
+class Index(BaseObject):
+    """A Consumer Price Index value generated by the Bureau of Labor Statistics."""
+
+    table_name = "indexes"
+
+    def __init__(self, series_id: str, year: int, period: Period, value: float):
+        self.series_id = series_id
+        self.year = year
+        self.period = period
+        self.value = value
+
+    def __str__(self) -> str:
+        return f"{self.date} ({self.period}): {self.value}"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Index):
+            return NotImplemented
+        return (
+            self.value == other.value
+            and self.series_id == other.series_id
+            and self.year == other.year
+            and self.period == other.period
+        )
+
+    def __dict__(self):
+        return {
+            "series_id": self.series_id,
+            "year": self.year,
+            "date": str(self.date),
+            "period": self.period.__dict__(),
+            "value": self.value,
+        }
+
+    @property
+    def date(self) -> Date:
+        """
+        Accepts a row from the raw BLS data. Returns a Python date object based on its period.
+        """
+        return Date(self.year, self.period.month, 1)
+
+
+class Series(BaseObject):
+    """
+    A set of CPI data observed over an extended period of time over consistent time intervals ranging from
+    a specific consumer item in a specific geographical area whose price is gathered monthly to a category
+    of worker in a specific industry whose employment rate is being recorded monthly, etc.
+
+    Yes, that's the official government definition. I'm not kidding.
+    """
+
+    def __init__(
+        self,
+        id: str,
+        title: str,
+        survey: str,
+        seasonally_adjusted: str,
+        periodicity: Periodicity,
+        area: Area,
+        items: Item,
+        indexes: list[Index],
+    ):
+        self.id = id
+        self.title = title
+        self.survey = survey
+        self.seasonally_adjusted = seasonally_adjusted
+        self.periodicity = periodicity
+        self.area = area
+        self.items = items
+        self.indexes = indexes
+
+    def __str__(self) -> str:
+        return f"{self.id}: {self.title}"
+
+    def __dict__(self):
+        return {
+            "id": self.id,
+            "title": self.title,
+            "survey": self.survey,
+            "seasonally_adjusted": self.seasonally_adjusted,
+            "periodicity": self.periodicity.__dict__(),
+            "area": self.area.__dict__(),
+            "items": self.items.__dict__(),
+        }
+
+    def to_dataframe(self):
+        """
+        Returns this series and all its indexes as a pandas DataFrame.
+        """
+        dict_list = [obj.__dict__() for obj in self.indexes]
+        return json_normalize(dict_list, sep="_")
+
+    @property
+    def latest_month(self) -> Date:
+        return max([i.date for i in self.indexes if i.period.type == "monthly"])
+
+    @property
+    def latest_year(self) -> int:
+        return max([i.year for i in self.indexes if i.period.type == "annual"])
+
+    def get_index_by_date(self, date: Date, period_type: str = "annual") -> Index:
+        period_list = [i for i in self.indexes if i.period.type == period_type]
+        try:
+            return next(i for i in period_list if i.date == date)
+        except StopIteration:
+            raise CPIObjectDoesNotExist(
+                f"Index of {period_type} type for {date} does not exist"
+            )
+
+    @classmethod
+    def get_by_id(cls, value: str) -> Series:
+        # If it's not there, try querying the database
+        d = queryone("SELECT * FROM 'series' WHERE id=?", (value,))
+
+        # Get the other bits
+        seasonalities = {1: True, 0: False}
+        d["seasonally_adjusted"] = seasonalities[d["seasonally_adjusted"]]
+        d["periodicity"] = Periodicity.get_by_id(d["periodicity"])
+        d["area"] = Area.get_by_id(d["area"])
+        d["items"] = Item.get_by_id(d["items"])
+
+        # Get the indexes
+        dict_list = query("SELECT * FROM 'indexes' WHERE series=?", (value,))
+
+        # Cache the periods to reduce queries
+        period_cache = {p.id: p for p in Period.all()}
+
+        # Load the indexes one by one
+        d["indexes"] = []
+        for i in dict_list:
+            obj = Index(
+                series_id=d["id"],
+                year=int(i["year"]),
+                period=period_cache[i["period"]],
+                value=float(i["value"]),
+            )
+            d["indexes"].append(obj)
+
+        # Convert it into a Series object
+        return cls(**d)
+
+
+class SeriesList(list[Series]):
+    """
+    A custom list of indexes in a series.
+    """
+
+    SEASONALITIES = {True: "S", False: "U"}
+    SURVEYS = {
+        "All urban consumers": "CU",
+        "Urban wage earners and clerical workers": "CW",
+    }
+
+    # Set a cache
+    _dict: dict[str, Series] = {}
+
+    def to_dataframe(self):
+        """
+        Returns the list as a pandas DataFrame.
+        """
+        dict_list = [obj.__dict__() for obj in self]
+        return json_normalize(dict_list, sep="_")
+
+    def append(self, obj: Series):
+        """
+        Override to default append method that allows validation and dictionary-style lookups
+        """
+        # Add to dictionary lookup
+        self._dict[obj.id] = obj
+
+        # Append to list
+        super().append(obj)
+
+    def get_by_id(self, value: str) -> Series:
+        """Returns the CPI series object with the provided identifier code."""
+        logger.debug(f"Retrieving series with id {value}")
+
+        # First try the cache
+        try:
+            return self._dict[value]
+        except KeyError:
+            pass
+
+        # Get it
+        obj = Series.get_by_id(value)
+
+        # Cache it
+        self._dict[value] = obj
+
+        # Return it
+        return obj
+
+    def all(self) -> list[Series]:
+        """Get all of the series from our database."""
+        # Query all of the series ids from the database
+        series_list = query("SELECT id FROM 'series';")
+
+        # Get all of them, to ensure they're all loaded in the cache
+        return [self.get_by_id(d["id"]) for d in series_list]
+
+    def get(
+        self,
+        survey: str = DEFAULTS_SERIES_ATTRS["survey"],
+        seasonally_adjusted: bool = DEFAULTS_SERIES_ATTRS["seasonally_adjusted"],
+        periodicity: str = DEFAULTS_SERIES_ATTRS["periodicity"],
+        area: str = DEFAULTS_SERIES_ATTRS["area"],
+        items: str = DEFAULTS_SERIES_ATTRS["items"],
+    ) -> Series:
+        """Returns a single CPI Series object based on the input.
+
+        The default series is returned if not configuration is made to the keyword arguments.
+        """
+        # Get all the codes for these humanized input.
+        try:
+            survey_code = self.SURVEYS[survey]
+        except KeyError:
+            raise CPIObjectDoesNotExist(f"Survey with the name {survey} does not exist")
+
+        try:
+            seasonality_code = self.SEASONALITIES[seasonally_adjusted]
+        except KeyError:
+            raise CPIObjectDoesNotExist(
+                f"Seasonality {seasonally_adjusted} does not exist"
+            )
+
+        # Generate the series id
+        series_id = "{}{}{}{}{}".format(
+            survey_code,
+            seasonality_code,
+            Periodicity.get_by_name(periodicity).code,
+            Area.get_by_name(area).code,
+            Item.get_by_name(items).code,
+        )
+
+        # Pull the series
+        return self.get_by_id(series_id)

cpi/parsers.py

@@ -0,0 +1,215 @@
+#! /usr/bin/env python
+"""
+Parse and prepare the Consumer Price Index (CPI) dataset.
+"""
+
+import logging
+import os
+import sqlite3
+from typing import Any
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+class BaseParser:
+    THIS_DIR = os.path.dirname(__file__)
+
+    def get_file(self, file):
+        """
+        Returns the CPI data file provided as a list of dictionaries.
+        """
+        # Connect to database
+        db_path = os.path.join(self.THIS_DIR, "cpi.db")
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+
+        # Query this file
+        query = cursor.execute(f'SELECT * FROM "{file}"')
+        columns = [d[0] for d in query.description]
+        result_list = [dict(zip(columns, r)) for r in query.fetchall()]
+
+        # Close database connection
+        cursor.close()
+        cursor.connection.close()
+
+        # Return data
+        return result_list
+
+    def parse(self) -> list[dict[str, Any]]:
+        raise NotImplementedError
+
+    def get_df(self) -> pd.DataFrame:
+        """Convert the database table to a polished dataframe."""
+        return pd.DataFrame(self.parse()).drop_duplicates()
+
+
+class ParseArea(BaseParser):
+    """Parse the raw list of CPI areas."""
+
+    def parse(self):
+        """
+        Returns a list Area objects.
+        """
+        logger.debug("Parsing area file")
+        object_list = []
+        for row in self.get_file("cu.area"):
+            d = dict(
+                id=row["area_code"],
+                code=row["area_code"],
+                name=row["area_name"],
+            )
+            object_list.append(d)
+        return object_list
+
+
+class ParseItem(BaseParser):
+    """
+    Parses the raw list of CPI items.
+    """
+
+    def parse(self):
+        """
+        Returns a list Area objects.
+        """
+        logger.debug("Parsing item file")
+        object_list = []
+        for row in self.get_file("cu.item"):
+            d = dict(
+                id=row["item_code"],
+                code=row["item_code"],
+                name=row["item_name"],
+            )
+            object_list.append(d)
+        return object_list
+
+
+class ParsePeriod(BaseParser):
+    """
+    Parses the raw list of CPI periods.
+    """
+
+    def parse(self):
+        """
+        Returns a list Area objects.
+        """
+        logger.debug("Parsing period file")
+        object_list = []
+        for row in self.get_file("cu.period"):
+            d = dict(
+                id=row["period"],
+                code=row["period"],
+                abbreviation=row["period_abbr"],
+                name=row["period_name"],
+            )
+            object_list.append(d)
+        return object_list
+
+
+class ParsePeriodicity(BaseParser):
+    """
+    Parses the raw list of CPI periodicities.
+    """
+
+    def parse(self):
+        """
+        Returns a list Periodicity objects.
+        """
+        logger.debug("Parsing periodicity file")
+        object_list = []
+        for row in self.get_file("cu.periodicity"):
+            d = dict(
+                id=row["periodicity_code"],
+                code=row["periodicity_code"],
+                name=row["periodicity_name"],
+            )
+            object_list.append(d)
+        return object_list
+
+
+class ParseSeries(BaseParser):
+    """
+    Parses the raw list of CPI series from the BLS.
+    """
+
+    SURVEYS = {
+        "CU": "All urban consumers",
+        "CW": "Urban wage earners and clerical workers",
+    }
+
+    def parse_id(self, id):
+        return dict(
+            survey_code=id[:2],
+            seasonal_code=id[2:3],
+            periodicity_code=id[3:4],
+            area_code=id[4:8],
+            item_code=id[8:],
+        )
+
+    def parse(self):
+        """Parse the data."""
+        logger.debug("Parsing series file")
+        object_list = []
+        for row in self.get_file("cu.series"):
+            parsed_id = self.parse_id(row["series_id"])
+            d = dict(
+                id=row["series_id"],
+                title=row["series_title"],
+                survey=self.SURVEYS[parsed_id["survey_code"]],
+                seasonally_adjusted=row["seasonal"] == "S",
+                periodicity=row["periodicity_code"],
+                area=row["area_code"],
+                items=row["item_code"],
+            )
+            object_list.append(d)
+        return object_list
+
+
+class ParseIndex(BaseParser):
+    """Parse indexes."""
+
+    FILE_LIST = [
+        "cu.data.0.Current",
+        "cu.data.1.AllItems",
+        "cu.data.2.Summaries",
+        "cu.data.3.AsizeNorthEast",
+        "cu.data.4.AsizeNorthCentral",
+        "cu.data.5.AsizeSouth",
+        "cu.data.6.AsizeWest",
+        "cu.data.7.OtherNorthEast",
+        "cu.data.8.OtherNorthCentral",
+        "cu.data.9.OtherSouth",
+        "cu.data.10.OtherWest",
+        "cu.data.11.USFoodBeverage",
+        "cu.data.12.USHousing",
+        "cu.data.13.USApparel",
+        "cu.data.14.USTransportation",
+        "cu.data.15.USMedical",
+        "cu.data.16.USRecreation",
+        "cu.data.17.USEducationAndCommunication",
+        "cu.data.18.USOtherGoodsAndServices",
+        "cu.data.19.PopulationSize",
+        "cu.data.20.USCommoditiesServicesSpecial",
+    ]
+
+    def parse(self):
+        logger.debug("Parsing index files")
+        # Loop through all the files ...
+        object_list = []
+        for file in self.FILE_LIST:
+            # ... and for each file ...
+            for row in self.get_file(file):
+                # Skip rows where value is '-' (missing data) or None
+                if row["value"] == "-" or row["value"] is None:
+                    continue
+                # Create an object
+                d = dict(
+                    series=row["series_id"],
+                    year=int(row["year"]),
+                    period=row["period"],
+                    value=float(row["value"]),
+                )
+                object_list.append(d)
+        return object_list

cpi-2.1.0.dist-info/METADATA

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: cpi
+Version: 2.1.0
+Summary: Quickly adjust U.S. dollars for inflation using the Consumer Price Index (CPI)
+Author-email: Ben Welsh <b@palewi.re>
+License-Expression: MIT
+Project-URL: Documentation, https://palewi.re/docs/cpi/
+Project-URL: Maintainer, https://github.com/palewire
+Project-URL: Source, https://github.com/palewire/cpi
+Project-URL: Tracker, https://github.com/palewire/cpi/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click
+Requires-Dist: pandas
+Requires-Dist: python-dateutil
+Requires-Dist: requests
+Dynamic: license-file
+
+### Links
+
+* Docs: [palewi.re/docs/cpi/](https://palewi.re/docs/cpi/)
+* Code: [github.com/palewire/cpi](https://github.com/palewire/cpi/)
+* Issues: [github.com/palewire/cpi/issues](https://github.com/palewire/cpi/issues)
+* Packaging: [pypi.python.org/pypi/cpi](https://pypi.python.org/pypi/cpi)
+* Testing: [github.com/palewire/cpi/actions](https://github.com/palewire/cpi/actions)

cpi-2.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+cpi/__init__.py,sha256=_4B1P9fcyzc5Ht-xSc1poMunvuP2Kc_MvVQJ4f2xqig,5900
+cpi/cli.py,sha256=LsYT2aZr41W26ODAY5XBHPI2WypunNMPzD5RrFu6KFk,1811
+cpi/cpi.db,sha256=KKMjAxauPyoFZkKPFNjWQCwlq1cC9j-rVl1J4UMnahw,63467520
+cpi/defaults.py,sha256=kzpp1JsVJGlOO8fngt52vuyW1Um4-jOVZjNhgbUjPc8,490
+cpi/download.py,sha256=as7Q3GEJgLUo_k7QqDKo5uymJHPklhczwBPLAnbbt8E,5898
+cpi/errors.py,sha256=CKP9J93kC6o_KjNZ_CObKBFr-tyRF4yKB58R8xQxzyU,432
+cpi/models.py,sha256=MXvGc_ssgTTOldzXVfH2YWG8zG62KDjQS12znrzetZs,13101
+cpi/parsers.py,sha256=zJJIk43hv9eOJ9MgmBCqjgsIzZAUQZxhI0AxZ5zmHjE,5937
+cpi-2.1.0.dist-info/licenses/LICENSE,sha256=rL8rZwFTGsHogbAIXzBuGPZrc7tRu-aJT7pU9z6kjX8,1076
+cpi-2.1.0.dist-info/METADATA,sha256=Ex3xZM4sajvR0YhZAiWFq9BPJKXXXr1poE480zG2j34,1314
+cpi-2.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+cpi-2.1.0.dist-info/entry_points.txt,sha256=QK4gpcr7Qk2WAwXKvSTAHKQqi3b-oXnqCRcTTie9HCc,44
+cpi-2.1.0.dist-info/top_level.txt,sha256=9TRAFyj1-KCSznuPFdi9rBS8IzNiz97gvDjVhQIg-s4,4
+cpi-2.1.0.dist-info/RECORD,,

cpi-2.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cpi-2.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+inflate = cpi.cli:inflate

cpi-2.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 Ben Welsh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cpi-2.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cpi