# FlyForms reference

## Forms

`Form` is the root class of FlyForms that provide the highest level API for validation and mapping of data structures. All user-defined forms must inherit this class.

### Form class

class `flyforms.form.``Form`

  Base class for all user-defined Forms

  Construction

  `__init__`(**data)

    Parameters: | data (dict) – additional data to form

    When a Form is instantiated you can access given data via instance attributes or get everything at once using `form.data`

  Note

  Even if you do not pass some keys in `kwargs`, you can use instance attributes, but will receive `UNSET` value

  Properties

  `is_bound`

    Checks is Form instance bound. Returns True if all fields is bound. Otherwise, False.

  `is_valid`

    Checks is Form instance valid. Returns there are no errors. Otherwise, False.

  `data`

    Returns `dict` with bound data (if you need all data even `UNSET` values - use `form.raw_data`)

  Attributes

  `raw_data`

    Normal Python `dict` contains all Form data (even `UNSET` values)

  `_fields`

    Python `set` contains all defined fields names

### Defining Forms

Forms defining is quite simply process. All you need to do is to make a subclass of `Form` and define fields as class attributes. If you need to extend Forms, inheritance is available. New Form will contain all fields of the parent form as well as it’s own.

### Using Forms

Todo

Write usage

## In flight data validation

If you already have defined Form and you want to just validate some data structure via it you can use `validate_schema()` function from `flyforms.form` module.

### Usage

Todo

Write usage

### Signature for validate_schema

`flyforms.form.``validate_schema`(form_cls, **data)

  This function validates given data via given Form subclass without defined Form instantiation.

  Parameters: | form_cls (Form subclass) – defined Form class data – data to validate
  Returns: | boolean flag is data valid for given `form_cls`
  Raises TypeError:
  | if given `form_cls` is not class or not `Form` subclass

## Fields

Fields represent a set of rules to data validation via set of `Validator` instances. When you define yours custom `Form` you define Fields as its class attributes. This is the most common usage of Fields, but nothing prevents you to use them standalone.

### Field class

class `flyforms.fields.``Field`

  Construction

  `__init__`(required=True, choices=(), validators=(), **kwargs)

    Parameters: | required (bool) – boolean flag is this field required or can be empty choices (iterable) – iterable object contains possible values of this field validators (list of callable) – the additional validators for field default (instance of value_types) – the default value of the field
    Raises TypeError:
    | if passed arguments invalid

  Methods

  `validate`(value)

    Validates given value via defined set of `Validators`

    Parameters: | value – the value to validate

  `is_valid`(value)

    The ‘silent’ variant of value validation.

    Parameters: | value – the value to validate
    Returns: | True if given value is valid, otherwise - False

  Attributes

  `required`

    Boolean flag passed to constructor

  `default`

    The default value for Field (passed to constructor value or `UNSET`)

  `base_validators`

    List of attached by processing construction arguments `Validators`

  `custom_validators`

    Iterable object contains `custom_validators` passed to constructor

  Property

  `validators`

    Chain, contains `base_validators` and `custom_validators`

### UNSET value

`flyforms.fields.``UNSET`

  frequently used constant, it is a reflection of unidentified values

### Basic Fields

#### StringField

class `flyforms.fields.``StringField`(min_length=None, max_length=None, regex='', **kwargs)

  Reflects Python strings

  `__init__`(min_length=None, max_length=None, regex='', **kwargs)

    Parameters: | required (bool) – boolean flag is this field required min_length (int or None) – the minimum length of the string max_length (int or None) – the maximum length of the string regex (str or regexp) – the regular expression to validate choices (iterable) – iterable object contains possible values of this field validators (list of callable) – the additional validators for field default (instance of value_types) – the default value of the field

#### EmailField

class `flyforms.fields.``EmailField`(**kwargs)

  Reflects Python string corresponding to an email

  `__init__`(**kwargs)

    Parameters: | required (bool) – boolean flag is this field required choices (iterable) – iterable object contains possible values of this field validators (list of callable) – the additional validators for field default (instance of value_types) – the default value of the field

#### IntField

class `flyforms.fields.``IntField`(min_value=None, max_value=None, **kwargs)

  Reflects Python integer (`int`)

  `__init__`(min_value=None, max_value=None, **kwargs)

    Parameters: | required (bool) – boolean flag is this field required min_value – the minimum valid value max_value – the maximum valid value choices (iterable) – iterable object contains possible values of this field validators (list of callable) – the additional validators for field default (instance of value_types) – the default value of the field

#### FloatField

class `flyforms.fields.``FloatField`(min_value=None, max_value=None, **kwargs)

  Reflects Python float (`float`)

  `__init__`(min_value=None, max_value=None, **kwargs)

    Parameters: | required (bool) – boolean flag is this field required min_value – the minimum valid value max_value – the maximum valid value choices (iterable) – iterable object contains possible values of this field validators (list of callable) – the additional validators for field default (instance of value_types) – the default value of the field

#### BooleanField

class `flyforms.fields.``BooleanField`(**kwargs)

  Reflects Python boolean (`bool`)

  `__init__`(**kwargs)

    Parameters: | required (bool) – boolean flag is this field required validators (list of callable) – the additional validators for field default (instance of value_types) – the default value of the field

#### Ip4Field

class `flyforms.fields.``Ip4Field`(**kwargs)

  Reflects Python string corresponding to an IPv4 address

  `__init__`(**kwargs)

    Parameters: | required (bool) – boolean flag is this field required choices (iterable) – iterable object contains possible values of this field validators (list of callable) – the additional validators for field default (instance of value_types) – the default value of the field

### Custom Fields

Sometimes, it is necessary to design custom fields for validation of some special data structures. If you want do this, you should design your custom subclass of the `Field`.

## Validators

Validators validate given value via their internal logic. If value is invalid `ValidationError` will be raised.

### ValidationError

class `flyforms.validators.``ValidationError`

  Raised when a validator fails to validate it’s input.

### Builtin validators

#### RequiredValidator

class `flyforms.validators.``RequiredValidator`

  Validates is given value not `UNSET` object

#### TypedValidator

class `flyforms.validators.``TypedValidator`(value_types)

  Validates is given value instance of defined `value_types`

  `__init__`(value_types)

    Parameters: | value_types – list of possible value types

#### EntryValidator

class `flyforms.validators.``EntryValidator`(iterable)

  Validates is given value in specified during initialization iterable object

  `__init__`(iterable)

    Parameters: | iterable – the iterable object
    Raise: | TypeError if given object is not iterable

#### MinValueValidator

class `flyforms.validators.``MinValueValidator`(min_value, strong=True)

  Validates is given value greater than specified during initialization value

  `__init__`(min_value, strong=True)

    Parameters: | min_value – the minimum valid value strong (bool) – boolean flag should be comparison strict or not

#### MaxValueValidator

class `flyforms.validators.``MaxValueValidator`(max_value, strong=True)

  Validates is given value less than specified during initialization value

  `__init__`(max_value, strong=True)

    Parameters: | max_value – the maximum valid value strong (bool) – boolean flag should be comparison strict or not

#### MinLengthValidator

class `flyforms.validators.``MinLengthValidator`(min_length, strong=True)

  Validates the minimum object length

  `__init__`(min_length, strong=True)

    Parameters: | min_length – the minimum valid length strong (bool) – boolean flag should be comparison strict or not

#### MaxLengthValidator

class `flyforms.validators.``MaxLengthValidator`(max_length, strong=True)

  Validates the maximum object length

  `__init__`(max_length, strong=True)

    Parameters: | max_length – the maximum valid length strong (bool) – boolean flag should be comparison strict or not

#### RegexValidator

class `flyforms.validators.``RegexValidator`(regex, flags=0)

  Validates matching with regular expression

  `__init__`(regex, flags=0)

    Parameters: | regex – the regular expression flags – flags passed to re.match function

#### EmailValidator

class `flyforms.validators.``EmailValidator`

  Validates an email address via simple regex.

#### Ip4AddressValidator

class `flyforms.validators.``Ip4AddressValidator`

  Validates an IPv4 address via simple regex.

### Custom Validators

If you need to make additional data validation you can use your custom validators. There is one requirement: validator should be an initialized and callable object. If you want, you can use and extend one of this classes: `Validator` or `SimpleValidator`.

#### Validator class

class `flyforms.validators.``Validator`

  This the base class for all Fields.

  `validate`(value)

    Validate the given value

    Parameters: | value – given value to validate

    :raise ValidationError if given value is not valid

  `is_valid`(value)

    The ‘silent’ variant of validation

    Parameters: | value – given value to validate
    Returns: | boolean flag is given value valid
    Return type: | bool

#### SimpleValidator class

class `flyforms.validators.``SimpleValidator`

  The Validator’s subclass with only one validation case. Given value should satisfies condition in positive_case method