citric#

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

Submodules#

Package Contents#

Classes#

Client

LimeSurvey Remote Control client.

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

New in version 0.3.0.

activate_survey(survey_id)[source]#

Activate a survey.

Calls RPC method activate_survey.

Parameters:

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

Returns:

Status and plugin feedback.

Return type:

citric.types.OperationStatus

New in version 0.0.1.

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]

>>> 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='')[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)[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.

Returns:

Dictionary of status message and the new survey ID.

Return type:

dict[str, Any]

New in version 0.0.10.

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) – 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) – 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) – Parameter language for multilingual questions.

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_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 (BinaryIO) – 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 (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

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.

Parameters:
  • file (BinaryIO) – 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]]

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:
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 (typing_extensions.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 (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]

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

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 (BinaryIO) – 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) – 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.