`pyramid_formencode_classic` is a port of some classic `Pylons` form validation concepts onto the `Pyramid` framework.
The package automates validation of `.formencode.Schema` objects under Pyramid, and offers its own `FormStash` object to manage the validation results.
## Lighweight Validation
Formencode validators offer lightweight validation. They essentially check to see if submitted data matches certain formats, regexes and options. They can be chained together for complex tasks, however they do not do advanced validation: they can be used to determine if a login/password meet required input characteristics, but do not check to see if this information is in the database or not.
To handle complex situations, this package offers a FormStash object that can be used to persist data around business logic
## The FormStash object
A `FormStash` object is created when validating a form and used to manage the results.
There are several key attributes:
* `FormStash.results` - a dict of successfully validated field values
* `FormStash.errors` - a dict of fields that failed validation, along with the errors
* `FormStash.defaults` - a dict of containing the pre-validated form data, which is used as the defaults when rendering the form.
There are several helpful utility functions that can be used to check the validation state:
* `FormStash.set_error`
* `FormStash.get_error`
* `FormStash.has_errors`
And there are several functions that can be used to Fail validation after processing:
* `FormStash.fatal_form`
* `FormStash.fatal_field`
## Advanced (Common) Usage
Here is an example of validating a form with advanced logic:
try:
(result, formStash) = form_validate(
request, schema=Form_Login, raise_FormInvalid=True
)
dbUser = ctx.load_user(
username=formStash.results["username"],
raw_password_=formStash.results["password"],
)
if not dbUser:
# fatal_form and fatal_field will both raise a FormInvlalid
# formStash.fatal_form("Invalid Credentials")
# or ...
formStash.fatal_field(field="password, error_field=""Password invalid.")
except FormInvalid as exc:
# formStash is an attribute of FormInvalid
formStash = exc.formStash
## Installation
This requires the 2.0 branch of formencode.
### Current Version(s)
Version 0.8.0 is current and recommended. It has major breaking changes against earlier versions. The API has slightly changed but should be easy to adapt.
Version 0.7.0 offers minimal breaking changes against earlier versions while fixing some issues.
## Under the Hood
A `FormStash` object saves the parsed form data into a `ParsedForm` dict.
FormStash.parsed_form: ParsedForm = {}
The `ParsedForm` dict has 3 entries, which are all dicts:
results
errors
defaults
`results`, `errors` and `defaults` have accessor properties on the FormStash object.
"special_errors", such as "nothing_submitted", are stored in the main "errors" dict
with an asterisk prefix (e.g. "*nothing_submitted")
The errors have multiple accessors:
`FormStash.errors` - returns `FormStash.errors_normal`
`FormStash.errors_normal` - only returns `ParsedForm["errors"]` without a "*" prefix
`FormStash.errors_special` - only returns `ParsedForm["errors"]` with a "*" prefix
`FormStash.errors_all` - returns all `ParsedForm["errors"]`
### Error Concepts
For the purpose of this package, errors can be grouped into two concepts:
meta-errors
Errors about the Form itself, such as:
"There is an error with the form"
"nothing was submitted."
field-errors
Errors for specific fields
#### meta-errors: Error_Main or error_main_key
To integrate meta-errors into the form, the FormStash will create an "Error_Main"
entry in the `PrasedForm["errors"]` dict, which is available as `FormStash.errors`.
`Error_Main` is a key in the `FormStash.error` (`ParsedForm["errors"]`) Dict which corresponds
to the main message of a form failure.
The `set_error` routine will integrate meta errors, such as `nothing_submitted` into
the `Error_Main` text, when setting the main form error.
#### field errors
The `errors` dict will contain the field errors as validated.
### Versioning Policy
This project using a Semantic Versioning Policy: `Major.Minor.Patch`.
`Major`: significant API changes
`Minor`: backwards incompatible API changes
`Patch`: backwards compatible API changes and bugfixes
The recommended usage is to pin versioning within the `Major.Minor` range:
pyramid_formencode_classic >=0.9.0, <0.10.0
## This looks more complicated than it should be.
Yes, it is.
This library tries to generate and manage useful errors.
Assume we have a login for that is just email/password::
class Form_Login(formencode.Schema):
username = formencode.validators.UnicodeString(not_empty=True)
password = formencode.validators.UnicodeString(not_empty=True)
And this is our basic validation pattern::
(result, formStash) = pyramid_formencode_classic.form_validate(
request,
schema=Form_Login,
)
What should happen if we don't fill anything out?
We don't just want to simply indicate an error, we also need to note there was
nothing submitted to the form.
This package offers defaults, but can customize messages like such:
(result, formStash) = pyramid_formencode_classic.form_validate(
request,
schema=Form_Login,
error_main_text = "There was an error with your form",
error_no_submission_text = "Nothing submitted.",
)
The package will then merge the `error_main_text` and `error_no_submission_text`
into `FormStash.errors["error_main"] = "There was an error with your form. Nothing submitted."`
Now imagine you need to set a form error yourself:
(result, formStash) = pyramid_formencode_classic.form_validate(
request,
schema=Form_Login,
error_main_text = "There was an error with your form",
error_no_submission_text = "Nothing submitted.",
)
user = get_user_by_login(formStash.results["username"], formStash.results["password"])
if not user:
formStash.fatal_form("Invalid credentials")
# or
# raise FormInvalid(formStash, "Invalid credentials")
How should that render?
We don't want to just see:
Invalid Credentials.
We want to see as the "form error":
There was an error with your form. Invalid credentials.
So this package tries to do the right thing, and merges `error_main_text` with `Invalid credentials`.
If you only want to show a specific message though, you can invoke:
if not user:
formStash.fatal_form("Invalid credentials", error_main_overwrite=True)
# or
# raise FormInvalid(formStash, "Invalid credentials", error_main_overwrite=True)
Which will render:
Invalid Credentials.
Most of the work put into this package over the past decade has been to keep a
simple interface to achieve this type of error rendering, while also giving the
flexibility to be more interactive.
## Debugtoolbar Support?
Yes. just add to your development.ini
debugtoolbar.includes = pyramid_formencode_classic_.debugtoolbar
The debugtoolbar will now have a `FormencodeClassic` panel.
The panel shows information such as:
* which forms were processed/setup
* form results (errors, defaults, actual results)
* form schema
* form parsing status
* form configuration
## How does this handle form validation?
The simplest way to utilize this library is with this code:
result: bool
formStash: pyramid_formencode_classic.FormStash
request: pyramid.request.Request
Form_Email: formencode.Schema
(result, formStash) = pyramid_formencode_classic.form_validate(request, schema=Form_Email)
`form_validate` can either raise an Exception (`pyramid_formencode_classic.exceptions.FormInvalid`) or return `False``, based on the kwargs.
if `form_validate` raises an Exception, the `FormStash` is available as an attribute.
Formencode's htmlfill can be used to re-render the form with errors.
## Pyramid Integration
Just do this::
config.include('pyramid_formencode_classic')
Which will invoke `Pyramid`'s `add_request_method` to add a new attribute to your request.
`request.pyramid_formencode_classic` will be a per-request instance of `pyramid_formencode_classic.FormStashList`.
Parsing a form will manage the formdata in `request.pyramid_formencode_classic['_default']` the default form stash.
If you want to specify a particular stash, because you use multiple forms on a page or have other needs:
* `request.pyramid_formencode_classic.get_form(...)` accepts a `form_stash` kwarg, which defaults to `_default`
* `form_validate(...)` accepts a `form_stash` kwarg, which defaults to `_default`
* `form_reprint(...)` accepts a `form_stash` kwarg, which defaults to `_default`
## Caveats, Oddities, Etc
### Custom Errors, Custom Error Displays and Missing Fields
#### Where are errors placed? What about missing fields?
`formencode.htmlfill` prefers to upgrade a html form element with the error information.
If the html input for an error is missing, such as a custom `Error_Main` field, `formencode` will attempt to do two things:
1. `formencode` will look for a custom `form:error` field, such as `<form:error name="Error_Main"/>`.
2. If no fields are available, `formencode` will *PREPEND* the error messages to the document. This can create problems if you are running the reprint on a full (not partial) html page.
#### How are errors styled?
`formencode` styles errors using two arguments.
* `auto_error_formatter` is a function that formats the error messages for fields which do not appear on the document and are pre-pended.
* `error_formatters` is a dict of error formatters that can be passed into `htmlfill`. if provided, these will be merged into the htmlfill defaults.
`htmlfill` allows a bit of customization by supporting a `format` attribute in `<form:error/>` declarations, which will invoke the respective entry in the `error_formatters` dict.
#### How can a "global" form error be handled?
Handling a custom error can be achieved by reserving a special `error_main` key. By default, `pyramid_formencode_classic` uses `Error_Main`.
Once you set that field as a form error, `formencode.htmlfill` will replace this markup in your template
<form:error name="Error_Main"/>
with the following html:
<!-- for: Error_Main -->
<span class="error-message">%(Error_Main)s</span><br/>
In which the `Error_main` text has been run through `error_formatters['default']`
There is a small caveat:
In order for the text to appear in the form where you wish, you must write `<form:error name="Error_Main"/>` in the form. Non-error views will contain that text in the html source, but not render it; error views will replace it with properly formatted errors.
This package offers a convenience method to conditionally render that text:
<html><head></head><body><div>
<form action="/" method="POST">
<% form = request.pyramid_formencode_classic.get_form() %>
${form.html_error_placeholder()|n}
<input type="text" name="email" value="" />
<input type="text" name="username" value="" />
</form>
</div></body></html>
If the marking is not in your template, it will be at the top of the document (before the html), after being run through the `auto_error_formatter`
<!-- for: Error_Main -->
<span class="error-message">${error_main}</span>
### Why doesn't form_validate` raise an Exception by default?
This design choice was made to allow for flexible scoping by default::
try:
(result, formStash) = form_validate(request, schema=Form_Email)
if not result:
raise FormInvalid(formStash)
except FormInvalid as exc:
# formStash is scoped here
The alternative is::
try:
(result, formStash) = form_validate(
request, schema=Form_Email, raise_FormInvalid=True
)
except FormInvalid as exc:
# formStash is an attribute of FormInvalid
formStash = exc.formStash
Most implementations will want to define their own `form_validate()` function
that invokes `pyramid_formencode_classic.form_validate` with custom defaults, so
the default behavior is somewhat irrelevant.
# Examples
## Usage Overview
### define your form
import formencode
class _Schema_Base(formencode.Schema):
allow_extra_fields = True
filter_extra_fields = False
class FormLogin(_Schema_Base):
email_address = formencode.validators.Email(not_empty=True)
password = formencode.validators.UnicodeString(not_empty=True)
remember_me = formencode.validators.Bool()
### define your view/handler
import pyramid_formencode_classic as formhandling
class WebLogin(base):
def login(self):
if 'login' in self.request.POST:
return self._login_submit()
return self._login_print()
def _login_print(self):
return render_to_response("web/account/login.mako", {}, self.request)
def _login_submit(self):
try:
(result, formStash) = formhandling.form_validate(
self.request,
schema=forms.FormLogin,
)
if not result:
formStash.fatal_form("Invalid Form")
results = formStash.results
useraccount = model.find_user(results['email_address'])
if not useraccount:
# set a custom error and raise an exception to reprint
# `formStash.fatal_field(` will raise `formhandling.FormInvalid(`
formStash.fatal_field(field="email_address",
message="Email not registered",
)
if not useraccount.verify_submitted_password(results['password']):
# set a custom error and raise an exception to reprint
# `formStash.fatal_field(` will raise `formhandling.FormInvalid(`
formStash.fatal_field(
field="email_address",
message="Wrong password",
)
do_login()
return HTTPFound(location='/account/home')
except formhandling.FormInvalid as exc:
# our reprint logic
return formhandling.form_reprint(
self.request,
self._login_print
)
Bootstrap Example
=========================
To handle bootstrap style errors, it's a bit more manual work -- but doable
Mako:
<% form= request.pyramid_formencode_classic.get_form() %>
${form.html_error_placeholder()|n}
<div class="control-group ${form.css_error('email_address')}">
<label class="control-label" for="email_address">Email</label>
<input id="email_address" name="email_address" placeholder="Email Address" size="30" type="text" />
${form.html_error('email_address')|n}
</div>
you could also show an error with:
% if form.has_error('email_address'):
<span class="help-inline">${form.get_error('email_address')}</span>
% endif
Pyramid:
text = formhandling.form_reprint(self.request,
self._login_print,
auto_error_formatter=formhandling.formatter_none,
)
in the above example there are a few things to note:
1. in the mako template we use `get_form` to pull/create the default formStash object for the request. You can specify a specific formStash object if you'd like.
2. a call is made to `form.css_error()` specifying the 'email_address' field. this would result in the "control-group error" css mix if there is an error in 'email_address'.
3. We tell pyramid to use 'formhandling.formatter_none' as the error formatter. This surpresses errors. We need to do that instead of using custom error formatters, because FormEncode places errors BEFORE the fields, not AFTER.
4. I've included two methods of presenting field errors. they are funtinoally the same.
5. I've used an ErrorMain to show that there are issues on the form - not just a specific field.
#### How does it work?
The `form_stash` argument represents the unique `FormStash` object on the `request` (when it is not explicitly provided, it defaults to `_default`)
The `data_formencode_form` argument is passed from `form_reprint` to `formencode.htmlfill`; when provided, `formencode` will ignore tags which don't match the active formencode form's elements.
The HTML form elements are associated with a form via the attribute `data-formencode-form`
Raw data
{
"_id": null,
"home_page": "https://github.com/jvanasco/pyramid_formencode_classic",
"name": "pyramid-formencode-classic",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": "Jonathan Vanasco",
"author_email": "jonathan@findmeon.com",
"download_url": "https://files.pythonhosted.org/packages/40/0d/857aea6ad7e1645e3212aa576127bfe485df43cfb001d4a90a166f14a7cd/pyramid_formencode_classic-0.11.3.tar.gz",
"platform": null,
"description": "\n\n`pyramid_formencode_classic` is a port of some classic `Pylons` form validation concepts onto the `Pyramid` framework.\n\nThe package automates validation of `.formencode.Schema` objects under Pyramid, and offers its own `FormStash` object to manage the validation results.\n\n## Lighweight Validation\n\nFormencode validators offer lightweight validation. They essentially check to see if submitted data matches certain formats, regexes and options. They can be chained together for complex tasks, however they do not do advanced validation: they can be used to determine if a login/password meet required input characteristics, but do not check to see if this information is in the database or not.\n\nTo handle complex situations, this package offers a FormStash object that can be used to persist data around business logic\n\n## The FormStash object\n\nA `FormStash` object is created when validating a form and used to manage the results.\n\nThere are several key attributes:\n\n* `FormStash.results` - a dict of successfully validated field values\n* `FormStash.errors` - a dict of fields that failed validation, along with the errors\n* `FormStash.defaults` - a dict of containing the pre-validated form data, which is used as the defaults when rendering the form.\n\nThere are several helpful utility functions that can be used to check the validation state:\n\n* `FormStash.set_error`\n* `FormStash.get_error`\n* `FormStash.has_errors`\n\nAnd there are several functions that can be used to Fail validation after processing:\n\n* `FormStash.fatal_form`\n* `FormStash.fatal_field`\n\n\n## Advanced (Common) Usage\n\nHere is an example of validating a form with advanced logic:\n\n\ttry:\n\t\t(result, formStash) = form_validate(\n\t\t request, schema=Form_Login, raise_FormInvalid=True\n\t\t)\n\t\tdbUser = ctx.load_user(\n\t\t username=formStash.results[\"username\"],\n\t\t raw_password_=formStash.results[\"password\"],\n\t\t)\n\t\tif not dbUser:\n\t\t # fatal_form and fatal_field will both raise a FormInvlalid\n\t\t # formStash.fatal_form(\"Invalid Credentials\")\n\t\t # or ...\n\t\t formStash.fatal_field(field=\"password, error_field=\"\"Password invalid.\")\n\texcept FormInvalid as exc:\n\t # formStash is an attribute of FormInvalid\n\t\tformStash = exc.formStash\n\n\n## Installation\n\nThis requires the 2.0 branch of formencode.\n\n\n### Current Version(s)\n\nVersion 0.8.0 is current and recommended. It has major breaking changes against earlier versions. The API has slightly changed but should be easy to adapt.\n\nVersion 0.7.0 offers minimal breaking changes against earlier versions while fixing some issues.\n\n\n## Under the Hood\n\nA `FormStash` object saves the parsed form data into a `ParsedForm` dict.\n\n FormStash.parsed_form: ParsedForm = {}\n\nThe `ParsedForm` dict has 3 entries, which are all dicts:\n\n results\n errors\n defaults\n\n`results`, `errors` and `defaults` have accessor properties on the FormStash object.\n\n\"special_errors\", such as \"nothing_submitted\", are stored in the main \"errors\" dict\nwith an asterisk prefix (e.g. \"*nothing_submitted\")\n\nThe errors have multiple accessors:\n\n `FormStash.errors` - returns `FormStash.errors_normal`\n `FormStash.errors_normal` - only returns `ParsedForm[\"errors\"]` without a \"*\" prefix\n `FormStash.errors_special` - only returns `ParsedForm[\"errors\"]` with a \"*\" prefix\n `FormStash.errors_all` - returns all `ParsedForm[\"errors\"]`\n\n### Error Concepts\n\nFor the purpose of this package, errors can be grouped into two concepts:\n\nmeta-errors\n Errors about the Form itself, such as:\n \"There is an error with the form\"\n \"nothing was submitted.\"\nfield-errors\n Errors for specific fields\n\n#### meta-errors: Error_Main or error_main_key\n\nTo integrate meta-errors into the form, the FormStash will create an \"Error_Main\"\nentry in the `PrasedForm[\"errors\"]` dict, which is available as `FormStash.errors`.\n\n`Error_Main` is a key in the `FormStash.error` (`ParsedForm[\"errors\"]`) Dict which corresponds\nto the main message of a form failure.\n\nThe `set_error` routine will integrate meta errors, such as `nothing_submitted` into\nthe `Error_Main` text, when setting the main form error.\n\n#### field errors\n\nThe `errors` dict will contain the field errors as validated.\n\n\n### Versioning Policy\n\nThis project using a Semantic Versioning Policy: `Major.Minor.Patch`.\n\n`Major`: significant API changes\n`Minor`: backwards incompatible API changes\n`Patch`: backwards compatible API changes and bugfixes\n\nThe recommended usage is to pin versioning within the `Major.Minor` range:\n\n\tpyramid_formencode_classic >=0.9.0, <0.10.0\n\n\n## This looks more complicated than it should be.\n\nYes, it is.\n\nThis library tries to generate and manage useful errors.\n\nAssume we have a login for that is just email/password::\n\n class Form_Login(formencode.Schema):\n username = formencode.validators.UnicodeString(not_empty=True)\n password = formencode.validators.UnicodeString(not_empty=True)\n\nAnd this is our basic validation pattern::\n\n (result, formStash) = pyramid_formencode_classic.form_validate(\n request,\n schema=Form_Login,\n )\n\nWhat should happen if we don't fill anything out?\n\nWe don't just want to simply indicate an error, we also need to note there was\nnothing submitted to the form.\n\nThis package offers defaults, but can customize messages like such:\n\n (result, formStash) = pyramid_formencode_classic.form_validate(\n request,\n schema=Form_Login,\n error_main_text = \"There was an error with your form\",\n error_no_submission_text = \"Nothing submitted.\",\n )\n\nThe package will then merge the `error_main_text` and `error_no_submission_text`\ninto `FormStash.errors[\"error_main\"] = \"There was an error with your form. Nothing submitted.\"`\n\nNow imagine you need to set a form error yourself:\n\n (result, formStash) = pyramid_formencode_classic.form_validate(\n request,\n schema=Form_Login,\n error_main_text = \"There was an error with your form\",\n error_no_submission_text = \"Nothing submitted.\",\n )\n user = get_user_by_login(formStash.results[\"username\"], formStash.results[\"password\"])\n if not user:\n formStash.fatal_form(\"Invalid credentials\")\n # or\n # raise FormInvalid(formStash, \"Invalid credentials\")\n\nHow should that render?\n\nWe don't want to just see:\n\n Invalid Credentials.\n\nWe want to see as the \"form error\":\n\n There was an error with your form. Invalid credentials.\n\nSo this package tries to do the right thing, and merges `error_main_text` with `Invalid credentials`.\n\nIf you only want to show a specific message though, you can invoke:\n \n if not user:\n formStash.fatal_form(\"Invalid credentials\", error_main_overwrite=True)\n # or\n # raise FormInvalid(formStash, \"Invalid credentials\", error_main_overwrite=True)\n\nWhich will render:\n\n Invalid Credentials.\n\nMost of the work put into this package over the past decade has been to keep a\nsimple interface to achieve this type of error rendering, while also giving the\nflexibility to be more interactive.\n\n\n## Debugtoolbar Support?\n\nYes. just add to your development.ini\n\n\tdebugtoolbar.includes = pyramid_formencode_classic_.debugtoolbar\n\nThe debugtoolbar will now have a `FormencodeClassic` panel.\n\nThe panel shows information such as:\n\n* which forms were processed/setup\n* form results (errors, defaults, actual results)\n* form schema\n* form parsing status\n* form configuration\n\n\n## How does this handle form validation?\n\nThe simplest way to utilize this library is with this code:\n\n result: bool\n formStash: pyramid_formencode_classic.FormStash\n request: pyramid.request.Request\n Form_Email: formencode.Schema\n\n\t(result, formStash) = pyramid_formencode_classic.form_validate(request, schema=Form_Email)\n\n`form_validate` can either raise an Exception (`pyramid_formencode_classic.exceptions.FormInvalid`) or return `False``, based on the kwargs.\n\nif `form_validate` raises an Exception, the `FormStash` is available as an attribute.\n\nFormencode's htmlfill can be used to re-render the form with errors.\n\n## Pyramid Integration\n\nJust do this::\n\n\tconfig.include('pyramid_formencode_classic')\n\nWhich will invoke `Pyramid`'s `add_request_method` to add a new attribute to your request.\n\n`request.pyramid_formencode_classic` will be a per-request instance of `pyramid_formencode_classic.FormStashList`.\n\nParsing a form will manage the formdata in `request.pyramid_formencode_classic['_default']` the default form stash.\n\nIf you want to specify a particular stash, because you use multiple forms on a page or have other needs:\n\n* `request.pyramid_formencode_classic.get_form(...)` accepts a `form_stash` kwarg, which defaults to `_default`\n* `form_validate(...)` accepts a `form_stash` kwarg, which defaults to `_default`\n* `form_reprint(...)` accepts a `form_stash` kwarg, which defaults to `_default`\n\n\n## Caveats, Oddities, Etc\n\n### Custom Errors, Custom Error Displays and Missing Fields\n\n#### Where are errors placed? What about missing fields?\n\n`formencode.htmlfill` prefers to upgrade a html form element with the error information.\n\nIf the html input for an error is missing, such as a custom `Error_Main` field, `formencode` will attempt to do two things:\n\n1. `formencode` will look for a custom `form:error` field, such as `<form:error name=\"Error_Main\"/>`.\n2. If no fields are available, `formencode` will *PREPEND* the error messages to the document. This can create problems if you are running the reprint on a full (not partial) html page.\n\n#### How are errors styled?\n\n`formencode` styles errors using two arguments.\n\n* `auto_error_formatter` is a function that formats the error messages for fields which do not appear on the document and are pre-pended.\n* `error_formatters` is a dict of error formatters that can be passed into `htmlfill`. if provided, these will be merged into the htmlfill defaults.\n\n`htmlfill` allows a bit of customization by supporting a `format` attribute in `<form:error/>` declarations, which will invoke the respective entry in the `error_formatters` dict.\n\n#### How can a \"global\" form error be handled?\n\nHandling a custom error can be achieved by reserving a special `error_main` key. By default, `pyramid_formencode_classic` uses `Error_Main`.\n\nOnce you set that field as a form error, `formencode.htmlfill` will replace this markup in your template\n\n <form:error name=\"Error_Main\"/>\n\nwith the following html:\n\n <!-- for: Error_Main -->\n\t<span class=\"error-message\">%(Error_Main)s</span><br/>\n\nIn which the `Error_main` text has been run through `error_formatters['default']`\n\nThere is a small caveat:\n\nIn order for the text to appear in the form where you wish, you must write `<form:error name=\"Error_Main\"/>` in the form. Non-error views will contain that text in the html source, but not render it; error views will replace it with properly formatted errors.\n\nThis package offers a convenience method to conditionally render that text:\n\n\t<html><head></head><body><div>\n\t<form action=\"/\" method=\"POST\">\n\t\t<% form = request.pyramid_formencode_classic.get_form() %>\n\t\t${form.html_error_placeholder()|n}\n\t\t<input type=\"text\" name=\"email\" value=\"\" />\n\t\t<input type=\"text\" name=\"username\" value=\"\" />\n\t</form>\n\t</div></body></html>\n\n\nIf the marking is not in your template, it will be at the top of the document (before the html), after being run through the `auto_error_formatter`\n\n <!-- for: Error_Main -->\n <span class=\"error-message\">${error_main}</span>\n\n\n### Why doesn't form_validate` raise an Exception by default?\n\nThis design choice was made to allow for flexible scoping by default::\n\n\ttry:\n\t\t(result, formStash) = form_validate(request, schema=Form_Email)\n\t\tif not result:\n\t\t\traise FormInvalid(formStash)\n\texcept FormInvalid as exc:\n\t\t# formStash is scoped here\n\nThe alternative is::\n\n\ttry:\n\t\t(result, formStash) = form_validate(\n\t\t request, schema=Form_Email, raise_FormInvalid=True\n\t\t)\n\texcept FormInvalid as exc:\n\t # formStash is an attribute of FormInvalid\n\t\tformStash = exc.formStash\n\nMost implementations will want to define their own `form_validate()` function\nthat invokes `pyramid_formencode_classic.form_validate` with custom defaults, so\nthe default behavior is somewhat irrelevant.\n\n\n# Examples\n\n## Usage Overview\n\n### define your form\n\n import formencode\n\n class _Schema_Base(formencode.Schema):\n allow_extra_fields = True\n filter_extra_fields = False\n\n class FormLogin(_Schema_Base):\n email_address = formencode.validators.Email(not_empty=True)\n password = formencode.validators.UnicodeString(not_empty=True)\n remember_me = formencode.validators.Bool()\n\n\n### define your view/handler\n\n import pyramid_formencode_classic as formhandling\n\n class WebLogin(base):\n\n def login(self):\n if 'login' in self.request.POST:\n return self._login_submit()\n return self._login_print()\n\n def _login_print(self):\n return render_to_response(\"web/account/login.mako\", {}, self.request)\n\n def _login_submit(self):\n\n try:\n (result, formStash) = formhandling.form_validate(\n self.request,\n schema=forms.FormLogin,\n )\n if not result:\n formStash.fatal_form(\"Invalid Form\")\n\n results = formStash.results\n\n useraccount = model.find_user(results['email_address'])\n if not useraccount:\n \t# set a custom error and raise an exception to reprint\n # `formStash.fatal_field(` will raise `formhandling.FormInvalid(`\n formStash.fatal_field(field=\"email_address\",\n\t\t\t\t\t\t\t\t\t\t message=\"Email not registered\",\n\t\t\t\t\t\t\t\t\t\t )\n\n if not useraccount.verify_submitted_password(results['password']):\n \t# set a custom error and raise an exception to reprint\n # `formStash.fatal_field(` will raise `formhandling.FormInvalid(`\n formStash.fatal_field(\n field=\"email_address\",\n message=\"Wrong password\",\n )\n\n\t\t\t\tdo_login()\n\t\t\t\treturn HTTPFound(location='/account/home')\n\n except formhandling.FormInvalid as exc:\n # our reprint logic\n return formhandling.form_reprint(\n self.request,\n self._login_print\n )\n\n\nBootstrap Example\n=========================\n\n To handle bootstrap style errors, it's a bit more manual work -- but doable\n\n Mako:\n <% form= request.pyramid_formencode_classic.get_form() %>\n ${form.html_error_placeholder()|n}\n <div class=\"control-group ${form.css_error('email_address')}\">\n <label class=\"control-label\" for=\"email_address\">Email</label>\n <input id=\"email_address\" name=\"email_address\" placeholder=\"Email Address\" size=\"30\" type=\"text\" />\n ${form.html_error('email_address')|n}\n </div>\n\n you could also show an error with:\n % if form.has_error('email_address'):\n <span class=\"help-inline\">${form.get_error('email_address')}</span>\n % endif\n\n\n Pyramid:\n text = formhandling.form_reprint(self.request,\n \t\t\t\t\t\t\t\t self._login_print,\n \t\t\t\t\t\t\t\t auto_error_formatter=formhandling.formatter_none,\n \t\t\t\t\t\t\t\t )\n\n in the above example there are a few things to note:\n\n 1. in the mako template we use `get_form` to pull/create the default formStash object for the request. You can specify a specific formStash object if you'd like.\n 2. a call is made to `form.css_error()` specifying the 'email_address' field. this would result in the \"control-group error\" css mix if there is an error in 'email_address'.\n 3. We tell pyramid to use 'formhandling.formatter_none' as the error formatter. This surpresses errors. We need to do that instead of using custom error formatters, because FormEncode places errors BEFORE the fields, not AFTER.\n 4. I've included two methods of presenting field errors. they are funtinoally the same.\n 5. I've used an ErrorMain to show that there are issues on the form - not just a specific field.\n\n\n#### How does it work?\n\nThe `form_stash` argument represents the unique `FormStash` object on the `request` (when it is not explicitly provided, it defaults to `_default`)\n\nThe `data_formencode_form` argument is passed from `form_reprint` to `formencode.htmlfill`; when provided, `formencode` will ignore tags which don't match the active formencode form's elements.\n\nThe HTML form elements are associated with a form via the attribute `data-formencode-form`\n\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "('An implementation of the classic Pylons formencode validation, for Pyramid',)",
"version": "0.11.3",
"project_urls": {
"Homepage": "https://github.com/jvanasco/pyramid_formencode_classic"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "400d857aea6ad7e1645e3212aa576127bfe485df43cfb001d4a90a166f14a7cd",
"md5": "342ef2e79e7c7f88eab8466ad13e07b6",
"sha256": "5a94aa5e70789cc9989acbd020c32bebf53be4dac29bc419dd01b5371c27da9d"
},
"downloads": -1,
"filename": "pyramid_formencode_classic-0.11.3.tar.gz",
"has_sig": false,
"md5_digest": "342ef2e79e7c7f88eab8466ad13e07b6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 46374,
"upload_time": "2025-10-21T16:36:26",
"upload_time_iso_8601": "2025-10-21T16:36:26.258983Z",
"url": "https://files.pythonhosted.org/packages/40/0d/857aea6ad7e1645e3212aa576127bfe485df43cfb001d4a90a166f14a7cd/pyramid_formencode_classic-0.11.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 16:36:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jvanasco",
"github_project": "pyramid_formencode_classic",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pyramid-formencode-classic"
}
JSON
