citric.client
#
Python API Client.
Module Contents#
Classes#
Uploaded file question reference. |
|
Uploaded file metadata. |
|
A file uploaded to a survey response. |
|
LimeSurvey Remote Control client. |
- class citric.client.FileMetadata[source]#
Uploaded file metadata.
- question: QuestionReference[source]#
QuestionReference
object.
- class citric.client.UploadedFile[source]#
A file uploaded to a survey response.
- meta: FileMetadata[source]#
FileMetadata
object.
- content: io.BytesIO[source]#
File content as
io.BytesIO
.
- class citric.client.Client(url, username, password, *, requests_session=None, auth_plugin='Authdb')[source]#
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"
).
New in version 0.0.6: Support Auth plugins with the
auth_plugin
parameter.- property session: citric.session.Session[source]#
Low-level RPC session.
- get_fieldmap(survey_id)[source]#
Get fieldmap for a survey.
Calls RPC method get_fieldmap.
- Parameters:
survey_id (int) – ID of survey to get fieldmap for.
- Returns:
Dictionary mapping response keys to LimeSurvey internal representation.
- Return type:
New in version 0.3.0.
- activate_survey(survey_id, *, user_activation_settings=None)[source]#
Activate a survey.
Calls RPC method activate_survey.
- Parameters:
survey_id (int) – ID of survey to be activated.
user_activation_settings (citric.types.SurveyUserActivationSettings | None) – Optional user activation settings.
- Returns:
Status and plugin feedback.
- Return type:
New in version 0.0.1.
Changed in version 0.10.0: The
user_activation_settings
optional parameter was added.
- activate_tokens(survey_id, attributes=None)[source]#
Initialise the survey participant table.
New participant tokens may be later added.
Calls RPC method activate_tokens.
- Parameters:
- Returns:
Status message.
- Return type:
New in version 0.0.1.
- add_language(survey_id, language)[source]#
Add a survey language.
Calls RPC method add_language.
- Parameters:
- Returns:
Status message.
- Return type:
New in version 0.0.10.
- add_participants(survey_id, *, participant_data, create_tokens=True)[source]#
Add participants to a survey.
Calls RPC method add_participants.
- Parameters:
- Returns:
Information of newly created participants.
- Return type:
New in version 0.0.1.
Changed in version 0.4.0: Use keyword-only arguments.
- add_quota(survey_id, name, limit, *, active=True, action=enums.QuotaAction.TERMINATE, autoload_url=False, message='', url='', url_description='')[source]#
Add a quota to a LimeSurvey survey.
Calls RPC method add_quota.
- 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:
New in version 0.6.0.
Note
This method is only supported in LimeSurvey >= 6.0.0.
- add_survey(survey_id, title, language, survey_format='G')[source]#
Add a new empty survey.
Calls RPC method add_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 | citric.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:
New in version 0.0.10.
- delete_participants(survey_id, participant_ids)[source]#
Add participants to a survey.
Calls RPC method delete_participants.
- Parameters:
- Returns:
Information of removed participants.
- Return type:
New in version 0.0.1.
- _get_question_mapping(survey_id)[source]#
Get question mapping.
- Parameters:
survey_id (int) – Survey ID.
- Returns:
Question mapping.
- Return type:
- static _map_response_keys(response_data, question_mapping)[source]#
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:
>>> 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} >>> questions = {"Q1": q1, "Q2": q2} >>> mapped_keys = Client._map_response_keys(keys, questions) >>> mapped_keys {'123X7X9': 'foo', '123X7X10': 'bar', 'BAZ': 'qux'}
- add_group(survey_id, title, description='')[source]#
Add a new empty question group to a survey.
Calls RPC method add_group.
- Parameters:
- Returns:
The id of the new group.
- Return type:
New in version 0.0.8.
- add_response(survey_id, response_data)[source]#
Add a single response to a survey.
- Parameters:
- Returns:
ID of the new response.
- Return type:
New in version 0.0.1.
- add_responses(survey_id, responses)[source]#
Add multiple responses to a survey.
- Parameters:
- Returns:
IDs of the new responses.
- Return type:
New in version 0.0.1.
- update_response(survey_id, response_data)[source]#
Update a response.
Calls RPC method update_response.
- Parameters:
- Returns:
True if the response was updated, False otherwise.
- Return type:
New in version 0.2.0.
- copy_survey(survey_id, name, *, destination_survey_id=None)[source]#
Copy a survey.
Calls RPC method copy_survey.
- Parameters:
- Returns:
Dictionary of status message and the new survey ID.
- Return type:
New in version 0.0.10.
Changed in version 0.10.0: The
destination_survey_id
optional parameter was added.Warning
The parameter destination_survey_id is only supported in LimeSurvey >= 6.4.0.
- import_cpdb_participants(participants, *, update=False)[source]#
Import CPDB participants.
Calls RPC method cpd_importParticipants.
- Parameters:
participants (Sequence[citric.objects.Participant]) – CPDB participant data.
update (bool) – Whether to update existing participants.
- Returns:
IDs of the new participants.
- Return type:
New in version 0.7.0.
- delete_group(survey_id, group_id)[source]#
Delete a group.
- Parameters:
- Returns:
ID of the deleted group.
- Return type:
New in version 0.0.10.
- delete_language(survey_id, language)[source]#
Delete a language from a survey.
- Parameters:
- Returns:
Status message.
- Return type:
New in version 0.0.12.
Note
This method is only supported in LimeSurvey >= 5.3.4.
- delete_quota(quota_id)[source]#
Delete a LimeSurvey quota.
Calls RPC method delete_quota.
- Parameters:
quota_id (int) – ID of the quota to delete.
- Returns:
True if the quota was deleted.
- Return type:
New in version 0.6.0.
Note
This method is only supported in LimeSurvey >= 6.0.0.
- delete_response(survey_id, response_id)[source]#
Delete a response in a survey.
- Parameters:
- Returns:
Status message.
- Return type:
New in version 0.0.2.
- delete_question(question_id)[source]#
Delete a survey.
Calls RPC method delete_question.
- Parameters:
question_id (int) – ID of Question to delete.
- Returns:
ID of the deleted question.
- Return type:
New in version 0.1.0.
Note
This method is only supported in LimeSurvey >= 5.3.19.
- delete_survey(survey_id)[source]#
Delete a survey.
Calls RPC method delete_survey.
- Parameters:
survey_id (int) – Survey to delete.
- Returns:
Status message.
- Return type:
New in version 0.0.1.
- 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)[source]#
Export responses to a file-like object.
Calls RPC method export_responses.
- Parameters:
survey_id (int) – Survey to add the response to.
token (str | None) – Optional participant token to get responses for.
file_format (str | citric.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 | citric.enums.SurveyCompletionStatus) – Incomplete, complete or all.
heading_type (str | citric.enums.HeadingType) – Use response codes, long or abbreviated titles.
response_type (str | citric.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:
New in version 0.0.1.
Changed in version 0.0.2: Return raw bytes instead of number of bytes written.
- 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)[source]#
Save responses to a file.
- Parameters:
filename (os.PathLike[str]) – 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:
New in version 0.0.10.
- export_statistics(survey_id, *, file_format='pdf', language=None, graph=False, group_ids=None)[source]#
Export survey statistics.
Calls RPC method export_statistics.
- Parameters:
survey_id (int) – ID of the Survey.
file_format (str | citric.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:
New in version 0.0.10.
- save_statistics(filename, survey_id, *, file_format='pdf', language=None, graph=False, group_ids=None)[source]#
Save survey statistics to a file.
- Parameters:
filename (os.PathLike[str]) – 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:
- export_timeline(survey_id, period, start, end=None)[source]#
Export survey submission timeline.
Calls RPC method export_timeline.
- Parameters:
survey_id (int) – ID of the Survey.
period (Literal[day, hour] | citric.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:
New in version 0.0.10.
- get_group_properties(group_id, *, settings=None, language=None)[source]#
Get the properties of a group of a survey.
Calls RPC method get_group_properties.
- Parameters:
- Returns:
Dictionary of group properties.
- Return type:
New in version 0.0.10.
- get_language_properties(survey_id, *, settings=None, language=None)[source]#
Get survey language properties.
- Parameters:
- Returns:
Dictionary of survey language properties.
- Return type:
New in version 0.0.10.
- get_participant_properties(survey_id, query, properties=None)[source]#
Get properties a single survey participant.
Calls RPC method get_participant_properties.
- Parameters:
- Returns:
List of participants properties.
- Return type:
New in version 0.0.1.
- get_question_properties(question_id, *, settings=None, language=None)[source]#
Get properties of a question in a survey.
Calls RPC method get_question_properties.
- Parameters:
- Returns:
Dictionary of question properties.
- Return type:
New in version 0.0.10.
- get_quota_properties(quota_id, settings=None, language=None)[source]#
Get properties of a LimeSurvey quota.
Calls RPC method get_quota_properties.
- Parameters:
- Returns:
Quota properties.
- Return type:
New in version 0.6.0.
Note
This method is only supported in LimeSurvey >= 6.0.0.
- get_response_ids(survey_id, token)[source]#
Find response IDs given a survey ID and a token.
Calls RPC method get_response_ids.
- Parameters:
- Returns:
A list of response IDs.
- Return type:
New in version 0.0.1.
- get_available_site_settings()[source]#
Get all available site settings.
Calls RPC method get_available_site_settings.
New in version 0.6.0.
Note
This method is only supported in LimeSurvey >= 6.0.0.
- _get_site_setting(setting_name)[source]#
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
New in version 0.0.1.
- get_default_theme()[source]#
Get the global default theme.
Calls get_site_settings(“defaulttheme”).
- Returns:
The name of the theme.
- Return type:
New in version 0.0.1.
- get_site_name()[source]#
Get the site name.
Calls get_site_settings(“sitename”).
- Returns:
The name of the site.
- Return type:
New in version 0.0.1.
- get_default_language()[source]#
Get the default site language.
Calls get_site_settings(“defaultlang”).
- Returns:
A string representing the language.
- Return type:
New in version 0.0.1.
- get_available_languages()[source]#
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:
New in version 0.0.1.
- get_server_version()[source]#
Get the server version.
Calls get_site_settings(“versionnumber”).
- Returns:
The LimeSurvey server version.
- Return type:
New in version 0.9.0.
- get_db_version()[source]#
Get the LimeSurvey database version.
Calls get_site_settings(“dbversionnumber”).
- Returns:
The LimeSurvey database version.
- Return type:
New in version 1.0.0.
- get_summary(survey_id)[source]#
Get survey summary.
Calls RPC method get_summary.
- Parameters:
survey_id (int) – ID of the survey to get summary of.
- Returns:
Mapping of survey statistics.
- Return type:
New in version 0.0.10.
- get_survey_properties(survey_id, properties=None)[source]#
Get properties of a survey.
Calls RPC method get_survey_properties.
- Parameters:
- Returns:
Dictionary of survey properties.
- Return type:
New in version 0.0.1.
- get_uploaded_files(survey_id, token=None)[source]#
Get a dictionary of files uploaded in a survey response.
Calls RPC method get_uploaded_files.
- Parameters:
- Returns:
Dictionary with uploaded files metadata.
- Return type:
New in version 0.0.5.
- get_uploaded_file_objects(survey_id, token=None)[source]#
Iterate over uploaded files in a survey response.
- Parameters:
- Yields:
UploadedFile
objects.
New in version 0.0.13.
- download_files(directory, survey_id, token=None)[source]#
Download files uploaded in survey response.
- Parameters:
directory (str | pathlib.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:
New in version 0.0.1.
- import_group(file, survey_id, file_type='lsg')[source]#
Import group from a file.
Create a new group from an exported LSG file.
TODO: Check support for custom name and description.
Calls RPC method import_group.
- Parameters:
file (IO[bytes]) – File object.
survey_id (int) – The ID of the Survey that the question will belong to.
file_type (str | citric.enums.ImportGroupType) – Type of file. One of LSS, CSV, TXT and LSA.
- Returns:
The ID of the new group.
- Return type:
New in version 0.0.10.
- import_question(file, survey_id, group_id)[source]#
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.
Calls RPC method import_question.
- Parameters:
- Returns:
The ID of the new question.
- Return type:
New in version 0.0.8.
- import_survey(file, file_type='lss', survey_name=None, survey_id=None)[source]#
Import survey from a file.
Create a new survey from an exported LSS, CSV, TXT or LSA file.
Calls RPC method import_survey.
Warning
Different versions of LimeSurvey seem to expect slightly different structures for exported files. If you get errors when importing a survey, try importing it manually in the LimeSurvey web interface. If it works, try exporting it from the web interface and importing the new file. If it still doesn’t work, you might need to import it with a different version of LimeSurvey.
- Parameters:
file (IO[bytes]) – File object.
file_type (str | citric.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:
New in version 0.0.1.
Changed in version 0.0.5: Accept a binary file object instead of a path.
- list_participants(survey_id, *, start=0, limit=10, unused=False, attributes=False, conditions=None)[source]#
Get participants in a survey.
Calls RPC method list_participants.
- 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 participants 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:
Some valid participant attributes are:
tid
participant_id
firstname
lastname
email
emailstatus
token
language
blacklisted
sent
remindersent
remindercount
completed
usesleft
validfrom
validuntil
New in version 0.0.1.
Changed in version 0.4.0: Use keyword-only arguments.
- list_users()[source]#
Get LimeSurvey users.
Calls RPC method list_users.
New in version 0.0.3.
- list_groups(survey_id, language=None)[source]#
Get the IDs and all attributes of all question groups in a Survey.
Calls RPC method list_groups.
- Parameters:
- Returns:
List of question groups.
- Return type:
New in version 0.0.10.
- list_questions(survey_id, group_id=None, language=None)[source]#
Get questions in a survey, in a specific group or all.
Calls RPC method list_questions.
- Parameters:
- Returns:
List of questions with basic information.
- Return type:
New in version 0.0.1.
- list_quotas(survey_id)[source]#
Get all quotas for a LimeSurvey survey.
Calls RPC method list_quotas.
- Parameters:
survey_id (int) – ID of the survey to get quotas for.
- Returns:
List of quotas.
- Return type:
New in version 0.6.0.
Note
This method is only supported in LimeSurvey >= 6.0.0.
- list_surveys(username=None)[source]#
Get all surveys or only those owned by a user.
Calls RPC method list_surveys.
- Parameters:
username (str | None) – Owner of the surveys to retrieve.
- Returns:
List of surveys with basic information.
- Return type:
New in version 0.0.1.
- list_survey_groups(username=None)[source]#
Get all survey groups or only those owned by a user.
Calls RPC method list_survey_groups.
- Parameters:
username (str | None) – Owner of the survey groups to retrieve.
- Returns:
List of survey groups with basic information.
- Return type:
New in version 0.0.2.
- set_group_properties(group_id, **properties)[source]#
Set properties of a group.
Calls RPC method set_group_properties.
- Parameters:
group_id (int) – ID of the group.
properties (Unpack[citric.types.GroupProperties]) – Properties to set.
- Returns:
Mapping of property names to whether they were set successfully.
- Return type:
New in version 0.0.11.
- set_language_properties(survey_id, language=None, **properties)[source]#
Set properties of a survey language.
Calls RPC method set_language_properties.
- Parameters:
survey_id (int) – ID of the survey for which to set the language properties.
language (str | None) – Language code.
properties (Unpack[citric.types.LanguageProperties]) – Properties to set.
- Returns:
Mapping with status and updated properties.
- Return type:
New in version 0.0.11.
- set_participant_properties(survey_id, token_query_properties, **token_data)[source]#
Set properties of a participant. Only one participant can be updated.
Calls RPC method set_participant_properties.
- Parameters:
- Returns:
New participant properties.
- Return type:
New in version 0.0.11.
- set_question_properties(question_id, language=None, **properties)[source]#
Set properties of a question.
- Parameters:
question_id (int) – ID of the question to set the properties of.
language (str | None) – Language code.
properties (Unpack[citric.types.QuestionProperties]) – Properties to set.
- Returns:
Mapping of property names to whether they were set successfully.
- Return type:
New in version 0.0.11.
- set_quota_properties(quota_id, **properties)[source]#
Set properties of a quota.
Calls RPC method set_quota_properties.
- Parameters:
quota_id (int) – Quota ID.
properties (Unpack[citric.types.QuotaProperties]) – Properties to set.
- Returns:
Mapping with success status and updated properties.
- Return type:
New in version 0.6.0.
- set_survey_properties(survey_id, **properties)[source]#
Set properties of a survey.
Calls RPC method set_survey_properties.
- Parameters:
survey_id (int) – ID of the survey to set the properties of.
properties (Unpack[citric.types.SurveyProperties]) – Properties to set.
- Returns:
Mapping of property names to whether they were set successfully.
- Return type:
New in version 0.0.11.
- upload_file_object(survey_id, field, filename, file)[source]#
Upload a file to a LimeSurvey survey.
Calls RPC method upload_file.
- Parameters:
- Returns:
File metadata with final upload path.
- Return type:
New in version 0.0.14.
- upload_file(survey_id, field, path, *, filename=None)[source]#
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[str]) – 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:
New in version 0.0.14.
- invite_participants(survey_id, *, token_ids=None, strategy=enums.EmailSendStrategy.PENDING)[source]#
Invite participants to a survey.
Calls RPC method invite_participants.
- Parameters:
survey_id (int) – ID of the survey to invite participants to.
token_ids (list[int] | None) – IDs of the participants to invite.
strategy (int) – Strategy to use for sending emails. See
EmailSendStrategy
.
- Returns:
Number of emails left to send.
- Raises:
LimeSurveyStatusError – If the number of emails left to send could not be determined.
RuntimeError – If an unexpected error occurs.
- Return type:
New in version 0.8.0.