gformlib.builder

Google Forms API request builder.

This module converts a validated FormConfig into the JSON structures expected by the Google Forms REST API v1.

The main entry-point is FormBuilder.

class gformlib.builder.FormBuilder(config)

Bases: object

Converts a FormConfig into Google Forms API payloads.

This class is used internally by GoogleFormsClient but is also exposed publicly so that callers can inspect or further customise the generated request bodies before submitting them.

Example:

from gformlib.builder import FormBuilder
from gformlib.models import FormConfig, QuestionConfig, QuestionType

config = FormConfig(
    title="Demo",
    questions=[
        QuestionConfig(
            title="Favourite colour?",
            question_type=QuestionType.SHORT_ANSWER,
        ),
    ],
)
builder = FormBuilder(config)
create_body = builder.build_create_body()
batch_body  = builder.build_batch_update_body()

Parameters:

config (FormConfig)

build_create_body()

Build the request body for the forms().create() API call.

Returns:

A dict suitable for passing as the body argument of service.forms().create(body=...). Contains only the form title and document title; questions are added separately via build_batch_update_body().

Return type:

Dict[str, Any]

Example:

body = builder.build_create_body()
# {"info": {"title": "Demo", "documentTitle": "Demo"}}

build_batch_update_body()

Build the batchUpdate request body that adds all questions.

Returns:

A dict suitable for passing as the body argument of service.forms().batchUpdate(formId=..., body=...). Returns an empty {"requests": []} dict when the form has no questions.

Return type:

Dict[str, Any]

Example:

body = builder.build_batch_update_body()
# {"requests": [{"createItem": {...}}, ...]}

classmethod build_update_body(update_config, start_index=0)

Build a batchUpdate request body for updating an existing form.

Constructs a list of API requests based on what is set in update_config:

• If title is set, an updateFormInfo request with mask "title" is included.

• If description is set, an updateFormInfo request with mask "description" is included (combined with the title mask when both are provided).

• Each question in add_questions generates a createItem request positioned after the existing items (controlled by start_index).

Parameters:

• update_config (UpdateFormConfig) – The validated update configuration.

• start_index (int) – Zero-based index of the first new item. Pass the current number of items in the form so that new questions are appended at the end. Defaults to 0.

Returns:

A dict suitable for service.forms().batchUpdate(body=...). Returns {"requests": []} when update_config contains no changes.

Return type:

Dict[str, Any]

Example:

body = FormBuilder.build_update_body(
    UpdateFormConfig(title="New Title"),
)
# {"requests": [{"updateFormInfo": {"info": {"title": "New Title"},
#                                   "updateMask": "title"}}]}