ybe.lib package

Submodules

ybe.lib.errors module

exception ybe.lib.errors.YbeBaseError

Bases: Exception

Base exception class for all Ybe related errors.

exception ybe.lib.errors.YbeLoadingError(description='', question_ind=None)

Bases: ybe.lib.errors.YbeBaseError

Indicates an error while loading an .ybe file.

Parameters:

• description (str) – Human-readable description of the problem
• question_ind (int) – the question index regarding this loading error

exception ybe.lib.errors.YbeMultipleLoadingErrors(items, question_ind=None, question_id=None)

Bases: ybe.lib.errors.YbeLoadingError

Collection of multiple loading exceptions.

Parameters:

• List[YbeLoadingError] – list of exceptions
• question_ind (int) – the question index regarding this collection of errors
• question_id (str) – the ID of the question raising the error

to_string(in_recurse=False)

exception ybe.lib.errors.YbeVisitingError(description='')

Bases: ybe.lib.errors.YbeBaseError

Indicates an error while traversing the Ybe node objects.

Parameters:description (str) – Human-readable description of the problem

ybe.lib.latex_writer module

ybe.lib.latex_writer.get_jinja2_environment(**kwargs)

Get the default Jinja2 environment we use for writing the Latex files.

The provided kwargs overwrite the default keyword arguments we use to create the Jinja2 environment, meaning you can tune the environment to your needs.

Parameters:kwargs – keyword argument overwriting the default environment arguments. Returns:a configured environment Return type:jinja2.Environment

ybe.lib.latex_writer.get_jinja2_loader()

Get the default Jinja2 loader.

Returns:the default loader using the in build latex template. Return type:jinja2.PackageLoader

ybe.lib.latex_writer.write_latex_file(ybe_exam, fname, jinja2_env=None, jinja2_kwargs=None)

Write the provided Ybe object as a Latex file.

Parameters:

• ybe_exam (ybe.lib.ybe_exam.YbeExam) – the ybe file object to dump
• fname (str) – the filename to write to
• jinja2_env (jinja2.Environment) – the environment we use to render the Latex files. If not provided we use the environment returned by get_jinja2_environment().
• jinja2_kwargs (dict) – additional keyword arguments used when rendering the Jinja2 template. This will be unpacked and provided to the render method.

ybe.lib.latex_writer.write_latex_string(ybe_exam, jinja2_env=None, jinja2_kwargs=None)

Write the provided Ybe object as a Latex string.

Parameters:

• ybe_exam (ybe.lib.ybe_exam.YbeExam) – the ybe file object to dump
• jinja2_env (jinja2.Environment) – the environment we use to render the Latex files. If not provided we use the environment returned by get_jinja2_environment().
• jinja2_kwargs (dict) – additional keyword arguments used when rendering the Jinja2 template. This will be unpacked and provided to the render method.

Returns:

the filled in Latex template.

Return type:

str

ybe.lib.qti_reader module

ybe.lib.qti_reader.read_qti_dir(dir_name)

Parse the data from an extracted QTI zip file and return an ybe.lib.ybe_contents.YbeExam object.

Since there are some differences in the data stored by the QTI format and the Ybe format, round-trip conversion may not be lossless.

Parameters:dir_name (str) – the path to the directory with QTI data to load Returns:an .ybe exam loaded with the content from the QTI zip file. Return type:ybe.lib.ybe_contents.YbeExam

ybe.lib.qti_reader.read_qti_zip(zip_file)

Parse the data from the provided QTI zip file and return an ybe.lib.ybe_contents.YbeExam object.

Since there are some differences in the data stored by the QTI format and the Ybe format, round-trip conversion may not be lossless.

Parameters:zip_file (str) – the filename of the zip file with QTI data to load Returns:an .ybe exam loaded with the content from the QTI zip file. Return type:ybe.lib.ybe_contents.YbeExam

ybe.lib.qti_writer module

class ybe.lib.qti_writer.ConvertCanvasEquations

Bases: ybe.lib.qti_writer.TextFormatter

Converts MathJax equations to a special format used by the online Canvas platform.

This will replace <span class="math display">{equation}</span> and <span class="math inline">{equation}</span> to:

<img alt="LaTeX: {equation}" class="equation_image" data-equation-content="{equation}"
    src="equation_images/{equation_html}" title="{equation}"/>

format(text)

Format the provided string of HTML text.

Parameters:text (str) – the text to format according to this strategy Returns:the formatted HTML Return type:str

class ybe.lib.qti_writer.NoOpTextFormatter

Bases: ybe.lib.qti_writer.TextFormatter

Applies no additional formatting to the HTML

format(text)

Format the provided string of HTML text.

Parameters:text (str) – the text to format according to this strategy Returns:the formatted HTML Return type:str

class ybe.lib.qti_writer.TextFormatter

Bases: object

Strategy pattern for formatting the HTML text for use in the QTI XML files.

format(text)

Format the provided string of HTML text.

Parameters:text (str) – the text to format according to this strategy Returns:the formatted HTML Return type:str

ybe.lib.qti_writer.write_qti_dir(ybe_exam, dirname, text_formatter=None)

Write the provided Ybe object as a QTI zip.

Parameters:

• ybe_exam (ybe.lib.ybe_exam.YbeExam) – the ybe file object to dump
• dirname (str) – the directory to write to
• text_formatter (TextFormatter) – specific actions to format the HTML text for use in the QTI. If not specified, defaults to NoOpTextFormatter.

ybe.lib.qti_writer.write_qti_zip(ybe_exam, fname, text_formatter=None)

Write the provided Ybe object as a QTI zip.

Parameters:

• ybe_exam (ybe.lib.ybe_exam.YbeExam) – the ybe file object to dump
• fname (str) – the filename to dump to
• text_formatter (TextFormatter) – specific actions to format the HTML text for use in the QTI. If not specified, defaults to NoOpTextFormatter.

ybe.lib.utils module

ybe.lib.utils.copy_ybe_resources(ybe_exam, dirname)

Copy all the resource specified in the provided Ybe file object to the provided directory.

Parameters:

• ybe_exam (ybe.lib.ybe_contents.YbeExam) – the Ybe exam to search for (external) resources.
• dirname (str) – the directory to write the data to.

Returns:

list of path names to the copied resources

Return type:

List[str]

ybe.lib.utils.get_default_value(field)

Resolve the default value of a dataclass field.

This first looks if default is defined, next it tries to call the function default_factory, else it returns None.

Parameters:field (dataclass.field) – one field of a class with @dataclass decorator Returns:the default field object. Return type:Any

ybe.lib.utils.html_to_latex(text)

Convert text in HTML format to Latex.

Parameters:text – the text in HTML format Returns:a Latex conversion of the text in this node Return type:str

ybe.lib.utils.markdown_to_latex(text)

Convert text in MarkDown format to Latex.

Parameters:text – the text in Markdown format Returns:a Latex conversion of the text in this node Return type:str

ybe.lib.ybe_contents module

class ybe.lib.ybe_contents.AnalyticsQuestionMetaData(analytics: List[dict] = <factory>)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

Analytics about this question, e.g. usage statistics.

class ybe.lib.ybe_contents.ClassificationQuestionMetaData(skill_level: str = None, related_concepts: List[str] = <factory>, module: str = None, chapter: int = None, difficulty: int = None)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

The skill level and difficulty of the question.

Parameters:

• skill_level (str) – one of {Knowledge, Comprehension, Application, Analysis, Synthesis, Evaluation}
• related_concepts (List[str]) – list of related concepts / topics
• module (str) – the book or module this question is about
• chapter (int) – the chapter the work is about
• difficulty (int) – the difficulty level from 1 to 10, with 10 being the hardest

available_skill_levels = ['Knowledge', 'Comprehension', 'Application', 'Analysis', 'Synthesis', 'Evaluation']

chapter = None

difficulty = None

module = None

skill_level = None

class ybe.lib.ybe_contents.DirectoryContext(path: str)

Bases: ybe.lib.ybe_contents.YbeResourceContext

Loading resources from a directory

copy_resource(resource, dirname)

Copy the indicated resource to the indicated directory.

Parameters:

• resource (YbeResource) – the resource to copy
• dirname (str) – the directory to copy to

Returns:

the path to the new file

Return type:

str

class ybe.lib.ybe_contents.GeneralQuestionMetaData(description: 'str' = None, keywords: 'List[str]' = <factory>, language: 'str' = None)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

description = None

language = None

class ybe.lib.ybe_contents.ImageResource(path: Optional[str] = None, alt: Optional[str] = None)

Bases: ybe.lib.ybe_contents.YbeResource

Path and meta data of an image which need to be included as a resource.

alt = None

class ybe.lib.ybe_contents.LifecycleQuestionMetaData(author: 'str' = None)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

author = None

class ybe.lib.ybe_contents.MultipleChoice(id: 'str' = '', points: 'Union[float, int]' = 0, text: 'TextNode' = <factory>, meta_data: 'QuestionMetaData' = <factory>, answers: 'List[MultipleChoiceAnswer]' = <factory>)

Bases: ybe.lib.ybe_contents.Question

class ybe.lib.ybe_contents.MultipleChoiceAnswer(text: 'TextNode' = <factory>, correct: 'bool' = False)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

correct = False

class ybe.lib.ybe_contents.MultipleResponse(id: 'str' = '', points: 'Union[float, int]' = 0, text: 'TextNode' = <factory>, meta_data: 'QuestionMetaData' = <factory>, answers: 'List[MultipleResponseAnswer]' = <factory>)

Bases: ybe.lib.ybe_contents.Question

class ybe.lib.ybe_contents.MultipleResponseAnswer(text: 'TextNode' = <factory>, correct: 'bool' = False)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

correct = False

class ybe.lib.ybe_contents.OpenQuestion(id: 'str' = '', points: 'Union[float, int]' = 0, text: 'TextNode' = <factory>, meta_data: 'QuestionMetaData' = <factory>, options: 'OpenQuestionOptions' = <factory>)

Bases: ybe.lib.ybe_contents.Question

class ybe.lib.ybe_contents.OpenQuestionOptions(max_words: Optional[int] = None, min_words: Optional[int] = None, expected_lines: Optional[int] = None)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

Options concerning an open question.

Parameters:

• max_words (int) – the maximum number of allowed words
• min_words (int) – the minimum number of allowed words
• expected_lines (int) – the number of lines expected to be typed (size hint)

expected_lines = None

max_words = None

min_words = None

class ybe.lib.ybe_contents.Question(id: 'str' = '', points: 'Union[float, int]' = 0, text: 'TextNode' = <factory>, meta_data: 'QuestionMetaData' = <factory>)

Bases: ybe.lib.ybe_contents.YbeExamElement

id = ''

points = 0

class ybe.lib.ybe_contents.QuestionMetaData(general: 'GeneralQuestionMetaData' = <factory>, lifecycle: 'LifecycleQuestionMetaData' = <factory>, classification: 'ClassificationQuestionMetaData' = <factory>, analytics: 'AnalyticsQuestionMetaData' = <factory>)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

class ybe.lib.ybe_contents.SimpleYbeNode

Bases: ybe.lib.ybe_contents.YbeNode

Simple implementation of the required methods of an YbeNode.

get_default_value(attribute_name)

By default, resolve the default value using the dataclass fields.

get_resources()

Get a list of YbeResources in this node or sub-tree.

This will need to do a recursive lookup to find all the resources.

Returns:list of resources nodes. Return type:List[YbeResource]

class ybe.lib.ybe_contents.Text(text: str = '')

Bases: ybe.lib.ybe_contents.TextMarkdown

Subclass of TextMarkDown, i.e. short for text_markdown in the Ybe file.

class ybe.lib.ybe_contents.TextHTML(text: str = '')

Bases: ybe.lib.ybe_contents.TextNode

Text in HTML format, use as text_html.

get_resources()

Get a list of YbeResources in this node or sub-tree.

This will need to do a recursive lookup to find all the resources.

Returns:list of resources nodes. Return type:List[YbeResource]

to_html()

Convert the text in this node to HTML and return that.

Returns:a HTML conversion of this text block node Return type:str

to_latex()

Convert the text in this node to Latex and return that.

Returns:a Latex conversion of the text in this node Return type:str

class ybe.lib.ybe_contents.TextMarkdown(text: str = '')

Bases: ybe.lib.ybe_contents.TextNode

Text in Markdown format, use as text_markdown.

get_resources()

Get a list of YbeResources in this node or sub-tree.

This will need to do a recursive lookup to find all the resources.

Returns:list of resources nodes. Return type:List[YbeResource]

to_html()

Convert the text in this node to HTML and return that.

Returns:a HTML conversion of this text block node Return type:str

to_latex()

Convert the text in this node to Latex and return that.

Returns:a Latex conversion of the text in this node Return type:str

class ybe.lib.ybe_contents.TextNode(text: 'str' = '')

Bases: ybe.lib.ybe_contents.SimpleYbeNode

text = ''

to_html()

Convert the text in this node to HTML and return that.

Returns:a HTML conversion of this text block node Return type:str

to_latex()

Convert the text in this node to Latex and return that.

Returns:a Latex conversion of the text in this node Return type:str

class ybe.lib.ybe_contents.TextOnlyQuestion(id: 'str' = '', points: 'Union[float, int]' = 0, text: 'TextNode' = <factory>, meta_data: 'QuestionMetaData' = <factory>)

Bases: ybe.lib.ybe_contents.Question

class ybe.lib.ybe_contents.YbeExam(info: YbeInfo = <factory>, questions: List[Question] = <factory>, resource_context: YbeResourceContext = None)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

Representation of an Ybe file.

An Ybe file basically consists of a header followed of a number of questions.

get_points_possible()

Get the maximum number of points possible in this exam.

Returns:the maximum number of points possible. Return type:float

resource_context = None

class ybe.lib.ybe_contents.YbeExamElement

Bases: ybe.lib.ybe_contents.SimpleYbeNode

Base class for questions and other nodes appearing in an exam / questionnaire.

class ybe.lib.ybe_contents.YbeInfo(title: str = None, description: str = None, document_version: str = None, authors: List[str] = <factory>, date: date = None)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

The header information in a Ybe file.

date = None

description = None

document_version = None

title = None

class ybe.lib.ybe_contents.YbeNode

Bases: object

Basic inheritance class for all Ybe related content nodes.

accept_visitor(visitor)

Ybe nodes support the visitor pattern to allow for document traversal.

Parameters:visitor (YbeNodeVisitor) – the visitor we will give a callback.

get_default_value(attribute_name)

Get the default value for an attribute of this node.

Parameters:attribute_name (str) – the name of the attribute for which we want the default value Returns:the default value Return type:Any

get_resources()

Get a list of YbeResources in this node or sub-tree.

This will need to do a recursive lookup to find all the resources.

Returns:list of resources nodes. Return type:List[YbeResource]

class ybe.lib.ybe_contents.YbeNodeVisitor

Bases: object

Interface class for a node visitor, part of the visitor design pattern.

visit(node)

Visit method, called by the node which accepted this visitor.

Parameters:node (YbeNode) – the node being visited.

class ybe.lib.ybe_contents.YbeResource(path: Optional[str] = None)

Bases: ybe.lib.ybe_contents.SimpleYbeNode

Reference to another file for included content.

path = None

class ybe.lib.ybe_contents.YbeResourceContext

Bases: object

The context used to load Ybe resource.

copy_resource(resource, dirname)

Copy the indicated resource to the indicated directory.

Parameters:

• resource (YbeResource) – the resource to copy
• dirname (str) – the directory to copy to

Returns:

the path to the new file

Return type:

str

class ybe.lib.ybe_contents.ZipArchiveContext(path: str)

Bases: ybe.lib.ybe_contents.YbeResourceContext

Loading resources from a zipped archive.

copy_resource(resource, dirname)

Copy the indicated resource to the indicated directory.

Parameters:

• resource (YbeResource) – the resource to copy
• dirname (str) – the directory to copy to

Returns:

the path to the new file

Return type:

str

ybe.lib.ybe_reader module

ybe.lib.ybe_reader.read_ybe_file(fname)

Load the data from the provided .ybe file and return an ybe.lib.ybe_contents.YbeExam object.

Parameters:fname (str) – the filename of the .ybe file to load Returns:the contents of the .ybe file. Return type:ybe.lib.ybe_contents.YbeExam Raises:ybe.lib.errors.YbeLoadingError – if the file could not be loaded due to syntax errors

ybe.lib.ybe_reader.read_ybe_string(ybe_str)

Load the data from the provided Ybe formatted string and return an ybe.lib.ybe_contents.YbeExam object.

Parameters:ybe_str (str) – an .ybe formatted string to load Returns:the contents of the .ybe file. Return type:ybe.lib.ybe_contents.YbeExam Raises:ybe.lib.errors.YbeLoadingError – if the file could not be loaded due to syntax errors

ybe.lib.ybe_writer module

class ybe.lib.ybe_writer.YbeConversionVisitor(minimal=False)

Bases: ybe.lib.ybe_contents.YbeNodeVisitor

Converts an YbeExam into a Python dictionary.

Parameters:minimal (boolean) – if set to True we only print the configured options. By default this flag is False, meaning we print all the available options, if needed with null placeholders.

visit(node)

Visit method, called by the node which accepted this visitor.

Parameters:node (YbeNode) – the node being visited.

ybe.lib.ybe_writer.write_ybe_file(ybe_exam, fname, minimal=False)

Dump the provided Ybe file object to the indicated file.

Parameters:

• ybe_exam (ybe.lib.ybe_contents.YbeExam) – the ybe file object to dump
• fname (str) – the filename to dump to
• minimal (boolean) – if set to True we only print the configured options. By default this flag is False, meaning we print all the available options, if needed with null placeholders.

ybe.lib.ybe_writer.write_ybe_string(ybe_exam, minimal=False)

Dump the provided YbeExam as a .ybe formatted string.

Parameters:

• ybe_exam (ybe.lib.ybe_contents.YbeExam) – the ybe file contents to dump
• minimal (boolean) – if set to True we only print the configured options. By default this flag is False, meaning we print all the available options, if needed with null placeholders.

Returns:

an .ybe (Yaml) formatted string

Return type:

str

Module contents