citric
#
A client to the LimeSurvey Remote Control API 2, written in modern Python.
Submodules#
Package Contents#
Classes#
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]