{ "info": { "author": "Ahmad Khayyat", "author_email": "akhayyat@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: Education", "License :: OSI Approved :: BSD License", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3 :: Only", "Topic :: Education", "Topic :: Education :: Computer Aided Instruction (CAI)", "Topic :: Software Development :: Libraries", "Topic :: Utilities" ], "description": "qudb: Question Database\n=======================\n\n*Manage a database of questions and use it to generate assessments, e.g.\nassignments, quizzes, and exams.*\n\n*qudb* is a personal question bank for instructors. It allows you to:\n\n1. Manage your collection of questions for a given course, and assemble\n various assessments out of them.\n\n2. Track how you are using your questions. Query your database for\n *questions*, *terms*, *assessments*, or *assessment types*.\n\n An *assessment type* refers to a type of assessments that recur at\n most once every term, such as *quiz1*, *assignment2*, and *final*. It\n can be any arbitrary string identifying a type of assessment. An\n *assessment* is a specific occurrence of an *assessment type* in a\n given *term*, and hence is identified by a pair of a *term* and an\n *assessment type*.\n\n Example queries:\n\n - In which assessments has a given question been used?\n - What questions make up a given assessment?\n - What questions have been used in a given term?\n - What questions have been used in final exams across all terms?\n\n3. Use a template to render an assessment document using its questions.\n\n4. Distinguish between essay questions (default) and multiple-choice\n questions.\n\n5. Use arbitrary additional variables in your templates, so you can use\n the same templates across courses by introducing, for example, an\n additional *course name* variable.\n\nGetting Started\n---------------\n\n1. Create a database:\n\n ::\n\n qm init\n\n By default, this command creates a ``./qu.db`` database file. Use the\n ``-D`` (or ``--database``) option to specify the database file\n location.\n\n2. Add questions to assessments (an assessment is identified by a *term*\n and an *assessment type*):\n\n ::\n\n qm add --term 151 --assessment-type quiz1 questions/chapter1/whats-your-name.tex\n qm add --term 151 --assessment-type quiz1 questions/chapter1/mcq/choose-a-month.tex\n\n Use the ``-Q`` (or ``--questions-directory``) option to specify where\n to look for the question files. You can also specify a question's\n *points* (``-p``), whether it's a *bonus* question (``-b``), and its\n *order* in the assessment (``-o``) if you want to insert it somewhere\n in the middle. The *points*, *bonus*, and *order* fields of a\n question are per assessment, and can change from one assessment to\n another.\n\n3. Generate an assessment:\n\n ::\n\n qm render --term 151 --assessment-type quiz1 --pdflatex quiz-template.tex\n\n The ``--pdflatex`` option (or ``-P``) assumes that your template is a\n LaTeX file, requires the ``pdflatex`` program, and generates a PDF.\n Without it, you get a rendered template.\n\n The ``--config`` option (or ``-C``) allows specifying additional\n arbitrary template variables using an `INI-style configuration\n file `__.\n\nCommands\n--------\n\nAlthough the ``init``, ``add``, and ``render`` commands described above\nare often enough, there are a few other commands that complement them.\nMoreover, these three commands have a few options that control their\noperation. Here are all the supported commands and their options.\n\n``init``\n~~~~~~~~\n\n::\n\n usage: qm init [-h] [-D DATABASE]\n\n Create a new database file as specified by the -D option. Defaults to ./qu.db.\n If the database exists, do nothing\n\n optional arguments:\n -h, --help show this help message and exit\n -D DATABASE, --database DATABASE\n SQLite database file path\n\n``list``\n~~~~~~~~\n\n::\n\n usage: qm list [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] [-t TERM]\n [-y ASSESSMENT_TYPE] [-q QUESTION] [-m]\n {terms,assessment-types,assessments,questions}\n\n List existing entities: terms, assessment-types, assessments, or questions\n\n positional arguments:\n {terms,assessment-types,assessments,questions}\n what to list\n\n optional arguments:\n -h, --help show this help message and exit\n -D DATABASE, --database DATABASE\n SQLite database file path\n -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY\n where to look for questions. Question paths stored in\n the database are relative to this path\n -t TERM, --term TERM academic semester code, e.g. 142\n -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE\n examples: major1, assignment2, quiz3\n -q QUESTION, --question QUESTION\n include results related to this question only\n -m, --mcq whether to retrieve MCQs or non-MCQs. cannot retrieve\n both at once\n\n``add``\n~~~~~~~\n\n::\n\n usage: qm add [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] -t TERM -y\n ASSESSMENT_TYPE [-b] [-p POINTS] [-o ORDER] [-d DATE]\n question\n\n Add a question file to a given assessment, specified by a term and an\n assessment-type (required options)\n\n positional arguments:\n question path to the question file\n\n optional arguments:\n -h, --help show this help message and exit\n -D DATABASE, --database DATABASE\n SQLite database file path\n -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY\n where to look for questions. Question paths stored in\n the database are relative to this path\n -t TERM, --term TERM academic semester (3 digits)\n -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE\n examples: major1, assignment2, quiz3\n -b, --bonus this is a bonus question\n -p POINTS, --points POINTS\n default points for question\n -o ORDER, --order ORDER\n the order of the question in this assessment; defaults\n to last\n -d DATE, --date DATE assessment date; format YYYY-MM-DD\n\n``update``\n~~~~~~~~~~\n\n::\n\n usage: qm update [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] -t TERM -y\n ASSESSMENT_TYPE [-b] [-p POINTS] [-o ORDER] [-d DATE]\n question\n\n Update an existing assessment or question\n\n positional arguments:\n question path to the question file\n\n optional arguments:\n -h, --help show this help message and exit\n -D DATABASE, --database DATABASE\n SQLite database file path\n -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY\n where to look for questions. Question paths stored in\n the database are relative to this path\n -t TERM, --term TERM academic semester (3 digits)\n -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE\n examples: major1, assignment2, quiz3\n -b, --bonus this is a bonus question\n -p POINTS, --points POINTS\n default points for question\n -o ORDER, --order ORDER\n the order of the question in this assessment; defaults\n to last\n -d DATE, --date DATE assessment date; format YYYY-MM-DD\n\n``remove`` (or ``rm``)\n~~~~~~~~~~~~~~~~~~~~~~\n\n::\n\n usage: qm remove [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] -t TERM -y\n ASSESSMENT_TYPE\n\n Remove a question from an assessment\n\n optional arguments:\n -h, --help show this help message and exit\n -D DATABASE, --database DATABASE\n SQLite database file path\n -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY\n where to look for questions. Question paths stored in\n the database are relative to this path\n -t TERM, --term TERM academic semester (3 digits)\n -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE\n examples: major1, assignment2, quiz3\n\n``render``\n~~~~~~~~~~\n\n::\n\n usage: qm render [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] -t TERM -y\n ASSESSMENT_TYPE [-O OUTPUT_DIRECTORY] [-C CONFIG] [-P]\n [-l MATERIAL]\n template\n\n Generate assessment documents using the specified template. Two documents are\n generated: TERM-ASSESSMENT_TYPE.tex and TERM-ASSESSMENT_TYPE-solution.tex,\n with the template variable \"solution\" set to False and True, respectively.\n Templates are rendered using the Jinja2 template engine, with the following\n delimiters: <% block %><% endblock %>, << variable >>, <# comment #>\n\n positional arguments:\n template path to the jinja2 template file\n\n optional arguments:\n -h, --help show this help message and exit\n -D DATABASE, --database DATABASE\n SQLite database file path\n -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY\n where to look for questions. Question paths stored in\n the database are relative to this path\n -t TERM, --term TERM academic semester (3 digits)\n -y ASSESSMENT_TYPE, --assessment-type ASSESSMENT_TYPE\n examples: major1, assignment2, quiz3\n -O OUTPUT_DIRECTORY, --output-directory OUTPUT_DIRECTORY\n the directory in which the rendered files will be\n saved\n -C CONFIG, --config CONFIG\n ini-style configuration file defining additional\n template variables. (Use section [templates])\n -P, --pdflatex process rendered file with pdflatex (4 runs)\n -l MATERIAL, --material MATERIAL\n specify the material to which this assessment\n pertains. Available to the template in the \"material\"\n variable\n\n``export``\n~~~~~~~~~~\n\n::\n\n usage: qm export [-h] [-D DATABASE] [--overwrite] file\n\n Export the database to a YAML file (does not include the contents of question\n files)\n\n positional arguments:\n file YAML file to export to\n\n optional arguments:\n -h, --help show this help message and exit\n -D DATABASE, --database DATABASE\n SQLite database file path\n --overwrite overwrite the file if it already exists\n\n``import``\n~~~~~~~~~~\n\n::\n\n usage: qm import [-h] [-D DATABASE] [-Q QUESTIONS_DIRECTORY] [-u] file\n\n Import data from a YAML file into the database. To learn the YAML schema,\n export a minimal database, or see the README.md file\n\n positional arguments:\n file YAML file to import\n\n optional arguments:\n -h, --help show this help message and exit\n -D DATABASE, --database DATABASE\n SQLite database file path\n -Q QUESTIONS_DIRECTORY, --questions-directory QUESTIONS_DIRECTORY\n where to look for questions. Question paths stored in\n the database are relative to this path\n -u, --update ignore existing, identical questions\n\nExample valid YAML data:\n\n.. code:: yaml\n\n '142': # term code\n quiz1: # assessment type: creates an assessment in the parent term\n - file: questions/chapter1/q1.tex # each item in the list is a question\n - file: questions/chapter2/q5.tex # file: the file containing the question text\n date: 2015-02-14 # a date in any question sets the assessment date\n - bonus: true # set this question as a bonus question\n file: questions/chapter2/arm-gcc.tex\n points: 20 # how many points are assigned to this question in this assessment\n quiz2: # another assessment in the same term\n - date: 2015-03-07\n file: questions/chapter3/q2.tex\n - file: questions/chapter3/q3.tex\n points: 20\n '151': # another term\n quiz1: # this is a different assessment from the previous quiz1,\n # because it belongs to a different term\n - file: questions/chapter6/q3.tex\n\nTemplates\n---------\n\nTemplates use the `Jinja2 `__ template\nlanguage. The ``render`` command requires the ``--term`` and\n``--assessment-type`` options to specify an *assessment*. The following\nassessment variables are available in the template:\n\n- ``term``: the term of the specified assessment.\n- ``title``: assessment title, based on its type. For example, *quiz1*\n results in the title *Quiz 1*, and *major1* results in the title\n *Major Exam 1*.\n- ``date``: assessment date, as specified using the ``--date`` option\n of the ``add`` and ``update`` commands.\n- ``solution`` (Boolean): whether we are rendering the solution.\n- ``qs``: an ordered list of question objects belonging to this\n assessment. Includes the following fields:\n\n - ``question.file``: path of the question file.\n - ``points``: question points.\n - ``bonus`` (Boolean): whether this is a bonus question.\n\n- ``mcqs``: an ordered list of multiple-choice question objects,\n otherwise similar to ``qs``.\n- ``questions_relpath``: the relative path from the current directory\n to the questions as specified by the ``-Q``/``--questions-directory``\n option.\n\nVariables can be referenced in the template by enclosing them in ``<<``\nand ``>>``. For example, ``<< title >>`` renders the assessment's\n*title*.\n\nTo use some basic logic in the template, use template statements, such\nas ``for`` loops or ``if`` conditionals, by enclosing them in ``<%`` and\n``%>``. For example:\n\n.. code:: jinja\n\n <% for q in qs %>\n <% if q.bonus %>\n \\bonusquestion\n <% else %>\n \\question\n <% endif %>\n <% if q.points %>[<< q.points >>]<% endif %>\n \\input{<< questions_relpath >>/<< q.question.file >>}\n <% endfor %>\n\nFor information about the template language, consult the `Jinja2\nTemplate Designer\nDocumentation `__.\n\nAssumptions\n-----------\n\n- One `SQLite `__ database file per course.\n- Questions and templates are text files.\n- Multiple choice questions have an ``/mcq/`` component in their paths.\n- Each question file includes the question's solution in a way that\n allows it to be easily listed or omitted in a template.\n- Although it is not required, *qudb* works well with the\n `exam `__ LaTeX package. For example,\n each question file can wrap the solution in a ``solution``\n environment, then the template can easily include or exclude the\n solution based on the value of the ``solution`` template variable as\n follows:\n\n.. code:: jinja\n\n <% if solution %>\n \\printanswers\n <% endif %>\n\nLicense\n-------\n\nBSD (2-clause).", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://bitbucket.org/akhayyat/qudb", "keywords": "", "license": "BSD", "maintainer": "", "maintainer_email": "", "name": "qudb", "package_url": "https://pypi.org/project/qudb/", "platform": "UNKNOWN", "project_url": "https://pypi.org/project/qudb/", "project_urls": { "Homepage": "https://bitbucket.org/akhayyat/qudb" }, "release_url": "https://pypi.org/project/qudb/0.6/", "requires_dist": [ "jinja2", "sqlalchemy", "pyyaml (>=3.11); extra == 'import_export'" ], "requires_python": "", "summary": "qudb: Question Database", "version": "0.6" }, "last_serial": 1772553, "releases": { "0.5": [ { "comment_text": "", "digests": { "md5": "5df1f964ad98698ccdacb2098a4dc308", "sha256": "e2f6b1b17a31f7cb63b2edad4a57d76cbfd4949c1c2f007ee356c7efb4e167d9" }, "downloads": -1, "filename": "qudb-0.5-py3-none-any.whl", "has_sig": false, "md5_digest": "5df1f964ad98698ccdacb2098a4dc308", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 11543, "upload_time": "2015-05-13T23:43:20", "url": "https://files.pythonhosted.org/packages/7d/94/8c8bb1a32608350cde39411692cd1139e40297412bab1fac5ed73b40d182/qudb-0.5-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "dd6a3a0ea1f60d047fb7aca46e99a11f", "sha256": "a4c4724513ce1a486f0403cfa1c0a7604dd269243eba9d00789b0432f47eb3aa" }, "downloads": -1, "filename": "qudb-0.5.tar.gz", "has_sig": false, "md5_digest": "dd6a3a0ea1f60d047fb7aca46e99a11f", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 8674, "upload_time": "2015-05-13T23:43:24", "url": "https://files.pythonhosted.org/packages/fb/b1/4b81f5f9d2b264a0246e0ac45573dca5926ffdf1eff69034e27cb32bebba/qudb-0.5.tar.gz" } ], "0.6": [ { "comment_text": "", "digests": { "md5": "df848842c55e96f474d18633a5a57e0a", "sha256": "06e5a7d4262706823301ff6a46d7b34e867384f77ba7b86256a886438abcf690" }, "downloads": -1, "filename": "qudb-0.6-py3-none-any.whl", "has_sig": false, "md5_digest": "df848842c55e96f474d18633a5a57e0a", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 19503, "upload_time": "2015-10-16T23:02:59", "url": "https://files.pythonhosted.org/packages/93/39/563f88c229798fcd238713ea2ad943a8bd2432d885be1595c092671e63d4/qudb-0.6-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "7f7550c0624e549632f611ef4bb999d2", "sha256": "cb8fd477cfd57de43b066fbd1020e175a0202edd4980543427302d7e39bc601f" }, "downloads": -1, "filename": "qudb-0.6.tar.gz", "has_sig": false, "md5_digest": "7f7550c0624e549632f611ef4bb999d2", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19471, "upload_time": "2015-10-16T23:03:18", "url": "https://files.pythonhosted.org/packages/13/6e/8021d825472744cbaabf87d6be422a185936a71c802130f779ab076886ca/qudb-0.6.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "df848842c55e96f474d18633a5a57e0a", "sha256": "06e5a7d4262706823301ff6a46d7b34e867384f77ba7b86256a886438abcf690" }, "downloads": -1, "filename": "qudb-0.6-py3-none-any.whl", "has_sig": false, "md5_digest": "df848842c55e96f474d18633a5a57e0a", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": null, "size": 19503, "upload_time": "2015-10-16T23:02:59", "url": "https://files.pythonhosted.org/packages/93/39/563f88c229798fcd238713ea2ad943a8bd2432d885be1595c092671e63d4/qudb-0.6-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "7f7550c0624e549632f611ef4bb999d2", "sha256": "cb8fd477cfd57de43b066fbd1020e175a0202edd4980543427302d7e39bc601f" }, "downloads": -1, "filename": "qudb-0.6.tar.gz", "has_sig": false, "md5_digest": "7f7550c0624e549632f611ef4bb999d2", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 19471, "upload_time": "2015-10-16T23:03:18", "url": "https://files.pythonhosted.org/packages/13/6e/8021d825472744cbaabf87d6be422a185936a71c802130f779ab076886ca/qudb-0.6.tar.gz" } ] }