kde_cpi.data package

Top-level data module for CPI processing.

class kde_cpi.data.Area(code, name)

Bases: object

Geographic area metadata from the CPI area lookup table.

Parameters:

• code (str)

• name (str)

code: str

name: str

class kde_cpi.data.CpiDatabaseLoader(dsn=None, schema='public', connection_kwargs=NOTHING)

Bases: object

Persist CPI datasets into PostgreSQL using asyncpg primitives.

Parameters:

• dsn (str | None)

• schema (str)

• connection_kwargs (dict[str, Any])

async bulk_load(dataset, *, truncate=True)

Copy the full dataset into PostgreSQL, optionally truncating first.

Return type:

None

Parameters:

• dataset (Dataset)

• truncate (bool)

async close()

Close the open connection, if any.

Return type:

None

async connect(**overrides)

Establish (or reuse) the async connection.

Return type:

Connection

Parameters:

overrides (Any)

connection_kwargs: dict[str, Any]

dsn: str | None

async ensure_schema()

Create the CPI tables if they do not already exist.

Return type:

None

async fetch_dataset()

Reconstruct a Dataset from the current database contents.

Return type:

Dataset

async merge_dataset(dataset)

Synchronize metadata and upsert observations in place.

Return type:

None

Parameters:

dataset (Dataset)

schema: str

async sync_metadata(dataset)

Upsert mapping tables and series definitions without touching observations.

Return type:

None

Parameters:

dataset (Dataset)

async upsert_observations(observations)

Upsert one or more observation rows.

Return type:

None

Parameters:

observations (Iterable[Observation])

class kde_cpi.data.CpiDatasetBuilder(client=NOTHING)

Bases: object

Coordinate retrieval and parsing of CPI datasets from BLS flat files.

Parameters:

client (CpiHttpClient)

client: CpiHttpClient

close()

Close the underlying HTTP client.

Return type:

None

load_current_observations()

Load only the current-year data partition.

Return type:

Dataset

load_dataset(*, data_files=None)

Fetch mapping tables, series definitions, and observations into a dataset.

Return type:

Dataset

Parameters:

data_files (Sequence[str] | None)

class kde_cpi.data.CpiHttpClient(base_url='https://download.bls.gov/pub/time.series/cu/', timeout=30.0, session=NOTHING, headers=NOTHING)

Bases: object

Thin HTTP wrapper around the BLS CPI flat-file endpoints.

Parameters:

• base_url (str)

• timeout (float)

• session (Session)

• headers (dict[str, str])

base_url: str

close()

Release the underlying HTTP session.

Return type:

None

get_text(filename, *, encoding='utf-8')

Fetch a remote CPI resource and return its decoded text payload.

Return type:

str

Parameters:

• filename (str)

• encoding (str)

headers: dict[str, str]

session: Session

timeout: float

class kde_cpi.data.Dataset(areas=NOTHING, items=NOTHING, periods=NOTHING, footnotes=NOTHING, series=NOTHING, observations=NOTHING)

Bases: object

Aggregate CPI dataset containing mapping tables, series, and observations.

Parameters:

• areas (dict[str, Area])

• items (dict[str, Item])

• periods (dict[str, Period])

• footnotes (dict[str, Footnote])

• series (dict[str, Series])

• observations (list[Observation])

add_area(area)

Insert or update an area in the dataset.

Return type:

None

Parameters:

area (Area)

add_footnote(footnote)

Insert or update a footnote definition.

Return type:

None

Parameters:

footnote (Footnote)

add_item(item)

Insert or update an item in the dataset.

Return type:

None

Parameters:

item (Item)

add_period(period)

Insert or update a period definition.

Return type:

None

Parameters:

period (Period)

add_series(series)

Insert or update a series metadata record.

Return type:

None

Parameters:

series (Series)

areas: dict[str, Area]

extend_observations(observations)

Append observation records to the dataset, dropping duplicates.

Return type:

None

Parameters:

observations (Iterable[Observation])

footnotes: dict[str, Footnote]

items: dict[str, Item]

observations: list[Observation]

periods: dict[str, Period]

series: dict[str, Series]

to_dict()

Return a JSON-friendly representation of the dataset.

Return type:

dict[str, object]

class kde_cpi.data.Footnote(code, text)

Bases: object

Footnote reference associated with CPI observations.

Parameters:

• code (str)

• text (str)

code: str

text: str

class kde_cpi.data.Item(code, name, display_level, selectable, sort_sequence)

Bases: object

Item metadata describing CPI product groupings.

Parameters:

• code (str)

• name (str)

• display_level (int)

• selectable (bool)

• sort_sequence (int)

code: str

display_level: int

name: str

selectable: bool

sort_sequence: int

class kde_cpi.data.Observation(series_id, year, period, value, footnotes=NOTHING)

Bases: object

Single CPI observation value tied to a series and period.

Parameters:

• series_id (str)

• year (int)

• period (str)

• value (Decimal)

• footnotes (tuple[str, ...])

footnotes: tuple[str, ...]

is_annual()

Return True when the observation corresponds to annual data.

Return type:

bool

period: str

series_id: str

value: Decimal

year: int

class kde_cpi.data.Period(code, abbr, name)

Bases: object

Period metadata describing CPI reporting intervals.

Parameters:

• code (str)

• abbr (str)

• name (str)

abbr: str

code: str

name: str

class kde_cpi.data.Series(series_id, area_code, item_code, seasonal, periodicity_code, base_code, base_period, begin_year, begin_period, end_year, end_period, *, series_title='')

Bases: object

Metadata describing a CPI series and its structural attributes.

Parameters:

• series_id (str)

• area_code (str)

• item_code (str)

• seasonal (str)

• periodicity_code (str)

• base_code (str)

• base_period (str)

• begin_year (int)

• begin_period (str)

• end_year (int)

• end_period (str)

• series_title (str)

area_code: str

base_code: str

base_period: str

begin_period: str

begin_year: int

end_period: str

end_year: int

is_seasonally_adjusted()

Return True when the series is flagged as seasonally adjusted.

Return type:

bool

item_code: str

periodicity_code: str

seasonal: str

series_id: str

series_title: str

async kde_cpi.data.load_full_history(dsn, *, schema='public', truncate=True, data_files=None)

Load the full CPI history and write it into the database.

Return type:

Dataset

Parameters:

• dsn (str)

• schema (str)

• truncate (bool)

• data_files (Sequence[str] | None)

async kde_cpi.data.update_current_periods(dsn, *, schema='public')

Refresh the current-year CPI data without truncating history.

Return type:

Dataset

Parameters:

• dsn (str)

• schema (str)

Submodules

• kde_cpi.data.client module
  • CpiHttpClient
    • CpiHttpClient.base_url
    • CpiHttpClient.close()
    • CpiHttpClient.get_text()
    • CpiHttpClient.headers
    • CpiHttpClient.session
    • CpiHttpClient.timeout
• kde_cpi.data.files module
  • FileRequest
    • FileRequest.description
    • FileRequest.name
• kde_cpi.data.ingest module
  • CpiDatasetBuilder
    • CpiDatasetBuilder.client
    • CpiDatasetBuilder.close()
    • CpiDatasetBuilder.load_current_observations()
    • CpiDatasetBuilder.load_dataset()
• kde_cpi.data.loader module
  • CpiDatabaseLoader
    • CpiDatabaseLoader.bulk_load()
    • CpiDatabaseLoader.close()
    • CpiDatabaseLoader.connect()
    • CpiDatabaseLoader.connection_kwargs
    • CpiDatabaseLoader.dsn
    • CpiDatabaseLoader.ensure_schema()
    • CpiDatabaseLoader.fetch_dataset()
    • CpiDatabaseLoader.merge_dataset()
    • CpiDatabaseLoader.schema
    • CpiDatabaseLoader.sync_metadata()
    • CpiDatabaseLoader.upsert_observations()
• kde_cpi.data.models module
  • Area
    • Area.code
    • Area.name
  • AreaSchema
    • AreaSchema.make_area()
    • AreaSchema.opts
  • Dataset
    • Dataset.add_area()
    • Dataset.add_footnote()
    • Dataset.add_item()
    • Dataset.add_period()
    • Dataset.add_series()
    • Dataset.areas
    • Dataset.extend_observations()
    • Dataset.footnotes
    • Dataset.items
    • Dataset.observations
    • Dataset.periods
    • Dataset.series
    • Dataset.to_dict()
  • DatasetSchema
    • DatasetSchema.make_dataset()
    • DatasetSchema.opts
  • Footnote
    • Footnote.code
    • Footnote.text
  • FootnoteSchema
    • FootnoteSchema.make_footnote()
    • FootnoteSchema.opts
  • Item
    • Item.code
    • Item.display_level
    • Item.name
    • Item.selectable
    • Item.sort_sequence
  • ItemSchema
    • ItemSchema.make_item()
    • ItemSchema.opts
  • Observation
    • Observation.footnotes
    • Observation.is_annual()
    • Observation.period
    • Observation.series_id
    • Observation.value
    • Observation.year
  • ObservationSchema
    • ObservationSchema.make_observation()
    • ObservationSchema.opts
  • Period
    • Period.abbr
    • Period.code
    • Period.name
  • PeriodSchema
    • PeriodSchema.make_period()
    • PeriodSchema.opts
  • Series
    • Series.area_code
    • Series.base_code
    • Series.base_period
    • Series.begin_period
    • Series.begin_year
    • Series.end_period
    • Series.end_year
    • Series.is_seasonally_adjusted()
    • Series.item_code
    • Series.periodicity_code
    • Series.seasonal
    • Series.series_id
    • Series.series_title
  • SeriesSchema
    • SeriesSchema.make_series()
    • SeriesSchema.opts
• kde_cpi.data.parser module
  • parse_areas()
  • parse_footnotes()
  • parse_items()
  • parse_observations()
  • parse_periods()
  • parse_series()
• kde_cpi.data.pipeline module
  • load_full_history()
  • update_current_periods()