provident-py

Python client library for the Provident (MeterConnex) utility monitoring API. Supports both synchronous and asynchronous usage with full type safety.

Installation

pip install provident

Quick Start

from datetime import date

from provident import MeterType, Period, ProvidentClient, ProvidentConfig

config = ProvidentConfig(base_url="https://provident.meterconnex.com")

with ProvidentClient(config) as client:
    # Authenticate
    result = client.login("account-id", "password")
    if not result.success:
        print(result.msg)
        return

    # Read meter data
    electricity = client.get_chart_data(
        MeterType.ELECTRICITY, Period.MONTH, date(2026, 1, 1)
    )
    print(f"Units: {electricity.units}")  # kWh
    print(f"Data: {electricity.data}")     # [1.79, 2.76, ...]

    # Read all meter types
    for meter in [MeterType.COLD_WATER, MeterType.HOT_WATER, MeterType.ELECTRICITY]:
        data = client.get_chart_data(meter, Period.YEAR, date(2026, 1, 1))
        print(f"{meter.value}: {len(data.data)} data points in {data.units}")

Async Usage

from datetime import date

from provident import AsyncProvidentClient, MeterType, Period, ProvidentConfig

config = ProvidentConfig(base_url="https://provident.meterconnex.com")

async with AsyncProvidentClient(config) as client:
    await client.login("account-id", "password")

    result = await client.get_chart_data(
        MeterType.ELECTRICITY, Period.DAY, date(2026, 6, 1)
    )
    print(result.data)

API Reference

Client Classes

Authentication

Meter Data

meter_type accepts a MeterType or a plain string, so names returned by get_utilities() can be passed straight back in — useful for accounts whose utilities fall outside MeterType.

Enums

MeterType

Period

Models

ChartDataResult.error mirrors an upstream flag and is independent of whether data is populated — the API is observed returning error: true alongside a complete dataset. Check data to decide whether a response is usable.

Errors

All exceptions inherit from ProvidentError.

Requirements

• Python 3.12+
• httpx
• pydantic v2

Support

If this project saved you some time, consider buying me a beer 🍺!

License

MIT