Basic field classes

Basic field classes

class genshi_forms.fields.Field

Base class for all form fields.

needs_multipart

Whether this field requires a form to be submitted in multipart/form-data encoding. Set this attribute to True if the field renders an <input type="file">.

default_error_messages

A dictionary of field-specific error messages. Messages may be overridden by passing a dictionary as the error_overrides parameter of __init__().

widget

The widgets.Widget to render the field with. A field does not need a widget, but the default implementations of render() and render_request() require one.

__init__(required=True, widget=None, label=None, default=None, error_overrides=None, **kwargs)

Base field constructor.

required

Whether this field must be filled out for the form to be considered valid.

widget

A widget instance to be used instead of this field’s default widget.

label

If set, this will override the automatically generated label for this field.

default

Provides a default value for use in unbound forms.

error_overrides

A dictionary of key -> message values that will override the error messages for this field.

error_message(key, **kwargs)

Find the full error message for an error key.

This will search in the field’s default and overridden error messages for a message matching key. If no message can be found, raises KeyError. Once the template has been found, it will be formatted using kwargs.

get_label(name)

Retrieve the label for this field.

If no label has been specified, attempts to generate one using the field’s assigned name in the form.

This method should not be overridden. Instead, pass a value for the label parameter of __init__().

id_for_label(base_id)

Retrieve what ID labels for this field should use.

By default, returns base_id unchanged. Fancier implementations could append text to base_id before returning it.

For use with fields that render multiple widgets. In such fields, this method should be overridden to return the ID used for the first widget.

clean(name, post, files)

Convert data in an HTTP request to a Python value.

name

The name this field should use for lookup in post or files.

post

A dictionary of lists of unicode strings. For a Django request object, you can retrieve an appropriately formatted dictionary using dict (request.POST.lists ()).

files

A dictionary of Django file objects, in the same format as request.FILES.

If there is an error converting the data, an instance of genshi_forms.errors.ValidationError will be raised.

render(name, value, attrs)

Render this field into a Genshi markup stream.

name

The name this field has been assigned within the form.

value

The Python value bound to this field, or None.

attrs

Extra attributes to be rendered in the final widget, if applicable.

render_request(name, post, files, attrs)

Render this field into a Genshi markup stream, using data from an HTTP request.

This method is used because a user might enter invalid data into the form, but when the form is rendered their data should still be the default values for the fields.

name, and attrs are used as in render(). post and files are used as in clean().

class genshi_forms.fields.BooleanField

A field whose values are True or False.

When cleaning, this field assumes that False values will not be present in the POST dictionary.

class genshi_forms.fields.TextField

A field that cleans to a Python unicode object.

If this field is not present in the POST data, it will be cleaned to ''.

class genshi_forms.fields.IntegerField([minimum = None[, maximum = None]])

A field that cleans to an integer object.

Returns the result of int(), or None on empty data.

class genshi_forms.fields.PasswordField

Like TextField, but for passwords.

By default, renders with an genshi_forms.widgets.InputPassword widget. This blocks existing password data from being rendered.

class genshi_forms.fields.FileField

A field for uploaded files.

By default, renders with an genshi_forms.widgets.InputFile widget. If this field is present in a form, that form’s enctype attribute will be set to multipart/form-data.

Data is cleaned to a valid Django file object.

class genshi_forms.fields.DateField

Field for inputting dates.

Data is cleaned to an instance of datetime.date. Any format supported by genshi_forms.parsers.date() is supported by this field. When rendered, it will set class="date" on its widget.

class genshi_forms.fields.TimeField

Field for inputting times.

Data is cleaned to an instance of datetime.time. Any format supported by genshi_forms.parsers.time is supported by this field. When rendered, it will set class="time" on its widget.

class genshi_forms.fields.ChoiceField(choices[, size = None])

A field for choosing between a series of key-value options.

When comparing, keys are normalized to strings using unicode().

Cleans data to a (key, value) tuple.

class genshi_forms.fields.MultipleChoiceField(choices[, size = None])

Like ChoiceField, but for more than one choice.

Data is cleaned to a list of (key, value) tuples.

class genshi_forms.fields.MultiValueField(subfields)

A field that contains multiple sub-fields

Instead of overriding Field.clean() and Field.render(), subclasses may implement the compress() and decompress() methods.

Subclasses must implement the format_output() method.

compress(cleaned)

Convert a list of cleaned values into a single value.

cleaned is a list of values from the Field.clean() methods of each subfield, in order. The return value may be of any type appropriate for the field.

By default, returns cleaned unchanged.

decompress(value)

Convert a compressed value into a list of values.

The returned list may be shorter than the list of subfields, in which case it will be padded with None.

By default, returns:

• None -> []
• sequence -> sequence
• value -> [value]

format_output(rendered_fields, name, attrs)

Generate a Genshi markup stream.

rendered_fields is a list of markup streams from subfields. name and attrs are as in Field.render().

class genshi_forms.fields.DateTimeField([timezone = UTC])

Field for inputting combined date/times.

Data is cleaned to an instance of datetime.datetime. Any formats supported by genshi_forms.parsers.date() and genshi_forms.parsers.time() are supported. Values are returned in the UTC timezone. If the input should be assumed to use a different timezone, one may be passed to the constructor. By default, all times are assumed to be in UTC.

class genshi_forms.fields.EMailField

Field for inputting e-mail addresses.

This field performs only basic validation, that there is a single @ sign in the text.