How-to Guide#
For the full JSON-RPC reference, see the RemoteControl 2 API docs.
Automatically close the session with a context manager#
from citric import Client
LS_URL = "http://localhost:8001/index.php/admin/remotecontrol"
with Client(LS_URL, "iamadmin", "secret") as client:
# Do stuff with the client
...
Otherwise, you can manually close the session with client.close()
.
Get surveys and questions#
from citric import Client
LS_URL = "http://localhost:8001/index.php/admin/remotecontrol"
client = Client(LS_URL, "iamadmin", "secret")
# Get all surveys from user "iamadmin"
surveys = client.list_surveys("iamadmin")
for s in surveys:
print(s["surveyls_title"])
# Get all questions, regardless of group
questions = client.list_questions(s["sid"])
for q in questions:
print(q["title"], q["question"])
Export responses to a pandas
dataframe#
import io
import pandas as pd
from citric import Client
survey_id = 123456
client = Client(
"https://mylimeserver.com/index.php/admin/remotecontrol",
"iamadmin",
"secret",
)
# Export responses to CSV and read into a Pandas DataFrame
df = pd.read_csv(
io.BytesIO(client.export_responses(survey_id, file_format="csv")),
delimiter=";",
parse_dates=["datestamp", "startdate", "submitdate"],
index_col="id",
)
Export responses to a DuckDB database and analyze with SQL#
import citric
import duckdb
client = citric.Client(
"https://mylimeserver.com/index.php/admin/remotecontrol",
"iamadmin",
"secret",
)
with open("responses.csv", "wb") as file:
file.write(client.export_responses(12345, file_format="csv"))
duckdb.execute("CREATE TABLE responses AS SELECT * FROM 'responses.csv'")
duckdb.sql("""
SELECT
token,
submitdate - startdate AS duration
FROM responses
ORDER BY 2 DESC
LIMIT 10
""").show()
Change the default HTTP session attributes#
import requests
from citric import Client
session = requests.Session()
# Set to False to accept any TLS certificate presented by the server
# https://requests.readthedocs.io/en/latest/api/#requests.Session.verify
session.verify = False
client = Client(
"https://mylimeserver.com/index.php/admin/remotecontrol",
"iamadmin",
"secret",
requests_session=session,
)
Use a custom requests
session#
It’s possible to use a custom session object to make requests. For example, to cache the requests
and reduce the load on your server in read-intensive applications, you can use
requests-cache
:
import requests_cache
from citric import Client
cached_session = requests_cache.CachedSession(
expire_after=60,
allowable_methods=["POST"],
)
client = Client(
"https://example.com/index.php/admin/remotecontrol",
"iamadmin",
"secret",
requests_session=cached_session,
)
# Get all surveys from user "iamadmin".
# All responses will be cached for 1 minute.
surveys = client.list_surveys("iamadmin")
Use a different authentication plugin#
By default, this client uses the internal database for authentication but
different plugins are supported using the
auth_plugin
argument.
from citric import Client
client = Client(
"https://example.com/index.php/admin/remotecontrol",
"iamadmin",
"secret",
auth_plugin="AuthLDAP",
)
Common plugins are Authdb
(default), AuthLDAP
and Authwebserver
.
Get files uploaded to a survey and move them to S3#
import boto3
from citric import Client
s3 = boto3.client("s3")
client = Client(
"https://mylimeserver.com/index.php/admin/remotecontrol",
"iamadmin",
"secret",
)
survey_id = 12345
# Get all uploaded files and upload them to S3
for file in client.get_uploaded_file_objects(survey_id):
s3.upload_fileobj(
file.content,
"my-s3-bucket",
f"uploads/sid={survey_id}/qid={file.meta.question.qid}/{file.meta.filename}",
)
Use the session attribute for low-level interaction#
This library doesn’t implement all RPC methods, so if you’re in dire need of using a method not currently supported, you can use the session
attribute to invoke the underlying RPC interface without having to pass a session key explicitly:
client = Client(
"https://mylimeserver.com/index.php/admin/remotecontrol",
"iamadmin",
"secret",
)
# Get the raw response from mail_registered_participants
result = client.session.call("mail_registered_participants", 35239)
# Get the raw response from remind_participants
result = client.session.call("remind_participants", 35239)