Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tarsil/polyforce
Enforce annotations in your python code
https://github.com/tarsil/polyforce
pydantic pydantic-v2 python python-types python-typing python3 static-typing typing
Last synced: 25 days ago
JSON representation
Enforce annotations in your python code
- Host: GitHub
- URL: https://github.com/tarsil/polyforce
- Owner: tarsil
- License: mit
- Created: 2023-10-09T15:18:46.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-01-03T12:15:04.000Z (10 months ago)
- Last Synced: 2024-10-03T07:58:12.705Z (about 1 month ago)
- Topics: pydantic, pydantic-v2, python, python-types, python-typing, python3, static-typing, typing
- Language: Python
- Homepage: https://polyforce.tarsild.io/
- Size: 133 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: docs/contributing.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Polyforce
🔥 Enforce static typing in your codebase at runtime 🔥
---
**Documentation**: [https://polyforce.tarsild.io][polyforce] 📚
**Source Code**: [https://github.com/tarsil/polyforce](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][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.
* [Via model](./model.md)
* [Via decorator](./decorator.md)
## Installation
```shell
$ 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
```python
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:
```python
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
```python
class MyClass:
def my_function(self, name: str):
return name
```
And then this will be also valid.
```python
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)
### Polyforce
Now, let us use the same examples used before but using **Polyforce** and see what happens?
#### Simple function
```python hl_lines="1"
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.
```python
my_function("Polyforce") # Throws an exception
```
The correct way would be:
```python hl_lines="1 5"
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?
```python
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.
```python hl_lines="1 4"
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:
```python hl_lines="1 4"
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`.
```python
from polyforce import PolyModel
```
And to use the decorator you simply can:
```python
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.
[polyforce]: https://polyforce.tarsild.io
[mypy]: https://mypy.readthedocs.io/en/stable/