`citric.client`#

Python API Client.

Module Contents#

Classes#

`QuestionReference`	Uploaded file question reference.
`FileMetadata`	Uploaded file metadata.
`UploadedFile`	A file uploaded to a survey response.
`Client`	LimeSurvey Remote Control client.

Attributes#

_T

citric.client._T#

class citric.client.QuestionReference#

Uploaded file question reference.

title: str#: Question title.

qid: int#: Question ID.

class citric.client.FileMetadata#

Uploaded file metadata.

title: str#: File title.

comment: str#: File comment.

name: str#: File name.

filename: str#: LimeSurvey internal file name.

size: float#: File size in bytes.

ext: str#: File extension.

question: QuestionReference#: QuestionReference object.

index: int#: File index.

class citric.client.UploadedFile#

A file uploaded to a survey response.

meta: FileMetadata#: FileMetadata object.

content: io.BytesIO#: File content as io.BytesIO.

class citric.client.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").

property session: citric.session.Session#

Low-level RPC session.

session_class#

close()#

Close client session.

__enter__()#

Create client context.

__exit__(exc_type, exc_value, traceback)#

Safely exit the client context.

get_fieldmap(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(survey_id)#

Activate a survey.

Parameters:: survey_id (int) – ID of survey to be activated.
Returns:: Status and plugin feedback.
Return type:: citric.types.OperationStatus

activate_tokens(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:

citric.types.OperationStatus

add_language(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:

citric.types.OperationStatus

add_participants(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_quota(survey_id, name, limit, *, active=True, action=enums.QuotaAction.TERMINATE, autoload_url=False, message='', url='', url_description='')#

Add a quota to a LimeSurvey survey.

Parameters:

survey_id (int) – ID of the survey to add the quota to.
name (str) – Name of the quota.
limit (int) – Limit of the quota.
active (bool) – Whether the quota is active.
action (str) – Action to take when the limit is reached.
autoload_url (bool) – Whether to automatically load the URL.
message (str) – Message to display to the respondent when the limit is reached.
url (str) – URL to redirect the respondent to when the limit is reached.
url_description (str) – Description of the URL.

Returns:

ID of the newly created quota.

Return type:

int

New in version 0.6.0.

Warning

This method is only available in LimeSurvey >= 6.0 (currently in development).

add_survey(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 | enums.NewSurveyType) – 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(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]]

_get_question_mapping(survey_id)#

Get question mapping.

Parameters:: survey_id (int) – Survey ID.
Returns:: Question mapping.
Return type:: dict[str, citric.types.QuestionsListElement]

static _map_response_keys(response_data, question_mapping)#

Convert response keys to LimeSurvey’s internal representation.

Parameters:

response_data (Mapping[str, Any]) – The response mapping.
question_mapping (dict[str, citric.types.QuestionsListElement]) – A mapping of question titles to question dictionaries.

Returns:

A new dictionary with the keys mapped to the <SID>X<GID>X<QID> format.

Return type:

dict[str, Any]

>>> mapped_keys = Client._map_response_keys(
...     {"Q1": "foo", "Q2": "bar", "BAZ": "qux"},
...     {
...         "Q1": {
...             "title": "Q1",
...             "qid": 9,
...             "gid": 7,
...             "sid": 123,
...         },
...         "Q2": {
...             "title": "Q2",
...             "qid": 10,
...             "gid": 7,
...             "sid": 123,
...         },
...     },
... )
>>> mapped_keys
{'123X7X9': 'foo', '123X7X10': 'bar', 'BAZ': 'qux'}

add_group(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(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 from question codes of the form <SID>X<GID>X<QID> to response values.

Returns:

ID of the new response.

Return type:

int

add_response(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(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(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(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(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(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:

citric.types.OperationStatus

delete_quota(quota_id)#

Delete a LimeSurvey quota.

Parameters:: quota_id (int) – ID of the quota to delete.
Returns:: True if the quota was deleted.
Return type:: citric.types.OperationStatus

New in version 0.6.0.

Warning

This method is only available in LimeSurvey >= 6.0 (currently in development).

delete_response(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:

citric.types.OperationStatus

delete_question(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(survey_id)#

Delete a survey.

Parameters:: survey_id (int) – Survey to delete.
Returns:: Status message.
Return type:: citric.types.OperationStatus

export_responses(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 | enums.ResponsesExportFormat) – 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 | enums.SurveyCompletionStatus) – Incomplete, complete or all.
heading_type (str | enums.HeadingType) – Use response codes, long or abbreviated titles.
response_type (str | enums.ResponseType) – 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(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(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 | enums.StatisticsExportFormat) – 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(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(survey_id, period, start, end=None)#

Export survey submission timeline.

Parameters:

survey_id (int) – ID of the Survey.
period (Literal['day', 'hour'] | enums.TimelineAggregationPeriod) – 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(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:

citric.types.GroupProperties

get_language_properties(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:

citric.types.LanguageProperties

get_participant_properties(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(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:

citric.types.QuestionProperties

get_quota_properties(quota_id, settings=None, language=None)#

Get properties of a LimeSurvey quota.

Parameters:

quota_id (int) – ID of the quota to get properties for.
settings (list[str] | None) – Properties to get, default to all.
language (str | None) – Parameter language for multilingual quotas.

Returns:

Quota properties.

Return type:

citric.types.QuotaProperties

New in version 0.6.0.

Warning

This method is only available in LimeSurvey >= 6.0 (currently in development).

get_response_ids(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_available_site_settings()#

Get all available site settings.

Returns:: A list of all the available site settings.
Return type:: list[str]

New in version 0.6.0.

Warning

This method is only available in LimeSurvey >= 6.0 (currently in development).

_get_site_setting(setting_name)#

Get a global setting.

Function to query site settings. Can only be used by super administrators.

Parameters:: setting_name (str) – Name of the setting to get.
Returns:: The requested setting value.
Return type:: citric.types.Result

get_default_theme()#

Get the global default theme.

Calls get_site_settings(“defaulttheme”).

Returns:: The name of the theme.
Return type:: str

get_site_name()#

Get the site name.

Calls get_site_settings(“sitename”).

Returns:: The name of the site.
Return type:: str

get_default_language()#

Get the default site language.

Calls get_site_settings(“defaultlang”).

Returns:: A string representing the language.
Return type:: str

get_available_languages()#

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(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(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:

citric.types.SurveyProperties

get_uploaded_files(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(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(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(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 | enums.ImportGroupType) – Type of file. One of LSS, CSV, TXT and LSA.

Returns:

The ID of the new group.

Return type:

int

import_question(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(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 | enums.ImportSurveyType) – 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(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()#

Get LimeSurvey users.

Returns:: List of users.
Return type:: list[dict[str, Any]]

list_groups(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(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[citric.types.QuestionsListElement]

list_quotas(survey_id)#

Get all quotas for a LimeSurvey survey.

Parameters:: survey_id (int) – ID of the survey to get quotas for.
Returns:: List of quotas.
Return type:: list[citric.types.QuotaListElement]

New in version 0.6.0.

Warning

This method is only available in LimeSurvey >= 6.0 (currently in development).

list_surveys(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(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(group_id, **properties)#

Set properties of a group.

Parameters:

group_id (int) – ID of the group.
properties (typing_extensions.Unpack[citric.types.GroupProperties]) – Properties to set.

Returns:

Mapping of property names to whether they were set successfully.

Return type:

dict[str, bool]

set_language_properties(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 (typing_extensions.Unpack[citric.types.LanguageProperties]) – Properties to set.

Returns:

Mapping with status and updated properties.

Return type:

dict[str, Any]

set_participant_properties(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(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 (typing_extensions.Unpack[citric.types.QuestionProperties]) – Properties to set.

Returns:

Mapping of property names to whether they were set successfully.

Return type:

dict[str, bool]

set_quota_properties(quota_id, **properties)#

Set properties of a quota.

Calls RPC method set_quota_properties.

Parameters:

quota_id (int) – Quota ID.
properties (typing_extensions.Unpack[citric.types.QuotaProperties]) – Properties to set.

Returns:

Mapping with success status and updated properties.

Return type:

citric.types.SetQuotaPropertiesResult

New in version 0.6.0.

set_survey_properties(survey_id, **properties)#

Set properties of a survey.

Parameters:

survey_id (int) – ID of the survey to set the properties of.
properties (typing_extensions.Unpack[citric.types.SurveyProperties]) – Properties to set.

Returns:

Mapping of property names to whether they were set successfully.

Return type:

dict[str, bool]

upload_file_object(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:

citric.types.FileUploadResult

upload_file(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:

citric.types.FileUploadResult

citric.client#

Module Contents#

Classes#

Attributes#

`citric.client`#