Skip to content

Commit 8ed2f4c

Browse files
MarenzMarenz
authored
Validate init examples with sybil (#57)
- **Move documentation and code examples to the documentation website** - **Update Release Notes** - **Enable validation of init file examples** - **Fix init file example errors** Based on #52
2 parents 5737257 + 4c10890 commit 8ed2f4c

File tree

4 files changed

+180
-85
lines changed

4 files changed

+180
-85
lines changed

‎README.md‎

Lines changed: 16 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -27,99 +27,32 @@ The following platforms are officially supported (tested):
2727

2828
### Installation
2929

30-
You can install the Frequenz Electricity Trading API client via pip. Replace `VERSION` with the specific version you wish to install.
30+
We assume you are on a system with Python available. If that is not the case,
31+
please [download and install Python](https://www.python.org/downloads/) first.
3132

32-
```sh
33-
# Choose the version you want to install
34-
VERSION=0.2.3
35-
pip install frequenz-client-electricity-trading==$VERSION
36-
```
3733

38-
### Initialization
34+
To install the Frequenz Electricity Trading AP, you probably want to create a new virtual
35+
environment first. For example, if you use a `sh` compatible shell, you can do this:
3936

40-
First, initialize the client with the appropriate server URL and API key.
41-
42-
```python
43-
from frequenz.client.electricity_trading import Client
44-
45-
# Change server address if needed
46-
SERVICE_URL = "grpc://electricity-trading.api.frequenz.com:443?ssl=true"
47-
API_KEY = open('/path/to/api_key.txt').read().strip()
48-
client = Client(
49-
server_url=SERVICE_URL,
50-
auth_key=API_KEY
51-
)
52-
```
53-
54-
### Create an Order
55-
56-
Here's an example of how one can create a limit order to buy energy.
57-
58-
```python
59-
from frequenz.client.electricity_trading import (
60-
Currency,
61-
DeliveryArea,
62-
DeliveryPeriod,
63-
Energy,
64-
EnergyMarketCodeType,
65-
MarketSide,
66-
OrderType,
67-
Price,
68-
)
69-
from datetime import datetime, timedelta
70-
from decimal import Decimal
71-
72-
# Define order parameters
73-
gridpool_id = 1
74-
delivery_area = DeliveryArea(
75-
code="10YDE-EON------1", # TenneT
76-
code_type=EnergyMarketCodeType.EUROPE_EIC
77-
)
78-
delivery_period = DeliveryPeriod(
79-
start=datetime.fromisoformat("2024-05-01T00:00:00+00:00"),
80-
duration=timedelta(minutes=15)
81-
)
82-
price = Price(amount=Decimal("50.0"), currency=Currency.EUR)
83-
quantity = Energy(mwh=Decimal("0.1"))
84-
order = await client.create_gridpool_order(
85-
gridpool_id=gridpool_id,
86-
delivery_area=delivery_area,
87-
delivery_period=delivery_period,
88-
order_type=OrderType.LIMIT,
89-
side=MarketSide.BUY,
90-
price=price,
91-
quantity=quantity,
92-
)
37+
```sh
38+
python3 -m venv .venv
39+
. .venv/bin/activate
9340
```
9441

95-
### List Orders for a Gridpool
42+
Then, just install using `pip`. Replace `VERSION` with the specific version you wish to install:
9643

97-
Orders for a given gridpool can be listed using various filters.
98-
99-
```python
100-
from frequenz.client.electricity_trading import MarketSide
101-
102-
# List all orders for a given gridpool
103-
orders = await self._client.list_gridpool_orders(
104-
gridpool_id=gridpool_id,
105-
)
106-
107-
# List only the buy orders for a given gridpool
108-
buy_orders = await self._client.list_gridpool_orders(
109-
gridpool_id=gridpool_id,
110-
side=MarketSide.BUY,
111-
)
44+
```sh
45+
# Choose the version you want to install
46+
VERSION=0.2.3
47+
pip install frequenz-client-electricity-trading==$VERSION
11248
```
11349

114-
### Streaming Public Trades
11550

116-
To get real-time updates on market trades, one can use the following code snippet.
51+
## Documentation
52+
53+
For more information, please visit the [documentation
54+
website](https://frequenz-floss.github.io/frequenz-client-electricity-trading/).
11755

118-
```python
119-
stream_public_trades = await client.stream_public_trades()
120-
async for public_trade in stream_public_trades:
121-
print(f"Received public trade: {public_trade}")
122-
```
12356

12457
## Contributing
12558

‎RELEASE_NOTES.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212

1313
* Replace assert statements with proper exception handling
1414
* Implement client instance reuse to avoid redundant TCP connections
15+
* Move documentation and code examples to the documentation website
1516

1617
## Bug Fixes
1718

‎src/frequenz/client/electricity_trading/__init__.py‎

Lines changed: 157 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,163 @@
11
# License: MIT
22
# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
33

4-
"""Electricity Trading API client for Python."""
4+
"""
5+
Electricity Trading API client for Python.
6+
7+
## Frequenz Electricity Trading API Client
8+
9+
This module provides an easy-to-use Python interface to interact with the Frequenz Electricity
10+
Trading API. It allows you to create orders, manage market data, and interact with the electricity
11+
trading ecosystem.
12+
13+
### Features
14+
15+
- **Create and manage gridpool orders**: Place new orders, update existing ones, and cancel orders
16+
when necessary.
17+
- **Stream live data**: Get real-time updates on market data, including order books, trades,
18+
and market prices.
19+
- **Retrieve historical data**: Access historical data on market trades.
20+
21+
### Installation
22+
23+
You can install the Frequenz Electricity Trading API client via pip. Replace `VERSION`
24+
with the specific version you wish to install.
25+
26+
# Choose the version you want to install
27+
```bash
28+
VERSION=0.2.3
29+
pip install frequenz-client-electricity-trading==$VERSION
30+
```
31+
32+
### Initialization
33+
34+
First, initialize the client with the appropriate server URL and API key.
35+
36+
???+ example "Initialize the client"
37+
38+
```python
39+
from frequenz.client.electricity_trading import Client
40+
41+
# Change server address if needed
42+
SERVICE_URL = "grpc://electricity-trading.api.frequenz.com:443?ssl=true"
43+
with open('/path/to/api_key.txt', 'r', encoding='utf-8') as f:
44+
API_KEY = f.read().strip()
45+
client = Client(
46+
server_url=SERVICE_URL,
47+
auth_key=API_KEY
48+
)
49+
```
50+
51+
### Example Usage
52+
53+
#### Create an Order
54+
55+
Here's an example of how to create a limit order to buy energy.
56+
57+
58+
???+ example "Create a limit order"
59+
60+
```python
61+
from frequenz.client.electricity_trading import (
62+
Client,
63+
Currency,
64+
DeliveryArea,
65+
DeliveryPeriod,
66+
Energy,
67+
EnergyMarketCodeType,
68+
MarketSide,
69+
OrderType,
70+
Price,
71+
)
72+
from datetime import datetime, timedelta
73+
from decimal import Decimal
74+
75+
# Change server address if needed
76+
SERVICE_URL = "grpc://electricity-trading.api.frequenz.com:443?ssl=true"
77+
with open('/path/to/api_key.txt', 'r', encoding='utf-8') as f:
78+
API_KEY = f.read().strip()
79+
client = Client(
80+
server_url=SERVICE_URL,
81+
auth_key=API_KEY
82+
)
83+
84+
# Define order parameters
85+
GRIDPOOL_ID = 1
86+
delivery_area = DeliveryArea(
87+
code="10YDE-EON------1", # TenneT
88+
code_type=EnergyMarketCodeType.EUROPE_EIC
89+
)
90+
delivery_period = DeliveryPeriod(
91+
start=datetime.fromisoformat("2024-05-01T00:00:00+00:00"),
92+
duration=timedelta(minutes=15)
93+
)
94+
price = Price(amount=Decimal("50.0"), currency=Currency.EUR)
95+
quantity = Energy(mwh=Decimal("0.1"))
96+
order = await client.create_gridpool_order(
97+
gridpool_id=GRIDPOOL_ID,
98+
delivery_area=delivery_area,
99+
delivery_period=delivery_period,
100+
order_type=OrderType.LIMIT,
101+
side=MarketSide.BUY,
102+
price=price,
103+
quantity=quantity,
104+
)
105+
```
106+
107+
#### List Orders for a Gridpool
108+
109+
Orders for a given gridpool can be listed using various filters.
110+
???+ example "List orders for a gridpool"
111+
112+
```python
113+
from frequenz.client.electricity_trading import ( Client, MarketSide )
114+
115+
# Change server address if needed
116+
SERVICE_URL = "grpc://electricity-trading.api.frequenz.com:443?ssl=true"
117+
with open('/path/to/api_key.txt', 'r', encoding='utf-8') as f:
118+
API_KEY = f.read().strip()
119+
client = Client(
120+
server_url=SERVICE_URL,
121+
auth_key=API_KEY
122+
)
123+
124+
gridpool_id: int = 1
125+
126+
# List all orders for a given gridpool
127+
orders = await client.list_gridpool_orders(
128+
gridpool_id=gridpool_id,
129+
)
130+
131+
# List only the buy orders for a given gridpool
132+
buy_orders = await client.list_gridpool_orders(
133+
gridpool_id=gridpool_id,
134+
side=MarketSide.BUY,
135+
)
136+
```
137+
138+
139+
#### Streaming Public Trades
140+
141+
To get real-time updates on market trades, use the following code:
142+
143+
???+ example "Stream public trades"
144+
```python
145+
from frequenz.client.electricity_trading import Client
146+
147+
# Change server address if needed
148+
SERVICE_URL = "grpc://electricity-trading.api.frequenz.com:443?ssl=true"
149+
with open('/path/to/api_key.txt', 'r', encoding='utf-8') as f:
150+
API_KEY = f.read().strip()
151+
client = Client(
152+
server_url=SERVICE_URL,
153+
auth_key=API_KEY
154+
)
155+
stream_public_trades = await client.stream_public_trades()
156+
async for public_trade in stream_public_trades:
157+
print(f"Received public trade: {public_trade}")
158+
```
159+
160+
"""
5161

6162
from ._client import Client
7163
from ._types import (

‎src/frequenz/client/electricity_trading/conftest.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,9 @@
1010
from frequenz.repo.config.pytest import examples
1111
from sybil import Sybil
1212

13-
pytest_collect_file = Sybil(**examples.get_sybil_arguments()).pytest()
13+
args = examples.get_sybil_arguments()
14+
# Pop "excludes" which was added upstream to work around a sybil bug
15+
# with __init__.py files
16+
args.pop("excludes", None)
17+
18+
pytest_collect_file = Sybil(**args).pytest()

0 commit comments

Comments
 (0)