Skip to content

Info

info

API information, version, and health-check functions.

check_api(api_version=API_VERSION, server=None)

Test connectivity to the PIP API.

Hits the health-check endpoint and returns the parsed response. Mirrors pipr::check_api().

Parameters:

Name Type Description Default
api_version str

API version (only "v1" currently).

 API_VERSION
server str | None

Server target — None/"prod", "qa", or "dev".

 None

Returns:

Type Description
dict

A dict with the health-check response from the API.

Raises:

Type Description
PIPConnectionError

If the network is unreachable.
PIPAPIError

If the health-check endpoint returns an error.
Example

import povineq status = povineq.check_api()

Source code in src/povineq/info.py 
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def check_api(
    api_version: str = API_VERSION,
    server: str | None = None,
) -> dict:
    """Test connectivity to the PIP API.

    Hits the ``health-check`` endpoint and returns the parsed response.
    Mirrors ``pipr::check_api()``.

    Args:
        api_version: API version (only ``"v1"`` currently).
        server: Server target — ``None``/``"prod"``, ``"qa"``, or ``"dev"``.

    Returns:
        A dict with the health-check response from the API.

    Raises:
        PIPConnectionError: If the network is unreachable.
        PIPAPIError: If the health-check endpoint returns an error.

    Example:
        >>> import povineq
        >>> status = povineq.check_api()
    """
    logger.debug("check_api()")
    response = build_and_execute(ENDPOINT_HEALTH_CHECK, {}, server=server, api_version=api_version)
    result = parse_response(response, simplify=False, is_raw=True)
    if isinstance(result, dict):
        return result
    return {"status": response.status_code}

get_versions(api_version=API_VERSION, server=None, simplify=True, dataframe_type='pandas')

List available data versions.

Mirrors pipr::get_versions().

Parameters:

Name Type Description Default
api_version str

API version (only "v1" currently).

 API_VERSION
server str | None

Server target.

 None
simplify bool

If True (default), return a DataFrame.

 True
dataframe_type Literal['pandas', 'polars']

"pandas" (default) or "polars".

 'pandas'

Returns:

Type Description
DataFrame | dict | list

A DataFrame of available versions when simplify is True,
DataFrame | dict | list

or the raw dict/list otherwise.
Example

import povineq df = povineq.get_versions()

Source code in src/povineq/info.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def get_versions(
    api_version: str = API_VERSION,
    server: str | None = None,
    simplify: bool = True,
    dataframe_type: Literal["pandas", "polars"] = "pandas",
) -> pd.DataFrame | dict | list:
    """List available data versions.

    Mirrors ``pipr::get_versions()``.

    Args:
        api_version: API version (only ``"v1"`` currently).
        server: Server target.
        simplify: If ``True`` (default), return a DataFrame.
        dataframe_type: ``"pandas"`` (default) or ``"polars"``.

    Returns:
        A DataFrame of available versions when *simplify* is ``True``,
        or the raw dict/list otherwise.

    Example:
        >>> import povineq
        >>> df = povineq.get_versions()
    """
    logger.debug("get_versions()")
    response = build_and_execute(ENDPOINT_VERSIONS, {}, server=server, api_version=api_version)
    return parse_response(response, simplify=simplify, dataframe_type=dataframe_type)

get_pip_info(api_version=API_VERSION, server=None)

Get metadata about the PIP API.

Mirrors pipr::get_pip_info().

Parameters:

Name Type Description Default
api_version str

API version (only "v1" currently).

 API_VERSION
server str | None

Server target.

 None

Returns:

Type Description
dict

A dict with API metadata (version, endpoints, etc.).
Example

import povineq info = povineq.get_pip_info()

Source code in src/povineq/info.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def get_pip_info(
    api_version: str = API_VERSION,
    server: str | None = None,
) -> dict:
    """Get metadata about the PIP API.

    Mirrors ``pipr::get_pip_info()``.

    Args:
        api_version: API version (only ``"v1"`` currently).
        server: Server target.

    Returns:
        A dict with API metadata (version, endpoints, etc.).

    Example:
        >>> import povineq
        >>> info = povineq.get_pip_info()
    """
    logger.debug("get_pip_info()")
    response = build_and_execute(ENDPOINT_PIP_INFO, {}, server=server, api_version=api_version)
    result = parse_response(response, simplify=False, is_raw=True)
    if isinstance(result, dict):
        return result
    return {}