quizzable 1.1.0

Description:

quizzable 1.1.0

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.
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

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