forms module

class campos.forms.Form(options=('ok', 'cancel'), fields=(), validation='current', **kwargs)[source]

Forms are used to arrange fields in order to facilitate data input and validation.

You can create a form by calling the Form constructor and providing fields and options:

fields = [StringField(), SelectField(), FileField(), TextField()]
buttons = ('reset', 'ok', 'cancel')
form = Form(fields=fields, options=buttons)

Or also by calling from_source() which generates form’s fields introspecting a source object:

class Person:
    def __init__(self, name, last_name, age):
        self.name = name
        self.last_name = last_name
        self.age = age

p = Person('Sheldon', 'Cooper', 25)
form = Form.from_source(p)

You can group related fields using group() method:

form.group('Identification', ['name', 'last_name'])

Also you can find a field contained in the form using its name:

field = form.field('last_name')

and obtain it’s value using dot notation:

value = form.last_name

Forms provide validation through validate() method which is called automatically when validation is set to ‘instant’.

More specialized forms can be created using CreationForm and EditionForm subclasses which provide some useful default behaviour for object creation and modification.

Parameters:
  • validation (str or a Validation member) – validation mechanism used by the form, if it’s ‘instant’ all fields are checked anytime one of them changes and corresponding buttons are enabled/disabled accordingly. If it’s ‘manual’ you should invoke validate() method by yourself.
  • fields (iterable of Field) – fields to add to this form
  • options (iterable of str, ButtonType or QPushButton) –

    options to show in the form, these can be QPushButton instances or ButtonType enum members (note that you can use strings too).

    If you use ButtonType members(or string) then you can connect the button with a callback passed as a keyword argument.

    For instance, if your options are ['save', 'cancel'] you can pass two keyword arguments named on_save and on_cancel which will be connected to save and cancel buttons. Note that the keyword(except the on_ part) matches the option name(ButtonType member’s name).

    Buttons with a rejection role(accept, cancel, etc) will be connected to form’s close() method if no callback is settled for them.

See also

CreationForm and EditionForm

add_button(btn, on_click=None)[source]

Adds a new button or option to form’s button box and connects it with a callback. The new button is always returned.

Buttons with a rejection role(accept, cancel, etc) will be connected to form’s close() method if no callback is settled for them.

Parameters:
  • btn (str, ButtonType or QPushButton) – new option to add, can be a QPushButton instance or ButtonType enum members(note that you can use strings too)
  • on_click (callable) – callback to invoke whenever the button is clicked.
Returns:

the new button

Return type:

QPushButton

add_field(field)[source]

Adds a field to this form.

Parameters:field (Field) – new field
button(which)[source]

Finds a button given its type.

Parameters:which (str or ButtonType) – button type to find, must be a valid member of ButtonType enum(note that you can use strings)
Returns:the button which type matches the argument
Return type:QPushButton
Raises ValueError:
 if no button of the given type was found
field(name)[source]

Find a field by its name.

Parameters:name (str) – name of the field
Returns:a field
Return type:Field
Raises ValueError:
 if there is no field in the form with the given name
static from_source(obj, source_kw={}, form_kw={})[source]

Creates a form introspecting fields from an object.

Fields are generated using a suited FieldSource instance.

Parameters:
  • obj (any) – object to extract fields from.
  • source_kw (dict) – keyword arguments to pass to FieldSource constructor
  • form_kw (dict) – keyword arguments to pass to Form constructor
group(title, fieldnames, layout='vertical')[source]

Groups fields in a common area under a title using chosen layout.

Parameters:
  • title (str) – title of the group
  • fieldnames (iterable of str) – names of the fields to group
  • layout (one of (‘vertical’, ‘horizontal’, ‘grid’)) – layout manager used to arrange fields inside the group. Defaults to ‘vertical’.
remove_field(name)[source]

Removes and returns a field from this form using its name.

Parameters:name (Field) – name of the field to remove
Returns:the removed field
Return type:Field
validate(title='Invalid fields', msg=None)[source]

Runs validation on every field of this form.

This method is automatically called if form validation is set to ‘instant’, all buttons with an acceptance role are disabled when invalid fields are found.

If form validation is set to ‘manual’ then a message is shown when invalid fields are found.

Parameters:
  • title (str) – title of the message shown when invalid fields are found. Used only when form validation is set to ‘manual’
  • msg (str) – text to show when invalid fields are found. Used only when form validation is set to ‘manual’
validation

Validation mechanism used by the form.

If it’s ‘instant’ all fields are checked whenever one of them changes. If it’s ‘manual’ you should invoke validate() method by yourself.
Type:Validation
class campos.forms.CreationForm(**kwargs)[source]

Form subclass with useful defaults to create new objects.

This form’s options defaults to ('reset', 'save', 'cancel'). Also, a reset() method is included and connected by default to the reset button to restore all fields in the form to their default values.

See also

EditionForm

reset()[source]

Restores all fields in the form to their default values

class campos.forms.EditionForm(**kwargs)[source]

Form subclass with useful defaults to edit existing objects.

This form’s options defaults to ('reset', 'save', 'cancel'). Also, a reset() method is included and connected by default to a reset button to restore all fields in the form to their saved values.

You can edit an existing object using edit() method which obtains a value for every field from the object, field names must be equal to attributes names in the object in order to obtain their current value:

class Person:
    def __init__(self, name, last_name, age):
        self.name = name
        self.last_name = last_name
        self.age = age

billy = Person('Billy', 'Smith', 20)
john = Person('John', 'Bit', 26)

# create form's fields using Person attributes
form = EditionForm.from_source(billy)

# prepares the form for edition and fills fields with current values
form.edit(john)

See also

CreationForm

edit(obj, disabled=())[source]

Puts the form in edition mode, filling fields with object values.

To prevent some of the fields from been modified when editing use disable keyword and provide the names of the fields. Field names must match object attributes in order to load values correctly.

Parameters:
  • obj (any) – object used to fill form fields, only those attributes which match field names will be used.
  • disabled (iterable of str) – names of the fields to be disabled in edition mode.
reset()[source]

Restores all fields in the form to their saved values if edit() method has been called, otherwise restores to default values