How to use type hints in Python. Application: Energy
Understanding type hints for energy applications in Python
Quick Reminder: Subscribe to view the Python code of this post and all previous posts, and get 2 such posts every week. Also, you will join daily Q&A sessions with me and be invited to the Energy Data Scientist community on Skool.com to find 110 online courses on Energy Data Science (Economics / Finance).
The Reliability Problem in Energy Systems
In energy markets, there is no tolerance for errors in the Python code. If instead of 1198 we pass “1198” this may affect the reliable grid operation.
This is why type hints exist so we include them in our Python code.
With Python, you can pass any type of data to any function, and Python will attempt to process it. This flexibility is powerful during code development, but it can lead to errors if we are not careful.
Consider a function that registers available generation capacity. The function expects each power source as a tuple containing a name (string) and its available capacity (number) in MW.
In this function you can pass this information in the form of a tuple (”Hornsea Wind Farm”, “1218”) where the capacity is a string.
Or, you can give the name of the power station as a number: (1218, “Hornsea Wind Farm”)
Or, you can give a single value instead of a tuple: “Hornsea Wind Farm”
etc.
The function will be called and execute the code. It will fail somewhere inside though, maybe immediately, maybe after several iterations/operations. You’ll waste some minutes debugging the code, while your code is supposed to manage, in real-time, the day-ahead electricity market operations. In such a case, there is no time for debugging.
The idea is that the code must be perfect! No errors are allowed for code that is to be used in a real setting in electricity markets (and in energy markets generally). Energy market software runs continuously. The UK’s day-ahead market processes bids every single day. Settlement systems calculate payments worth billions annually. Grid balancing mechanisms respond to frequency deviations within seconds. There is no maintenance window where you can take the system offline to debug type errors.
This matters because electricity markets don’t tolerate failures. When National Grid balances the system, they need generation responses within seconds. When EPEX SPOT clears the day-ahead market, the results must be mathematically precise. When settlement systems calculate payments, the numbers must be exact to the penny.
This is why we need to use type hints. Type hints solve this problem by declaring what a function is expected to receive and return. This is helpful because when writing code you can instantly remind yourself of how to call the function and what to expect from the function’s output.
The cost of preventing these errors is minimal, by adding type annotations to function signatures. The cost of not preventing them is substantial such as incident response, financial corrections, regulatory scrutiny, reputation damage. Type hints cost little to add and prevent significant classes of errors. They make codebases more maintainable, more reviewable, and more reliable. They reduce the cognitive load on developers trying to understand what a function expects and what it returns.
Three Levels of Type Safety
You can choose how much type information to declare, from none to comprehensive.
No type hints: zero safety guarantees. You have no idea what to pass into the function. Errors may occur at runtime. The only positive here is that your code has fewer size i.e. you do not include the type hints.
Partial type hints : you include type hints only for what the function can accept. So when we call the function ,we know what to pass in, but we don’t know what we will get back from the function.
Complete type hints: Full specification of inputs and outputs. We know what to pass in the function and what to expect from the function.
Type hints are documentation that tell future developers, or yourself in six months, exactly what data flows through each function. They eliminate ambiguity about whether capacity is in megawatts or gigawatts, whether names can be null, whether the function returns a single number or a complex data structure.
In energy trading, ambiguity is risk. Type hints reduce risk.
Code Implementation: First level of Type Safety
Let’s examine the three progressively detailed ways to declare the same function. Each way offers different levels of type safety for capacity registration in the wholesale electricity market.
First, we have no level of safety i.e. no type hints.
What this tells you: Nothing. You do not know what *sources is supposed to be. And you do not know what ‘total_capacity’ is. Or, what ‘breakdown’ is.
Below, we are calling this function by passing two tuples. The first tuple works well. But the second tuple causes an error. When the function goes not the for - loop, we get an error.
Code Implementation: Second level of Type Safety
In this case we are adding a type hint in the arguments of the function. This enables us to know what *sources is i.e. what data type it is.
