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.

get_xml(form_id, project_id=None, encoding='utf-8')

Read the form XForms XML document.

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
encoding	str | None	The string encoding of the XML document. If "bytes" then the document will be returned as bytes, otherwise the encoding parameter value will be used to decode the bytes to return a string.	'utf-8'

Returns:

Type	Description
str | bytes	The XForms XML document.

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