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)

Notebook samples#