diff --git a/.gitmodules b/.gitmodules index 61b777e..a3b100e 100644 --- a/.gitmodules +++ b/.gitmodules @@ -1,6 +1,3 @@ [submodule "submodules/api-common-protos"] path = submodules/api-common-protos url = https://github.com/googleapis/googleapis.git -[submodule "submodules/frequenz-api-common"] - path = submodules/frequenz-api-common - url = https://github.com/frequenz-floss/frequenz-api-common.git diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 94fb025..4730bea 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -2,15 +2,24 @@ ## Summary - +This API interface's client requires the SDK, which depends on +frequenz-api-common in the version range of 0.3.0 to < 0.4.0. However, +electricity_trading.proto needs some proto files from frequenz-api-common, +which are only available from version 0.5.0. This discrepancy creates +a dependency conflict. To resolve this, the current PR incorporates +the required protos directly from the frequenz-api-common repository and +stores them locally. This approach eliminates the dependency on the common +repository for the time being, until the SDK is updated to a newer version +of frequenz-api-common. ## Upgrading ## New Features + * Addition of missing types to the `__init__` file ## Bug Fixes - +* Remove dependency conflict on `frequenz-api-common` by adding it locally diff --git a/proto/frequenz/api/common/.DS_Store b/proto/frequenz/api/common/.DS_Store new file mode 100644 index 0000000..c19b5d2 Binary files /dev/null and b/proto/frequenz/api/common/.DS_Store differ diff --git a/proto/frequenz/api/common/v1/grid/delivery_area.proto b/proto/frequenz/api/common/v1/grid/delivery_area.proto new file mode 100644 index 0000000..6639147 --- /dev/null +++ b/proto/frequenz/api/common/v1/grid/delivery_area.proto @@ -0,0 +1,62 @@ +// Frequenz definitions of grids as entites participating in trading. +// +// Copyright 2023 Frequenz Energy-as-a-Service GmbH +// +// Licensed under the MIT License (the "License"); +// you may not use this file except in compliance with the License. + +syntax = "proto3"; + +package frequenz.api.common.v1.grid; + +// CodeType specifies the type of identification code used for uniquely +// identifying various entities such as delivery areas, market participants, and +// grid components within the energy market. This enumeration aims to offer +// compatibility across different jurisdictional standards. +// +// !!! note "Understanding Code Types" +// Different regions or countries may have their own standards for uniquely +// identifying various entities within the energy market. For example, in +// Europe, the Energy Identification Code (EIC) is commonly used for this +// purpose. +// +// !!! info "Extensibility" +// New code types can be added to this enum to accommodate additional +// regional standards, enhancing the API's adaptability. +// +// !!! caution "Validation Required" +// The chosen code type should correspond correctly with the `code` field in +// the relevant message objects, such as `DeliveryArea` or `Counterparty`. +// Failure to match the code type with the correct code could lead to +// processing errors. +// +enum EnergyMarketCodeType { + // Unspecified type. This value is a placeholder and should not be used. + ENERGY_MARKET_CODE_TYPE_UNSPECIFIED = 0; + + // European Energy Identification Code Standard. + ENERGY_MARKET_CODE_TYPE_EUROPE_EIC = 1; + + // North American Electric Reliability Corporation identifiers. + ENERGY_MARKET_CODE_TYPE_US_NERC = 2; +} + +// DeliveryArea represents the geographical or administrative region, usually +// defined and maintained by a Transmission System Operator (TSO), where +// electricity deliveries for a contract occur. +// +// The concept is important to energy trading as it delineates the agreed-upon +// delivery location. Delivery areas can have different codes based on the// +// jurisdiction in which they operate. +// +// !!! note "Jurisdictional Differences" +// This is typically represented by specific codes according to local +// jurisdiction. In Europe, this is represented by an EIC +// (Energy Identification Code). +message DeliveryArea { + // Code representing the unique identifier for the delivery area. + string code = 1; + + // Type of code used for identifying the delivery area itself. + EnergyMarketCodeType code_type = 2; +} diff --git a/proto/frequenz/api/common/v1/grid/delivery_duration.proto b/proto/frequenz/api/common/v1/grid/delivery_duration.proto new file mode 100644 index 0000000..d0f9d0a --- /dev/null +++ b/proto/frequenz/api/common/v1/grid/delivery_duration.proto @@ -0,0 +1,61 @@ +// Frequenz definitions of the time increment used for electricity +// deliveries and trading. +// +// Copyright 2023 Frequenz Energy-as-a-Service GmbH +// +// Licensed under the MIT License (the "License"); +// you may not use this file except in compliance with the License. + +syntax = "proto3"; + +package frequenz.api.common.v1.grid; + +import "google/protobuf/timestamp.proto"; + +// DeliveryDuration represents the time increment, in minutes, +// used for electricity deliveries and trading. These durations +// serve as the basis for defining the delivery period in contracts, +// and they dictate how energy is scheduled and delivered to meet +// contractual obligations. +// +// !!! note "Compatibility Constraints" +// Not all delivery durations are universally +// compatible with all delivery areas or markets. +// +enum DeliveryDuration { + // Default value, indicates that the duration is unspecified. + DELIVERY_DURATION_UNSPECIFIED = 0; + + // 5-minute duration + DELIVERY_DURATION_5 = 1; + + // 15-minute contract duration. + DELIVERY_DURATION_15 = 2; + + // 30-minute contract duration. + DELIVERY_DURATION_30 = 3; + + // 1-hour contract duration. + DELIVERY_DURATION_60 = 4; +} + +// DeliveryPeriod represents the time period during which the contract +// is delivered. It is defined by a start timestamp and a duration. +message DeliveryPeriod { + // Start UTC timestamp represents the beginning of the delivery period. + // This timestamp is inclusive, meaning that the delivery period starts + // from this point in time. + // + // !!! note + // Delivery period start time constraints: + // - 5-minute durations must start at times that are multiples of + // 5 minutes past the hour. + // - 15-minute durations must start at :00, :15, :30, or + // :45 past the hour. + // - 30-minute durations must start at :00 or :30 past the hour. + // - 60-minute durations must start at :00 past the hour. + google.protobuf.Timestamp start = 1; + + // The length of the delivery period. + DeliveryDuration duration = 2; +} diff --git a/proto/frequenz/api/common/v1/market/energy.proto b/proto/frequenz/api/common/v1/market/energy.proto new file mode 100644 index 0000000..fcff1fe --- /dev/null +++ b/proto/frequenz/api/common/v1/market/energy.proto @@ -0,0 +1,24 @@ +// Frequenz definitions of energy for electricity trading. +// +// Copyright 2023 Frequenz Energy-as-a-Service GmbH +// +// Licensed under the MIT License (the "License"); +// you may not use this file except in compliance with the License. + +syntax = "proto3"; + +package frequenz.api.common.v1.market; + +import "google/type/decimal.proto"; + +// Represents a single unit of electricity. +// +// !!! note +// In these trading orders, the unit of energy is denominated in MWh +// (Megawatt-hours) as opposed to MW (Megawatts). MWh is a unit of energy +// representing total output over a period, while MW is a unit of power that +// represents the rate of energy production or consumption. +message Energy { + // Represents energy unit in Megawatthours (MWh). + google.type.Decimal mwh = 1; +} diff --git a/proto/frequenz/api/common/v1/market/price.proto b/proto/frequenz/api/common/v1/market/price.proto new file mode 100644 index 0000000..15759ed --- /dev/null +++ b/proto/frequenz/api/common/v1/market/price.proto @@ -0,0 +1,53 @@ +// Frequenz definitions of price for electricity trading. +// +// Copyright 2023 Frequenz Energy-as-a-Service GmbH +// +// Licensed under the MIT License (the "License"); +// you may not use this file except in compliance with the License. + +syntax = "proto3"; + +package frequenz.api.common.v1.market; + +import "google/type/decimal.proto"; + +// Represents a monetary price for electricity trading, including +// the amount and currency. The currency used should align with the +// delivery area's standard currency. +// +// !!! caution "Validation Required" +// It's essential to ensure that the currency aligns with the +// standard currency of the associated delivery area. Failure to +// do so may result in the API service rejecting the request due to currency +// mismatches. +// +// !!! info "Relation to Delivery Area" +// The currency specified is intrinsically related to the delivery area +// for the contract. Make sure the chosen currency is compatible with +// the delivery area's currency standards. +// +message Price { + // List of supported currencies. + // + // !!! info "Extensibility" + // New currencies can be added to this enum to support additional markets. + enum Currency { + CURRENCY_UNSPECIFIED = 0; + CURRENCY_USD = 1; + CURRENCY_CAD = 2; + CURRENCY_EUR = 3; + CURRENCY_GBP = 4; + CURRENCY_CHF = 5; + CURRENCY_CNY = 6; + CURRENCY_JPY = 7; + CURRENCY_AUD = 8; + CURRENCY_NZD = 9; + CURRENCY_SGD = 10; + } + + // The amount of the price. + google.type.Decimal amount = 1; + + // The currency in which the price is denominated. + Currency currency = 2; +} diff --git a/proto/frequenz/api/common/v1/pagination/pagination_info.proto b/proto/frequenz/api/common/v1/pagination/pagination_info.proto new file mode 100644 index 0000000..83579a5 --- /dev/null +++ b/proto/frequenz/api/common/v1/pagination/pagination_info.proto @@ -0,0 +1,27 @@ +// Parameters for pagination. +// +// Copyright 2023 Frequenz Energy-as-a-Service GmbH +// +// Licensed under the MIT License (the "License"); +// you may not use this file except in compliance with the License. + +syntax = "proto3"; + +package frequenz.api.common.v1.pagination; + +// A message providing metadata about paginated list results. +// The PaginationInfo message delivers metadata concerning the paginated list +// results and should be appended to the response message of a list request. The +// total_items field must be set to the total count of items that adhere to the +// filter criteria defined in the request. The next_page_token field should be +// populated with the token to be used in the subsequent request to fetch the +// next page of results. If there are no additional results, the next_page_token +// field should be omitted. +message PaginationInfo { + // The total number of items that match the filter criteria defined in the + // request. + uint32 total_items = 1; + + // Token for retrieving the next set of results. + optional string next_page_token = 2; +} diff --git a/proto/frequenz/api/common/v1/pagination/pagination_params.proto b/proto/frequenz/api/common/v1/pagination/pagination_params.proto new file mode 100644 index 0000000..a21bffa --- /dev/null +++ b/proto/frequenz/api/common/v1/pagination/pagination_params.proto @@ -0,0 +1,26 @@ +// Parameters for pagination. +// +// Copyright 2023 Frequenz Energy-as-a-Service GmbH +// +// Licensed under the MIT License (the "License"); +// you may not use this file except in compliance with the License. + +syntax = "proto3"; + +package frequenz.api.common.v1.pagination; + +// A message defining parameters for paginating list requests. +// It can be appended to a request message to specify the desired page of +// results and the maximum number of results per page. For initial requests +// (requesting the first page), the page_token should not be provided. For +// subsequent requests (requesting any page after the first), the +// next_page_token from the previous responses PaginationInfo must be supplied. +// The page_size should only be specified in the initial request and will be +// disregarded in subsequent requests. +message PaginationParams { + // The maximum number of results to be returned per request. + optional uint32 page_size = 1; + + // The token identifying a specific page of the list results. + optional string page_token = 2; +} diff --git a/py/frequenz/api/common/v1/__init__.py b/py/frequenz/api/common/v1/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/py/frequenz/api/common/v1/grid/__init__.py b/py/frequenz/api/common/v1/grid/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/py/frequenz/api/common/v1/market/__init__.py b/py/frequenz/api/common/v1/market/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/py/frequenz/api/common/v1/pagination/__init__.py b/py/frequenz/api/common/v1/pagination/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/py/frequenz/api/common/v1/py.typed b/py/frequenz/api/common/v1/py.typed new file mode 100644 index 0000000..e69de29 diff --git a/pyproject.toml b/pyproject.toml index 94e25ed..2b80ac6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -26,7 +26,6 @@ classifiers = [ ] requires-python = ">= 3.11, < 4" dependencies = [ - "frequenz-api-common >= 0.5.3, < 0.6.0", "googleapis-common-protos >= 1.56.4, < 2", "grpcio >= 1.60.0, < 2", "frequenz-channels >= 0.16.0, < 0.17.0", diff --git a/submodules/frequenz-api-common b/submodules/frequenz-api-common deleted file mode 160000 index 6800adb..0000000 --- a/submodules/frequenz-api-common +++ /dev/null @@ -1 +0,0 @@ -Subproject commit 6800adb2fc75def50f2c4cdc63e2c3bc831608f4