From d1c5c5ae1006db55c126af6475236d327fff357d Mon Sep 17 00:00:00 2001 From: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> Date: Tue, 19 Aug 2025 16:06:44 +0200 Subject: [PATCH 1/5] Update README.md Add detailed description Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> --- README.md | 79 ++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 70 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index e248bc8..accce8c 100644 --- a/README.md +++ b/README.md @@ -25,20 +25,80 @@ The following platforms are officially supported (tested): If you want to know how to build this project and contribute to it, please check out the [Contributing Guide](CONTRIBUTING.md). +## Getting Started -## Usage +To get started, follow the steps below to set up your development environment and run the client. -Please also refer to source of the [CLI tool](https://github.com/frequenz-floss/frequenz-client-reporting-python/blob/v0.x.x/src/frequenz/client/reporting/cli/__main__.py) -for a practical example of how to use the client. +### 1. Install VS Code + +Download and install **Visual Studio Code** from the [official website](https://code.visualstudio.com/). + +Once installed, add the following extensions: + +- [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) +- [Jupyter extension](https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter) + +These enable Python development and interactive notebooks within VS Code. + +### 2. Set Up a Virtual Environment + +It is recommended to use a **virtual environment** for isolating dependencies. +When using a virtual environment, you create something like a sandbox or containerized workspace that isolates dependencies and packages so they don’t conflict with the system or other projects. After creating the virtual environment, you can install all packages you need for the current project. To set up an initial virtual environment for using the Reporting API, go through the following steps: -### Installation +### Linux / macOS ```bash -# Choose the version you want to install -VERSION=0.18.0 -pip install frequenz-client-reporting==$VERSION +# Create a virtual environment +python3 -m venv .venv + +# Activate the environment +source .venv/bin/activate + +# Install the version of the reporting client you want to use +pip install frequenz-client-reporting==0.18.0 + +# Install python-dotenv --> Used to load environment variables from a `.env` file into the projects environment +pip install python-dotenv + +# Install ipkernel --> Python execution backend for Jupyter +pip install ipkernel + +# Register the virtual environment as a kernel +python -m ipykernel install --user --name=myenv --display-name "Python (myenv)" + +# Install pandas +pip install pandas ``` +## Create API Keys via Kuiper + +To access the API, a key has to be created via Kuiper and stored locally on your computer. For that go through the following steps: + +### 1 create .env file + +When creating the API key, you will get two keys. One is the API key itself and the other one is the API secret. Create a textfile named ".env" in your project folder where you can store the API key and the API secret. + +```bash +# .env +REPORTING_API_AUTH_KEY= +REPORTING_API_SIGN_SECRET= +``` + +### 2 Create API key via Kuiper + +Log into your Kuiper account and click on your email-address on the bottom left. Then continue with "API keys" and "Create API key". The created API key will be shown in the UI. This is the only time, the API key will be shown to you. whenever you loose it, you have to create a new one. +Copy the API key and the API secret and add it to the .env file. + +```bash +# .env +REPORTING_API_AUTH_KEY=EtQurK8LXA8vmEd4M6DqxeNp +REPORTING_API_SIGN_SECRET=DCG5x7XrJa2hN3spRTjVyQk9w16xXqR6hEUkYcoCG9yjx7Pp +``` + +## Usage + +Please also refer to source of the [CLI tool](https://github.com/frequenz-floss/frequenz-client-reporting-python/blob/v0.x.x/src/frequenz/client/reporting/cli/__main__.py) +for a practical example of how to use the client. ### Initialize the client @@ -52,15 +112,16 @@ See [this documentation](https://github.com/frequenz-floss/frequenz-client-base- ```python from datetime import datetime, timedelta import os +import pandas as pd from frequenz.client.common.metric import Metric from frequenz.client.reporting import ReportingApiClient +load_dotenv() + # Change server address SERVER_URL = "grpc://replace-this-with-your-server-url:port" AUTH_KEY = os.environ['REPORTING_API_AUTH_KEY'].strip() -# It is recommended to use a proper secret store to get the secret -# For local development, make sure not to leave it in the shell history SIGN_SECRET= os.environ['REPORTING_API_SIGN_SECRET'].strip() client = ReportingApiClient(server_url=SERVER_URL, auth_key=AUTH_KEY, sign_secret=SIGN_SECRET) ``` From 3cfff6bc718738029c8ec1cd592305d0c9d18584 Mon Sep 17 00:00:00 2001 From: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> Date: Tue, 19 Aug 2025 17:03:29 +0200 Subject: [PATCH 2/5] Update README.md add more detailed description to the README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 58 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index accce8c..21ecb2a 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,6 @@ A Python client for interacting with the Frequenz Reporting API to efficiently r > **Who should use this?** > This client is for developers building applications on top of Frequenz's platform who need structured access to historical component or sensor data via Python or CLI. - ## Supported Platforms The following platforms are officially supported (tested): @@ -27,7 +26,7 @@ check out the [Contributing Guide](CONTRIBUTING.md). ## Getting Started -To get started, follow the steps below to set up your development environment and run the client. +To get started, create a directory for your project and follow the steps below to set up your development environment and run the client. ### 1. Install VS Code @@ -45,22 +44,27 @@ These enable Python development and interactive notebooks within VS Code. It is recommended to use a **virtual environment** for isolating dependencies. When using a virtual environment, you create something like a sandbox or containerized workspace that isolates dependencies and packages so they don’t conflict with the system or other projects. After creating the virtual environment, you can install all packages you need for the current project. To set up an initial virtual environment for using the Reporting API, go through the following steps: -### Linux / macOS +#### Linux / macOS ```bash +### Go to your projects directory, open a terminal and run the following commands + # Create a virtual environment python3 -m venv .venv # Activate the environment -source .venv/bin/activate +source .venv/bin/activate # when using bash +source .venv/bin/activate.fish # when using fish # Install the version of the reporting client you want to use pip install frequenz-client-reporting==0.18.0 -# Install python-dotenv --> Used to load environment variables from a `.env` file into the projects environment +# Install python-dotenv +# --> Used to load environment variables from a `.env` file into the projects environment pip install python-dotenv -# Install ipkernel --> Python execution backend for Jupyter +# Install ipkernel +# --> Python execution backend for Jupyter pip install ipkernel # Register the virtual environment as a kernel @@ -68,6 +72,41 @@ python -m ipykernel install --user --name=myenv --display-name "Python (myenv)" # Install pandas pip install pandas + +# Deactivate the environment +deactivate +``` + +#### Windows (PowerShell) + +```powershell +### Go to your projects directory, open PowerShell and run the following commands + +# Create a virtual environment +python -m venv .venv + +# Activate the environment +.venv\Scripts\Activate.ps1 + +# Install the version of the reporting client you want to use +pip install frequenz-client-reporting==0.18.0 + +# Install python-dotenv +# --> Used to load environment variables from a `.env` file into the project's environment +pip install python-dotenv + +# Install ipykernel +# --> Python execution backend for Jupyter +pip install ipykernel + +# Register the virtual environment as a kernel +python -m ipykernel install --user --name=myenv --display-name "Python (myenv)" + +# Install pandas +pip install pandas + +# Deactivate the environment +deactivate ``` ## Create API Keys via Kuiper @@ -76,7 +115,8 @@ To access the API, a key has to be created via Kuiper and stored locally on your ### 1 create .env file -When creating the API key, you will get two keys. One is the API key itself and the other one is the API secret. Create a textfile named ".env" in your project folder where you can store the API key and the API secret. +When creating the API key, you will get two keys. One is the API key itself and the other one is the API secret. Go to your projects directory and create a textfile named ".env" in your project folder where you can store the API key and the API secret. +Prepare the textfile as follows: ```bash # .env @@ -100,26 +140,34 @@ REPORTING_API_SIGN_SECRET=DCG5x7XrJa2hN3spRTjVyQk9w16xXqR6hEUkYcoCG9yjx7Pp Please also refer to source of the [CLI tool](https://github.com/frequenz-floss/frequenz-client-reporting-python/blob/v0.x.x/src/frequenz/client/reporting/cli/__main__.py) for a practical example of how to use the client. +### Create a notebook + +Open your projects directory with VS Code. You should see your .venv and .env files in the directory when using VS Code. +Create a new .ipynb file (Jupyter notebook file) in the directory. When selecting the empty ipynb file, you will find "Select Kernel" on the top right of the file. Click on it and select "Jupyter Kernel" > "Python (myenv). Now the notebook will use your virtual environment as an interpreter. + ### Initialize the client To use the Reporting API client, you need to initialize it with the server URL and authentication credentials. -The server URL should point to your Frequenz Reporting API instance, and you will need an authentication key and a signing secret. -See [this documentation](https://github.com/frequenz-floss/frequenz-client-base-python/blob/v0.x.x/README.md#authorization-and-signing) for further details. +The server URL should point to your Frequenz Reporting API instance, and you will need an authentication key and a signing secret, as described above. > **Security Note** > Always keep your authentication key and signing secret secure. Do not hard-code them in your source code or share them publicly. ```python +# Import basic packages +from dotenv import load_dotenv from datetime import datetime, timedelta import os import pandas as pd +# Import Metrics and ReportingApiClient from frequenz.client.common.metric import Metric from frequenz.client.reporting import ReportingApiClient +# Read the API key from .env and sets it as environment variables in the current python process load_dotenv() -# Change server address +# Create Reporting API Client SERVER_URL = "grpc://replace-this-with-your-server-url:port" AUTH_KEY = os.environ['REPORTING_API_AUTH_KEY'].strip() SIGN_SECRET= os.environ['REPORTING_API_SIGN_SECRET'].strip() From 770a128b1988959cc1dd0484a34b1d879d908aea Mon Sep 17 00:00:00 2001 From: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> Date: Tue, 19 Aug 2025 17:14:03 +0200 Subject: [PATCH 3/5] Update README.md add more details to README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> --- README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 21ecb2a..a92cc5c 100644 --- a/README.md +++ b/README.md @@ -115,7 +115,7 @@ To access the API, a key has to be created via Kuiper and stored locally on your ### 1 create .env file -When creating the API key, you will get two keys. One is the API key itself and the other one is the API secret. Go to your projects directory and create a textfile named ".env" in your project folder where you can store the API key and the API secret. +When creating the API key, you will get two keys. One is the API key itself and the other one is the API secret. Go to your projects directory and create a textfile named `.env` where you can store the API key and the API secret. Prepare the textfile as follows: ```bash @@ -126,8 +126,8 @@ REPORTING_API_SIGN_SECRET= ### 2 Create API key via Kuiper -Log into your Kuiper account and click on your email-address on the bottom left. Then continue with "API keys" and "Create API key". The created API key will be shown in the UI. This is the only time, the API key will be shown to you. whenever you loose it, you have to create a new one. -Copy the API key and the API secret and add it to the .env file. +Log into your Kuiper account and click on your email-address on the bottom left. Then continue with `API keys` and `Create API key`. The created API key will be shown in the UI. This is the only time, the API key will be shown to you. whenever you loose it, you have to create a new one. +Copy the API key and the API secret and add it to the `.env` file. ```bash # .env @@ -142,15 +142,18 @@ for a practical example of how to use the client. ### Create a notebook -Open your projects directory with VS Code. You should see your .venv and .env files in the directory when using VS Code. -Create a new .ipynb file (Jupyter notebook file) in the directory. When selecting the empty ipynb file, you will find "Select Kernel" on the top right of the file. Click on it and select "Jupyter Kernel" > "Python (myenv). Now the notebook will use your virtual environment as an interpreter. +Open your projects directory with VS Code. You should see your `.venv` and `.env` files in the directory when using VS Code. +Create a new `.ipynb` file (Jupyter notebook file) in the directory. When selecting the empty ipynb file, you will find `Select Kernel` on the top right of the file. Click on it and select `Jupyter Kernel > Python (myenv)`. Now the notebook will use your virtual environment as an interpreter. ### Initialize the client To use the Reporting API client, you need to initialize it with the server URL and authentication credentials. The server URL should point to your Frequenz Reporting API instance, and you will need an authentication key and a signing secret, as described above. -> **Security Note** +> **SERVER URL:** +> Please ask your service administrator for the SERVER URL + +> **Security Note:** > Always keep your authentication key and signing secret secure. Do not hard-code them in your source code or share them publicly. ```python From 339210fb675f67601455817e1ca801bfc3d64f8d Mon Sep 17 00:00:00 2001 From: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> Date: Tue, 19 Aug 2025 17:17:35 +0200 Subject: [PATCH 4/5] Update README.md minor change in README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a92cc5c..3f0795d 100644 --- a/README.md +++ b/README.md @@ -109,7 +109,7 @@ pip install pandas deactivate ``` -## Create API Keys via Kuiper +## API Keys To access the API, a key has to be created via Kuiper and stored locally on your computer. For that go through the following steps: From 1747dc776558358bf3a20f42824a243f7292b799 Mon Sep 17 00:00:00 2001 From: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> Date: Tue, 19 Aug 2025 17:18:45 +0200 Subject: [PATCH 5/5] Update README.md minor change in README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3f0795d..0033b04 100644 --- a/README.md +++ b/README.md @@ -113,7 +113,7 @@ deactivate To access the API, a key has to be created via Kuiper and stored locally on your computer. For that go through the following steps: -### 1 create .env file +### 1. create .env file When creating the API key, you will get two keys. One is the API key itself and the other one is the API secret. Go to your projects directory and create a textfile named `.env` where you can store the API key and the API secret. Prepare the textfile as follows: @@ -124,7 +124,7 @@ REPORTING_API_AUTH_KEY= REPORTING_API_SIGN_SECRET= ``` -### 2 Create API key via Kuiper +### 2. Create API key via Kuiper Log into your Kuiper account and click on your email-address on the bottom left. Then continue with `API keys` and `Create API key`. The created API key will be shown in the UI. This is the only time, the API key will be shown to you. whenever you loose it, you have to create a new one. Copy the API key and the API secret and add it to the `.env` file.