gformlib.utils

Validation utilities for gformlib.

This module provides helpers that validate user-supplied configuration dictionaries and convert them into typed gformlib.models objects before any API call is made.

gformlib.utils.parse_question(data, index=0)

Parse and validate a single question configuration dict.

Parameters:

• data (Dict[str, Any]) – Raw question configuration dict supplied by the caller. Must contain at least "title" and "type" keys.

• index (int) – Zero-based position of the question in the form (used in error messages).

Returns:

A validated QuestionConfig instance.

Raises:

InvalidConfigError – If a required key is missing, the type is unknown, or type-specific constraints are violated.

Return type:

QuestionConfig

Example:

from gformlib.utils import parse_question

q = parse_question(
    {"title": "Pick one", "type": "multiple_choice", "options": ["A", "B"]},
    index=0,
)

gformlib.utils.parse_form_config(data)

Parse and validate a complete form configuration dict.

Parameters:

data (Dict[str, Any]) – Raw form configuration dict. Must contain at least a "title" key. The optional "questions" key should be a list of question dicts (see parse_question()).

Returns:

A validated FormConfig instance.

Raises:

• InvalidConfigError – If the configuration is structurally invalid.

• TypeError – If data is not a dict.

Return type:

FormConfig

Example:

from gformlib.utils import parse_form_config

cfg = parse_form_config(
    {
        "title": "My Survey",
        "questions": [
            {"title": "Name?", "type": "short_answer"},
        ],
    }
)

gformlib.utils.parse_update_config(data)

Parse and validate a form update configuration dict.

All keys are optional. At least one of title, description, or add_questions should normally be present, though an empty update is accepted (it simply returns the current form state unchanged).

Parameters:

data (Dict[str, Any]) –

Raw update configuration dict. Recognised keys:

• "title" (str) – new form title.

• "description" (str) – new form description.

• "add_questions" (list) – question dicts to append (same format as in parse_form_config()).

Returns:

A validated UpdateFormConfig instance.

Raises:

• InvalidConfigError – If add_questions is present but not a list, or if any individual question dict is invalid.

• TypeError – If data is not a dict.

Return type:

UpdateFormConfig

Example:

from gformlib.utils import parse_update_config

cfg = parse_update_config(
    {
        "title": "Revised Survey",
        "add_questions": [
            {"title": "Comments", "type": "paragraph"},
        ],
    }
)