ptah.form

ptah.form.null

Represents a null value in field-related operations.

ptah.form.required

Represents a required value in field-related operations.

class ptah.form.Invalid(field, msg)

An exception raised by data types and validators indicating that the value for a particular node was not valid.

Form

class ptah.form.Form(context, request)

A form

id: Form id

name: Form name

label: Form label

description: Form description

prefix: Form prefix, it used for html elements id generations.

fields: Form fields ptah.form.Fieldset

buttons: Form buttons ptah.form.Buttons

actions: Instance of ptah.form.Actions class

widgets: Instance of FormWidgets class

content: Form content, it should be None or dictionary with data for fields.

params: None

mode: Form mode. It can be ptah.form.FORM_INPUT or

ptah.form.FORM_DISPLAY

action: Form action, by default request.url

method: HTML Form method (post, get)

csrf: Enable/disable form csrf protection

token: csrf token

csrf-name: csrf field name

extract()

extract form values

form_content()

Return form content. By default it returns Form.content attribute.

form_params()

get request params

render()

render form

update(**data)

update form

update_actions()

Prepare form actions, this method should be called directly. Form.update calls this method during initialization.

update_widgets()

prepare form widgets

validate(data, errors)

additional form validation

validate_csrf_token()

csrf token validation

class ptah.form.DisplayForm(context, request)

Special form that just display content

class ptah.form.FormWidgets(fields, form, request)

Form widgets manager. Widget is bound to content field.

Field

class ptah.form.Field(name, **kw)

Field base class.

name: Name of this field.

title: The title of this field. Defaults to a titleization

of the name (underscores replaced with empty strings and the first letter of every resulting word capitalized). The title is used by form for generating html form.

description: The description for this field. Defaults to

'' (the empty string). The description is used by form.

validator: Optional validator for this field. It should be

an object that implements the ptah.form.interfaces.Validator interface.

default: Default field value.

missing: Field value if value is not specified in bound value.

tmpl_input: The path to input widget template. It should be

compatible with pyramid renderers.

tmpl_display: The path to display widget template. It should be

compatible with pyramid renderers.

bind(prefix, value, params, context=None)

Bind field to value and request params

deserialize(value)

convert form value to field value

dumps(value)

return json value representation

extract(default=<widget.null>)

extract value from params

loads(s)

load field value from json

render(request)

render field

serialize(value)

Return value representation siutable for html widget

update(request)

Update field, prepare field for rendering

validate(value)

validate value

class ptah.form.FieldFactory(typ, name, **kw)

Create field by name. First argument name of field registered with ptah.form.field() decorator.

Example:

@form.field('customfield')
class CustomField(form.Field):
    ...

# Now `customfield` can be used for generating field:

field = form.FieldFactory(
    'customfield', 'fieldname', ...)

class ptah.form.Fieldset(*args, **kwargs)

class ptah.form.FieldsetErrors(fieldset, *args)

class ptah.form.field(name, _field__depth=1)

Field registration directive. Field should be inherited from ptah.form.Field class.

@form.field('text')
class TextField(form.Field):
    ...

ptah.form.fieldpreview(cls)

Register fieldpreview factory for field class. Fieldpreview factory is used in Field types management module. It should be an object that implements the ptah.form.interfaces.Preview interface.

@form.fieldpreview(form.TextField)
def textPreview(request):
    field = form.TextField(
        'TextField',
        title = 'Text field',
        description = 'Text field preview description',
        default = 'Test text in text field.')

    widget = field.bind('preview.', form.null, {})
    widget.update(request)
    return widget.snippet('form-widget', widget)

ptah.form.get_field_factory(name)

Return field factory by name.

ptah.form.get_field_preview(cls)

Return field preview factory for field class.

Button

ptah.form.button(title, **kwargs)

Register new form button.

Parameters:

• title – Button title. it is beeing used for html form generations.
• kwargs – Keyword arguments

class CustomForm(form.Form):

    field = form.Fieldset()

    @form.button('Cancel')
    def handle_cancel(self):
        ...

class ptah.form.Button

A simple button in a form.

class ptah.form.Buttons(*args)

Form buttons manager.

ptah.form.AC_DEFAULT

ptah.form.AC_PRIMARY

ptah.form.AC_DANGER

ptah.form.AC_SUCCESS

ptah.form.AC_INFO

Vocabulary

class ptah.form.SimpleTerm(value, token=None, title=None, description=None)

Simple tokenized term used by SimpleVocabulary.

class ptah.form.SimpleVocabulary(*terms)

Vocabulary that works from a sequence of terms.

classmethod create_term(*args)

Create a single term from data.

classmethod from_items(*items)

Construct a vocabulary from a list of (token, value) pairs.

classmethod from_values(*values)

Construct a vocabulary from a simple list.

Validators

class ptah.form.All(*validators)

Composite validator which succeeds if none of its subvalidators raises an Invalid exception

class ptah.form.Function(function, message=u'Invalid value')

Validator which accepts a function and an optional message; the function is called with the value during validation.

If the function returns anything falsy (None, False, the empty string, 0, an object with a __nonzero__ that returns False, etc) when called during validation, an ptah.form.Invalid exception is raised (validation fails); its msg will be the value of the message argument passed to this class’ constructor.

If the function returns a stringlike object (a str or unicode object) that is not the empty string , a ptah.form.Invalid exception is raised using the stringlike value returned from the function as the exeption message (validation fails).

If the function returns anything except a stringlike object object which is truthy (e.g. True, the integer 1, an object with a __nonzero__ that returns True, etc), an ptah.form.Invalid exception is not raised (validation succeeds).

The default value for the message when not provided via the constructor is Invalid value.

class ptah.form.Regex(regex, msg=None)

Regular expression validator.

Initialize it with the string regular expression regex that will be compiled and matched against value when validator is called. If msg is supplied, it will be the error message to be used; otherwise, defaults to ‘String does not match expected pattern’.

The regex argument may also be a pattern object (the result of re.compile) instead of a string.

When calling, if value matches the regular expression, validation succeeds; otherwise, ptah.form.Invalid is raised with the msg error message.

class ptah.form.Email(msg=None)

Email address validator. If msg is supplied, it will be the error message to be used when raising ptah.form.Invalid; otherwise, defaults to ‘Invalid email address’.

class ptah.form.Range(min=None, max=None, min_err=None, max_err=None)

Validator which succeeds if the value it is passed is greater or equal to min and less than or equal to max. If min is not specified, or is specified as None, no lower bound exists. If max is not specified, or is specified as None, no upper bound exists.

min_err is used to form the msg of the ptah.form.Invalid error when reporting a validation failure caused by a value not meeting the minimum. If min_err is specified, it must be a string. The string may contain the replacement targets ${min} and ${val}, representing the minimum value and the provided value respectively. If it is not provided, it defaults to '${val} is less than minimum value ${min}'.

max_err is used to form the msg of the ptah.form.Invalid error when reporting a validation failure caused by a value exceeding the maximum. If max_err is specified, it must be a string. The string may contain the replacement targets ${max} and ${val}, representing the maximum value and the provided value respectively. If it is not provided, it defaults to '${val} is greater than maximum value ${max}'.

class ptah.form.Length(min=None, max=None)

Validator which succeeds if the value passed to it has a length between a minimum and maximum. The value is most often a string.

class ptah.form.OneOf(choices)

Validator which succeeds if the value passed to it is one of a fixed set of values

Predefined fields

Any field can be create with two different way. Using field class:

field = ptah.form.TextField(
    'field',
    title='Text',
    description='Field description')

Or using field factory:

field = ptah.form.FieldFactory(
    'text', 'field',
    title='Text',
    description='Field description')

class ptah.form.TextField(name, **kw)

HTML Text input widget. Field name is text.

class ptah.form.IntegerField(name, **kw)

Integer input widget. Field name is int.

class ptah.form.FloatField(name, **kw)

Float input widget. Field name is float.

class ptah.form.DecimalField(name, **kw)

Decimal input widget. Field name is decimal.

class ptah.form.TextAreaField(name, **kw)

HTML Text Area input widget. Field name is textarea.

class ptah.form.FileField(name, **kw)

HTML File input widget. Field name is file.

class ptah.form.LinesField(name, **kw)

Text area based widget, each line is treated as sequence element. Field name is lines.

class ptah.form.PasswordField(name, **kw)

HTML Password input widget. Field name is password.

class ptah.form.DateField(name, **kw)

Simple date input field.

class ptah.form.DateTimeField(name, **kw)

class ptah.form.RadioField(name, **kw)

HTML Radio input widget. Field name is radio.

class ptah.form.BoolField(name, **kw)

Boolean input widget. Field name is bool.

class ptah.form.ChoiceField(name, **kw)

HTML Select input widget. Field name is choice.

class ptah.form.MultiChoiceField(name, **kw)

HTML Checkboxs input based widget. Field name is multichoice.

class ptah.form.MultiSelectField(name, **kw)

HTML Multi Select input widget. Field name is multiselect.

Extra params:

Parameters:size – Size of multiselect field, default is 5

class ptah.form.JSDateField(name, **kw)

Date input widget with JQuery Datepicker. Field name is date.

class ptah.form.JSDateTimeField(name, **kw)

DateTime input widget with JQuery Datepicker. Field name is datetime.

Form snippets

ptah.form.FORM_VIEW

ptah.form.FORM_ACTIONS

ptah.form.FORM_WIDGET

ptah.form.FORM_DISPLAY_WIDGET