Edit README by merlin-esser-frequenz · Pull Request #219 · frequenz-floss/frequenz-client-reporting-python

merlin-esser-frequenz · 2025-08-19T15:20:09Z

Add more details for setting up and using the API

Add detailed description Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com>

add more detailed description to the README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com>

add more details to README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com>

minor change in README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com>

matthias-wende-frequenz

I'm unsure if add specific use cases to the readme is what we want. You should also squash your commits or give each of them a meaningful commit message.

matthias-wende-frequenz · 2025-08-20T07:12:53Z


-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


I don't think we shouldn't advertise specific editors in this library.

matthias-wende-frequenz · 2025-08-20T07:14:57Z

+
+#### Linux / macOS
+
+```bash


In general I like the idea of having copy paste friendly instructions. Maybe we should only focus on the reporting part in this case and skip the notebook part. I also suggest to create a separate manual page for dealing with notebooks and keep the README at a bare minimum.

I agreee with @matthias-wende-frequenz

Also this applies to most if not all projects, so probably something to be discussed here:

Improve and split CONTRIBUTING.md frequenz-repo-config-python#266

cwasicki

I don't think these recommendations should go into the reporting client README, because they are 1) optional recommendations not required for the reporting client to run, 2) not specific to the reporting client but potentially useful for other python clients or our python tools in general.

cwasicki · 2025-08-20T07:05:52Z


-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


This is not related to the reporting API, but a general recommendation how to set up a working environment. If we want to document this, I suggest to put it into another place than the reporting client README and link to it from here.

Apart from that, this sounds like vscode is required for the reporting API. It is not, and IMO it's overkill to recommend it.

cwasicki · 2025-08-20T07:08:20Z

+
+These enable Python development and interactive notebooks within VS Code.
+
+### 2. Set Up a Virtual Environment


Same for this section, not only relevant for reporting API. Do we have instructions on environments already somewhere documented @llucax ?

The problem with documenting it here is that we will have to maintain similar sections in all client repositories.

Improve and split CONTRIBUTING.md frequenz-repo-config-python#266

Now we have https://github.com/frequenz-floss/docs/, so we can put common docs here and leave only project-specific stuff for the project. I think we still need some time to sort this out properly, but I have a rough idea of how we should move forward.

cwasicki · 2025-08-20T07:09:59Z

+
+# Install python-dotenv
+# --> Used to load environment variables from a `.env` file into the projects environment
+pip install python-dotenv


This should be optional

And I would remove it, we shouldn't be so opinionated on how users should run stuff. We could provide some separate guide for a newbie with some opinionated suggested configuration and IDE, but that should be definitely not part of the README.

cwasicki · 2025-08-20T07:11:03Z

+
+# Install ipkernel
+# --> Python execution backend for Jupyter
+pip install ipkernel


Also optional. Moreover I think there is a typo in the package name.

I don't even know what this is 😆

cwasicki · 2025-08-20T07:11:34Z

+pip install ipkernel
+
+# Register the virtual environment as a kernel
+python -m ipykernel install --user --name=myenv --display-name "Python (myenv)"


All of these things are optional and not required for the reporting API.

cwasicki · 2025-08-20T07:12:25Z

+
+```bash
+# .env
+REPORTING_API_AUTH_KEY=EtQurK8LXA8vmEd4M6DqxeNp


I hope this is not what it looks like.

You can be relieved it's not an active key!

Please remove the key no matter if valid or not and replace with just a template parameter like . Surely, you can find a suggestion from the GPTs of this world ;-)

cwasicki · 2025-08-20T07:14:07Z

+from dotenv import load_dotenv
 from datetime import datetime, timedelta
 import os
+import pandas as pd


Why this import?

to use pandas data frames

cwasicki · 2025-08-20T07:15:43Z

-VERSION=0.18.0
-pip install frequenz-client-reporting==$VERSION
+# .env
+REPORTING_API_AUTH_KEY=


Probably good to follow our standard naming REPORTING_API_{URL,KEY,SECRET}

Yes, please.

@cwasicki this is copied from the current README

Since we introduced signing keys we are trying to use these names as standard:

XXX_API_URL

XXX_API_AUTH_KEY

XXX_API_SIGN_SECRET

as using plain KEY and SECRET could be ambiguous.

merlin-esser-frequenz · 2025-08-20T17:56:45Z

Thanks for the review!

From what I read, I realized, that I didnt really understand, what the README is supposed to be used for.
From my thinking, I wanted to collect a bunch of information for Customers, who are not that familiar with things like that, and give them a point to start.

So I guess a pdf where I summarize these steps and actively highlight, that these are just suggestions to start and that the API can be used in a lot of different other ways, makes definetly more sense.

After talking to the Customer, I realized, that they are only little steps away from really using the API to create their own notebooks, and for that I wanted to provide some help.

matthias-wende-frequenz · 2025-08-20T19:03:34Z

So I guess a pdf where I summarize these steps and actively highlight, that these are just suggestions to start and that the API can be used in a lot of different other ways, makes definetly more sense.

After talking to the Customer, I realized, that they are only little steps away from really using the API to create their own notebooks, and for that I wanted to provide some help.

This repository has an auto rendered documentation which is in sync with the code. That's the place, where all of the above can be placed, for instance as tutorials or simple or advanced usage examples.

https://frequenz-floss.github.io/frequenz-client-reporting-python/

llucax · 2025-08-22T07:16:18Z

+
+# Activate the environment
+source .venv/bin/activate # when using bash
+source .venv/bin/activate.fish # when using fish


I think we should stick with one example environment and let users with more niche configuration figure things out for themselves (i.e. skip fish and mention at the start of the readme that we assume bash as the shell), otherwise we need to maintain all possible user configuration in our docs, which doesn't make a lot of sense.

Again something for:

Improve and split CONTRIBUTING.md frequenz-repo-config-python#266

llucax · 2025-08-22T07:20:48Z

+pip install pandas
+
+# Deactivate the environment
+deactivate


Why deactivating the env? If users do this then nothing works.

llucax · 2025-08-22T07:21:08Z

+deactivate
+```
+
+#### Windows (PowerShell)


We are not officially supporting Windows yet, so I wouldn't include a section on how to install in a platform we don't officially support. Maybe we should start supporting Windows, but that's a separate discussion. Again, all of this is pretty general, so we probably should include it in docs for all projects.

In the context of making this a separate tutorial for newbies, we could even leave this section with a big warning saying that Windows is not YET officially supported.

Well it might discourage some people start trying to use it on Windows and hence they might solve some issues for us on the way.

llucax

All in all, I think this is useful, but it is definitely not for a README.

BUT if you split what you created and add it to docs/tutorials/basic.md, then I guess we get a nice tutorial for newbies.

llucax · 2025-08-22T07:21:41Z

+
+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


This is also opinionated, creating an .env file is not necessary, there are many other ways to define an env var.

llucax · 2025-08-22T07:23:08Z

-VERSION=0.18.0
-pip install frequenz-client-reporting==$VERSION
+# .env
+REPORTING_API_AUTH_KEY=


Since we introduced signing keys we are trying to use these names as standard:

XXX_API_URL

XXX_API_AUTH_KEY

XXX_API_SIGN_SECRET

as using plain KEY and SECRET could be ambiguous.

llucax · 2025-08-25T10:08:25Z

Here is an example on how to convert this into a tutorial:

Convert README changes to a Newcomer Tutorial merlin-esser-frequenz/frequenz-client-reporting-python#1

llucax · 2025-09-11T07:30:51Z

Closing in favor of #220.

merlin-esser-frequenz added 5 commits August 19, 2025 16:06

Update README.md

d1c5c5a

Add detailed description Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com>

Update README.md

3cfff6b

add more detailed description to the README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com>

Update README.md

770a128

add more details to README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com>

Update README.md

339210f

minor change in README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com>

Update README.md

1747dc7

minor change in README Signed-off-by: merlin-esser-frequenz <116643299+merlin-esser-frequenz@users.noreply.github.com>

github-actions Bot added the part:docs Affects the documentation label Aug 19, 2025

matthias-wende-frequenz requested changes Aug 20, 2025

View reviewed changes

cwasicki requested changes Aug 20, 2025

View reviewed changes

llucax reviewed Aug 22, 2025

View reviewed changes

llucax mentioned this pull request Sep 10, 2025

Add a newcomer tutorial #220

Closed

llucax closed this Sep 11, 2025


		These enable Python development and interactive notebooks within VS Code.

		### 2. Set Up a Virtual Environment


		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


		#### Linux / macOS

		```bash

Uh oh!

Conversation

merlin-esser-frequenz commented Aug 19, 2025

Uh oh!

matthias-wende-frequenz left a comment

Choose a reason for hiding this comment

Uh oh!

matthias-wende-frequenz Aug 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cwasicki left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

merlin-esser-frequenz commented Aug 20, 2025

Uh oh!

matthias-wende-frequenz commented Aug 20, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

llucax left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthias-wende-frequenz Aug 20, 2025 •

edited

Loading

llucax left a comment •

edited

Loading