diff --git a/HISTORY.rst b/HISTORY.rst index daca7cd..80b8459 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -2,7 +2,7 @@ History ======= -0.1.0 (2020-08-15) +0.1.0 (2020-09-28) ------------------ -* First release on PyPI. +* First (alpha) release on PyPI. diff --git a/Makefile b/Makefile index 0fb87e4..ea46214 100644 --- a/Makefile +++ b/Makefile @@ -68,9 +68,9 @@ coverage: ## check code coverage quickly with the default Python docs: ## generate Sphinx HTML documentation, including API docs rm -f docs/questions.rst rm -f docs/modules.rst - sphinx-apidoc -o docs/ questions + sphinx-apidoc -e -o docs/ questions $(MAKE) -C docs clean - $(MAKE) -C docs html + $(MAKE) -b spelling -C docs html $(BROWSER) docs/_build/html/index.html servedocs: docs ## compile the docs watching for changes diff --git a/docs/_static/README.txt b/docs/_static/README.txt new file mode 100644 index 0000000..548d720 --- /dev/null +++ b/docs/_static/README.txt @@ -0,0 +1 @@ +Include static resources here. diff --git a/docs/conf.py b/docs/conf.py index 0c2afb5..fc8ed59 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,7 +31,12 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', + 'sphinx_autodoc_typehints', + 'sphinxcontrib.spelling', +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -89,7 +94,13 @@ # theme further. For a list of options available for each theme, see the # documentation. # -# html_theme_options = {} +html_theme_options = { + "page_width": "1200px", + "github_user": "cguardia", + "github_repo": "questions", + "github_banner": "true", + "github_button": "false", +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -159,4 +170,8 @@ ] +# -- Options for spell checking ---------------------------------------- +# File containing list of words known to be spelled correctly, but not in +# the dictionary. +spelling_word_list_filename = 'spelling_word_list.txt' diff --git a/docs/index.rst b/docs/index.rst index d5315aa..e84286c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,6 +1,13 @@ Welcome to Questions's documentation! ====================================== +Questions is a Python form library that uses the power of SurveyJS_ for the UI. +The philosophy behind Questions is that modern form rendering usually requires +integrating some complex Javascript widgets anyway, so why not skip the markup +generation completely? + +.. _SurveyJS: https://surveyjs.io + .. toctree:: :maxdepth: 2 :caption: Contents: diff --git a/docs/questions.cli.rst b/docs/questions.cli.rst new file mode 100644 index 0000000..cc4e039 --- /dev/null +++ b/docs/questions.cli.rst @@ -0,0 +1,7 @@ +questions.cli module +==================== + +.. automodule:: questions.cli + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/questions.form.rst b/docs/questions.form.rst new file mode 100644 index 0000000..c6b2c2f --- /dev/null +++ b/docs/questions.form.rst @@ -0,0 +1,7 @@ +questions.form module +===================== + +.. automodule:: questions.form + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/questions.questions.rst b/docs/questions.questions.rst new file mode 100644 index 0000000..84ddd19 --- /dev/null +++ b/docs/questions.questions.rst @@ -0,0 +1,7 @@ +questions.questions module +========================== + +.. automodule:: questions.questions + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/questions.rst b/docs/questions.rst index a3f0acb..9f68863 100644 --- a/docs/questions.rst +++ b/docs/questions.rst @@ -4,59 +4,20 @@ questions package Submodules ---------- -questions.cli module --------------------- - -.. automodule:: questions.cli - :members: - :undoc-members: - :show-inheritance: - -questions.form module ---------------------- - -.. automodule:: questions.form - :members: - :undoc-members: - :show-inheritance: - -questions.questions module --------------------------- - -.. automodule:: questions.questions - :members: - :undoc-members: - :show-inheritance: - -questions.settings module -------------------------- - -.. automodule:: questions.settings - :members: - :undoc-members: - :show-inheritance: - -questions.templates module --------------------------- - -.. automodule:: questions.templates - :members: - :undoc-members: - :show-inheritance: - -questions.validators module ---------------------------- - -.. automodule:: questions.validators - :members: - :undoc-members: - :show-inheritance: +.. toctree:: + :maxdepth: 4 + questions.cli + questions.form + questions.questions + questions.settings + questions.templates + questions.validators Module contents --------------- .. automodule:: questions - :members: - :undoc-members: - :show-inheritance: + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/questions.settings.rst b/docs/questions.settings.rst new file mode 100644 index 0000000..75153be --- /dev/null +++ b/docs/questions.settings.rst @@ -0,0 +1,7 @@ +questions.settings module +========================= + +.. automodule:: questions.settings + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/questions.templates.rst b/docs/questions.templates.rst new file mode 100644 index 0000000..37cd79d --- /dev/null +++ b/docs/questions.templates.rst @@ -0,0 +1,7 @@ +questions.templates module +========================== + +.. automodule:: questions.templates + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/questions.validators.rst b/docs/questions.validators.rst new file mode 100644 index 0000000..309d2f0 --- /dev/null +++ b/docs/questions.validators.rst @@ -0,0 +1,7 @@ +questions.validators module +=========================== + +.. automodule:: questions.validators + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/spelling_word_list.txt b/docs/spelling_word_list.txt new file mode 100644 index 0000000..c06ba61 --- /dev/null +++ b/docs/spelling_word_list.txt @@ -0,0 +1,18 @@ +cli +darkblue +darkrose +docstring +docstrings +dropdown +dropdowns +javascript +JQuery +jquery +ko +repo +submodules +validator +validators +virtualenvwrapper +vue +winterstone diff --git a/docs/usage.rst b/docs/usage.rst index 9320adf..03c74f6 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -1,7 +1,330 @@ +=========== +Quick Start +=========== + +Questions forms are basically class definitions, where each question is a form +attribute:: + + from questions import Form + from questions import DropdownQuestion + from questions import TextQuestion + + + class PreferencesForm(Form): + email = TextQuestion(input_type="email") + email_format = DropdownQuestion(choices=["PDF", "HTML", "Plain Text"]) + +There are many kinds of :doc:`questions `, for different kinds of +input types. Most questions have several possible parameters, but most of them +are optional, so the question can be defined with just the parameters that are +needed for each case, as in the example above. + +To use a form, an instance has to be created. The Form constructor also +accepts various parameters, but like the Question parameters, they are only +used when they are needed:: + + prefs = PreferencesForm() + +Displaying the forms +==================== + +Questions generates a SurveyJS form, which requires a few Javascript and CSS +resources to work. The simplest way to display a form is to use the SurveyJS +CDN to serve all these resources, which requires no work and is the default +form display mode. A full HTML page with all required resources and Javascript +code can be generated like this:: + + prefs = PreferencesForm() + html = prefs.render_html() + +This should be just enough for many small applications, but most applications +will need to combine the form code with their own layout and resources. Again, +this can be accomplished using the CDN or not. Here's a simple example of how +to integrate a Questions form into an existing web application using the CDN: + +Python view code +---------------- + +To render a form in a template, the Python view code must pass the form +instance to the template. In a generic Python web framework, this would look +like the following:: + + def preferences_form(): + prefs = PreferencesForm() + return {"form": prefs} + +HTML template +------------- + +In the template, using Jinja_ the form would be used like this: + +.. code-block:: html+jinja + + + + + + {% for script in form.js %} + + {% endfor %} + + + + + + + {% for stylesheet in form.css %} + + {% endfor %} + + + + +
+ + + +What is needed to make the form work is to insert all the required JS and CSS +resources, followed by the form definition and initialization script. The only +thing needed on the HTML side, is the ``div`` where the form will be inserted. +It *must* use the `questions_form` id, unless a different id is passed in +when creating the form, by using the ``html_id`` parameter. + +.. _Jinja: https://jinja.palletsprojects.com/ + +Displaying forms without using the CDN +-------------------------------------- + +When not using the SurveyJS CDN, there are two ways to display the forms. The +first one requires downloading or installing all the resources under the same +directory, and passing the URL for this directory to the form constructor:: + + prefs = PreferencesForm(resource_url="/static_resources") + +This is the easiest way to do it, and requires no changes to the HTML above. + +The other way to do this also requires downloading or installing all the +required resources, but instead of using the `resource_url` parameter, remove +the JS and CSS loops from the HTML template, and in their place put in the +list of locally installed resources. + +Panels +====== + +A panel is a container of form controls that are presented as a group. It's +like a question with multiple parts. To create a panel, a separate form has to +be defined, and it is then passed in to the panel constructor:: + + from questions import Form + from questions import FormPanel + from questions import BooleanQuestion + from questions import DropdownQuestion + from questions import TextQuestion + + + class PreferencesForm(Form): + email = TextQuestion(input_type="email") + email_format = DropdownQuestion(choices=["PDF", "HTML", "Plain Text"]) + + + class ProfileForm(Form): + receive_newsletter = BooleanQuestion( + title="Do you wish to receive our newsletter?", + is_required=True, + ) + newsletter_panel = FormPanel( + PreferencesForm, + title="Newsletter Preferences", + visible_if="{receive_newsletter} == True", + ) + +In the example above, ``PreferencesForm`` will act as a panel inside +``ProfileForm``. Note that that the ``FormPanel`` constructor takes the form +definition (the class) as the parameter, *not* an instance of the form. The +use of the ``visible_if`` condition makes sure the newsletter preferences +panel will only be shown if the user elects to receive the newsletter. + +It is possible to have a panel inside a panel, and even more nested panels if +desired. However, be aware that multiple levels of nesting can be confusing +for the user and require more complex code to get at the form data later. + +Dynamic panels +============== + +A dynamic panel is also a container for questions with multiple parts, but it +has the added feature that copies of it can be dynamically added and removed +from a form. In this way a user can add two or more related panels, like for +example relatives, social media accounts, or previous illnesses. It is +defined in the same way as a regular panel, except the ``dynamic`` parameter +is set to true:: + + from questions import Form + from questions import FormPanel + from questions import BooleanQuestion + from questions import DropdownQuestion + from questions import TextQuestion + + + class SocialMediaForm(Form): + service = DropdownQuestion(choices=["Twitter", "Instagram", "Snapchat"]) + account = TextQuestion() + + + class ProfileForm(Form): + social_media = FormPanel( + SocialMediaForm, + title="Social Media Accounts", + dynamic=True, + panel_count=2, + ) + +The above form will allow the user to add any number of social accounts. Pay +attention to the ``panel_count`` parameter, which signals that two panels will +be active when the form is first rendered. + +Pages ===== -Usage -===== -To use Questions in a project:: +Questions also allows the user to easily create multiple page forms. A page +form is like a panel that will be presented on its own page. When a form has +more than one page, Questions will add page navigation controls to move back +and forth between the pages. The final page will show a `complete` button:: + + from questions import Form + from questions import FormPage + from questions import TextQuestion + from questions import DropdownQuestion + + + class PageOne(Form): + name = TextQuestion() + email = TextQuestion(input_type="email", is_required="True") + + + class PageTwo(Form): + country = DropdownQuestion(choices_by_url={"value_name": "name", + "url": "https://restcountries.eu/rest/v2/all"}) + birthdate = TextQuestion(input_type="date") + + + class Profile(Form): + page_one = FormPage(PageOne, title="Identification Information") + page_two = FormPage(PageTwo, title="Additional Information") + +Although Questions will not complain if a page is added to another page, the +nested page will be treated like a panel, not a page. + +Accessing form data +=================== + +Once a questions form is submitted, the data will be posted to the page URL. To +get the form data, simply use you web framework's way of accessing JSON data. +For example, in Flask:: + + @app.route("/", methods=("POST",)) + def post(): + form_data = request.get_json() + +The form data is returned in a dictionary format, a key for each form field, +regardless of the page and panel structure of the form. A dynamic panel will +be represented as a list of dictionaries. For example:: + + { + 'name': 'John Smith', + 'email': 'smith@smith.me', + 'birthdate': '1980-05-08', + 'country': 'US' + } + +Since the data is returned as a single dictionary, it's not allowed to use +the same name for more than one field, even if the form has multiple pages. + +Edit Forms +========== + +An edit form is a form that shows predetermined values at render time. The +user can then change only the desired values. This would be used to edit +objects stored in a database, for example. To set up an edit form in +Questions, simply pass in a dictionary with the data to the form rendering +method, using the ``form_data`` parameter:: + + form = Profile() + + profile_data = { + 'name': 'John Smith', + 'email': 'smith@smith.me', + 'birthdate': '1980-05-08', + 'country': 'US' + } + + questions_js = form.render_js(form_data=profile_data) + +Here we are using a simple dictionary to set up the data, but of course the +usual thing to do for an edit form would be to get the data from a database. + +Validation +========== + +Form questions can have one or more validators assigned. The form data will be +validated on the front end, and the form cannot be sent unless they all pass. +Still, a user or bot could submit a Questions form directly to the Python +view, bypassing the validation. This is why questions includes mirror +validators that perform the same checks as the SurveyJS front end on the +server side. + +SurveyJS has five standard validators: + + - `Numeric`. Fails if the question answer is not a number, or if an entered + number is outside the ``min_value`` and ``max_value`` range. + - `Text`. Fails the entered text length is outside the ``min_length`` and + ``max_length`` range. + - `Expression`. Fails when ``expression`` returns false. + - `Regex`. Fails if the entered value does not fit a regular expression + (``regex``). + - `Email`. Fails if the entered value is not a valid e-mail. + +Questions allows the use of any of this validators, using its corresponding +validator classes:: + + from questions import Form + from questions import DropdownQuestion + from questions import TextQuestion + from questions import ExpressionValidator + from questions import NumericValidator + + class ValidatedForm(Form): + age = TextQuestion( + input_type="number", + validators=[ + NumericValidator( + max_value=130, + message="We sincerely doubt that is your age", + ) + ] + ) + tickets = DropdownQuestion( + choices=[1, 2, 3, 4, 5], + validators = [ + ExpressionValidator( + expression="{age} > 18 or {tickets} < 2", + message="Minors can only buy one ticket", + ) + ] + ) + +Notice that the expression validator allows referring to any other question +on the form, using the question name in brackets. This permits complex +validations. + +As mentioned above, validation will be performed in the front end, but it is +recommended to call the mirroring server side validation anyway, for safety. +To do that simply call the ``validate`` method on the form data:: - import questions + @app.route("/", methods=("POST",)) + def post(): + form.ValidatedForm() + form_data = request.get_json() + if form.validate(form_data): + # validation successful. Save data or something. diff --git a/questions/__init__.py b/questions/__init__.py index c7eb887..cd5dac7 100644 --- a/questions/__init__.py +++ b/questions/__init__.py @@ -16,8 +16,10 @@ from .questions import CKEditorQuestion from .questions import CommentQuestion from .questions import DropdownQuestion +from .questions import EmailValidator from .questions import EmotionsRatingQuestion from .questions import ExpressionBlock +from .questions import ExpressionValidator from .questions import FileQuestion from .questions import HtmlBlock from .questions import ImageBlock @@ -29,13 +31,16 @@ from .questions import MicrophoneQuestion from .questions import MultipleTextQuestion from .questions import NoUISliderQuestion +from .questions import NumericValidator from .questions import RadioGroupQuestion from .questions import RatingQuestion +from .questions import RegexValidator from .questions import Select2Question from .questions import SignaturePadQuestion from .questions import SortableJSQuestion from .questions import TagBoxQuestion from .questions import TextQuestion +from .questions import TextValidator __all__ = [ @@ -47,8 +52,10 @@ "CKEditorQuestion", "CommentQuestion", "DropdownQuestion", + "EmailValidator", "EmotionsRatingQuestion", "ExpressionBlock", + "ExpressionValidator", "FileQuestion", "Form", "FormPage", @@ -63,11 +70,14 @@ "MicrophoneQuestion", "MultipleTextQuestion", "NoUISliderQuestion", + "NumericValidator", "RadioGroupQuestion", "RatingQuestion", + "RegexValidator", "Select2Question", "SignaturePadQuestion", "SortableJSQuestion", "TagBoxQuestion", "TextQuestion", + "TextValidator", ] diff --git a/questions/form.py b/questions/form.py index 47d520a..a0a549f 100644 --- a/questions/form.py +++ b/questions/form.py @@ -27,13 +27,31 @@ class Form(object): setting up the form configuration and performing validation, it generates the SurveyJS form JSON and keeps track of the required Javascript and CSS resources. + + :param name: + The name of the form. If empty, the class name is used. + :param action: + The URL where the form data will be posted. If empty, the + same URL for the form is used. + :param html_id: + The id for the div element that will be used to render the form. + :param theme: + The name of the base theme for the form. Default value is 'default'. + :param platform: + The JS platform to use for generating the form. Default value is 'jquery'. + :param resource_url: + The base URL for the theme resources. If provided, + Questions will expect to find all resources under this URL. If + empty, the SurveyJS CDN will be used for all resources. + :param params: + Optional list of parameters to be passed to the SurveyJS form object. """ def __init__( self, name: str = "", - method: Literal[("GET", "POST")] = "POST", action: str = "", + html_id: str = "questions_form", theme: Literal[SURVEY_JS_THEMES] = "default", platform: Literal[SURVEY_JS_PLATFORMS] = "jquery", resource_url: str = SURVEY_JS_CDN, @@ -42,9 +60,9 @@ def __init__( if name == "": name = self.__class__.__name__ self.name = name - self.theme = theme - self.method = method self.action = action + self.html_id = html_id + self.theme = theme self.platform = platform self.resource_url = resource_url self.params = params @@ -52,8 +70,8 @@ def __init__( self._extra_css = [] self._form_elements = {} - def __call__(self): - return self.render_html() + def __call__(self, form_data=None): + return self.render_html(form_data=form_data) def _construct_survey(self): self._extra_js = [] @@ -121,54 +139,114 @@ def _add_elements(self, survey, form, top_level=False, container_name="questions @property def extra_js(self): + """ + Any extra JS resources required by the form's question types. + """ self._construct_survey() return self._extra_js @property def extra_css(self): + """ + Any extra CSS resources required by the form's question types. + """ self._construct_survey() return self._extra_css @property def required_js(self): + """ + Required JS resources needed to run SurveyJS on chosen platform. + """ return get_platform_js_resources(self.platform, self.resource_url) @property def required_css(self): + """ + Required CSS resources needed to run SurveyJS on chosen platform. + """ return get_theme_css_resources(self.theme, self.resource_url) @property def js(self): + """ + Combined JS resources for this form. + """ return self.required_js + self.extra_js @property def css(self): + """ + Combined CSS resources for this form. + """ return self.required_css + self.extra_css def to_json(self): + """ + Convert the form to JSON, in the SurveyJS format. + + :Returns: + JSON object with the form definition. + """ survey = self._construct_survey() return survey.json(by_alias=True, include=INCLUDE_KEYS) def render_js(self, form_data=None): + """ + Generate the SurveyJS initialization code for the chosen platform. + + :param form_data: answers to show on the form for each + question (for edit forms). + + :Returns: + String with the generated javascript. + """ return get_survey_js( - self.to_json(), form_data, self.action, self.theme, self.platform + self.to_json(), + form_data, + self.html_id, + self.action, + self.theme, + self.platform, ) def render_html(self, title=None, form_data=None): + """ + Render a full HTML page showing this form. + + :param title: + The form title. + :param form_data: + answers to show on the form for each question (for edit forms). + + :Returns: + String with the generated HTML. + """ if title is None: title = self.params.get("title", self.name) if form_data is None: form_data = {} survey_js = self.render_js(form_data=form_data) - return get_form_page(title, self.platform, survey_js, self.js, self.css) + return get_form_page( + title, self.html_id, self.platform, survey_js, self.js, self.css + ) - def validate(self, form_data): + def validate(self, form_data, set_errors=False): """ Server side validation mimics what client side validation should do. This means that any validation errors here are due to form data being sent from outside the SurveyJS form, possibly by directly posting the data to the form. Questions keeps track of the errors, even though the UI will show them anyway. Validation returns False if at least one validator doesn't pass. + + :param form_data: + A dictionary-like object with the form data to be validated. + :param set_errors: + set to :data:`True` to add an `__errors__` key to the + form data dictionary, containing the validation errors. + + :Returns: + :data:`True` if the validation passes, :data:`False` otherwise. """ validated = True errors = [] @@ -178,19 +256,26 @@ def validate(self, form_data): if value is None and element.is_required: errors.append({"question": name, "message": "An answer is required"}) validated = False - for validator_data in element.validators: - if not call_validator(validator_data, value, form_data): - errors.append( - {"question": name, "message": validator_data["message"]} - ) + for validator in element.validators: + if not call_validator(validator, value, form_data): + errors.append({"question": name, "message": validator.message}) validated = False - form_data["__errors__"] = errors + if set_errors: + form_data["__errors__"] = errors return validated class FormPage(object): """ Represents an individual page from a multi-page form. + + :param form: + A subclass of questions.Form (not an instance). The form + to be shown in its own page. + :param name: + The name of the form. + :param params: + Optional list of parameters to be passed to the SurveyJS page object. """ def __init__(self, form: Type[Form], name: str = "", **params): @@ -205,7 +290,18 @@ def __init__(self, form: Type[Form], name: str = "", **params): class FormPanel(object): """ A panel is a set of fields that go together. It can be used for visual - separation, or as a dinamically added group of fields for complex questions. + separation, or as a dynamically added group of fields for complex questions. + + :param form: + A subclass of questions.Form (not an instance). The form + to be shown in its own page. + :param name: + The name of the form. + :param dynamic: + Set to :data:`True` if the panel will be used as a template for adding + or removing groups of questions. + :param params: + Optional list of parameters to be passed to the SurveyJS panel object. """ def __init__( diff --git a/questions/questions.py b/questions/questions.py index ef11ec4..8cdcbb9 100644 --- a/questions/questions.py +++ b/questions/questions.py @@ -40,6 +40,38 @@ def fix_name(cls, name): alias_generator = fix_name +class Validator(Base): + kind: str + message: str = "Invalid value" + + +class TextValidator(Validator): + kind: str = "text" + max_length: int = 0 + min_length: int = 0 + allow_digits: bool = True + + +class NumericValidator(Validator): + kind: str = "numeric" + max_value: int = 0 + min_value: int = 0 + + +class EmailValidator(Validator): + kind: str = "email" + + +class RegexValidator(Validator): + kind: str = "regex" + regex: str = "" + + +class ExpressionValidator(Validator): + kind: str = "regex" + expression: str = "" + + class Question(Base): kind: str name: str = "" @@ -63,7 +95,7 @@ class Question(Base): max_width: str = "initial" min_width: str = "300px" use_display_values_in_title: bool = True - validators: List[Dict[str, Any]] = [] + validators: List[Validator] = [] extra_js: List[HttpUrl] = [] extra_css: List[HttpUrl] = [] diff --git a/questions/templates.py b/questions/templates.py index b9fb479..257d7e1 100644 --- a/questions/templates.py +++ b/questions/templates.py @@ -42,51 +42,50 @@ PLATFORM_JS = { "jquery": """var survey = new Survey.Model(json); survey.data = data; -$("#questions_form").Survey({ +$("#{}").Survey({{ model:survey, onComplete:sendDataToServer -}); +}}); """, "angular": """window.survey = new Survey.Model(json); survey .onComplete .add(sendDataToServer); survey.data = data; -function onAngularComponentInit() { +function onAngularComponentInit() {{ Survey .SurveyNG .render("surveyElement", {model: survey}); -} +}} var QuestionsApp = ng .core - .Component({selector: 'ng-app', template: '
'}) - .Class({ - constructor: function () {}, - ngOnInit: function () { + .Component({{selector: 'ng-app', template: '
'}}) + .Class({{ + constructor: function () {{}}, + ngOnInit: function () {{ onAngularComponentInit(); - } - }); + }} + }}); document.addEventListener('DOMContentLoaded', function () { ng .platformBrowserDynamic .bootstrap(QuestionsApp); -}); +}}); """, - "ko": """var survey = new Survey.Model(json, "questions_form"); + "ko": """var survey = new Survey.Model(json, "{}"); survey.data = data; survey.onComplete.add(sendDataToServer); """, "react": """window.survey = new Survey.Model(json); -survey.data = data; -ReactDOM.render(, - document.getElementById("questions_form")); +ReactDOM.render(, + document.getElementById("{}")); """, "vue": """var survey = new Survey.Model(json); survey.data = data; survey .onComplete .add(sendDataToServer); -new Vue({ el: '#questions_form', data: { survey: survey } }); +new Vue({{ el: '#{}', data: {{ survey: survey }} }}); """, } @@ -100,7 +99,7 @@ -
+
@@ -116,7 +115,7 @@ - + @@ -132,7 +131,7 @@ -
+
@@ -148,7 +147,7 @@ -
+
@@ -164,7 +163,7 @@ -
+
@@ -197,19 +196,19 @@ def get_theme_css_resources(theme, resource_url): return [f"{resource_url}/{name}.css"] -def get_survey_js(form_json, form_data, action, theme, platform): +def get_survey_js(form_json, form_data, html_id, action, theme, platform): if form_data is None: form_data = {} - platform_js = PLATFORM_JS[platform] + platform_js = PLATFORM_JS[platform].format(html_id) data = json.dumps(form_data) return SURVEY_JS.format(theme, form_json, data, action, platform_js) -def get_form_page(title, platform, js, js_resources, css_resources): +def get_form_page(title, html_id, platform, js, js_resources, css_resources): resources = "" platform_html = SURVEY_HTML[platform] for resource in js_resources: resources += f'\n' for resource in css_resources: resources += f'\n' - return platform_html.format(title, resources, js) + return platform_html.format(title, resources, html_id, js) diff --git a/questions/validators.py b/questions/validators.py index 40620f3..f2eaeb1 100644 --- a/questions/validators.py +++ b/questions/validators.py @@ -6,10 +6,10 @@ from simpleeval import InvalidExpression -def text_validator(validator_data, value, form_data): - max_length = int(validator_data.get("max_length", "0")) - min_length = int(validator_data.get("min_length", "0")) - allow_digits = int(validator_data.get("allow_digits", False)) +def text_validator(validator, value, form_data): + max_length = int(validator.max_length) + min_length = int(validator.min_length) + allow_digits = validator.allow_digits result = True value = str(value) length = len(value) @@ -22,9 +22,9 @@ def text_validator(validator_data, value, form_data): return result -def number_validator(validator_data, value, form_data): - max_value = float(validator_data.get("max_value", 0)) - min_value = float(validator_data.get("min_value", 0)) +def numeric_validator(validator, value, form_data): + max_value = float(validator.max_value) + min_value = float(validator.min_value) result = True value = float(value) if value < min_value or max_value > 0 and value > max_value: @@ -32,7 +32,7 @@ def number_validator(validator_data, value, form_data): return result -def email_validator(validator_data, value, form_data): +def email_validator(validator, value, form_data): result = True try: validate_email(value) @@ -41,14 +41,14 @@ def email_validator(validator_data, value, form_data): return result -def regex_validator(validator_data, value, form_data): - regex = validator_data["regex"] +def regex_validator(validator, value, form_data): + regex = validator.regex regex = re.compile(regex) return regex.match(value) is not None -def expression_validator(validator_data, value, form_data): - expression = validator_data["expression"] +def expression_validator(validator, value, form_data): + expression = validator.expression result = True if expression: expression = expression.replace("{", "").replace("}", "") @@ -65,13 +65,13 @@ def expression_validator(validator_data, value, form_data): VALIDATORS = { "text": text_validator, - "number": number_validator, + "numeric": numeric_validator, "email": email_validator, "regex": regex_validator, "expression": expression_validator, } -def call_validator(validator_data, value, form_data): - validator = VALIDATORS[validator_data["type"]] - return validator(validator_data, value, form_data) +def call_validator(validator, value, form_data): + validator_method = VALIDATORS[validator.kind] + return validator_method(validator, value, form_data) diff --git a/requirements_dev.txt b/requirements_dev.txt index 597c20c..cb6c71d 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -11,3 +11,5 @@ Click==7.1.2 pytest==6.0.2 pytest-runner==5.2 black==20.8b1 +sphinx-autodoc-typehints==1.11.0 +sphinxcontrib.spelling==5.4.0 diff --git a/setup.py b/setup.py index d4fd8ea..16ba647 100644 --- a/setup.py +++ b/setup.py @@ -33,6 +33,9 @@ 'Programming Language :: Python :: 3.6', 'Programming Language :: Python :: 3.7', 'Programming Language :: Python :: 3.8', + 'Topic :: Internet :: WWW/HTTP', + 'Topic :: Internet :: WWW/HTTP :: Dynamic Content', + 'Topic :: Software Development :: Libraries :: Python Modules', ], description="Questions is a form library that uses the power of SurveyJS for the UI.", entry_points={ diff --git a/tests/test_form.py b/tests/test_form.py index 556088e..3a4ae01 100644 --- a/tests/test_form.py +++ b/tests/test_form.py @@ -4,12 +4,12 @@ from questions import form from questions import questions +from questions import TextValidator def test_initialize(): test_form = form.Form(name="testing", param1=0) assert test_form.name == "testing" - assert test_form.method == "POST" assert "param1" in test_form.params @@ -149,7 +149,6 @@ class TestForm(form.Form): test_form = TestForm(name="testing") form_data = {} assert test_form.validate(form_data) is True - assert form_data["__errors__"] == [] def test_validate_required_valid(): @@ -159,7 +158,6 @@ class TestForm(form.Form): test_form = TestForm(name="testing") form_data = {"text1": "hello"} assert test_form.validate(form_data) is True - assert form_data["__errors__"] == [] def test_validate_required_invalid(): @@ -169,11 +167,10 @@ class TestForm(form.Form): test_form = TestForm(name="testing") form_data = {} assert test_form.validate(form_data) is False - assert form_data["__errors__"][0]["question"] == "text1" def test_validate_with_validators_valid(): - text_validator = {"type": "text", "min_length": 5, "message": "fail"} + text_validator = TextValidator(min_length=5) class TestForm(form.Form): text1 = questions.TextQuestion(validators=[text_validator]) @@ -181,16 +178,16 @@ class TestForm(form.Form): test_form = TestForm(name="testing") form_data = {"text1": "hello is enough"} assert test_form.validate(form_data) is True - assert form_data["__errors__"] == [] + assert "__errors__" not in form_data -def test_validate_with_validators_invalid(): - text_validator = {"type": "text", "min_length": 5, "message": "fail"} +def test_validate_with_validators_invalid_with_set_errors(): + text_validator = TextValidator(min_length=5) class TestForm(form.Form): text1 = questions.TextQuestion(validators=[text_validator]) test_form = TestForm(name="testing") form_data = {"text1": "Bye"} - assert test_form.validate(form_data) is False + assert test_form.validate(form_data, set_errors=True) is False assert form_data["__errors__"][0]["question"] == "text1" diff --git a/tests/test_templates.py b/tests/test_templates.py index d0410ea..66e1515 100644 --- a/tests/test_templates.py +++ b/tests/test_templates.py @@ -29,28 +29,28 @@ def test_get_theme_css_resources(): def test_get_survey_js(): survey_js = templates.get_survey_js( - "FORM_JSON", "FORM_DATA", "http://testing", "default", "jquery" + "FORM_JSON", "FORM_DATA", "id", "http://testing", "default", "jquery" ) assert "FORM_JSON" in survey_js assert "FORM_DATA" in survey_js assert "http://testing" in survey_js assert "default" in survey_js - assert templates.PLATFORM_JS["jquery"] in survey_js + assert templates.PLATFORM_JS["jquery"].format("id") in survey_js def test_get_survey_js_form_data_is_none(): survey_js = templates.get_survey_js( - "FORM_JSON", None, "http://testing", "default", "jquery" + "FORM_JSON", None, "id", "http://testing", "default", "jquery" ) assert "FORM_JSON" in survey_js assert "http://testing" in survey_js assert "default" in survey_js - assert templates.PLATFORM_JS["jquery"] in survey_js + assert templates.PLATFORM_JS["jquery"].format("id") in survey_js def test_get_form_page(): html = templates.get_form_page( - "Title", "jquery", "GENERATED_JS", ["file.js"], ["file.css"] + "Title", "id", "jquery", "GENERATED_JS", ["file.js"], ["file.css"] ) assert "Title" in html assert "GENERATED_JS" in html diff --git a/tests/test_validators.py b/tests/test_validators.py index e2d71c2..00eb306 100644 --- a/tests/test_validators.py +++ b/tests/test_validators.py @@ -2,68 +2,65 @@ """Tests for `validators` package.""" +from unittest import mock + from questions import validators +from questions import EmailValidator +from questions import ExpressionValidator +from questions import NumericValidator +from questions import RegexValidator +from questions import TextValidator def test_text_validator_bad_min_length(): - validator_data = {"min_length": "7"} - assert validators.text_validator(validator_data, "hello", {}) is False - assert validators.text_validator(validator_data, "goodbye", {}) is True + validator = TextValidator(min_length=7) + assert validators.text_validator(validator, "hello", {}) is False + assert validators.text_validator(validator, "goodbye", {}) is True def test_text_validator_bad_max_length(): - validator_data = {"max_length": "4"} - assert validators.text_validator(validator_data, "hello", {}) is False - assert validators.text_validator(validator_data, "Bye", {}) is True + validator = TextValidator(max_length=4) + assert validators.text_validator(validator, "hello", {}) is False + assert validators.text_validator(validator, "Bye", {}) is True def test_text_validator_allow_digits(): - validator_data = {"allow_digits": False} - assert validators.text_validator(validator_data, "h4ll0", {}) is False - validator_data = {"allow_digits": True} - assert validators.text_validator(validator_data, "h4ll0", {}) is True + validator = TextValidator(allow_digits=False) + assert validators.text_validator(validator, "h4ll0", {}) is False + validator = TextValidator(allow_digits=True) + assert validators.text_validator(validator, "h4ll0", {}) is True -def test_number_validator_bad_min_value(): - validator_data = {"min_value": 7} - assert validators.number_validator(validator_data, 5, {}) is False - assert validators.number_validator(validator_data, 45, {}) is True +def test_numeric_validator_bad_min_value(): + validator = NumericValidator(min_value=7) + assert validators.numeric_validator(validator, 5, {}) is False + assert validators.numeric_validator(validator, 45, {}) is True -def test_number_validator_bad_max_value(): - validator_data = {"max_value": 42} - assert validators.number_validator(validator_data, 99, {}) is False - assert validators.number_validator(validator_data, 22, {}) is True +def test_numeric_validator_bad_max_value(): + validator = NumericValidator(max_value=42) + assert validators.numeric_validator(validator, 99, {}) is False + assert validators.numeric_validator(validator, 22, {}) is True def test_email_validator(): - assert validators.email_validator({}, "my.bad.address.com", {}) is False - assert validators.email_validator({}, "my@true.email.com", {}) is True + validator = EmailValidator() + assert validators.email_validator(validator, "my.bad.address.com", {}) is False + assert validators.email_validator(validator, "my@true.email.com", {}) is True def test_regex_validator(): - validator_data = {"regex": "[A-Z][a-z]+-[0-9][0-9]"} - assert validators.regex_validator(validator_data, "anything", {}) is False - assert validators.regex_validator(validator_data, "Abc-55", {}) is True + validator = RegexValidator(regex="[A-Z][a-z]+-[0-9][0-9]") + assert validators.regex_validator(validator, "anything", {}) is False + assert validators.regex_validator(validator, "Abc-55", {}) is True def test_expression_validator(): - validator_data = {"expression": "{var2} notempty and {var3} > 5"} + validator = ExpressionValidator(expression="{var2} notempty and {var3} > 5") form_data = {"var1": "something", "var2": "", "var3": 1} - assert ( - validators.expression_validator(validator_data, "anything", form_data) is False - ) - assert validators.expression_validator(validator_data, "anything", {}) is False + assert validators.expression_validator(validator, "anything", form_data) is False + assert validators.expression_validator(validator, "anything", {}) is False form_data = {"var1": "something", "var2": "other", "var3": 8} - assert ( - validators.expression_validator(validator_data, "anything", form_data) is True - ) - validator_data = {"expression": ""} - assert ( - validators.expression_validator(validator_data, "anything", form_data) is True - ) - - -def test_call_validator(): - validator_data = {"type": "text"} - validators.call_validator(validator_data, "anything", {}) + assert validators.expression_validator(validator, "anything", form_data) is True + validator = ExpressionValidator(expression="") + assert validators.expression_validator(validator, "anything", form_data) is True