`citric`#

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

Subpackages#

_rest

LimeSurvey REST API client.

Submodules#

`_compat`	Compatibility functions and classes for different versions of LimeSurvey.
`client`	Python API Client.
`enums`	Useful enums.
`exceptions`	Common exceptions.
`method`	RPC methods.
`objects`	Python classes associated with LimeSurvey objects (surveys, questions, etc.).
`session`	Low level wrapper for connecting to the LSRC2.
`types`	Citric Python types.

Classes#

Client

LimeSurvey Remote Control client.

Package Contents#

class citric.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.

session_class[source]#

close()[source]#

Close client session.

__enter__()[source]#

Create client context.

__exit__(exc_type, exc_value, traceback)[source]#

Safely exit the client context.

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:: dict[str, Any]

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:

citric.types.OperationStatus

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:

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

New in version 0.0.1.

add_language(survey_id, language)[source]#

Add a survey language.

Calls RPC method add_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

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:

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]]

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:

int

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:

int

New in version 0.0.10.

delete_participants(survey_id, participant_ids)[source]#

Add participants to a survey.

Calls RPC method delete_participants.

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]]

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:: dict[str, citric.types.QuestionsListElement]

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:

dict[str, Any]

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

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

New in version 0.0.8.

_add_response(survey_id, response_data)[source]#

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)[source]#

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

New in version 0.0.1.

add_responses(survey_id, responses)[source]#

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]

New in version 0.0.1.

update_response(survey_id, response_data)[source]#

Update a response.

Calls RPC method update_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

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:

survey_id (int) – ID of the source survey.
name (str) – Name of the new survey.
destination_survey_id (int | None) – ID of the new survey. If already used a, random one will be generated.

Returns:

Dictionary of status message and the new survey ID.

Return type:

dict[str, Any]

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:

citric.types.CPDBParticipantImportResult

New in version 0.7.0.

delete_group(survey_id, group_id)[source]#

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

New in version 0.0.10.

delete_language(survey_id, language)[source]#

Delete a language from a survey.

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

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:: citric.types.OperationStatus

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:

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

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

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:: citric.types.OperationStatus

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:

bytes

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:

int

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:

bytes

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:

int

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:

dict[str, int]

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:

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

New in version 0.0.10.

get_language_properties(survey_id, *, settings=None, language=None)[source]#

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) – Specify language for multilingual surveys.

Returns:

Dictionary of survey language properties.

Return type:

citric.types.LanguageProperties

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:

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]

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:

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

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:

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.

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:

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]

New in version 0.0.1.

get_available_site_settings()[source]#

Get all available site settings.

Calls RPC method get_available_site_settings.

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

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

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

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

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:: list[str] | None

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

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

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:: dict[str, int]

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:

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

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:

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]]

New in version 0.0.5.

get_uploaded_file_objects(survey_id, token=None)[source]#

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.

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:

list[pathlib.Path]

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:

int

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:

file (IO[bytes]) – 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

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:

int

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:

list[dict[str, Any]]

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.

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

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:

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]]

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:

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]

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:: list[citric.types.QuotaListElement]

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:: list[dict[str, Any]]

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:: list[dict[str, Any]]

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:

dict[str, bool]

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:

dict[str, Any]

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:

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]

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:

dict[str, bool]

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:

citric.types.SetQuotaPropertiesResult

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:

dict[str, bool]

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:

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 (IO[bytes]) – File-like object to upload.

Returns:

File metadata with final upload path.

Return type:

citric.types.FileUploadResult

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:

citric.types.FileUploadResult

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:

int

New in version 0.8.0.

citric#

Subpackages#

Submodules#

Classes#

Package Contents#

`citric`#