Metadata-Version: 2.4
Name: em-data-ingester
Version: 1.0.1
Summary: Python library for pushing data to the Energy Mutual (Konductor) platform
Project-URL: Homepage, https://energymutual.com
Author-email: Energy Mutual <info@energymutual.com>
Keywords: data-ingestion,energy-mutual,iot,konductor,mqtt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications
Requires-Python: >=3.9
Requires-Dist: paho-mqtt>=2.0.0
Description-Content-Type: text/markdown

<a name="readme-top"></a>

<!-- PROJECT LOGO -->
<br />
<div align="center">
  <a href="https://energymutual.com">
    <img src="https://energy-mutual-public.s3.eu-west-2.amazonaws.com/logos/logo.svg" alt="Logo" width="280">
  </a>

<h3 align="center">em-data-ingester</h3>

  <p align="center">
    Python helper module for publishing data to the Energy Mutual platform
  </p>
</div>

<!-- ABOUT THE PROJECT -->
## About Energy Mutual

Energy Mutual helps owners of distributed energy assets make the most of their renewable resources.
<br><br>
Check us out at [energymutual.com](https://energymutual.com)

<!-- GETTING STARTED -->
## Getting Started

### Prerequisites

You will need the following. Please contact Energy Mutual Support if you do not have them already.

1. Certificate files
    - `private.pem.key`
    - `certificate.pem.crt`
    - `CA.pem`
2. Your `client_id` and `topic`

Python 3.9 or newer is required.

### Installation

```sh
pip install em-data-ingester
```

or, with [uv](https://docs.astral.sh/uv/):

```sh
uv add em-data-ingester
```

<!-- USAGE EXAMPLES -->
## Usage

All examples below assume the following:

- `client_id` of `EM123456`
- `topic` of `MyTopicName`
- All required key/certificate files in a `certificates/` subdirectory

### Creating an `EMDataIngester` and connecting

```python
from em_data_ingester import EMDataIngester

ingester = EMDataIngester(
    client_id="EM123456",
    topic="MyTopicName",
    key_path="certificates/private.pem.key",
    cert_path="certificates/certificate.pem.crt",
    ca_path="certificates/CA.pem",
)

ingester.connect()
```

### Adding attributes to the payload

```python
from datetime import datetime, timezone

# Add a powerOutput reading (timestamp defaults to now, UTC)
ingester.add_to_payload("powerOutput", 123, units="kW")

# Or pass an explicit datetime
ingester.add_to_payload(
    "reservoirLevel",
    10,
    dt=datetime.now(timezone.utc),
    units="m",
)
```

_Adding the same attribute name more than once will overwrite the previous value._

### Sending the payload

```python
ingester.send_payload()
```

_This will clear the payload after a successful publish._

### Clearing the payload

```python
ingester.clear_payload()
```

### Viewing the payload

```python
print(ingester.payload)
```

### Closing the connection (Important!)

```python
ingester.end()
```

### Context manager

`EMDataIngester` also works as a context manager, which connects on entry
and closes the connection on exit:

```python
with EMDataIngester(
    client_id="EM123456",
    topic="MyTopicName",
    key_path="certificates/private.pem.key",
    cert_path="certificates/certificate.pem.crt",
    ca_path="certificates/CA.pem",
) as ingester:
    ingester.add_to_payload("powerOutput", 123, units="kW")
    ingester.send_payload()
```

<p align="right">(<a href="#readme-top">back to top</a>)</p>

<!-- CONTACT -->
## Contact

Energy Mutual - info@energymutual.com
