Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/shezadkhan137/required
Easy multi-field validation
https://github.com/shezadkhan137/required
api cross-field dependencies django flask python validation
Last synced: about 1 month ago
JSON representation
Easy multi-field validation
- Host: GitHub
- URL: https://github.com/shezadkhan137/required
- Owner: shezadkhan137
- License: mit
- Created: 2017-02-15T22:45:52.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-12-13T18:19:10.000Z (about 6 years ago)
- Last Synced: 2024-07-21T06:47:40.439Z (5 months ago)
- Topics: api, cross-field, dependencies, django, flask, python, validation
- Language: Python
- Homepage:
- Size: 77.1 KB
- Stars: 60
- Watchers: 4
- Forks: 1
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-python-models - required - Required is a simple library which allows you to validate dependencies across multiple fields. (Data validation)
README
# required: A easy to use DSL for validation
[]()
[](https://travis-ci.org/shezadkhan137/required)
[](https://coveralls.io/github/shezadkhan137/required?branch=master)
Required is a simple library which allows you to validate dependencies
across multiple fields. The goal is to make writing things like forms, seralizers and functions much easier by providing a declarative way to encode validation logic. It aims to:
- Have a declarative way to encode validation logic
- Allow you to maintain validation logic easily
- Allow you to reuse your validation logic easily
- Be flexible with what you want to validate
If this all sounds good. Read On!
## Installation
Install using `pip`
```
pip install required
```
## Quickstart
You can use required in a number of ways. The easiest way is to use the `validate` decorator to validate inputs to function calls.
```python
from required import validate
@validate
def calculate_sum(positive_number, negative_number):
"""
positive_number -> positive_number > 0
negative_number -> negative_number < 0
"""
return positive_number + negative_number
# the following will raise a validation exception
calculate_sum(1, 1)
# this will pass validation
calculate_sum(1, -1) # 0
```
If you want to have other information in the docstring, the validation rules can be wrapped inside of `Requires { }` as shown below:
```python
@validate
def calculate_sum(positive_number, negative_number):
"""
Other documentation relating to calculate_sum
Requires {
positive_number -> positive_number > 0
negative_number -> negative_number < 0
}
You can also put information after the requires rules
"""
return positive_number + negative_number
```
Validation rules are written in the doc string of the function. They look like:
`[param] -> [expression_1] [comparator] [expression_2]`
When `param` is present, it requires `expression_1 [comparator] expression_2` to evaluate to true.
The most simple expressions are just variables passed into the function to validate, however they can be more complex. See cookbook for more examples.
The comparator can be one of the standard python comparator operations; `==`, `!=`, `in`, `>=` `<=`, `>`, `<`.
## Cookbook
The following shows some examples for writing validation rules
```
# Arithmetic on the objects follow normal maths rules.
# you need to put brackets to define expressions
x -> (x + 1) < 1
x -> (x - y) == 1
# A value `x` needs to be in an array
x -> x in arr
# The length of x must be 10
# see section on registering functions
x -> len(x) == 10
# The length of x and y must be the same
x -> len(x) == len(y)
# when x is present y must not be present
# TODO: not implemented in DSL yet
x -> x ==
# x must be equal to the return value of a function
x -> x == func(x)
# Partial dependencies can be also specified
# when x == 1 then y must be 2
x == 1 -> y == 2
# when x == 1 then y must be set
x == 1 -> y
```
## Registering callables
You can register callables into the validation scope. This is useful when you want to call normal python builtins or custom callables.
```python
from required import validate
scoped_validate = validate.register_callables({
"len": len,
"abs": abs
})
@scoped_validate
def return_first_element(arr):
"""
arr -> len(arr) >= 1
"""
return arr[0]
# validation scoped callables can also be nested
# len, abs and my_func are available in the second_scoped_validate decorator
second_scoped_validate = scoped_validate.register_callables({
"my_func": my_func
})
# or inserted at function level
@validate(callables_dict={"new_func": new_func})
def other_function(var):
"""
var -> new_func(var) >= 1
"""
return var
```
## Contributing
If you want to contribute you are most welcome! This project is distributed under the [MIT](https://choosealicense.com/licenses/mit/) licence. It is tested using [tox](https://pypi.python.org/pypi/tox) against Python 2.7 and 3.4+