Skip to content

Commit 054bc7e

Browse files
camille-bouvy-frequenzMarenz
camille-bouvy-frequenz
authored and
Marenz
committed
Move documentation and code examples to the documentation website
Signed-off-by: camille-bouvy-frequenz <[email protected]>
1 parent 5737257 commit 054bc7e

File tree

2 files changed

+141
-84
lines changed

2 files changed

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

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

Lines changed: 125 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,131 @@
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+
```python
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+
API_KEY = open('/path/to/api_key.txt').read().strip()
44+
client = Client(
45+
server_url=SERVICE_URL,
46+
auth_key=API_KEY
47+
)
48+
```
49+
50+
### Example Usage
51+
52+
#### Create an Order
53+
54+
Here's an example of how to create a limit order to buy energy.
55+
56+
57+
???+ example "Create a limit order"
58+
59+
```python
60+
from frequenz.client.electricity_trading import (
61+
Currency,
62+
DeliveryArea,
63+
DeliveryPeriod,
64+
Energy,
65+
EnergyMarketCodeType,
66+
MarketSide,
67+
OrderType,
68+
Price,
69+
)
70+
from datetime import datetime, timedelta
71+
from decimal import Decimal
72+
73+
# Define order parameters
74+
gridpool_id = 1
75+
delivery_area = DeliveryArea(
76+
code="10YDE-EON------1", # TenneT
77+
code_type=EnergyMarketCodeType.EUROPE_EIC
78+
)
79+
delivery_period = DeliveryPeriod(
80+
start=datetime.fromisoformat("2024-05-01T00:00:00+00:00"),
81+
duration=timedelta(minutes=15)
82+
)
83+
price = Price(amount=Decimal("50.0"), currency=Currency.EUR)
84+
quantity = Energy(mwh=Decimal("0.1"))
85+
order = await client.create_gridpool_order(
86+
gridpool_id=gridpool_id,
87+
delivery_area=delivery_area,
88+
delivery_period=delivery_period,
89+
order_type=OrderType.LIMIT,
90+
side=MarketSide.BUY,
91+
price=price,
92+
quantity=quantity,
93+
)
94+
```
95+
96+
#### List Orders for a Gridpool
97+
98+
Orders for a given gridpool can be listed using various filters.
99+
???+ example "List orders for a gridpool"
100+
101+
```python
102+
from frequenz.client.electricity_trading import MarketSide
103+
104+
# List all orders for a given gridpool
105+
orders = await client.list_gridpool_orders(
106+
gridpool_id=gridpool_id,
107+
)
108+
109+
# List only the buy orders for a given gridpool
110+
buy_orders = await client.list_gridpool_orders(
111+
gridpool_id=gridpool_id,
112+
side=MarketSide.BUY,
113+
)
114+
```
115+
116+
117+
#### Streaming Public Trades
118+
119+
To get real-time updates on market trades, use the following code:
120+
121+
???+ example "Stream public trades"
122+
```python
123+
stream_public_trades = await client.stream_public_trades()
124+
async for public_trade in stream_public_trades:
125+
print(f"Received public trade: {public_trade}")
126+
```
127+
128+
"""
5129

6130
from ._client import Client
7131
from ._types import (

0 commit comments

Comments
 (0)