citric 0.0.4

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

Citric

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

Installation

$ pip install citric

Usage

from citric import Client

LS_URL = "http://localhost:8001/index.php/admin/remotecontrol"

with Client(LS_URL, "iamadmin", "secret") as client:
    # 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"])

Or more interestingly, export responses to a pandas dataframe:

import io
import pandas as pd

survey_id = 123456

df = pd.read_csv(
    io.BytesIO(client.export_responses(survey_id, file_format="csv")),
    delimiter=";",
    parse_dates=["datestamp", "startdate", "submitdate"],
    index_col="id",
)

It's possible to use a different session factory to make requests. For example, to cache the requests and reduce the load on your server in read-intensive applications, you can use request_cache:

import requests_cache

cached_session = requests_cache.CachedSession(
    expire_after=3600,
    allowable_methods=["POST"],
)

with Client(
    LS_URL,
    "iamadmin",
    "secret",
    requests_session=cached_session,
) as client:

    # Get all surveys from user "iamadmin"
    surveys = client.list_surveys("iamadmin")

    # This should hit the cache. Running the method in a new client context will
    # not hit the cache because the RPC session key would be different.
    surveys = client.list_surveys("iamadmin")

For the full JSON-RPC reference, see the RemoteControl 2 API docs.

Development

Use pyenv to setup default Python versions for this repo:

pyenv local 3.10.0 3.9.7 3.8.11 3.7.11 3.6.14

Install project dependencies

poetry install

Docker

You can setup a local instance of LimeSurvey with Docker Compose:

docker-compose up -d

Now you can access LimeSurvey at port 8001.

Import an existing survey file and start testing with it:

from citric import Client

LS_URL = "http://localhost:8001/index.php/admin/remotecontrol"
SURVEY_FILE = "examples/limesurvey_survey_432535.lss"

with Client(LS_URL, "iamadmin", "secret") as client:
    # Import survey from a file
    survey_id = client.import_survey(SURVEY_FILE, "lss")
    print("New survey:", survey_id)

Testing

This project uses nox for running tests and linting on different Python versions:

pip install --user --upgrade nox
nox -r

Run only a linting session

nox -rs lint

pre-commit

pip install --user --upgrade pre-commit
pre-commit install

Releasing an upgrade

Bump the package version

poetry version <version>
poetry publish

Credits

• Claudio Jolowicz and his amazing blog post.

License