azure_blob_energy_loader

azure_blob_energy_loader

AzureBlobEnergyLoader

AzureBlobEnergyLoader(
    container_name: str | None = None,
    *,
    connection_string: str | None = None,
    account_url: str | None = None,
    credential: Any | None = None,
    sas_url: str | None = None,
    prefix: str = "",
    max_workers: int = 8,
    thousands: str | None = None,
    decimal: str = "."
)

Load CSV energy timeseries and series metadata from Azure Blob Storage.

Bucket structure::

<system>-<region>-<location>-energy-data   (container)
  .meta/
    series.csv           ← series metadata
  csv/
    YYYY/MM/DD/
      <series_id>.csv    ← interval readings: time, value columns

Authentication supports three methods identical to AzureBlobParquetLoader:

1. SAS URL::

   loader = AzureBlobEnergyLoader( sas_url="https://account.blob.core.windows.net/container?sv=...&sig=..." )

2. Connection string::

   loader = AzureBlobEnergyLoader( connection_string="DefaultEndpointsProtocol=https;AccountName=...;", container_name="prod-west-plantA-energy-data", )

3. AAD credential::

   loader = AzureBlobEnergyLoader( account_url="https://account.blob.core.windows.net", container_name="prod-west-plantA-energy-data", credential=DefaultAzureCredential(), )

All load methods return a DataFrame with the standard ts-shape schema::

systime | uuid | value_double | is_delta

where uuid is the series_id (stem of the CSV filename).

Parameters:

Name	Type	Description	Default
container_name	str | None	Target container (not needed with sas_url).	None
connection_string	str | None	Azure Storage connection string.	None
account_url	str | None	Full account URL for AAD auth.	None
credential	Any | None	Azure credential object for AAD auth.	None
sas_url	str | None	Full Blob SAS URL including container and SAS token.	None
prefix	str	Optional blob prefix to narrow all listings.	''
max_workers	int	Max concurrent downloads.	8
thousands	str | None	Thousands separator for pd.read_csv (default None — standard floats).	None
decimal	str	Decimal separator for pd.read_csv (default ".").	'.'

from_account_name classmethod

from_account_name(
    account_name: str,
    container_name: str,
    *,
    credential: Any | None = None,
    endpoint_suffix: str = "blob.core.windows.net",
    prefix: str = "",
    max_workers: int = 8,
    thousands: str | None = None,
    decimal: str = "."
) -> AzureBlobEnergyLoader

Construct a loader using AAD credentials with an account name.

Parameters:

Name	Type	Description	Default
account_name	str	Storage account name.	required
container_name	str	Target container.	required
credential	Any | None	Azure credential (required).	None
endpoint_suffix	str	DNS suffix for sovereign clouds.	'blob.core.windows.net'
prefix	str	Optional listing prefix.	''
max_workers	int	Concurrency for downloads.	8
thousands	str | None	Thousands separator passed to pd.read_csv.	None
decimal	str	Decimal separator passed to pd.read_csv.	'.'

load_series_metadata

load_series_metadata() -> pd.DataFrame

Download .meta/series.csv and return as a DataFrame.

id, label_lvl1, label_lvl2, label_lvl3, label_lvl4,

description, unit, hierarchy_lvl1 … hierarchy_lvl6

Returns an empty DataFrame with the expected columns when the blob does not exist.

load_by_time_range

load_by_time_range(
    start: Union[str, Timestamp],
    end: Union[str, Timestamp],
    series_ids: list[str] | None = None,
) -> pd.DataFrame

Load all CSV files in csv/YYYY/MM/DD/ for each date in [start, end].

Parameters:

Name	Type	Description	Default
start	Union[str, Timestamp]	Start date/datetime (inclusive).	required
end	Union[str, Timestamp]	End date/datetime (inclusive).	required
series_ids	list[str] | None	Optional list of series IDs to load. Loads all if None.	None

Returns:

Type	Description
DataFrame	Standard schema DataFrame: systime | uuid | value_double | is_delta

load_by_series_ids

load_by_series_ids(
    series_ids: list[str],
    start: Union[str, Timestamp] | None = None,
    end: Union[str, Timestamp] | None = None,
) -> pd.DataFrame

Load specific series by ID.

With start/end: constructs direct paths for each (date, series_id) pair. Without dates: lists all blobs under csv/ and filters by stem.

Parameters:

Name	Type	Description	Default
series_ids	list[str]	Series IDs to load.	required
start	Union[str, Timestamp] | None	Optional start date filter.	None
end	Union[str, Timestamp] | None	Optional end date filter.	None

Returns:

Type	Description
DataFrame	Standard schema DataFrame: systime | uuid | value_double | is_delta

stream_by_time_range

stream_by_time_range(
    start: Union[str, Timestamp],
    end: Union[str, Timestamp],
    series_ids: list[str] | None = None,
) -> Iterator[tuple[str, pd.DataFrame]]

Stream CSV files one at a time as (series_id, DataFrame) tuples.

Memory-efficient alternative to load_by_time_range for large date ranges.

Parameters:

Name	Type	Description	Default
start	Union[str, Timestamp]	Start date/datetime (inclusive).	required
end	Union[str, Timestamp]	End date/datetime (inclusive).	required
series_ids	list[str] | None	Optional series filter.	None

Yields:

Type	Description
tuple[str, DataFrame]	(series_id, DataFrame) where DataFrame has the standard schema.

list_series

list_series() -> list[str]

List all series IDs present in the blob store by scanning csv/.

Returns:

Type	Description
list[str]	Sorted list of unique series ID strings.