spotlight 1.0.4

Laravel style data validation for Python.

Spotlight

Laravel style data validation for Python.

Table of Contents

• Installation
• Dependencies
• Usage
  • Simple Examples
  • Direct Validation
• Available Rules
• Advanced Usage
  • Custom Error Messages
  • Custom Rules
• Plugins
  • Spotlight SQLAlchemy

Installation

Spotlight can be installed via pip:

pip install spotlight

Dependencies

• python >= 3.6.0

Usage

from spotlight.validator import Validator

Simple Examples

rules = {
    "email": "required|email",
    "first_name": "required|string|max:255",
    "last_name": "required|string|max:255",
    "password": "required|min:8|max:255"
}

data = {
    "email": "[e-mail]",
    "first_name": "John",
    "last_name": "Doe",
    "password": "test1234"
}

validator = Validator()
errors = validator.validate(data, rules)

Nested validation:

rules = {
    "token": "required|string",
    "person": {
        "first_name": "required|string|max:255",
        "last_name": "required|string|max:255",
        "email": "required|email",
        "password": "required|min:8|max:255"
    }
}

data = {
    "token": "test-token",
    "person": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "[e-mail]",
        "password": "test1234"
    }
}

validator = Validator()
errors = validator.validate(data, rules)

List validation:

rules = {
    "players": "required|list|min:2",
    "players.*.username": "required"
}

data = {
    "players": [
        {
            "username": "Player 1"
        },
        {
            "username": "Player 2"
        }
    ]
}

validator = Validator()
errors = validator.validate(data, rules)

Direct Validation

Sometimes there is a need for quick and simple validation, without having to create a rule set. The Validator class exposes several static methods that can be used for direct validation.

Examples:

validator = Validator()
email = "[e-mail]"

if validator.valid_email(email):
    print("This is a valid email!")

# Or like this:

if Validator.valid_email(email):
    print("This is a valid email!")

Available methods:

• valid_alpha_num
• valid_alpha_num_space
• valid_boolean
• valid_date_time
• valid_dict
• valid_email
• valid_float
• valid_integer
• valid_ip
• valid_json
• valid_list
• valid_string
• valid_url
• valid_uuid4

Available Rules

• accepted
• after
• alpha_num
• alpha_num_space
• before
• boolean
• date_time
• dict
• email
• ends_with
• filled
• float
• in
• integer
• ip
• json
• list
• max
• min
• not_with
• required
• required_if
• required_unless
• required_with
• required_without
• size
• starts_with
• string
• url
• uuid4

accepted

The field under validation must be yes, on, 1, or true. This is useful for validating "Terms of Service" acceptance.

accepted

after

The field under validation must be a value after a given date/time. For more details about formatting see the date_time rule.

after:2019-12-31 12:00:00

If the after rule is accompanied by the date_time rule, and a non default format is specified, the specified format will be assumed for the after rule as well:

date_time:%H:%M:%S|after:12:00:00

Instead of passing a date/time string to be evaluated by the strptime Python function, you may specify another field to compare against the date/time:

after:some_field

alpha_num

The field under validation must be entirely alpha-numeric characters.

alpha_num

alpha_num_space

The field under validation may have alpha-numeric characters, as well as spaces.

alpha_num_space

before

The field under validation must be a value before a given date/time. For more details about formatting see the date_time rule.

before:2019-12-31 12:00:00

If the before rule is accompanied by the date_time rule, and a non default format is specified, the specified format will be assumed for the after rule as well:

date_time:%H:%M:%S|before:12:00:00

Instead of passing a date/time string to be evaluated by the strptime Python function, you may specify another field to compare against the date/time:

before:some_field

boolean

The field under validation must be a boolean.

boolean

date_time

The field under validation must be a valid date/time matching the "YYYY-MM-DD hh:mm:ss" format, or a custom specified format. For example, a field being validated with the following format "date_time:%m/%d/%Y" must match the "MM/DD/YYYY" format. The date/time validation uses the strptime Python function. For more info on valid formatting symbols check the following Python docs.

date_time

date_time:format

dict

The field under validation must be a dict.

dict

email

The field under validation must be a valid email address.

email

ends_with

The field under validation must end with one of the given values.

ends_with:value,other,...

filled

The field under validation must not be empty when it is present.

filled

float

The field under validation must be a float.

float

in

The field under validation must be included in the given list of values.

in:value,other,...

integer

The field under validation must be an integer.

integer

ip

The field under validation must be an IP address.

ip

json

The field under validation must be a valid JSON string.

json

list

The field under validation must be a list.

list

max

The field under validation must be less than or equal to the given maximum value. For strings, value corresponds to the number of characters. For integers, value corresponds to a given integer value. For floats, value corresponds to a given float value. For lists and dicts, value corresponds to the length of the list.

max:value

min

The field under validation must be greater than or equal to the given minimum value. For strings, value corresponds to the number of characters. For integers, value corresponds to a given integer value. For floats, value corresponds to a given float value. For lists and dicts, value corresponds to the length of the list.

min:value

not_with

The field under validation can't be present if the other specified field is present.

not_with:other

required

The field under validation must be present in the input data and not empty. A field is considered "empty" if one of the following conditions are true:

• The value is None.
• The value is an empty string.
• The value is an empty list.

required

required_if

The field under validation must be present and not empty if the other specified field equals a certain value.

required_if:other,value

required_unless

The field under validation must be present and not empty unless the other specified field equals a certain value.

required_unless:other,value

required_with

The field under validation must be present and not empty only if any of the other specified fields are present.

required_with:field1,field2,...

required_without

The field under validation must be present and not empty only when any of the other specified fields are not present.

required_without:field1,field2,...

size

The field under validation must have a size matching the given value. For strings, value corresponds to the number of characters. For integers, value corresponds to a given integer value. For floats, value corresponds to a given float value. For lists and dicts, value corresponds to the length of the list.

size:value

starts_with

The field under validation must start with one of the given values.

starts_with:value,other,...

string

The field under validation must be a string.

string

url

The field under validation must be a valid URL.

url

uuid4

The field under validation must be a valid uuid (version 4).

uuid4

Advanced Usage

Custom Error Messages

If needed, you can specify custom error messages to overwrite the default error messages.

Messages

You can overwrite all messages for a specific rule. In the example below we are overwriting all 'required' error messages:

validator = Validator()
validator.overwrite_messages = {
    "required": "Hey! This is a required field!"
}

You can overwrite all messages for a specific field. In the example below we are overwriting all the error messages for the 'first_name' field:

validator = Validator()
validator.overwrite_messages = {
    "first_name": "Hey! This field contains an error!"
}

You can overwrite an error message for a specific rule of a specific field. In the example below we are overwriting the 'first_name.required' error message:

validator = Validator()
validator.overwrite_messages = {
    "first_name.required": "Hey! This is a required field!"
}

Fields

If you would like the 'field' portion of your validation message to be replaced with a custom field name, you may do so like this:

validator = Validator()
validator.overwrite_fields = {
    "email": "e-mail address"
}

Values

Sometimes you may need the 'value' portion of your validation message to be replaced with a custom representation of the value. For example, consider the following rule that specifies that a credit card number is required if the payment_type has a value of cc:

rules = {
    "credit_card_number": "required_if:payment_type,cc"
}

If this validation rule fails, it will produce the following error message:

The credit_card_number field is required if the payment_type field equals cc.

Instead of displaying cc as the payment type value, you may specify a custom value:

validator = Validator()
validator.overwrite_values = {
    "cc": "credit card"
}

Now if the validation rule fails it will produce the following message:

The credit_card_number field is required if the payment_type field equals credit card.

Custom Rules

To create a new rule, create a class that inherits from the Rule class. A rule is required to have the following specifications:

• A rule should have a name attribute.
• A rule should implement the passes() method which contains the logic that determines if a value passes the rule.
• A rule should have a message property.

Here is an example of an uppercase rule:

from spotlight.rules import Rule


class UppercaseRule(Rule):
    """Uppercase"""

    name = "uppercase"

    def passes(self, field: str, value: Any, parameters: List[str], validator) -> bool:
        self.message_fields = dict(field=field)

        return value.upper() == value

    @property
    def message(self) -> str:
        return "The {field} field must be uppercase."

As shown in the above example, the passes() method will receive the following arguments:

• field -- name of the field under validation
• value -- value of the field under validation
• parameters -- list of rule parameters
• validator -- instance of the validator

After creating a custom rule it has to be registered with the validator:

from custom_rules import UppercaseRule

validator = Validator()
validator.register_rule(UppercaseRule())

After registering the rule, it can be used:

rules = {
    "test": "uppercase"
}

data = {
    "test": "HELLO WORLD!"
}

In addition to the name attribute, a rule has 2 additional attributes which are set to "False" by default: implicit & stop. These attributes may be overwritten.

Implicit

Setting implicit to "True" will cause the field under validation to be validated against the rule even if the field is not present. This is useful for rules such as "required".

Stop

Setting stop to "True" causes the validator to stop validating the rest of the rules specified for the current field if the current rule fails.

Message Fields

If a rule contains a message property that contains keyword arguments (words surrounded by curly braces) like the one in the example below, the "message_fields" variable needs to be set in the passes method.

@property
def message(self) -> str:
    return "The {field} field must be uppercase."

The "message_fields" variable can be set as shown in the example below. The keyword arguments in the message property will be replaced with the values from the "message_fields" dictionary.

def passes(self, field: str, value: Any, parameters: List[str], validator) -> bool:
    self.message_fields = dict(field=field)

Plugins

Spotlight SQLAlchemy

To use database rules such as unique and exists checkout the Spotlight SQLAlchemy plugin.