excel2moodle.core package — excel2moodle 0.3.0 documentation

# excel2moodle.core package

These Modules are the heart of the excel2moodle Package

## Submodules

## excel2moodle.core.category module

class excel2moodle.core.category.Category(n, name, description, dataframe, points=0, version=0)

  Bases: `object`

  Parameters:

    - n (int)

    - name (str)

    - description (str)

    - dataframe (DataFrame)

    - points (float)

    - version (int)

  getCategoryHeader()

    vor den Fragen einer Kategorie wird ein <question type='category'> eingefügt mit Name und Beschreibung

    Return type:

      `Element`

  property id
  property name
  parsAll(tree=None)
    Return type:

      `None`

    Parameters:

      tree (Element)

  parseQ(q, xmlTree=None)
    Return type:

      `bool`

    Parameters:

      - q (Question)

      - xmlTree (_Element | None)

## excel2moodle.core.dataStructure module

Main Module which does the heavy lifting

At the heart is the class `xmlTest`

class excel2moodle.core.dataStructure.QuestionDB(settings)

  Bases: `object`

  oberste Klasse für den Test

  Parameters:

    settings (Settings)

  appendQElements(cat, qList, tree, includeHeader=True)
    Return type:

      `None`

    Parameters:

      - cat (Category)

      - qList (list[Question])

      - tree (Element)

      - includeHeader (bool)

  appendQuestions(questions, file=None)
    Parameters:

      - questions (list[QuestionItem])

      - file (Path | None)

  dataChanged = <excel2moodle.QSignaler(0x5c3d8ccef910)>
  onSheetPathChanged(sheet)
    Return type:

      `None`

    Parameters:

      sheet (Path)

  parseAll()
  retrieveCategoriesData()

    Scans through the sheet with the metadata for all the question categories

    The information that will be shown in the UI like description and points is retrieved from one spreadsheet sheet. This method gathers this information and stores it in the `categoriesMetaData` dataframe

    Return type:

      `None`

## excel2moodle.core.etHelpers module

Helper Module which aids in creating XML-Elements for the Questions

This module host different functions. All of them will return an `lxml.etree.Element`

excel2moodle.core.etHelpers.getCdatTxtElement(subEle)

  Puts all `subEle` as `str` into a `<text><![CDATA[...subEle...]]</text>` element

  Return type:

    `Element`

  Parameters:

    subEle (_Element | list[_Element])

excel2moodle.core.etHelpers.getElement(eleName, text, **attribs)

  Creates an XML-Element with text

  If `type(text)``is a ``QuestionFields`, the specific field is directly read. Otherwise it will include whatever is `text` as a string :rtype: `Element`

  Parameters:

    - **kwargs --

      are treated as attributes for the Element

    - eleName (str)

    - text (str)

  Raises:

    NanException if the spreadsheet cell of text -- QuestionFields is `nan`

  Return type:

    Element

excel2moodle.core.etHelpers.getFeedBEle(feedback, text=None, style=None)

  Gets ET Elements with the feedback for the question.

  Return type:

    `Element`

  Parameters:

    - feedback (XMLTags)

    - text (str | None)

    - style (TextElements | None)

excel2moodle.core.etHelpers.getTextElement(eleName, text, **attribs)

  Creates two nested elements: `eleName` with child `text` which holds the text

  Return type:

    `Element`

  Parameters:

    - eleName (str)

    - text (str | DFIndex)

## excel2moodle.core.exceptions module

exception excel2moodle.core.exceptions.InvalidFieldException(message, qID, field, *args, **kwargs)

  Bases: `Exception`

  Parameters:

    - message (str)

    - qID (str)

    - field (DFIndex | list[DFIndex])

    - args (object)

  Return type:

    None

exception excel2moodle.core.exceptions.NanException(message, qID, field, *args, **kwargs)

  Bases: `QNotParsedException`

exception excel2moodle.core.exceptions.QNotParsedException(message, qID, *args, **kwargs)

  Bases: `Exception`

  Parameters:

    - message (str)

    - qID (str | int)

  Return type:

    None

## excel2moodle.core.globals module

class excel2moodle.core.globals.DFIndex(*values)

  Bases: `StrEnum`

  This Enum holds the identifier string for for the spreadsheet and the string for the xml-tag

  Each enum corresponds to a list of two values. The first Value is the index in the spreadsheet, the second is the name of the xml-tag

  ANSTYPE = 'answerType'
  BPOINTS = 'bulletPoints'
  FALSE = 'false'
  NAME = 'name'
  NUMBER = 'number'
  PICTURE = 'picture'
  RESULT = 'result'
  TEXT = 'text'
  TRUE = 'true'
  TYPE = 'type'

class excel2moodle.core.globals.TextElements(*values)

  Bases: `Enum`

  LISTITEM = ('li', 'text-align: left;')
  PLEFT = ('p', 'text-align: left;')
  SPANGREEN = ('span', 'color: rgb(152, 202, 62)')
  SPANORANGE = ('span', 'color: rgb(152, 100, 100)')
  SPANRED = ('span', 'color: rgb(239, 69, 64)')
  ULIST = ('ul', '')
  create(tag=None)
    Parameters:

      tag (str | None)

  property style: str

class excel2moodle.core.globals.XMLTags(_, dfkey=None, getEle=None)

  Bases: `StrEnum`

  ANSFEEDBACK = 'feedback'
  ANSWER = 'answer'
  CORFEEDB = 'correctfeedback'
  GENFEEDB = 'generalfeedback'
  HIDE = 'hidden'
  ID = 'idnumber'
  INCORFEEDB = 'incorrectfeedback'
  NAME = 'name'
  PCORFEEDB = 'partialcorrectfeedback'
  PENALTY = 'penalty'
  PICTURE = 'file'
  POINTS = 'defaultgrade'
  QTEXT = 'questiontext'
  QUESTION = 'question'
  TEXT = 'text'
  TOLERANCE = 'tolerance'
  TYPE = 'type'
  property dfkey: str
  set(getEle)
    Return type:

      `None`

## excel2moodle.core.numericMultiQ module

Numeric Multi Questions Module to calculate results from a formula

This module calculates a series of results from al matrix of variables. For each column in the matrix there will be one result. As well it returns a bullet points string that shows the numerical values corresponding to the set of variables

excel2moodle.core.numericMultiQ.getVariablesDict(df, keyList, index)

  Liest alle Variablen-Listen deren Name in `keyList` ist aus dem DataFrame im Column[index]

  Return type:

    `dict`

  Parameters:

    - df (DataFrame)

    - keyList (list)

    - index (int)

excel2moodle.core.numericMultiQ.getVarsList(bps)

  Durchsucht den bulletPoints String nach den Variablen, die als "{var}" gekennzeichnet sind

  Return type:

    `list`

  Parameters:

    bps (str)

excel2moodle.core.numericMultiQ.insertVariablesToBPoints(varDict, bulletPoints, index)

  Für jeden Eintrag im varDict, wird im bulletPoints String der Substring "{key}" durch value[index] ersetzt

  Return type:

    `str`

  Parameters:

    - varDict (dict)

    - bulletPoints (str)

    - index (int)

excel2moodle.core.numericMultiQ.parseNumericMultiQuestion(datFrame, bulletPoints, equation, questionIndex)

  Berechnet die Ergebnisse anhand der Variablen in bulletPoints

  Gibt eine Liste mit allen Ergebnissen zurück und eine Liste mit den bulletPoints-Strings, die die Numerischen Variablen enthalten

  Return type:

    `tuple`[`list`[`str`], `list`[`float`]]

  Parameters:

    - datFrame (DataFrame)

    - bulletPoints (str)

    - equation (str)

    - questionIndex (int)

excel2moodle.core.numericMultiQ.setParameters(parameters, index)

  Ubergibt die Parameter mit entsprechenden Variablen-Namen an den asteval-Interpreter.

  Dann kann dieser die equation loesen.

  Return type:

    `None`

  Parameters:

    - parameters (dict)

    - index (int)

## excel2moodle.core.parser module

class excel2moodle.core.parser.MCQuestionParser(*args)

  Bases: `QuestionParser`

  getAnsElementsList(answerList, fraction=50, format='html')
    Return type:

      `list`[`Element`]

    Parameters:

      - answerList (list)

      - fraction (float)

  setAnswers()

    Needs to be implemented in the type-specific subclasses

    Return type:

      `list`[`Element`]

class excel2moodle.core.parser.NFMQuestionParser(question, dataframe)

  Bases: `QuestionParser`

  Parameters:

    - question (Question)

    - dataframe (Series)

  getVariablesDict(keyList)

    Liest alle Variablen-Listen deren Name in `keyList` ist aus dem DataFrame im Column[index]

    Return type:

      `tuple`[`dict`[`str`, `list`[`str`]], `int`]

    Parameters:

      keyList (list)

  static getVarsList(bps)

    Durchsucht den bulletPoints String nach den Variablen, die als "{var}" gekennzeichnet sind

    Return type:

      `list`

    Parameters:

      bps (str | list[str])

  static insertVariablesToBPoints(varDict, bulletPoints, index)

    Für jeden Eintrag im varDict, wird im bulletPoints String der Substring "{key}" durch value[index] ersetzt

    Return type:

      `str`

    Parameters:

      - varDict (dict)

      - bulletPoints (str)

      - index (int)

  setAnswers()

    Needs to be implemented in the type-specific subclasses

    Return type:

      `None`

  setVariants(number)
    Parameters:

      number (int)

class excel2moodle.core.parser.NFQuestionParser(*args)

  Bases: `QuestionParser`

  setAnswers()

    Needs to be implemented in the type-specific subclasses

    Return type:

      `list`[`Element`]

class excel2moodle.core.parser.QuestionParser(question, dataframe)

  Bases: `object`

  Parameters:

    - question (Question)

    - dataframe (Series)

  appendFromSettings(key='standards')

    Appends 1 to 1 mapped Elements defined in the parserSettings to the element

    Return type:

      `None`

  appendToQuestion(eleName, text, txtEle=False, **attribs)
    Parameters:

      - eleName (str)

      - text (str | DFIndex)

  formatBulletList(bps)
    Return type:

      `Element`

    Parameters:

      bps (str)

  getFeedBEle(feedback, text=None, style=None)
    Return type:

      `Element`

    Parameters:

      - feedback (XMLTags)

      - text (str | None)

      - style (TextElements | None)

  static getNumericAnsElement(result, tolerance=0.01, fraction=100, format='moodle_auto_format')
    Return type:

      `Element`

    Parameters:

      - result (int | float)

      - tolerance (float)

      - fraction (int | float)

      - format (str)

    Returns an `<answer/>` Element specific for the numerical Question The element contains those childs:

    > `<text/>` which holds the value of the answer `<tolerace/>` with the relative tolerance for the result `<feedback/>` with general feedback for a true answer

  hasPicture()

    Creates a `Picture` object inside `question`, if the question needs a pic

    Return type:

      `bool`

  parse(xmlTree=None)

    Parses the Question

    Generates an new Question Element stored as `self.tmpEle:ET.Element` if no Exceptions are raised, `self.tmpEle` is passed to `self.question.element`

    Return type:

      `None`

    Parameters:

      xmlTree (_Element | None)

  setAnswers()

    Needs to be implemented in the type-specific subclasses

    Return type:

      `list`[`Element`] | `None`

  setBPoints()

    If there bulletPoints are set in the Spreadsheet it creates an unordered List-Element in `Question.bulletList`

    Return type:

      `None`

  setMainText()
    Return type:

      `None`

## excel2moodle.core.question module

class excel2moodle.core.question.Picture(picKey, imgFolder, question)

  Bases: `object`

  Parameters:

    - picKey (str)

    - imgFolder (Path)

    - question (Question)

class excel2moodle.core.question.Question(category, name, number, parent=None, qtype='type', points=0)

  Bases: `object`

  Parameters:

    - name (str)

    - number (int)

    - qtype (str)

    - points (float)

  assemble(variant=1)
    Return type:

      `None`

    Parameters:

      variant (int)

  setID(id=0)
    Return type:

      `None`

## excel2moodle.core.questionValidator module

This Module checks if the data inside the Spreadsheet is valid

Those things are considered:

1. The mandatory entries must not be `Nan`

2. All fields must have the right data-type

If Those checks pass, a question is created, which can be accessed via `Validator.question`

class excel2moodle.core.questionValidator.Validator(category)

  Bases: `object`

  setup(df, index)
    Return type:

      `bool`

    Parameters:

      - df (Series)

      - index (int)

  validate()
    Return type:

      `bool`

## excel2moodle.core.questionWriter module

This Module holds the related Functions for writing the Questions to an xml-File

It is planned to rework those Functions, because they're not quite elegant.

excel2moodle.core.questionWriter.write_question_MC(save_dir, ID, name, s_1, s_2, s_3, points_avail, ans_type, true_ans, false_ans, pic)

  Funktion schreibt MC-Frage auf Grundlage der übergebenen strings nach Pfad f_path

excel2moodle.core.questionWriter.write_question_NF(save_dir, ID, name, s_1, s_2, s_3, b_str, points_avail, result, pic, tol_abs, picID=None)

  Funktion schreibt NF-Frage auf Grundlage der übergebenen strings nach Pfad f_path

## excel2moodle.core.stringHelpers module

This Module holds small Helperfunctions related to string manipulation

excel2moodle.core.stringHelpers.getBase64Img(imgPath)

excel2moodle.core.stringHelpers.getUnitsElementAsString(unit)

excel2moodle.core.stringHelpers.get_bullet_string(s)

  Formatiert die Angaben zum Statischen System hübsch

excel2moodle.core.stringHelpers.printDom(xmlElement, file=None)

  Prints the document tree of `xmlTree` to the `file`, if specified, else dumps to stdout

  Return type:

    `None`

  Parameters:

    - xmlElement (Element)

    - file (Path | None)

excel2moodle.core.stringHelpers.stripWhitespace(stringList)

excel2moodle.core.stringHelpers.texWrapper(text, style)

  Puts the strings inside `text` into a LaTex environment

  if `style == unit`: inside `\mathrm{}` if `style == math`: inside `\( \)`

  Return type:

    `list`[`str`]

  Parameters:

    - text (str | list[str])

    - style (str)