Commits

James Crasta committed de46c72

Documentation consistency: TextField -> StringField

  • Participants
  • Parent commits ea5b374

Comments (0)

Files changed (8)

File docs/crash_course.rst

 Key Concepts
 ------------
 
- - **Forms** are the core container of WTForms. Forms represent a collection of
-   fields, which can be accessed on the form dictionary-style or atrribute
-   style.
- - **Fields** do most of the heavy lifting. Each field represents a *data type*
+ - :class:`Forms <wtforms.form.Form>` are the core container of WTForms. Forms
+   represent a collection of fields, which can be accessed on the form 
+   dictionary-style or attribute style.
+ - :mod:`Fields <wtforms.fields>` do most of the heavy lifting. Each field represents a *data type*
    and the field handles coercing form input to that datatype. For example,
-   `IntegerField` and `TextField` represent two different data types. Fields
+   `IntegerField` and `StringField` represent two different data types. Fields
    contain a number of useful properties, such as a label, description, and a
    list of validation errors, in addition to the data the field contains.
- - Every field has a **Widget** instance. The widget's job is rendering an HTML
-   representation of that field. Widget instances can be specified for each
-   field but every field has one by default which makes sense. Some fields are
-   simply conveniences, for example `TextAreaField` is simply a `TextField`
-   with the default widget being a `TextArea`.
- - In order to specify validation rules, fields contain a list of **Validators**.
+ - Every field has a :mod:`Widget <wtforms.widgets>` instance. The widget's job
+   is rendering an HTML representation of that field. Widget instances can be
+   specified for each field but every field has one by default which makes 
+   sense. Some fields are simply conveniences, for example 
+   :class:`~wtforms.fields.TextAreaField` is simply a 
+   :class:`~wtforms.fields.StringField` with the default widget being a
+   :class:`~wtforms.widgets.TextArea`.
+ - In order to specify validation rules, fields contain a list of 
+   :mod:`Validators <wtforms.validators>`.
 
 Getting Started
 ---------------
 
 Let's get right down to business and define our first form::
 
-    from wtforms import Form, BooleanField, TextField, validators
+    from wtforms import Form, BooleanField, StringField, validators
 
     class RegistrationForm(Form):
-        username     = TextField('Username', [validators.Length(min=4, max=25)])
-        email        = TextField('Email Address', [validators.Length(min=6, max=35)])
+        username     = StringField('Username', [validators.Length(min=4, max=25)])
+        email        = StringField('Email Address', [validators.Length(min=6, max=35)])
         accept_rules = BooleanField('I accept the site rules', [validators.InputRequired()])
 
 When you create a form, you define the fields in a way that is similar to the
         signature = TextAreaField('Forum Signature')
 
     class AdminProfileForm(ProfileForm):
-        username = TextField('Username', [validators.Length(max=40)])
+        username = StringField('Username', [validators.Length(max=40)])
         level    = IntegerField('User Level', [validators.NumberRange(min=0, max=10)])
 
-Via subclassing, `AdminProfileForm`, gains all the fields already defined in
+Via subclassing, `AdminProfileForm` gains all the fields already defined in
 `ProfileForm`. This allows you to easily share common subsets of fields between
 forms, such as the example above, where we are adding admin-only fields to
 `ProfileForm`.
 find out what's available to you in a form is to play around with a form in the
 console::
 
-    >>> from wtforms import Form, TextField, validators
+    >>> from wtforms import Form, StringField, validators
     >>> class UsernameForm(Form):
-    ...     username = TextField('Username', [validators.Length(min=5)], default=u'test')
+    ...     username = StringField('Username', [validators.Length(min=5)], default=u'test')
     ...
     >>> form = UsernameForm()
     >>> form['username']
-    <wtforms.fields.TextField object at 0x827eccc>
+    <wtforms.fields.StringField object at 0x827eccc>
     >>> form.username.data
     u'test'
     >>> form.validate()
 or attribute-style. These fields have their own properties, as does the enclosing form.
 
 When we validate the form, it returns False, meaning at least one validator was
-not satisfied. form.errors will give you a summary of all the errors.
+not satisfied. :attr:`form.errors <wtforms.form.Form.errors>` will give you a 
+summary of all the errors.
 
 .. code-block:: python
 
 constructor's second argument, `validators`::
 
     class ChangeEmailForm(Form):
-        email = TextField('Email', [validators.Length(min=6, max=120), validators.Email()])
+        email = StringField('Email', [validators.Length(min=6, max=120), validators.Email()])
 
 You can provide any number of validators to a field. Typically, you will want to
 provide a custom error message::
 
     class ChangeEmailForm(Form):
-        email = TextField('Email', [
+        email = StringField('Email', [
             validators.Length(min=6, message=_(u'Little short for an email address?')),
             validators.Email(message=_(u'That\'s not a valid email address.'))
         ])
 
 Rendering a field is as simple as coercing it to a string::
 
-    >>> from wtforms import Form, TextField
+    >>> from wtforms import Form, StringField
     >>> class SimpleForm(Form):
-    ...   content = TextField('content')
+    ...   content = StringField('content')
     ...
     >>> form = SimpleForm(content='foobar')
     >>> str(form.content)
 template. First, our form::
 
     class LoginForm(Form):
-        username = TextField('Username')
+        username = StringField('Username')
         password = PasswordField('Password')
 
     form = LoginForm()

File docs/ext.rst

     :func:`model_form` attempts to glean as much metadata as possible from
     inspecting the model's fields, and will even attempt to guess at what
     validation might be wanted based on the field type. For example, converting
-    an `EmailField` will result in a :class:`~wtforms.fields.TextField` with
-    the :func:`~wtforms.validators.email` validator on it. if the `blank`
+    an `EmailField` will result in a :class:`~wtforms.fields.StringField` with
+    the :class:`~wtforms.validators.Email` validator on it. if the `blank`
     property is set on a model field, the resulting form field will have the
-    :func:`~wtforms.validators.optional` validator set.
+    :class:`~wtforms.validators.Optional` validator set.
 
-    Just like any other Form, forms created by ModelForm can be extended via
+    Just like any other Form, forms created by model_form can be extended via
     inheritance::
 
         UserFormBase = model_form(User)
     .. code-block:: python
 
         class ArticleEdit(Form):
-            title    = TextField()
+            title    = StringField()
             column   = QuerySetSelectField(get_label='title', allow_blank=True)
             category = QuerySetSelectField(queryset=Category.objects.all())
 
         return Category.query.filter_by(enabled=True)
 
     class BlogPostEdit(Form):
-        title    = TextField()
+        title    = StringField()
         blog     = QuerySelectField(get_label='title')
         category = QuerySelectField(query_factory=enabled_categories, allow_blank=True)
 
 Now that we have this taken care of, let's write a simple form and view which would implement this::
 
     class RegistrationForm(IPSecureForm):
-        name = TextField('Your Name')
-        email = TextField('Email', [validators.email()])
+        name = StringField('Your Name')
+        email = StringField('Email', [validators.email()])
 
     def register(request):
         form = RegistrationForm(request.POST, csrf_context=request.ip)
 Now incorporate it into any form/view by further subclassing::
 
     class Registration(MyBaseForm):
-        name = TextField()
+        name = StringField()
 
     def view(request):
         form = Registration(request.POST, csrf_context=request.session)

File docs/fields.rst

 Fields are defined as members on a form in a declarative fashion::
 
     class MyForm(Form):
-        name    = TextField(u'Full Name', [validators.required(), validators.length(max=10)])
+        name    = StringField(u'Full Name', [validators.required(), validators.length(max=10)])
         address = TextAreaField(u'Mailing Address', [validators.optional(), validators.length(max=200)])
 
 When a field is defined on a form, the construction parameters are saved until
         class TelephoneForm(Form):
             country_code = IntegerField('Country Code', [validators.required()])
             area_code    = IntegerField('Area Code/Exchange', [validators.required()])
-            number       = TextField('Number')
+            number       = StringField('Number')
 
         class ContactForm(Form):
-            first_name   = TextField()
-            last_name    = TextField()
+            first_name   = StringField()
+            last_name    = StringField()
             mobile_phone = FormField(TelephoneForm)
             office_phone = FormField(TelephoneForm)
 
 
         class IMForm(Form):
             protocol = SelectField(choices=[('aim', 'AIM'), ('msn', 'MSN')])
-            username = TextField()
+            username = StringField()
 
         class ContactForm(Form):
-            first_name  = TextField()
-            last_name   = TextField()
+            first_name  = StringField()
+            last_name   = StringField()
             im_accounts = FieldList(FormField(IMForm))
 
 

File docs/forms.rst

 declaratively as class attributes::
 
     class MyForm(Form):
-        first_name = TextField(u'First Name', validators=[validators.input_required()])
-        last_name  = TextField(u'Last Name', validators=[validators.optional()])
+        first_name = StringField(u'First Name', validators=[validators.input_required()])
+        last_name  = StringField(u'Last Name', validators=[validators.optional()])
 
 Field names can be any valid python identifier, with the following restrictions:
 
         code     = TextAreaField()
 
     class PastebinEntry(PastebinEdit):
-        name = TextField(u'User Name')
+        name = StringField(u'User Name')
 
 
 .. _inline-validators:
         .. code-block:: python
 
             form = BaseForm({
-                'name': TextField(),
+                'name': StringField(),
                 'customer.age': IntegerField("Customer's Age")
             })
 
 
         .. code-block:: python
 
-            form['openid.name'] = TextField()
+            form['openid.name'] = StringField()
 
         Fields can be added and replaced in this way, but this must be done
         **before** :meth:`process` is called, or the fields will not have the

File docs/i18n.rst

 Here's a simple example of how one would provide translated strings to WTForms::
 
     from somelibrary import ugettext_lazy as _
-    from wtforms import Form, TextField, IntegerField, validators as v
+    from wtforms import Form, StringField, IntegerField, validators as v
 
     class RegistrationForm(Form):
-        name = TextField(_(u'Name'), [v.InputRequired(_(u'Please provide your name'))])
+        name = StringField(_(u'Name'), [v.InputRequired(_(u'Please provide your name'))])
         age = IntegerField(
             _(u'Age'),
             [v.NumberRange(min=12, message=_(u'Must be at least %(min)d years old.'))]

File docs/specific_problems.rst

 .. code-block:: python
 
     class MagazineIssueForm(Form):
-        title  = TextField()
+        title  = StringField()
         year   = IntegerField('Year')
         month  = SelectField(choices=MONTHS)
 
         class F(MyBaseForm):
             pass
 
-        F.username = TextField('username')
+        F.username = StringField('username')
         for name in iterate_some_model_dynamically():
-            setattr(F, name, TextField(name.title())) 
+            setattr(F, name, StringField(name.title())) 
 
         form = F(request.POST, ...)
         # do view stuff

File docs/validators.rst

 Let's start with a simple form with a name field and its validation::
 
     class MyForm(Form):
-        name = TextField('Name', [InputRequired()])
+        name = StringField('Name', [InputRequired()])
 
         def validate_name(form, field):
             if len(field.data) > 50:
             raise ValidationError('Field must be less than 50 characters')
 
     class MyForm(Form):
-        name = TextField('Name', [InputRequired(), my_length_check])
+        name = StringField('Name', [InputRequired(), my_length_check])
 
 All we've done here is move the exact same code out of the class and as a
 function. Since a validator can be any callable which accepts the two
         return _length
 
     class MyForm(Form):
-        name = TextField('Name', [InputRequired(), length(max=50)])
+        name = StringField('Name', [InputRequired(), length(max=50)])
 
 Now we have a configurable length-checking validator that handles both minimum
 and maximum lengths. When ``length(max=50)`` is passed in your validators list,

File wtforms/ext/csrf/session.py

             expires = ''
             csrf_build = session['csrf']
 
-        hmac_csrf = hmac.new(self.SECRET_KEY, csrf_build.encode('utf8'), digestmod=sha1) 
+        hmac_csrf = hmac.new(self.SECRET_KEY, csrf_build.encode('utf8'), digestmod=sha1)
         return '%s##%s' % (expires, hmac_csrf.hexdigest())
 
     def validate_csrf_token(self, field):