Eneffco Connection

EneffcoConnection

class eta_nexus.connections.EneffcoConnection(url: str, usr: str, pwd: str, *, nodes: Nodes[EneffcoNode] | None = None, retry_total: int = 3, retry_backoff_factor: float = 1.0)[source]

EneffcoConnection is a class to download and upload multiple features from and to the Eneffco database as timeseries.

Parameters:

url – URL of the server with scheme (https://).
usr – Username in EnEffco for login.
pwd – Password in EnEffco for login.
nodes – Nodes to select in connection.
retry_total – Total number of retries for failed HTTP requests (default: 3).
retry_backoff_factor – Backoff factor for retries (default: 1s-> e.g. 1s, 2s, 4s for 3 retries).

API_PATH: str = '/API/v1.0'

logger: Logger = <Logger eta_nexus.connections.eneffco_connection (WARNING)>

property authentication: HTTPBasicAuth: Return the authentication method for the API.

classmethod from_ids(ids: Sequence[str], url: str, usr: str, pwd: str) → EneffcoConnection[source]

Initialize the connection object from an Eneffco protocol through the node IDs.

Parameters:

ids – Identification of the Node.
url – URL for EnEffco connection.
usr – Username for Eneffco login.
pwd – Password for Eneffco login.

Returns:

EneffcoConnection object.

read(nodes: EneffcoNode | Nodes[EneffcoNode] | None = None) → pd.DataFrame[source]

Download current value from the Eneffco Database.

Parameters:: nodes – Single node or list/set of nodes to read values from.
Returns:: pandas.DataFrame containing the data read from the connection.

write(values: Mapping[EneffcoNode, Primitive] | pd.Series[datetime, Primitive], time_interval: timedelta | None = None) → None[source]

Writes some values to the Eneffco Database.

Parameters:

values – Dictionary of nodes and data to write {node: value}.
time_interval – Interval between datapoints (i.e. between “From” and “To” in Eneffco Upload) (default 1s).

read_info(nodes: EneffcoNode | Nodes[EneffcoNode] | None = None) → pd.DataFrame[source]

Read additional datapoint information from Database.

Parameters:: nodes – Single node or list/set of nodes values from.
Returns:: pandas.DataFrame containing the data read from the connection.

subscribe(handler: SubscriptionHandler, nodes: EneffcoNode | Nodes[EneffcoNode] | None = None, interval: TimeStep = 1) → None[source]

Subscribe to nodes and call handler when new data is available. This will return only the last available values.

Parameters:

handler – SubscriptionHandler object with a push method that accepts node, value pairs.
interval – Interval for receiving new data. It is interpreted as seconds when given as an integer.
nodes – Single node or list/set of nodes to subscribe to.

read_series(from_time: datetime, to_time: datetime, nodes: EneffcoNode | Nodes[EneffcoNode] | None = None, interval: TimeStep = 1, **kwargs: Any) → pd.DataFrame[source]

Download timeseries data from the Eneffco Database.

Parameters:

nodes – Single node or list/set of nodes to read values from.
from_time – Starting time to begin reading (included in output).
to_time – Time to stop reading at (not included in output).
interval – Interval between time steps. It is interpreted as seconds if given as integer.
kwargs – Other parameters (ignored by this connection).

Returns:

Pandas DataFrame containing the data read from the connection.

read_node(node: EneffcoNode, from_time: datetime, to_time: datetime, interval: timedelta, **kwargs: Any) → pd.DataFrame[source]

Read data from a REST API endpoint.

Parameters:

node – Node to read data from.
from_time – Start of the time series (timezone-aware).
to_time – End of the time series (timezone-aware).
interval – Time interval between data points.
kwargs – Additional subclass-specific arguments.

Returns:

DataFrame containing the data read from the API.

subscribe_series(handler: SubscriptionHandler, req_interval: TimeStep, offset: TimeStep | None = None, nodes: EneffcoNode | Nodes[EneffcoNode] | None = None, interval: TimeStep = 1, data_interval: TimeStep = 1, **kwargs: Any) → None[source]

Subscribe to nodes and call handler when new data is available. This will always return a series of values. If nodes with different intervals should be subscribed, multiple connection objects are needed.

Parameters:

handler – SubscriptionHandler object with a push method that accepts node, value pairs.
req_interval – Duration covered by requested data (time interval). Interpreted as seconds if given as int.
offset – Offset from datetime.now from which to start requesting data (time interval). Interpreted as seconds if given as int. Use negative values to go to past timestamps.
data_interval – Time interval between values in returned data. Interpreted as seconds if given as int.
interval – interval (between requests) for receiving new data. It is interpreted as seconds when given as an integer.
nodes – Single node or list/set of nodes to subscribe to.
kwargs – Other, ignored parameters.

close_sub() → None[source]: Close an open subscription.

id_from_code(code: str, *, raw_datapoint: bool = False) → str[source]

Function to get the raw Eneffco ID corresponding to a specific (raw) datapoint.

Parameters:

code – Exact Eneffco code.
raw_datapoint – Returns raw datapoint ID.

timestr_from_datetime(dt: datetime) → str[source]

Create an Eneffco compatible time string.

Parameters:: dt – Datetime object to convert to string.
Returns:: Eneffco compatible time string.

url_parsed: ParseResult: URL of the server to connect to

usr: str | None: Username for login to server

pwd: str | None: Password for login to server

exc: BaseException | None

EneffcoNode

class eta_nexus.nodes.EneffcoNode(name: str, url: str, protocol: str, *args: Any, **kwargs: Any)[source]

Node for the Eneffco API.

eneffco_code: str: Eneffco datapoint code / ID.

connection_identifier() → str: Unique identifier for the connection that is associated with the node (i.e. would be created by Connection.from_node())

name: str: Name for the node.

url: str: URL of the connection.

url_parsed: ParseResult: Parse result object of the URL (in case more post-processing is required).

usr: str | None: Username for login to the connection (default: None).

pwd: str | None: Password for login to the connection (default: None).

interval: str | None: Interval

dtype: Callable | None: Data type of the node (for value conversion). Note that strings will be interpreted as utf-8 encoded. If you do not want this behaviour, use ‘bytes’.

Example Usage

A simple example using the Eneffco Connection:

# Create the connection object
# API Token must be provided by a .env file
connection = EneffcoConnection.from_ids(
    ["CH1.Elek_U.L1-N", "Pu3.425.ThHy_Q"],
    url="https://someurl.com/",
    usr="username",
    pwd="password",
)

# Read series data within a specified time interval
from_time = datetime.fromisoformat("2019-01-01 00:00:00")
to_time = datetime.fromisoformat("2019-01-02 00:00:00")
return connection.read_series(from_time, to_time, interval=900)