Forms

Form-related functionality is accessed through client.forms. For example:

from pyodk.client import Client

client = Client()
forms = client.forms.list()

create(definition, attachments=None, ignore_warnings=True, form_id=None, project_id=None)

Create a form.

Parameters:

Name	Type	Description	Default
definition	PathLike | str | bytes	The path to the file to upload (string or PathLike), or the form definition in memory (string (XML) or bytes (XLS/XLSX)).	required
attachments	Iterable[PathLike | str] | None	The paths of the form attachment file(s) to upload.	None
ignore_warnings	bool | None	If True, create the form if there are XLSForm warnings.	True
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project this form belongs to.	None

Returns:

Type	Description
Form	An object representation of the Form's metadata.

get(form_id, project_id=None)

Read Form details.

Parameters:

Name	Type	Description	Default
form_id	str	The id of this form as given in its XForms XML definition.	required
project_id	int | None	The id of the project this form belongs to.	None

Returns:

Type	Description
Form	An object representation of the Form's metadata.

list(project_id=None)

Read all Form details.

Parameters:

Name	Type	Description	Default
project_id	int | None	The id of the project the forms belong to.	None

Returns:

Type	Description
list[Form]	A list of object representations of all Forms' metadata.

update(form_id, project_id=None, definition=None, attachments=None, version_updater=None)

Update an existing Form. Must specify definition, attachments or both.

Accepted call patterns:

• form definition only
• form definition with attachments
• form attachments only
• form attachments with version_updater

If a definition is provided, the new version name must be specified in the definition. If no definition is provided, a default version will be set using the current datetime is ISO format.

The default datetime version can be overridden by providing a version_updater function. The function will be passed the current version name as a string, and must return a string with the new version name. For example:

• Parse then increment a version number: version_updater=lambda v: int(v) + 1
• Disregard the input and return a string: version_updater=lambda v: "v2.0".

Parameters:

Name	Type	Description	Default
form_id	str	The xmlFormId of the Form being referenced.	required
project_id	int | None	The id of the project this form belongs to.	None
definition	PathLike | str | bytes | None	The path to the file to upload (string or PathLike), or the form definition in memory (string (XML) or bytes (XLS/XLSX)). The form definition must include an updated version string.	None
attachments	Iterable[PathLike | str] | None	The paths of the form attachment file(s) to upload.	None
version_updater	Callable[[str], str] | None	A function that accepts a version name string and returns a version name string, which is used for the new form version. Not allowed if a form definition is specified.	None