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')[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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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 (typing_extensions.Unpack[citric.types.GroupProperties]) – Properties to set.
- Returns:
Mapping of property names to whether they were set successfully.
- Return type:
dict[str, bool]
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:
quota_id (int) – Quota ID.
properties (typing_extensions.Unpack[citric.types.QuotaProperties]) – Properties to set.
- Returns:
Mapping with success status and updated properties.
- Return type:
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:
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:
New in version 0.0.14.