quizzable

quizzable provides an easy-to-implement interface to build a framework for educational quiz apps built on top of Python. The quizzable library allows you to create quizzes consisting of MCQ, FRQ, True-or-false, or Matching questions, allowing you to build educational apps that leverage the power of Python with great ease. The full documentation is described below.

Quickstart

To get started, install the quizzable package through pip on a supported version of Python (quizzable currently supports Python 3.9+):

$ python -m pip install quizzable

Next, import the Terms class from the quizzable module:

from quizzable import Terms

Then, create a list of terms:

data = {
    "painter": "la pintura",
    "brush": "el pincel",
    "sculpture": "la escultura",
    "palette:": "la paleta",
    "self-portrait": "el autorretrato",
    "abstract": "abstracto/a",
    # more terms...
}
terms = Terms(data)

or create one from JSON data:

import json

with open("vocabulary.json") as terms_file:
    terms = Terms(json.loads(terms_file.read()))

Aftewards, you can choose to generate random types of questions using the get_random_question method:

question = terms.get_random_question()

generate an entire quiz of questions using the get_quiz method:

quiz = terms.get_quiz(
    types=["mcq", "match", "tf"],
    prompt="What is the translation of {term}?",
)  # customize question types and prompt

Or create different types of questions manually like so:

frq = terms.get_frq_question()  # free-response
mcq = terms.get_mcq_question()  # multiple-choice
tf = terms.get_true_false_question()  # true-or-false
matching = terms.get_frq_question()  # matching

A question has different properties, depending on its type:

print(mcq.prompt)
for option in mcq.options:
    print(option)
print()
answer = input("Answer: ")

To score a question, simply use its check_answer method:

correct, actual = mcq.check_answer(answer)
if correct:
    print("Correct!")
else:
    print(f"Incorrect...the answer was {actual}")

If you'd like, you can convert a question or quiz to back to its raw data at any time:

print(question.to_dict())
print(quiz.to_data())

Classes

`Terms`

A list of terms.

Should be a dictionary mapping terms to definitions, where in this case a term represents a question or vocabulary term, and a definition is used to refer to the answer or vocabulary definition. For example, here is a list of terms in which each term is an English word, and its definition is its English translation:

{
    "painter": "la pintura",
    "brush": "el pincel",
    "sculpture": "la escultura",
    "palette:": "la paleta",
    "self-portrait": "el autorretrato",
    "abstract": "abstracto/a"
}

`Terms.get_terms()`

Parameters:

answer_with = "def": can be "term", "def", or "both"; how the question should be answered (see Functions)

Returns the dictionary terms modified based on the value for answer_with. May be useful for making flashcards for which terms and definitions may need to be swapped on-demand.

`Terms.get_frq_question()`

Returns an FRQQuestion object with a random FRQ-format question generated from terms.

Parameters:

prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)

`Terms.get_mcq_question()`

Parameters:

n_options = 4: number of options per question.
prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)

Returns an MCQQuestion object with a random MCQ-format question generated from terms.

`Terms.get_true_false_question()`

Returns a TrueFalseQuestion object with a random True-or-false format question generated from terms.

Parameters:

prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)

`Terms.get_match_question()`

Parameters:

n_terms = 5: how many terms have to be matched
prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)

Returns a MatchQuestion object with a random matching-format question generated from terms.

`Terms.get_random_question()`

Parameters:

types = ["mcq", "frq", "tf"]: list that can contain "mcq", "frq", "tf", or "match"; types of questions that appear on the quiz
n_options = 4: (if MCQs are involved) number of options per MCQ question
n_terms = 5: (if matching questions are involved) number of terms to match per matching question
prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)
prompts = {}: prompt map to define specific prompts for specific questions

Returns a Question object of a random-format question generated from terms.

`Terms.get_quiz()`

Returns a Quiz object with random questions based on the below parameters.

Parameters:

terms: map of terms and definitions for quiz (see Terms)
types = ["mcq", "frq", "tf"]: list that can contain "mcq", "frq", "tf", or "match"; types of questions that appear on the quiz
length = 10: number of questions on quiz
answer_with = "def": can be "term", "def", or "both"; how the question should be answered (see below)
n_options = 4: (if MCQs are involved) number of options per MCQ question
n_terms = 5: (if matching questions are involved) number of terms to match per matching question
prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)
prompts = {}: prompt map to define specific prompts for specific questions

answer_with describes how the user should answer the question, where "term" means a question should be answered by giving the term, "def" implies that the question should be answered by providing the definition, and "both" means that there is a 50/50 chance of the question needing a term or a definition as input.

`Quiz`

Arbitrary quiz object.

`Quiz.questions`

List of questions within the quiz, represented by a list of arbitrary Question objects.

`Quiz.from_data()`

Reconstructs a Quiz object from a listlike representation. See Quiz.to_data() for more information on formatting.

`Quiz.to_data()`

Returns a listlike representation of the quiz, with each Question object being represented as its dictionary representation. For example, it could look like this:

[
    {
        "_type": "tf",
        "term": "la iglesia",
        "definition": "shop",
        "answer": "church",
        "prompt": "la iglesia"
    },
    {
        "_type": "mcq",
        "term": "la playa",
        "options": {
            "beach": True,
            "park": False,
            "downtown": False,
            "museum": False,
        },
        "prompt": "la playa"
    },
    {
        "_type": "frq",
        "term": "park",
        "answer": "el parque",
        "prompt": "park"
    }
]

Please see documentation for MCQQuestion, FRQQuestion, TrueFalseQuestion, and MatchQuestion for more information on the format of the above questions.

`Question`

Generic question object used for reconstruction of a question from JSON data.

Parameters:

_type: question type
term: question term
answer: question answer
prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)
**kwargs: other question data (e.g. options, definition, etc.)

`Question.term`

Term that the question is based on.

`Question.answer`

Correct answer to the prompt term.

`Question.prompt`

Prompt displayed to the user.

`Question.from_dict()`

Returns a reconstructed Question object made from data. Please see MCQQuestion.to_dict(), FRQQuestion.to_dict(), TrueFalseQuestion.to_dict(), and MatchQuestion.to_dict() for more information on formatting.

Parameters:

data: dictionary containing question data.

`Question.check_answer()`

Returns a tuple: the first item is a boolean whose value is True if answer matches the question's answer attribute or False otherwise, and the second item is the value for the question's answer attribute.

Parameters:

answer: answer provided by the user

`Question.to_dict()`

Returns a dictionary representation of the question. Each question has a _type key that can be used to determine how to render a question on the frontend (i.e. display multiple options for MCQ, textbox for FRQ, etc.), and a term key which represents the term the user is prompted with. Please see MCQQuestion.to_dict(), FRQQuestion.to_dict(), TrueFalseQuestion.to_dict(), and MatchQuestion.to_dict() for more information on formatting.

`MCQQuestion`

Representation of an MCQ-format question. Has the same attributes as Question objects, with some additional properties.

Parameters:

term: question term
options: question options
answer: question answer
prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)

`MCQQuestion.options`

List of potential answer choices.

`MCQQuestion.to_dict()`

The dictionary representation returned by the to_dict method of a MCQQuestion object looks like this:

{
    "_type": "mcq",
    "term": "term",
    "options": {
        "option1": False,
        "option2": False,
        "option3": True,
        "option4": False,
    },
    "answer": "answer"
}

Here's a brief overview:

term is what the user will be prompted with, whether that be to choose a term's definition or vice/versa.
options is the list of potential answer choices.
answer is correct choice out of options.

`FRQQuestion`

Representation of an FRQ-format question. Has the same attributes as Question objects, with some additional properties.

Parameters:

term: question term
answer: question answer
prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)

`FRQQuestion.to_dict()`

The dictionary representation returned by the to_dict method of a FRQQuestion object looks like this:

{
    "_type": "frq",
    "term": "term",
    "answer": "answer"
}

Here's a brief overview:

term is what the user will be prompted with, whether that be to define a term's definition or vice/versa.
answer is the response that will be accepted as correct given the user's prompt.

`TrueFalseQuestion`

Representation of an True-or-false format question. Has the same attributes as Question objects, with the some additional properties.

Parameters:

term: question term
definition: question definition (what the user has to determine is True or False)
answer: question answer
prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)

`TrueFalseQuestion.definition`

What the user has to determine is True or False.

`TrueFalseQuestion.to_dict()`

The dictionary representation returned by the to_dict method of a TrueFalseQuestion object looks like this:

{
    "_type": "tf",
    "term": "term",
    "definition": "definition",
    "answer": "answer"
}

Here's a brief overview:

term is what the user will be prompted with, whether that be to select True or False if the definition given matches with a specific term, or vice/versa.
definition is what the user has to determine is True or False.
answer is the actual definition that matches with the given prompt, or term.

`MatchQuestion`

Representation of an MCQ-format question. Has the same attributes as Question objects, with the some additional properties.

Parameters:

term: question term
definitions: question definitions (what the user has to match with the terms)
answer: question answer
prompt = "{term}": question prompt (use "{term}" to reference question term in custom prompts)

`MatchQuestion.definitions`

What the user has to match with the corresponding terms.

`MatchQuestion.to_dict()`

The dictionary representation returned by the to_dict method of a MatchQuestion object looks like this:

{
    "_type": "match",
    "term": [
        "term1",
        "term2",
        "term3",
        "term4"
    ],
    "definitions": [
        "definition4",
        "definition2",
        "definition1",
        "definition3",
    ],
    "answer": {
        "term1": "definition1",
        "term2": "definition2",
        "term3": "definition3",
        "term4": "definition4"
    }
}

Here's a brief overview:

term is what the user will be prompted with, whether that be to match the term with the definition, or vice/versa.
definitions is what the user has to match with the corresponding terms.
answer maps the terms term to their actual definitions definitions.

Exceptions

`BaseQuizzableException`

The base exception for all quizzable errors.

`InvalidLengthError`

The length specified is not valid (i.e. too short or too long)

Parameters:

length: invalid length of the quiz

`InvalidOptionsError`

The number of options (for MCQs) specified is not valid (i.e. too small or too large)

Parameters:

n_options: invalid number of options per MCQ question

`InvalidTermsError`

The number of terms (for matching questions) specified is not valid (i.e. too small or too large)

Parameters:

n_terms: invalid number of terms per matching question

`InvalidQuestionError`

The type of question specified is not valid (should only be "mcq", "frq", "tf", or "match").

Parameters:

question: invalid type of question

`DataIncompleteError`

The data passed into the constructor for Question is incomplete. See MCQQuestion.to_dict(), FRQQuestion.to_dict(), TrueFalseQuestion.to_dict(), and MatchQuestion.to_dict() for how the data for different types of questions should be formatted.

Parameters:

data: incomplete data

Authors

Sai Koushik Balusulapalem

GitHub

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
quizzable		quizzable
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
pyproject.toml		pyproject.toml
requirements-dev.txt		requirements-dev.txt
setup.cfg		setup.cfg
setup.py		setup.py

License

balusulapalemsaikoushik/quizzable

Folders and files

Latest commit

History

Repository files navigation

quizzable

Table of Contents

Quickstart

Classes

Terms

Terms.get_terms()

Terms.get_frq_question()

Terms.get_mcq_question()

Terms.get_true_false_question()

Terms.get_match_question()

Terms.get_random_question()

Terms.get_quiz()

Quiz

Quiz.questions

Quiz.from_data()

Quiz.to_data()

Question

Question.term

Question.answer

Question.prompt

Question.from_dict()

Question.check_answer()

Question.to_dict()

MCQQuestion

MCQQuestion.options

MCQQuestion.to_dict()

FRQQuestion

FRQQuestion.to_dict()

TrueFalseQuestion

TrueFalseQuestion.definition

TrueFalseQuestion.to_dict()

MatchQuestion

MatchQuestion.definitions

MatchQuestion.to_dict()

Exceptions

BaseQuizzableException

InvalidLengthError

InvalidOptionsError

InvalidTermsError

InvalidQuestionError

DataIncompleteError

Authors

Sai Koushik Balusulapalem

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

`Terms`

`Terms.get_terms()`

`Terms.get_frq_question()`

`Terms.get_mcq_question()`

`Terms.get_true_false_question()`

`Terms.get_match_question()`

`Terms.get_random_question()`

`Terms.get_quiz()`

`Quiz`

`Quiz.questions`

`Quiz.from_data()`

`Quiz.to_data()`

`Question`

`Question.term`

`Question.answer`

`Question.prompt`

`Question.from_dict()`

`Question.check_answer()`

`Question.to_dict()`

`MCQQuestion`

`MCQQuestion.options`

`MCQQuestion.to_dict()`

`FRQQuestion`

`FRQQuestion.to_dict()`

`TrueFalseQuestion`

`TrueFalseQuestion.definition`

`TrueFalseQuestion.to_dict()`

`MatchQuestion`

`MatchQuestion.definitions`

`MatchQuestion.to_dict()`

`BaseQuizzableException`

`InvalidLengthError`

`InvalidOptionsError`

`InvalidTermsError`

`InvalidQuestionError`

`DataIncompleteError`

Packages