citric

A client to the LimeSurvey Remote Control API 2, written in modern Python.

Submodules

• citric.client
• citric.enums
• citric.exceptions
• citric.method
• citric.session

Package Contents

Classes

Client

LimeSurvey Remote Control client.

class citric.Client(url, username, password, *, requests_session=None, auth_plugin='Authdb')

LimeSurvey Remote Control client.

Offers explicit wrappers for RPC methods and simplifies common workflows.

Parameters

• url (str) – LimeSurvey Remote Control endpoint.

• username (str) – LimeSurvey user name.

• password (str) – LimeSurvey password.

• requests_session (requests.Session | None) – A requests.Session object.

• auth_plugin (str) – Name of the plugin to use for authentication. For example, AuthLDAP. Defaults to using the internal database ("Authdb").

session_class

close(self)

Close client session.

__enter__(self)

Create client context.

__exit__(self, exc_type, exc_value, traceback)

Safely exit the client context.

property session(self)

Low-level RPC session.

get_fieldmap(self, survey_id)

Get fieldmap for a survey.

Parameters

survey_id (int) – ID of survey to get fieldmap for.

Returns

Dictionary mapping response keys to LimeSurvey internal representation.

Return type

dict

activate_survey(self, survey_id)

Activate a survey.

Parameters

survey_id (int) – ID of survey to be activated.

Returns

Status and plugin feedback.

Return type

dict[str, Any]

activate_tokens(self, survey_id, attributes=None)

Initialise the survey participant table.

New participant tokens may be later added.

Parameters

• survey_id (int) – ID of survey to be activated.

• attributes (list[int] | None) – Optional list of participant attributes numbers to be activated.

Returns

Status message.

Return type

dict[str, str]

add_language(self, survey_id, language)

Add a survey language.

Parameters

• survey_id (int) – ID of the Survey for which a language will be added.

• language (str) – A valid language shortcut to add to the current Survey. If the language already exists no error will be given.

Returns

Status message.

Return type

dict[str, Any]

add_participants(self, survey_id, *, participant_data, create_tokens=True)

Add participants to a survey.

Parameters

• survey_id (int) – Survey to add participants to.

• participant_data (Sequence[Mapping[str, Any]]) – Information to create participants with.

• create_tokens (bool) – Whether to create the participants with tokens.

Returns

Information of newly created participants.

Return type

list[dict[str, Any]]

add_survey(self, survey_id, title, language, survey_format='G')

Add a new empty survey.

Parameters

• survey_id (int) – The desired ID of the Survey to add.

• title (str) – Title of the new Survey.

• language (str) – Default language of the Survey.

• survey_format (str) – Question appearance format (A, G or S) for “All on one page”, “Group by Group”, “Single questions”, default to group by group (G).

Returns

The new survey ID.

Return type

int

delete_participants(self, survey_id, participant_ids)

Add participants to a survey.

Parameters

• survey_id (int) – Survey to delete participants to.

• participant_ids (Sequence[int]) – Participant IDs to be deleted.

Returns

Information of removed participants.

Return type

list[dict[str, Any]]

add_group(self, survey_id, title, description='')

Add a new empty question group to a survey.

Parameters

• survey_id (int) – ID of the Survey to add the group.

• title (str) – Name of the group.

• description (str) – Optional description of the group.

Returns

The id of the new group.

Return type

int

add_response(self, survey_id, response_data)

Add a single response to a survey.

Parameters

• survey_id (int) – Survey to add the response to.

• response_data (Mapping[str, Any]) – Single response as a mapping.

Returns

ID of the new response.

Return type

int

add_responses(self, survey_id, responses)

Add multiple responses to a survey.

Parameters

• survey_id (int) – Survey to add the response to.

• responses (Iterable[Mapping[str, Any]]) – Iterable of survey responses.

Returns

IDs of the new responses.

Return type

list[int]

update_response(self, survey_id, response_data)

Update a response.

Parameters

• survey_id (int) – Survey to update the response in.

• response_data (dict[str, Any]) – Response data to update.

Returns

True if the response was updated, False otherwise.

Return type

bool

copy_survey(self, survey_id, name)

Copy a survey.

Parameters

• survey_id (int) – ID of the source survey.

• name (str) – Name of the new survey.

Returns

Dictionary of status message and the new survey ID.

Return type

dict[str, Any]

delete_group(self, survey_id, group_id)

Delete a group.

Parameters

• survey_id (int) – ID of the Survey that the group belongs to.

• group_id (int) – ID of the group to delete.

Returns

ID of the deleted group.

Return type

int

delete_language(self, survey_id, language)

Delete a language from a survey.

Requires at LimeSurvey >= 5.3.4.

Parameters

• survey_id (int) – ID of the Survey for which a language will be deleted from.

• language (str) – Language to delete.

Returns

Status message.

Return type

dict[str, str]

delete_response(self, survey_id, response_id)

Delete a response in a survey.

Parameters

• survey_id (int) – ID of the survey the response belongs to.

• response_id (int) – ID of the response to delete.

Returns

Status message.

Return type

dict[str, str]

delete_question(self, question_id)

Delete a survey.

Requires at least LimeSurvey 5.3.19+220607.

TODO: Add links to issue, PR, etc.

Parameters

question_id (int) – ID of Question to delete.

Returns

ID of the deleted question.

Return type

int

delete_survey(self, survey_id)

Delete a survey.

Parameters

survey_id (int) – Survey to delete.

Returns

Status message.

Return type

dict[str, str]

export_responses(self, survey_id, *, token=None, file_format='json', language=None, completion_status='all', heading_type='code', response_type='short', from_response_id=None, to_response_id=None, fields=None)

Export responses to a file-like object.

Parameters

• survey_id (int) – Survey to add the response to.

• token (str | None) – Optional participant token to get responses for.

• file_format (str) – Type of export. One of PDF, CSV, XLS, DOC or JSON.

• language (str | None) – Export responses made to this language version of the survey.

• completion_status (str) – Incomplete, complete or all.

• heading_type (str) – Use response codes, long or abbreviated titles.

• response_type (str) – Export long or short text responses.

• from_response_id (int | None) – First response to export.

• to_response_id (int | None) – Last response to export.

• fields (Sequence[str] | None) – Which response fields to export. If none, exports all fields.

Returns

Content bytes of exported to file.

Return type

bytes

save_responses(self, filename, survey_id, *, token=None, file_format='json', language=None, completion_status='all', heading_type='code', response_type='short', from_response_id=None, to_response_id=None, fields=None)

Save responses to a file.

Parameters

• filename (os.PathLike) – Target file path.

• survey_id (int) – Survey to add the response to.

• token (str | None) – Optional participant token to get responses for.

• file_format (str) – Type of export. One of PDF, CSV, XLS, DOC or JSON.

• language (str | None) – Export responses made to this language version of the survey.

• completion_status (str) – Incomplete, complete or all.

• heading_type (str) – Use response codes, long or abbreviated titles.

• response_type (str) – Export long or short text responses.

• from_response_id (int | None) – First response to export.

• to_response_id (int | None) – Last response to export.

• fields (Sequence[str] | None) – Which response fields to export. If none, exports all fields.

Returns

Bytes length written to file.

Return type

int

export_statistics(self, survey_id, *, file_format='pdf', language=None, graph=False, group_ids=None)

Export survey statistics.

Parameters

• survey_id (int) – ID of the Survey.

• file_format (str) – Type of documents the exported statistics should be. Defaults to “pdf”.

• language (str | None) – Language of the survey to use (default from Survey). Defaults to None.

• graph (bool) – Export graphs. Defaults to False.

• group_ids (list[int] | None) – Question groups to generate statistics from. Defaults to None.

Returns

File contents.

Return type

bytes

save_statistics(self, filename, survey_id, *, file_format='pdf', language=None, graph=False, group_ids=None)

Save survey statistics to a file.

Parameters

• filename (os.PathLike) – Target file path.

• survey_id (int) – ID of the Survey.

• file_format (str) – Type of documents the exported statistics should be. Defaults to “pdf”.

• language (str | None) – Language of the survey to use (default from Survey). Defaults to None.

• graph (bool) – Export graphs. Defaults to False.

• group_ids (list[int] | None) – Question groups to generate statistics from. Defaults to None.

Returns

Bytes length written to file.

Return type

int

export_timeline(self, survey_id, period, start, end=None)

Export survey submission timeline.

Parameters

• survey_id (int) – ID of the Survey.

• period (Literal[day, hour]) – Granularity level for aggregation submission counts.

• start (datetime.datetime) – Start datetime.

• end (datetime.datetime | None) – End datetime.

Returns

Mapping of days/hours to submission counts.

Return type

dict[str, int]

get_group_properties(self, group_id, *, settings=None, language=None)

Get the properties of a group of a survey.

Parameters

• group_id (int) – ID of the group to get properties of.

• settings (list[str] | None) – Properties to get, default to all.

• language (str | None) – Parameter language for multilingual groups.

Returns

Dictionary of group properties.

Return type

dict[str, Any]

get_language_properties(self, survey_id, *, settings=None, language=None)

Get survey language properties.

Parameters

• survey_id (int) – ID of the survey.

• settings (list[str] | None) – Properties to get, default to all.

• language (str | None) – Parameter language for multilingual questions.

Returns

Dictionary of survey language properties.

Return type

dict[str, Any]

get_participant_properties(self, survey_id, query, properties=None)

Get properties a single survey participant.

Parameters

• survey_id (int) – Survey to get participants properties.

• query (dict[str, Any] | int) – Mapping of properties to query participants, or the token id as an integer.

• properties (Sequence[str] | None) – Which participant properties to retrieve.

Returns

List of participants properties.

Return type

dict[str, Any]

get_question_properties(self, question_id, *, settings=None, language=None)

Get properties of a question in a survey.

Parameters

• question_id (int) – ID of the question to get properties.

• settings (list[str] | None) – Properties to get, default to all.

• language (str | None) – Parameter language for multilingual questions.

Returns

Dictionary of question properties.

Return type

dict[str, Any]

get_response_ids(self, survey_id, token)

Find response IDs given a survey ID and a token.

Parameters

• survey_id (int) – Survey to get responses from.

• token (str) – Participant for which to get response IDs.

Returns

A list of response IDs.

Return type

list[int]

get_default_theme(self)

Get the global default theme.

Calls get_site_settings(“defaulttheme”).

Returns

The name of the theme.

Return type

str

get_site_name(self)

Get the site name.

Calls get_site_settings(“sitename”).

Returns

The name of the site.

Return type

str

get_default_language(self)

Get the default site language.

Calls get_site_settings(“defaultlang”).

Returns

A string representing the language.

Return type

str

get_available_languages(self)

Get the list of available languages.

Calls get_site_settings(“restrictToLanguages”).

Returns

Either a list of strings for the available languages or None if there are no restrictions.

Return type

list[str] | None

get_summary(self, survey_id)

Get survey summary.

Parameters

survey_id (int) – ID of the survey to get summary of.

Returns

Mapping of survey statistics.

Return type

dict[str, int]

get_survey_properties(self, survey_id, properties=None)

Get properties of a survey.

Parameters

• survey_id (int) – Survey to get properties.

• properties (Sequence[str] | None) – Which survey properties to retrieve. If none, gets all fields.

Returns

Dictionary of survey properties.

Return type

dict[str, Any]

get_uploaded_files(self, survey_id, token=None)

Get a dictionary of files uploaded in a survey response.

Parameters

• survey_id (int) – Survey for which to download files.

• token (str | None) – Optional participant token to filter uploaded files.

Returns

Dictionary with uploaded files metadata.

Return type

dict[str, dict[str, Any]]

get_uploaded_file_objects(self, survey_id, token=None)

Iterate over uploaded files in a survey response.

Parameters

• survey_id (int) – Survey for which to download files.

• token (str | None) – Optional participant token to filter uploaded files.

Yields

UploadedFile objects.

download_files(self, directory, survey_id, token=None)

Download files uploaded in survey response.

Parameters

• directory (str | Path) – Where to store the files.

• survey_id (int) – Survey for which to download files.

• token (str | None) – Optional participant token to filter uploaded files.

Returns

List with the paths of downloaded files.

Return type

list[pathlib.Path]

import_group(self, file, survey_id, file_type='lsg')

Import group from a file.

Create a new group from an exported LSG file.

TODO: Check support for custom name and description.

Parameters

• file (BinaryIO) – File object.

• survey_id (int) – The ID of the Survey that the question will belong to.

• file_type (str) – Type of file. One of LSS, CSV, TXT and LSA.

Returns

The ID of the new group.

Return type

int

import_question(self, file, survey_id, group_id)

Import question from a file.

Create a new question from an exported LSQ file.

TODO: Check support for additional fields like custom title, text, etc.

Parameters

• file (BinaryIO) – File object.

• survey_id (int) – The ID of the Survey that the question will belong to.

• group_id (int) – The ID of the Group that the question will belong to.

Returns

The ID of the new question.

Return type

int

import_survey(self, file, file_type='lss', survey_name=None, survey_id=None)

Import survey from a file.

Create a new survey from an exported LSS, CSV, TXT or LSA file.

Parameters

• file (BinaryIO) – File object.

• file_type (str) – Type of file. One of LSS, CSV, TXT and LSA.

• survey_name (str | None) – Override the new survey name.

• survey_id (int | None) – Desired ID of the new survey. A different ID will be used if there is already a survey with this ID.

Returns

The ID of the new survey.

Return type

int

list_participants(self, survey_id, *, start=0, limit=10, unused=False, attributes=False, conditions=None)

Get participants in a survey.

Parameters

• survey_id (int) – Survey to get participants from.

• start (int) – Retrieve participants starting from this index (zero-indexed).

• limit (int) – Maximum number of participants to retrieve.

• unused (bool) – Retrieve partipants with unused tokens.

• attributes (Sequence[str] | bool) – Extra participant attributes to include in the result.

• conditions (Mapping[str, Any] | None) – Dictionary of conditions to limit the list.

Returns

List of participants with basic information.

Return type

list[dict[str, Any]]

list_users(self)

Get LimeSurvey users.

Returns

List of users.

Return type

list[dict[str, Any]]

list_groups(self, survey_id, language=None)

Get the IDs and all attributes of all question groups in a Survey.

Parameters

• survey_id (int) – ID of the Survey containing the groups.

• language (str | None) – Optional parameter language for multilingual groups.

Returns

List of question groups.

Return type

list[dict[str, Any]]

list_questions(self, survey_id, group_id=None, language=None)

Get questions in a survey, in a specific group or all.

Parameters

• survey_id (int) – Survey.

• group_id (int | None) – Question group.

• language (str | None) – Retrieve question text, description, etc. in this language.

Returns

List of questions with basic information.

Return type

list[dict[str, Any]]

list_surveys(self, username=None)

Get all surveys or only those owned by a user.

Parameters

username (str | None) – Owner of the surveys to retrieve.

Returns

List of surveys with basic information.

Return type

list[dict[str, Any]]

list_survey_groups(self, username=None)

Get all survey groups or only those owned by a user.

Parameters

username (str | None) – Owner of the survey groups to retrieve.

Returns

List of survey groups with basic information.

Return type

list[dict[str, Any]]

set_group_properties(self, group_id, **properties)

Set properties of a group.

Parameters

• group_id (int) – ID of the group.

• properties (Any) – Properties to set.

Returns

Mapping of property names to whether they were set successfully.

Return type

dict[str, bool]

set_language_properties(self, survey_id, language=None, **properties)

Set properties of a survey language.

Parameters

• survey_id (int) – ID of the survey for which to set the language properties.

• language (str | None) – Language code.

• properties (Any) – Properties to set.

Returns

Mapping with status and updated properties.

Return type

dict[str, Any]

set_participant_properties(self, survey_id, token_query_properties, **token_data)

Set properties of a participant. Only one particpant can be updated.

Parameters

• survey_id (int) – ID of the survey to which the participant belongs.

• token_query_properties (Mapping[str, Any] | int) – Dictionary of properties to match the participant or token ID.

• token_data (Any) – Properties to set.

Returns

New participant properties.

Return type

dict[str, Any]

set_question_properties(self, question_id, language=None, **properties)

Set properties of a question.

Parameters

• question_id (int) – ID of the question to set the properties of.

• language (str | None) – Language code.

• properties (Any) – Properties to set.

Returns

Mapping of property names to whether they were set successfully.

Return type

dict[str, bool]

set_survey_properties(self, survey_id, **properties)

Set properties of a survey.

Parameters

• survey_id (int) – ID of the survey to set the properties of.

• properties (Any) – Properties to set.

Returns

Mapping of property names to whether they were set successfully.

Return type

dict[str, bool]

upload_file_object(self, survey_id, field, filename, file)

Upload a file to a LimeSurvey survey.

Parameters

• survey_id (int) – ID of the survey to upload the file to.

• field (str) – Field name to upload the file to.

• filename (str) – Name of the file to upload.

• file (BinaryIO) – File-like object to upload.

Returns

File metadata with final upload path.

Return type

dict[str, Any]

upload_file(self, survey_id, field, path, *, filename=None)

Upload a file to a LimeSurvey survey from a local path.

Parameters

• survey_id (int) – ID of the survey to which the file belongs.

• field (str) – Field to upload the file to.

• path (os.PathLike) – Path to the file to upload.

• filename (str | None) – Optional filename override to use in LimeSurvey.

Returns

File metadata with final upload path.

Return type

dict[str, Any]