diff options
Diffstat (limited to 'django/forms/forms.py')
| -rw-r--r-- | django/forms/forms.py | 87 |
1 files changed, 38 insertions, 49 deletions
diff --git a/django/forms/forms.py b/django/forms/forms.py index 99c2f03558..85f68e56eb 100644 --- a/django/forms/forms.py +++ b/django/forms/forms.py @@ -24,9 +24,7 @@ __all__ = ('BaseForm', 'Form') class DeclarativeFieldsMetaclass(MediaDefiningClass): - """ - Metaclass that collects Fields declared on the base classes. - """ + """Collect Fields declared on the base classes.""" def __new__(mcs, name, bases, attrs): # Collect fields from current class. current_fields = [] @@ -63,10 +61,12 @@ class DeclarativeFieldsMetaclass(MediaDefiningClass): @html_safe class BaseForm: - # This is the main implementation of all the Form logic. Note that this - # class is different than Form. See the comments by the Form class for more - # information. Any improvements to the form API should be made to *this* - # class, not to the Form class. + """ + The main implementation of all the Form logic. Note that this class is + different than Form. See the comments by the Form class for more info. Any + improvements to the form API should be made to this class, not to the Form + class. + """ default_renderer = None field_order = None prefix = None @@ -113,14 +113,14 @@ class BaseForm: def order_fields(self, field_order): """ - Rearranges the fields according to field_order. + Rearrange the fields according to field_order. - field_order is a list of field names specifying the order. Fields not - included in the list are appended in the default order for backward - compatibility with subclasses not overriding field_order. If field_order - is None, all fields are kept in the order defined in the class. - Unknown fields in field_order are ignored to allow disabling fields in - form subclasses without redefining ordering. + field_order is a list of field names specifying the order. Append fields + not included in the list in the default order for backward compatibility + with subclasses not overriding field_order. If field_order is None, + keep all fields in the order defined in the class. Ignore unknown + fields in field_order to allow disabling fields in form subclasses + without redefining ordering. """ if field_order is None: return @@ -153,7 +153,7 @@ class BaseForm: yield self[name] def __getitem__(self, name): - "Returns a BoundField with the given name." + """Return a BoundField with the given name.""" try: field = self.fields[name] except KeyError: @@ -170,21 +170,18 @@ class BaseForm: @property def errors(self): - "Returns an ErrorDict for the data provided for the form" + """Return an ErrorDict for the data provided for the form.""" if self._errors is None: self.full_clean() return self._errors def is_valid(self): - """ - Returns True if the form has no errors. Otherwise, False. If errors are - being ignored, returns False. - """ + """Return True if the form has no errors, or False otherwise.""" return self.is_bound and not self.errors def add_prefix(self, field_name): """ - Returns the field name with a prefix appended, if this Form has a + Return the field name with a prefix appended, if this Form has a prefix set. Subclasses may wish to override. @@ -192,13 +189,11 @@ class BaseForm: return '%s-%s' % (self.prefix, field_name) if self.prefix else field_name def add_initial_prefix(self, field_name): - """ - Add a 'initial' prefix for checking dynamic initial values - """ + """Add a 'initial' prefix for checking dynamic initial values.""" return 'initial-%s' % self.add_prefix(field_name) def _html_output(self, normal_row, error_row, row_ender, help_text_html, errors_on_separate_row): - "Helper function for outputting HTML. Used by as_table(), as_ul(), as_p()." + "Output HTML. Used by as_table(), as_ul(), as_p()." top_errors = self.non_field_errors() # Errors that should be displayed above all fields. output, hidden_fields = [], [] @@ -276,7 +271,7 @@ class BaseForm: return mark_safe('\n'.join(output)) def as_table(self): - "Returns this form rendered as HTML <tr>s -- excluding the <table></table>." + "Return this form rendered as HTML <tr>s -- excluding the <table></table>." return self._html_output( normal_row='<tr%(html_class_attr)s><th>%(label)s</th><td>%(errors)s%(field)s%(help_text)s</td></tr>', error_row='<tr><td colspan="2">%s</td></tr>', @@ -285,7 +280,7 @@ class BaseForm: errors_on_separate_row=False) def as_ul(self): - "Returns this form rendered as HTML <li>s -- excluding the <ul></ul>." + "Return this form rendered as HTML <li>s -- excluding the <ul></ul>." return self._html_output( normal_row='<li%(html_class_attr)s>%(errors)s%(label)s %(field)s%(help_text)s</li>', error_row='<li>%s</li>', @@ -294,7 +289,7 @@ class BaseForm: errors_on_separate_row=False) def as_p(self): - "Returns this form rendered as HTML <p>s." + "Return this form rendered as HTML <p>s." return self._html_output( normal_row='<p%(html_class_attr)s>%(label)s %(field)s%(help_text)s</p>', error_row='%s', @@ -304,8 +299,8 @@ class BaseForm: def non_field_errors(self): """ - Returns an ErrorList of errors that aren't associated with a particular - field -- i.e., from Form.clean(). Returns an empty ErrorList if there + Return an ErrorList of errors that aren't associated with a particular + field -- i.e., from Form.clean(). Return an empty ErrorList if there are none. """ return self.errors.get(NON_FIELD_ERRORS, self.error_class(error_class='nonfield')) @@ -315,15 +310,14 @@ class BaseForm: Update the content of `self._errors`. The `field` argument is the name of the field to which the errors - should be added. If its value is None the errors will be treated as - NON_FIELD_ERRORS. + should be added. If it's None, treat the errors as NON_FIELD_ERRORS. The `error` argument can be a single error, a list of errors, or a - dictionary that maps field names to lists of errors. What we define as - an "error" can be either a simple string or an instance of - ValidationError with its message attribute set and what we define as - list or dictionary can be an actual `list` or `dict` or an instance - of ValidationError with its `error_list` or `error_dict` attribute set. + dictionary that maps field names to lists of errors. An "error" can be + either a simple string or an instance of ValidationError with its + message attribute set and a "list or dictionary" can be an actual + `list` or `dict` or an instance of ValidationError with its + `error_list` or `error_dict` attribute set. If `error` is a dictionary, the `field` argument *must* be None and errors will be added to the fields that correspond to the keys of the @@ -369,8 +363,7 @@ class BaseForm: def full_clean(self): """ - Cleans all of self.data and populates self._errors and - self.cleaned_data. + Clean all of self.data and populate self._errors and self.cleaned_data. """ self._errors = ErrorDict() if not self.is_bound: # Stop further processing. @@ -433,9 +426,7 @@ class BaseForm: return self.cleaned_data def has_changed(self): - """ - Returns True if data differs from initial. - """ + """Return True if data differs from initial.""" return bool(self.changed_data) @cached_property @@ -464,9 +455,7 @@ class BaseForm: @property def media(self): - """ - Provide a description of all media required to render the widgets on this form - """ + """Return all media required to render the widgets on this form.""" media = Media() for field in self.fields.values(): media = media + field.widget.media @@ -474,8 +463,8 @@ class BaseForm: def is_multipart(self): """ - Returns True if the form needs to be multipart-encoded, i.e. it has - FileInput. Otherwise, False. + Return True if the form needs to be multipart-encoded, i.e. it has + FileInput, or False otherwise. """ for field in self.fields.values(): if field.widget.needs_multipart_form: @@ -484,14 +473,14 @@ class BaseForm: def hidden_fields(self): """ - Returns a list of all the BoundField objects that are hidden fields. + Return a list of all the BoundField objects that are hidden fields. Useful for manual form layout in templates. """ return [field for field in self if field.is_hidden] def visible_fields(self): """ - Returns a list of BoundField objects that aren't hidden fields. + Return a list of BoundField objects that aren't hidden fields. The opposite of the hidden_fields() method. """ return [field for field in self if not field.is_hidden] |