diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 40e493f7..417afbc7 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -10,7 +10,7 @@ ## New Features - +* Add a notebook containing example usage of the client ## Bug Fixes diff --git a/example/example.ipynb b/example/example.ipynb new file mode 100644 index 00000000..7652b69c --- /dev/null +++ b/example/example.ipynb @@ -0,0 +1,205 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Example Notebook\n", + "\n", + "This notebook demonstrates the implementation of an API Client and shows a couple examples of how to use it. \n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "#VERSION=\"0.3.1\"\n", + "#!pip install frequenz-client-electricity-trading==$VERSION" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "import asyncio\n", + "from datetime import datetime, timedelta, timezone\n", + "from decimal import Decimal\n", + "from frequenz.client.electricity_trading import (\n", + " Client, \n", + " Currency,\n", + " DeliveryArea,\n", + " DeliveryPeriod,\n", + " EnergyMarketCodeType,\n", + " MarketSide,\n", + " OrderType,\n", + " Power,\n", + " Price,\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Change server address if needed (default is the testing server)\n", + "SERVICE_URL = \"grpc://electricity-trading-testing.api.frequenz.com:443?ssl=true\"\n", + "\n", + "# with open('/path/to/api_key.txt', 'r', encoding='utf-8') as f:\n", + "with open('api_key.txt', 'r', encoding='utf-8') as f:\n", + " API_KEY = f.read().strip()\n", + "\n", + "# with open('/path/to/gridpool_id.txt', 'r', encoding='utf-8') as f:\n", + "with open('gridpool_id.txt', 'r', encoding='utf-8') as f:\n", + " GRIDPOOL_ID = int(f.read().strip())" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [], + "source": [ + "# Initialize the client\n", + "client = Client(\n", + " server_url=SERVICE_URL,\n", + " auth_key=API_KEY\n", + ")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Define some order parameters\n", + "delivery_area = DeliveryArea(\n", + " code=\"10YDE-EON------1\", # TenneT\n", + " code_type=EnergyMarketCodeType.EUROPE_EIC\n", + ")\n", + "delivery_period = DeliveryPeriod(\n", + " start=datetime.fromisoformat(\"2026-05-01T00:00:00+00:00\"),\n", + " duration=timedelta(minutes=15)\n", + ")\n", + "price = Price(amount=Decimal(\"50.0\"), currency=Currency.EUR)\n", + "quantity = Power(mw=Decimal(\"0.1\"))\n", + "\n", + "# Create a new limit order to buy energy.\n", + "order = await client.create_gridpool_order(\n", + " gridpool_id=GRIDPOOL_ID,\n", + " delivery_area=delivery_area,\n", + " delivery_period=delivery_period,\n", + " order_type=OrderType.LIMIT,\n", + " side=MarketSide.BUY,\n", + " price=price,\n", + " quantity=quantity,\n", + ")\n", + "\n", + "print(f\"Created order: {order}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### List Orders for a Gridpool\n", + "\n", + "Orders for a given gridpool can be listed using various filters." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# List all orders for a given gridpool\n", + "async for order in client.list_gridpool_orders(gridpool_id=GRIDPOOL_ID):\n", + " print(f\"Order: {order}\")\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# List only the buy orders for a given gridpool\n", + "async for order in client.list_gridpool_orders(gridpool_id=GRIDPOOL_ID, side=MarketSide.BUY):\n", + " print(f\"Buy order: {order}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "#### Streaming Public Trades\n", + "\n", + "To get real-time updates on market trades, use the following code:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [ + { + "name": "stderr", + "output_type": "stream", + "text": [ + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n", + "Broadcast receiver [Broadcast:GrpcStreamBroadcaster-electricity-trading-PublicTradeFilter(states=None, delivery_period=None, buy_delivery_area=None, sell_delivery_area=None):_Receiver] is full. Oldest message was dropped.\n" + ] + } + ], + "source": [ + "stream_public_trades = await client.stream_public_trades()\n", + "async for public_trade in stream_public_trades:\n", + " print(f\"Received public trade: {public_trade}\")\n" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": ".venv", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.0" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +}