Auxiliary

auxiliary

Auxiliary data functions and convenience wrappers.

AuxGetter

Bases: Protocol

Typed callable contract for generated auxiliary table getters.

__call__(version=None, ppp_version=None, release_version=None, api_version=API_VERSION, fmt='json', simplify=True, server=None, dataframe_type='pandas')

Fetch one named auxiliary table.

Source code in src/povineq/auxiliary.py

def __call__(
    self,
    version: str | None = None,
    ppp_version: int | None = None,
    release_version: str | None = None,
    api_version: Literal["v1"] = API_VERSION,
    fmt: Literal["json", "csv"] = "json",
    simplify: bool = True,
    server: str | None = None,
    dataframe_type: Literal["pandas", "polars"] = "pandas",
) -> DataFrameLike | PIPResponse:
    """Fetch one named auxiliary table."""
    ...

get_aux(table=None, version=None, ppp_version=None, release_version=None, api_version=API_VERSION, fmt='json', simplify=True, server=None, dataframe_type='pandas', assign_tb=False, replace=False)

Fetch an auxiliary dataset from the PIP API.

When no table is specified, returns a list of available table names. Mirrors pipr::get_aux().

Parameters:

Name	Type	Description	Default
table	str | None	Auxiliary table name (e.g. "gdp", "cpi"). If None, returns a list of available table names.	None
version	str | None	Data version string.	None
ppp_version	int | None	PPP base year.	None
release_version	str | None	Release date in YYYYMMDD format.	None
api_version	Literal['v1']	API version.	API_VERSION
fmt	Literal['json', 'csv']	Response format — "json" (default) or "csv". Arrow is not supported for auxiliary tables.	'json'
simplify	bool	If True (default), return a DataFrame.	True
server	str | None	Server target.	None
dataframe_type	Literal['pandas', 'polars']	"pandas" (default) or "polars".	'pandas'
assign_tb	bool | str	If False (default), return data normally. If True, store the table in memory under its own name. If a string, store it under that name.	False
replace	bool	If True, overwrite existing in-memory tables.	False

Returns:

Type	Description
DataFrameLike | list[str] | PIPResponse | bool	A list[str] of table names when table is None.
DataFrameLike | list[str] | PIPResponse | bool	A :class:~pandas.DataFrame when simplify is True.
DataFrameLike | list[str] | PIPResponse | bool	A :class:~povineq._response.PIPResponse when simplify is False.
DataFrameLike | list[str] | PIPResponse | bool	True when assign_tb is set and the table was stored.

Example

import povineq tables = povineq.get_aux() # list of available tables df = povineq.get_aux("gdp") # fetch GDP table povineq.get_aux("cpi", assign_tb=True) # fetch and store in memory

Source code in src/povineq/auxiliary.py

def get_aux(
    table: str | None = None,
    version: str | None = None,
    ppp_version: int | None = None,
    release_version: str | None = None,
    api_version: Literal["v1"] = API_VERSION,
    fmt: Literal["json", "csv"] = "json",
    simplify: bool = True,
    server: str | None = None,
    dataframe_type: Literal["pandas", "polars"] = "pandas",
    assign_tb: bool | str = False,
    replace: bool = False,
) -> DataFrameLike | list[str] | PIPResponse | bool:
    """Fetch an auxiliary dataset from the PIP API.

    When no *table* is specified, returns a list of available table names.
    Mirrors ``pipr::get_aux()``.

    Args:
        table: Auxiliary table name (e.g. ``"gdp"``, ``"cpi"``). If ``None``,
            returns a list of available table names.
        version: Data version string.
        ppp_version: PPP base year.
        release_version: Release date in ``YYYYMMDD`` format.
        api_version: API version.
        fmt: Response format — ``"json"`` (default) or ``"csv"``.
            Arrow is not supported for auxiliary tables.
        simplify: If ``True`` (default), return a DataFrame.
        server: Server target.
        dataframe_type: ``"pandas"`` (default) or ``"polars"``.
        assign_tb: If ``False`` (default), return data normally. If ``True``,
            store the table in memory under its own name. If a string, store
            it under that name.
        replace: If ``True``, overwrite existing in-memory tables.

    Returns:
        - A ``list[str]`` of table names when *table* is ``None``.
        - A :class:`~pandas.DataFrame` when *simplify* is ``True``.
        - A :class:`~povineq._response.PIPResponse` when *simplify* is ``False``.
        - ``True`` when *assign_tb* is set and the table was stored.

    Example:
        >>> import povineq
        >>> tables = povineq.get_aux()          # list of available tables
        >>> df = povineq.get_aux("gdp")         # fetch GDP table
        >>> povineq.get_aux("cpi", assign_tb=True)  # fetch and store in memory
    """
    params = AuxParams(
        table=table,
        version=version,
        ppp_version=ppp_version,
        release_version=release_version,
        api_version=api_version,
        format=fmt,
    )

    if table is None:
        # Return list of available tables
        query: dict[str, str] = {}
        if version is not None:
            query["version"] = version
        if release_version is not None:
            query["release_version"] = release_version

        response = build_and_execute(ENDPOINT_AUX, query, server=server, api_version=api_version)
        result = cast(
            DataFrameLike | PIPResponse,
            parse_response(response, simplify=simplify, dataframe_type=dataframe_type),
        )

        if simplify and not isinstance(result, PIPResponse):
            tables_list = _table_names(result)
            if tables_list is None:
                return result
            logger.info("Available auxiliary tables", tables=tables_list)
            return tables_list

        return result

    # Fetch specific table
    query = params.to_query_params()
    query.pop("api_version", None)

    response = build_and_execute(ENDPOINT_AUX, query, server=server, api_version=api_version)
    rt = cast(
        DataFrameLike | PIPResponse,
        parse_response(response, simplify=simplify, dataframe_type=dataframe_type),
    )

    if assign_tb is not False:
        tb_name: str
        if assign_tb is True:
            tb_name = table
        elif isinstance(assign_tb, str):
            tb_name = assign_tb
        else:
            raise ValueError("assign_tb must be a bool or a string.")

        if isinstance(rt, pd.DataFrame):
            return set_aux(tb_name, rt, replace=replace)
        if dataframe_type == "polars" and not isinstance(rt, PIPResponse):
            return set_aux(tb_name, cast(PolarsDataFrame, rt).to_pandas(), replace=replace)
        if isinstance(rt, PIPResponse):
            logger.warning(
                "assign_tb requires simplify=True to store the table in memory; "
                "got a PIPResponse object. The table was NOT stored."
            )

    return rt

display_aux(version=None, ppp_version=None, release_version=None, api_version=API_VERSION, fmt='json', simplify=True, server=None)

Display available auxiliary tables.

Fetches the list of auxiliary tables and prints them. Mirrors pipr::display_aux().

Parameters:

Name	Type	Description	Default
version	str | None	Data version string.	None
ppp_version	int | None	PPP base year.	None
release_version	str | None	Release date in YYYYMMDD format.	None
api_version	Literal['v1']	API version.	API_VERSION
fmt	Literal['json', 'csv']	Response format.	'json'
simplify	bool	Passed to :func:get_aux.	True
server	str | None	Server target.	None

Returns:

Type	Description
DataFrame | list[str]	List of available table name strings.

Example

import povineq povineq.display_aux()

Source code in src/povineq/auxiliary.py

def display_aux(
    version: str | None = None,
    ppp_version: int | None = None,
    release_version: str | None = None,
    api_version: Literal["v1"] = API_VERSION,
    fmt: Literal["json", "csv"] = "json",
    simplify: bool = True,
    server: str | None = None,
) -> pd.DataFrame | list[str]:
    """Display available auxiliary tables.

    Fetches the list of auxiliary tables and prints them. Mirrors
    ``pipr::display_aux()``.

    Args:
        version: Data version string.
        ppp_version: PPP base year.
        release_version: Release date in ``YYYYMMDD`` format.
        api_version: API version.
        fmt: Response format.
        simplify: Passed to :func:`get_aux`.
        server: Server target.

    Returns:
        List of available table name strings.

    Example:
        >>> import povineq
        >>> povineq.display_aux()
    """
    result = cast(
        pd.DataFrame | list[str],
        get_aux(
            table=None,
            version=version,
            ppp_version=ppp_version,
            release_version=release_version,
            api_version=api_version,
            fmt=fmt,
            simplify=simplify,
            server=server,
        ),
    )

    if isinstance(result, list):
        logger.info("Available auxiliary tables", tables=result)
        return result

    return result

call_aux(table=None)

Retrieve a previously stored auxiliary table from memory.

Mirrors pipr::call_aux().

Parameters:

Name	Type	Description	Default
table	str | None	Table name to retrieve. If None, lists all stored tables.	None

Returns:

Type	Description
DataFrame | list[str]	The stored DataFrame, or a list of stored table names.

Raises:

Type	Description
KeyError	If the requested table is not in the store.

Example

import povineq povineq.get_aux("gdp", assign_tb=True) df = povineq.call_aux("gdp")

Source code in src/povineq/auxiliary.py

def call_aux(table: str | None = None) -> pd.DataFrame | list[str]:
    """Retrieve a previously stored auxiliary table from memory.

    Mirrors ``pipr::call_aux()``.

    Args:
        table: Table name to retrieve. If ``None``, lists all stored tables.

    Returns:
        The stored DataFrame, or a list of stored table names.

    Raises:
        KeyError: If the requested table is not in the store.

    Example:
        >>> import povineq
        >>> povineq.get_aux("gdp", assign_tb=True)
        >>> df = povineq.call_aux("gdp")
    """
    return _call_aux_store(table)