KUB
An async Python library for retrieving utility usage data from the Knoxville Utilities Board (KUB) API.
Features
- Authenticates via Azure AD B2C using PKCE OAuth2, mirroring the KUB web app flow
- Supports electricity, gas, water, and wastewater services
- Retrieves hourly usage and cost data for any date range
- Session management with automatic token refresh
- Compatible with Home Assistant custom components
Requirements
- Python 3.12 or higher
- aiohttp 3.9 or higher
Installation
pip install kub
Usage
Basic setup
import asyncio
from kub import KubUtility
async def main():
utility = KubUtility("your@email.com", "yourpassword")
# Retrieve usage for the last 31 days
usage = await utility.retrieve_last_31_days()
print(usage)
asyncio.run(main())
Available methods
| Method | Description |
|---|---|
retrieve_last_31_days() |
Fetches hourly usage for the past 31 days across all services |
retrieve_monthly_usage() |
Fetches hourly usage from the first of the current month to today |
retrieve_recent_usage(days=7, start_date=None) |
Fetches the entire current month plus at least days of overlap; an earlier start_date extends the window for catch-up |
retrieve_last_year() |
Fetches a year of history for backfills or repairs |
retrieve_usage_by_range(start_date, end_date) |
Fetches usage for a custom range; dates are YYYY-MM-DD strings |
retrieve_account_info() |
Fetches account metadata (account ID, person ID, service list) without pulling usage data |
Usage data structure
The usage attribute is keyed by service point, then by date, then by time. For
an account with one meter for a utility, the service-point key is the utility
name (for example, "electricity"). When an account has multiple meters of the
same utility, the key is <utility>_<service-point-id> (for example,
"electricity_12345"). All accounts on the login are discovered in API order.
The first account retains these key rules; additional accounts always use
<utility>_<service-point-id>, keeping the first account's keys stable.
account_ids lists the accounts and account_people maps them to their owners.
Each usage request replaces the cached snapshot for that service with the
requested range. Use retrieve_recent_usage() for polling that includes recent
revisions and the whole current month. Its default dates use America/New_York.
{
"electricity": {
"2026-05-01": {
"08:00:00": {
"id": "...",
"readDateTime": "2026-05-01T08:00:00",
"utilityUsed": 0.42,
"uom": "kWh",
"cost": 0.06
},
...
},
...
},
"gas": { ... },
"water": { ... },
"wastewater": { ... }
}
Monthly totals (for the current calendar month) are available via monthly_total:
utility.monthly_total["electricity"]
# {"usage": 312.5, "cost": 42.18}
Totals include only intervals in the current month and year in America/New_York within the fetched range. Hourly timestamps mark the end of the interval, so a midnight reading on the first belongs to the preceding month.
Supported utility types
The KUBUtilityTypes enum represents the services KUB provides:
from kub import KUBUtilityTypes
KUBUtilityTypes.ELECTRICITY
KUBUtilityTypes.GAS
KUBUtilityTypes.WATER
KUBUtilityTypes.WASTEWATER
Only the services active on your account are populated. Check utility.service_list
after calling any retrieval method to see the available service-point keys.
Home Assistant
This library is designed to work as a dependency for a Home Assistant custom component. Place the kub directory inside custom_components/ and import from it using standard relative imports.
Development
Install development dependencies:
pip install -e ".[dev]"
Run the test suite:
pytest
License
MIT
Metadata
Release files for kub 0.8.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kub-0.8.1.tar.gz | 17.1 kB | With provenance | Details for kub-0.8.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kub-0.8.1-py3-none-any.whl | Python 3 | none | any | Details for kub-0.8.1-py3-none-any.whl |
Total release size: 29.3 kB
Release files / kub-0.8.1.tar.gz
| Download URL | kub-0.8.1.tar.gz |
|---|---|
| Size | 17.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8133d0ec8dff11c5e7ff63afe4eb1cf5618d3a33691e2a2e9bd06fa1b937053d
|
|
BLAKE2b-256 checksum How to use checksums |
c341b15bc51790fee112457181d0fb18b950137def12b3f7f5f13260600c7dac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logRelease files / kub-0.8.1-py3-none-any.whl
| Download URL | kub-0.8.1-py3-none-any.whl |
|---|---|
| Size | 12.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3f6d53fc12d3a8efb323873274258af93c9f3508a4aec881a3883cf7f6d1199f
|
|
BLAKE2b-256 checksum How to use checksums |
014ae9a5c11de52cfb28005b7a9437e72872d8aebe7427d2022ac253d2eab9f1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logSecurity for kub 0.8.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kub-0.8.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.