-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #3 from tarsil/feature/documentation
Feature/documentation
- Loading branch information
Showing
35 changed files
with
1,012 additions
and
80 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,33 @@ | ||
# polyforce | ||
# Polyforce | ||
|
||
Enforce annotations in your python code | ||
<p align="center"> | ||
<a href="https://polyforce.tarsild.io"><img src="https://res.cloudinary.com/tarsild/image/upload/v1696959172/packages/polyforce/logo_pyynl9.png" alt='Polyforce'></a> | ||
</p> | ||
|
||
<p align="center"> | ||
<em>🔥 Enforce static typing in your codebase 🔥</em> | ||
</p> | ||
|
||
<p align="center"> | ||
<a href="https://github.com/tarsil/polyforce/workflows/Test%20Suite/badge.svg?event=push&branch=main" target="_blank"> | ||
<img src="https://github.com/tarsil/polyforce/workflows/Test%20Suite/badge.svg?event=push&branch=main" alt="Test Suite"> | ||
</a> | ||
|
||
<a href="https://pypi.org/project/polyforce" target="_blank"> | ||
<img src="https://img.shields.io/pypi/v/polyforce?color=%2334D058&label=pypi%20package" alt="Package version"> | ||
</a> | ||
|
||
<a href="https://pypi.org/project/polyforce" target="_blank"> | ||
<img src="https://img.shields.io/pypi/pyversions/polyforce.svg?color=%2334D058" alt="Supported Python versions"> | ||
</a> | ||
</p> | ||
|
||
--- | ||
|
||
**Documentation**: [https://polyforce.tarsild.io][polyforce] 📚 | ||
|
||
**Source Code**: [https://github.com/tarsil/polyforce](https://github.com/tarsil/polyforce) | ||
|
||
--- | ||
|
||
[polyforce]: https://polyforce.tarsild.io |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,40 @@ | ||
# Config | ||
|
||
This is the object used for [PolyModel](./model.md) configuration options and only contains | ||
a very little amount of paramenters. | ||
|
||
## How to import | ||
|
||
Very easy to import. | ||
|
||
```python | ||
from polyforce import Config | ||
``` | ||
|
||
## How to use | ||
|
||
The `Config` object is used inside objects that inherit from [PolyModel](./model.md). | ||
|
||
```python | ||
{!> ../docs_src/config.py !} | ||
``` | ||
|
||
The same parameters of the config are also present in [polycheck](./decorator.md) decorator as well. | ||
|
||
```python | ||
{!> ../docs_src/decorator.py !} | ||
``` | ||
|
||
## Parameters | ||
|
||
* **ignore** - Flag indicating if the static type checking should be ignored. When this is applied | ||
on a `PolyModel` level, **it will disable the checks for the whole class**, whereas when applied | ||
on a `polycheck` level, it will only disable for the function where the decorator is being applied. | ||
|
||
<sup>Default: `False`</sup> | ||
|
||
* **ignored_types** - List or tuple of python types, **any type** that should be ignored from the | ||
static type checking. When a type is passed to `ignored_types=(...,)`, the attribute with declared | ||
with the type being ignored will be assumed as `Any`. | ||
|
||
<sup>Default: `()`</sup> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,77 @@ | ||
# Decorator | ||
|
||
**Polyforce** is quite versatile and for different tastes. You can use the [PolyModel](./model.md) | ||
for you own objects or you can simply use the `polycheck` decorator for everything else. | ||
|
||
## polycheck | ||
|
||
This is the decorator that helps you with everything you need without the need of using an inherited | ||
object. | ||
|
||
The same parameters of the `PolyModel` are also allowed within the `polycheck`. | ||
|
||
## How to use it | ||
|
||
When using the `polycheck` you must import it first. | ||
|
||
```python | ||
from polyforce import polycheck | ||
``` | ||
|
||
Once it is imported you can simply subclass it in your objects. Something like this: | ||
|
||
```python hl_lines="5 19 26 32 40" | ||
{!> ../docs_src/decorator/example.py !} | ||
``` | ||
|
||
When adding the `polycheck` object, will enable the static type checking to happen all over the | ||
functions declared. | ||
|
||
### Ignore the checks | ||
|
||
Well, there is not too much benefit of using `polycheck` if you want to ignore the checks, correct? | ||
Well, yes but you still can do it if you want. | ||
|
||
There might be some scenarios where you want to override some checks and ignore the checks. | ||
|
||
For this, **Polyforce** uses the [Config](./config.md) dictionary. | ||
|
||
You simply need to pass `ignore=True` and the static type checking will be disabled for the class. | ||
|
||
It will look like this: | ||
|
||
```python hl_lines="19 26" | ||
{!> ../docs_src/decorator/disable.py !} | ||
``` | ||
|
||
!!! Tip | ||
The decorator has the same fields as the `PolyModel` but since `polycheck` is done | ||
on a function basis, applying `ignore+True` **is the same as not adding the decorator at all**. | ||
This serves as example for documentation purposes only. | ||
|
||
### Ignore specific types | ||
|
||
What if you want to simply ignore some types? Meaning, you might want to pass arbitrary values that | ||
you don't want them to be static checked. | ||
|
||
```python hl_lines="3 22" | ||
{!> ../docs_src/decorator/ignored_types.py !} | ||
``` | ||
|
||
This will make sure that the type `Actor` is actually ignore and assumed as type `Any` which also means | ||
you can pass whatever value you desire since the type `Actor` is no longer checked. | ||
|
||
### Integrations | ||
|
||
**Polyforce** works also really well with integrations, for instance with [Pydantic](https://pydantic.dev). | ||
|
||
The only thing you need to do is to import the [decorator](./decorator.md) and use it inside the | ||
functions you want to enforce. | ||
|
||
This example is exactly the same as the one for [PolyModel](./model.md#integrations). | ||
|
||
```python hl_lines="5 18 22" | ||
{!> ../docs_src/model/integrations.py !} | ||
``` | ||
|
||
This way you can use your favourite libraries with **Polyforce**. |
Oops, something went wrong.