tcheasy 1.1.0

A python decorator which checks types & restrictions for user inputs

Checkout - freepik - the photographer of Mr. Tcheasy & Sorpa!

tcheasy

tcheasy is a python decorator that makes type checking (at runtime) easy!
Just import the decorator and start to check your function inputs from the get-go.
You want to define input restrictions as well? Then your are in the right place!

Python >= 3.8 needed. Tested ver. { 3.8.5, 3.9.9 }

CONTENT

1. why?
2. how?
3. install?
4. where is Sorpa?
5. examples?

WHY? _{Back to top}

For one of my projects I needed a way to check user inputs at runtime.
There were already packages that do type-checking, but they only use the - relatively simplistic - python type hints.
The problem, however, was that I needed not only type checking but also the option to restrict some parameter inputs.

Enter tcheasy!

Out of the need to have a tool for other projects, this python decorator was born.
This little kritter is able to use a predefined dict or the python type hinting. Please refere to the how? & example? section for more infos about the usage.

tcheasy ships also with his neat little friend sorpa:
The function sorpa() is able to extract and sort your passed function parameters at runtime.

If you are sololy looking for a type checking tool (and some handy utility-tools) you should also check out:

• beartype
• typeguard
• mypy

Else feel free to use and modify tcheasy as you please.

HOW? _{Back to top}

Just import the package

from tcheasy import tcheasy

and add the decorator @tcheasy() to your to-be-checked function.
If you are already using python type hinting tcheasy is ready out of the box.

In the current version, the following types (hints) are supported:

• NoneType(s): None
• number types: int, float, complex, bool
• sequence types: str, list, tuple
• mapping types: dict
• set types: sets
• callable types: object
• typing-module types: typing.Any, typing.Union

But the true might comes from using declarative dicts.
By passing a dict to @tcheasy() you can specify the parameter types, add rudimentary input restrictions & default values.
The structure of these dictionaries (and their used keywords) is always the same (type, restriction (optional) & default (optional)):

# define the dict!

to_check = {
    'positional':{
        'parameter-name':{
            'type': type,
            'restriction': "(optional) in the form: value condition",
            'default': "(optional) default value"
        },
        'next-parameter-name':{
            ...
        },
        ...
    },
    'args':[ {'type':type, 'restriction':str, 'default': "value" }, {...}, ...],
    'kwargs': {
        'parameter-name':{...},
        ...
    }
}

As you can see, you have the complete control over potential *args and **kwargs. The definition structure of 'kwargs' is also the same as for the positionals.
Keep in mind that you do not have to define restriction and/or default. These two keywords are completely optional.

After you have defined the dict you can pass it to @tcheasy() and it will start to monitor the function at runtime (e.g. if your dict is called to_check, then you pass it like this: @tcheasy(to_check)).

Note:
The separation of positional, args & kwargs is derived of the python parameter types. There are 5 distinct types, which can be boiled down to basically 3 'blocks':

• positional:
  • keyword parameters (your typical def test(a), while the call was test(a='some-value'))
  • (positional) parameters (again your typical def test(a) but this time calling just test('some-value'))
• *args:
  • arbitrary positional arguments (def test(a, *args), while calling test('value-a', 'value-args'))
• **kwargs:
  • arbitrary keyword arguments (def test(a, **kwargs), while calling test('value-a', add_kwargs="some-value"))

The structure of the default keyword is - as mentioned - always the same. For example consider the following:

...
    'parameter-name': {
        'type': int,
        'restriction':"value > 1"
    },
...

In this example, the passed int parameter gets evaluated and has to be be greater than one. The word value is the placeholder for your function parameter.
To give you another example, you can use "value in ['yes', 'no', 'maybe']" to evaluate if the passed string parameter is one of the elements in the list.
With this technique you are able to do some pretty awsome stuff!

If you want further examples, please refere to the examples? section.

INSTALL? _{Back to top}

There are two ways to install tcheasy.
The easy way is to use pip:

$ pip install tcheasy

The other option is to git clone the project and then run:

$ pip install 'path-to-your-clone'

If you want to tinker with your code, run the pip install with -e.

WHERE IS SORPA? _{Back to top}

Mr. Tcheasy comes packed with his friend Sorpa!

sorpa() is a python function which shows you the passed parameters, names, declartions and hints of your targeted python function at runtime.

The import is as easy as the import for tcheasy. Just:

from tcheasy import sorpa

This function takes as input the function (func) you want to analyse and the locals (loc).
As soon as you passed those two arguments, you get a handy dict which sorted the passed parameters, your declared parameter (during function definition) & python hints.
For example, lets consider the following test function:

# we define our test function (called 'test_function') with the parameters a, b & c
# also we add some type hinting
def test_function(a:int, b:str, c:float = .1) -> dict:
    """Our test function. Proper docstring skipped """

    # get our local variables
    loc = locals()

    # lets consider we already imported 'sorpa'
    # we set decorated to 'False' to tell the algorithmn
    # that we are not within a decorator scope.
    sortedParameters = sorpa(
        func = test_function, 
        loc = loc,
        decorated = False
        )

    return sortedParameters

Now we can call the function with some arguments (e.g. test_function(5, b="some-string")) and get as a return the following:

>> {
        'positional': {'a': 5, 'b': 'some-string', 'c': 0.1},
        'args':[],
        'kwargs':{},
        'hinting':{'a': <class 'int'>, 'b': <class 'str'>, 'c': <class 'float'>},
        'declared': ['a', 'b', 'c'],
        'self':{'available':False, 'value':None}
   }

EXAMPLES? _{Back to top}

To get some examples, please check out the examples directory (on github).
There you will find examples for Mr. Tcheasy's & and his friend Sorpa's usecases.