Skip to content

Commit

Permalink
Merge pull request #3 from tarsil/feature/documentation
Browse files Browse the repository at this point in the history
Feature/documentation
  • Loading branch information
tarsil authored Oct 10, 2023
2 parents 8ed4b24 + 611437b commit 4389e2a
Show file tree
Hide file tree
Showing 35 changed files with 1,012 additions and 80 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/1-issue.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ We can then decide if the discussion needs to be escalated into an "Issue" or no
This will make sure that everything is organised properly.
---

**polyforce version**:
**Polyforce version**:
**Python version**:
**OS**:
**Platform**:
Expand Down
34 changes: 32 additions & 2 deletions README.md
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
40 changes: 40 additions & 0 deletions docs/config.md
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>
77 changes: 77 additions & 0 deletions docs/decorator.md
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**.
Loading

0 comments on commit 4389e2a

Please sign in to comment.