fforms 1.1.1

Installation

fforms is a pure Python package with no dependencies, so installing it should be very straightforward. It’s tested on Python 3.3 through 3.6. [1]

1. Option A: pip install fforms

2. Option B: download the source code, change into the working directory, and run python setup.py install

Features

• A familiar interface for use in views

form = fforms.bind_dotted(registration_form, request.POST, request.FILES)
if request.method == 'POST':
    if form.is_valid():
        data = form.clean_data
        # do stuff with the data
        return redirect("/url/to/redirect")
return render_template("template-name.html", form=form)

• Logical data structures that allow easy access from templates

{% set field = form.username %}
<input type="text"{#
    #} value="{{ field.raw_data|default("", True) }}"{#
    #} {% if field.error %}class="invalid"{% endif %}{#
    #} name="field.full_name">
{% if field.error %}
    <span class="error-msg">{{ field.error }}</span>
{% endif %}

<ul>
    {% for field in form.attendees %}
        <input type="text" name="{{ field.full_name }}">
    {% endfor %}
</ul>

• Easy to add custom validators

myform['product_id'].validator = validators.from_regex(
    "^[A-Z]{2}-[0-9]{3}-[0-9]{4}$"
    "Please provide a valid product ID in the format XX-NNN-NNNN")
myform['state'].validator = validators.one_of(
    "ME", "NH", "VT",
    msg="We only serve the Northeast")
def funky_validator(data):
    left, right = data[:4], data[4:]
    if (int(left, 16), right) not in VALUES:
        raise ValidationError("Invalid format", data)
    # more funky tests
    return process(left, right)  # Set the field value
myform['funky-field'].validator = funky_validator

• Internationalization using your choice of framework.

def translate_msg(msg, kwargs):
    # msg is a str.format-formatted string, and kwargs has all the
    # field values.
    msg = _(msg)
    kwargs = {key: _(val) for key, val in kwargs.items()}
    return msg.format(**kwargs)

fforms.validators.DeferredMessage.process_message = translate_msg

• Pure Python with no outside dependencies. Don’t bring in a gigantic web framework just to use their forms library

License

This project is licensed under the MIT license.

Getting started

To use fforms, you’ll first need to define a schema for your form. This is most easily accomplished by using fforms.schema.make_from_literal as follows

from fforms import make_from_literal, validators, bind_dotted
schema = make_from_literal({
    'username': validators.from_regex("^[a-zA-Z][a-zA-Z0-9_]{0,25}"),
    'password': validators.chain(
        validators.limit_length(min=8, max=128),
        validators.from_regex("[a-z]",
                              "{field.name} must contain lowercase letters"),
        validators.from_regex("[A-Z]",
                              "{field.name} must contain uppercase letters"),
        validators.from_regex("[0-9]", "{field.name} must contain numbers"),
        validators.from_regex("[^a-zA-Z0-9]",
                              "{field.name} must contain special characters")
    ),
    'password2': validators.ensure_str,
    'email': validators.email,
    'address': {
        'street': validators.chain(validators.ensure_str,
                                   validators.limit_length(min=2)),
        'street2': validators.ensure_str,
        'zip_code': validators.chain(validators.from_regex("^[0-9]+$"),
                                     validators.limit_length(min=5, max=5)),
        'state': validators.one_of("ME", "NH", "VT", "MA")
    },
    'tags': [
        {'name': validators.ensure_str}
    ],
})
schema.validator = validators.chain(
    schema.validator,  # The default is validators.all_children
    validators.key_matcher("password", "password2",
                           "Please ensure the two passwords match"))

schema['tags'].validator = validators.chain(
      schema['tags'].validator,
      validators.limit_length(min=1, max=8)
)

Once you have a schema object, you can bind it to data to create a bound form object

form = bind_dotted(schema, {
    'username': 'felipeochoa',
    'password': '123abcDEF!@#',
    'password2': '123ABCdef!@#',
    'email': 'me@example',
    'address.street': '123 Main St.',
    'address.street2': 'Unit 1',
    'address.zip code': '1234',
    'tags:0.name': 'tag1',
    'tags:1.name': 'tag2',
})
assert not form.is_valid()
for field in form:
    print("%s %r (%s)" % (field.name, field.clean_data, field.error))

Which will print out:

username 'felipeochoa' (None)
password '123abcDEF!@#' (None)
password2 '123ABCdef!@#' (None)
tags [{'name': 'tag1'}, {'name': 'tag2'}] (None)
address None ()
email 'me@example' (Enter a valid email address.)

(address does not have an error message of its own; all the errors are in its children).

You can use this code in your views or templates in a conventient fashion

def my_view(request):
    form = bind_dotted(registration_form, request.POST, request.FILES)
    if request.method == 'POST':
        if form.is_valid():
            data = form.clean_data
            # do stuff with the data
            return redirect("/url/to/redirect")
    return render_template("template", form=form)

{% if form.error %}
   <span class="error-msg">form.error</span>
{% endif %}
{# more stuff #}
{% for field in form.tags %}
    <input type="text" value="{{ field.value }}" name="{{ field.full_name }}">
{% endfor %}

Detailed Documentation

fforms operates on three basic concepts: Schema, Validators, and Forms.

user_schema = {
    'username': limit_length(max=25),
    'password': ensure_complexity(numbers=True, uppercase=True),
    'password2': ensure_str,
}

many_users_schema = [
    {
      'username': limit_length(max=25),
      'password': ensure_complexity(numbers=True, uppercase=True),
      'password2': ensure_str,
    }
]

def as_int(data):
    "Extract an integer from the data."
    try:
        return int(data)
    except (TypeError, ValueError):
        raise ValidationError("{field.name} must be a whole number", data)