Metadata-Version: 2.1
Name: qualtrutils
Version: 0.1.5
Summary: A simple package to interact with the Qualtrics API
Home-page: https://github.com/emanuele-albini/qualtrutils
Author: Emanuele Albini
License: UNKNOWN
Project-URL: Documentation, https://emanuele-albini.github.io/qualtrutils
Project-URL: Source Code, https://github.com/emanuele-albini/qualtrutils
Project-URL: Bug Tracker, https://github.com/emanuele-albini/qualtrutils/issues
Project-URL: Author Website, https://www.emanuelealbini.com
Keywords: Qualtrics,API,surveys,survey
Platform: any
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

# QualtrUtils - A package to create questions from templates with Qualtrics (v3) API

[![PyPI pyversions](https://img.shields.io/pypi/pyversions/qualtrutils.svg)](https://pypi.python.org/pypi/qualtrutils/)
[![GitHub license](https://img.shields.io/github/license/Naereen/StrapDown.js.svg)](https://github.com/emanuele-albini/qualtrutils/blob/master/LICENSE)
[![PyPI](https://badge.fury.io/py/qualtrutils.svg)](https://pypi.python.org/pypi/qualtrutils/)
[![Maintaner](https://img.shields.io/badge/maintainer-Emanuele-lightgrey)](https://www.emanuelealbini.com)
[![Tests](https://github.com/emanuele-albini/qualtrutils/actions/workflows/tests.yml/badge.svg)](https://github.com/emanuele-albini/qualtrutils/actions/workflows/tests.yml)
[![Release](https://github.com/emanuele-albini/qualtrutils/actions/workflows/release.yml/badge.svg)](https://github.com/emanuele-albini/qualtrutils/actions/workflows/release.yml)

This package allows the creation of questions based on an existing template (i.e., a question created with the Qualtrics interface. The operations that this package supports are:

- Creating block
- Copying an existing question
- Replacing keywords
- Changing multiple choice answers
- Changing the initial position of the slider
- Changing a question JS code

## Installation

Using PIP:

```bash
pip install qualtrutils
```

Using CONDA:

```bash
conda install -c emanuele-albini qualtrutils
```

#### For developers

To use the package in editable mode use instead the following.

```bash
git clone https://github.com/emanuele-albini/qualtrutils.git
pip install --editable qualtrutils
```

## Configuration (optional)

Global configuration is in `~\.qualtrutils\qualtrics.toml`. Example:

```toml
API_URL = "https://yourdatacenter.qualtrics.com/API/v3/"
API_TOKEN = "your_token"
LIBRARY_ID = "UR_XXXXXXXXXXXXX"
SURVEY_ID = "SV_XXXXXXXXXXXXX"
```

The configuration saved in `~\.qualtrutils\qualtrics.toml` will be used as default in `QualtricsSurvey` constructor.

This configuration it's optional, the settigs can be directly passed to `QualtricsSurvey` at runtime.

## Usage example

```python
from qualtrutils import QualtricsSurvey

survey = QualtricsSurvey()

# Get a question from an existing survey
question = survey.get_question_by_name('QuestionName', 'MyNewQuestion')

# The following will replace (using regex) all the occurences
# of 'SOMETHING' in the question text and multiples choice answers (if any)
# with 'SOMETHING_ELSE'
question.text_sub('SOMETHING', 'SOMETHING_ELSE')

# The following will set the multiple choice answers
question.set_choices(['First Answer', 'Second Answer', 'Third Answer'])

# The flowwing will set the Javascript code of the question
question.set_js('var hello = 1;')

# Add this new question to the survey in a block called 'Block A'
# If the block does not exists it will be created
survey.create_question(question, 'Block A')
```

## Documentation

See [here](https://emanuele-albini.github.io/qualtrutils) for the complete documentation with all the functionalities.


