bpresentati / citric

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.

Features

Low-level JSON-RPC API

For the full reference, see the RemoteControl 2 API docs.

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"])

Development

Use pyenv to setup default Python versions for this repo:

pyenv local 3.9.0 3.8.6 3.7.9 3.6.12

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.