Polyforce¶
🔥 Enforce static typing in your codebase at runtime 🔥
Documentation: https://polyforce.tarsild.io 📚
Source Code: https://github.com/tarsil/polyforce
Motivation¶
During software development we face issues where we don't know what do pass as specific parameters or even return of the functions itself.
Tools like mypy for example, allow you to run static checking in your code and therefore allowing to type your codebase properly but it does not enforce it when running.
For those coming from hevily static typed languages like Java, .net and many others, Python can be overwhelming and sometimes confusing because of its versatility.
Polyforce was created to make sure you:
- Don't forget to type your functions and variables.
- Validates the typing in runtime.
- Don't forget thr return annotations.
Wouldn't be cool to have something like this:
What if my function that expects a parameter of type string, if something else is passed could simply fail, as intended?
This is where Polyforce enters.
The library¶
Polyforce was designed to enforce the static typing everywhere in your code base. From functions to parameters.
It was also designed to make sure the typing is enforced at runtime.
In other words, if you declare a type string
and decide to pass an integer
, it will blow throw
and intended error.
The library offers two ways of implementing the solution.
Installation¶
$ pip install polyforce
How to use it¶
Let us see some scenarios where the conventional python is applied and then where Polyforce can make the whole difference for you.
Conventional Python¶
Let us start with a simple python function.
Simple function¶
def my_function(name: str):
return name
In the normal python world, this wouldn't make any difference, and let us be honest, if you don't care about mypy or any related tools, this will work without any issues.
This will also allow this to run without any errors:
my_function("Polyfactory") # returns "Polyfactory"
my_function(1) # returns 1
my_function(2.0) # returns 2.0
The example above is 100% valid for that specific function and all values passed will be returned
equaly valid and the reson for this is because Python does not enforce the static typing so
the str
declared for the parameter name
is merely visual.
With objects¶
class MyClass:
def my_function(self, name: str):
return name
And then this will be also valid.
my_class = MyClass()
my_class.my_function("Polyfactory") # returns "Polyfactory"
my_class.my_function(1) # returns 1
my_class.my_function(2.0) # returns 2.0
I believe you understand the gist of what is being referred here. So, what if there was a solution where we actually enforce the typing at runtime? Throw some errors when something is missing from the typing and also when the wrong type is being sent into a function?
Enters Polyforce
Polyforce¶
Now, let us use the same examples used before but using Polyforce and see what happens?
Simple function¶
from polyforce import polycheck
@polycheck()
def my_function(name: str):
return name
The example above it will throw a ReturnSignatureMissing
or a MissingAnnotation
because the missing return annotation of the function or a parameter annotation respectively.
my_function("Polyforce") # Throws an exception
The correct way would be:
from polyforce import polycheck
@polycheck()
def my_function(name: str) -> str:
return name
So what if now you pass a value that is not of type string?
my_function(1) # Throws an exception
This will also throw a TypeError
exception because you are trying to pass a type int
into a
declared type str
.
With objects¶
The same level of validations are applied within class objects too.
from polyforce import PolyModel
class MyClass(PolyModel):
def __init__(self, name, age: int):
...
def my_function(self, name: str):
return name
The example above it will throw a ReturnSignatureMissing
and a MissingAnnotation
because the missing return annotation for both init and the function as well as the missing
types for the parameters in both.
The correct way would be:
from polyforce import PolyModel
class MyClass(PolyModel):
def __init__(self, name: str, age: int) -> None:
...
def my_function(self, name: str) -> str:
return name
The Polyforce¶
As you can see, utilising the library is very simple and very easy, in fact, it was never so easy to enforce statuc typing in python.
For classes, you simply need to import the PolyModel
.
from polyforce import PolyModel
And to use the decorator you simply can:
from polyforce import polycheck
PolyModel vs polycheck¶
When using PolyModel
, there is no need to apply the polycheck
decorator. The PolyModel
is
smart enough to apply the same level of validations as the polycheck
.
When using the PolyModel
you can use normal python as you would normally do and that means
classmethod
, staticmethod
and normal functions.
This like this, the polycheck
is used for all the functions that are not inside a class.
Limitations¶
For now, Polyforce is not looking at native magic methods (usually start and end with double underscore). In the future it is planned to understand those on a class level.