Metadata-Version: 1.2
Name: pedal
Version: 2.0.0
Summary: Tools to provide feedback on student code.
Home-page: https://pedal-edu.github.io/pedal
Author: acbart,lukesg08
Author-email: acbart@udel.edu
License: Creative Commons Attribution-Noncommercial-Share Alike license
Description: Pedal
        =====
        
        A collection of tools to analyze student's work in a pipeline. Pedal not only provides some of these tools, but it provides a *framework* around those tools.
        
        Installation
        ============
        
        Install from PyPi::
            
            pip install pedal
        
        Or install from the https://github.com/acbart/pedal
        
        Important Concepts
        ==================
        
        .. image:: docs/html/_static/pedal-overview.png
        
        * *Report*: A collection of Feedback and a namespace for the results of Tools, accessible by the Tool name. Reports can be generated imperatively (using the default Report, similar to MatPlotLib) or by explicitly creating and passing Report objects.
        * *Tool*: A system that can read and write to a Report, building on the work of previous Tools.
        * *Resolver*: A system that can analyze a Report and create a relevant bit of output for another system (e.g., BlockPy, Web-CAT).
        * *Feedback*: A structured representation of content to be delivered to a student in response to their submission of work.
        
        We base our idea of "Feedback" on concepts established by Narciss 2006. Our Feedback objects are composed of up to 7 components:
        
        * result (bool): Whether or not this feedback is associated with the learner completing the task ("Success!")
        * performance (float): A relative amount that this feedback contributes to the students' performance (think in terms of partial credit, like "Triggering this feedback is worth 20%").
        * misconceptions (Component): A description of the misconception that is believed to be in the student's mind, or perhaps the relevant concept from the material that should be associated with this. ("Variables must be initialized before they are used.")
        * mistakes (Component): A description of the error or bug that the student has created ("NameError on line 5: sum has not been defined")
        * hints (Component): A suggestion for what the student can do ("Initialize the sum variable one line 1")
        * constraints (Component): A description of the task requirements or task type that the student has violated ("You used a for loop, but this question expected you to use recursion.")
        * metacognitives (Component): A suggestion for more regulative strategies ("You have been working for 5 hours, perhaps it is time to take a break?")
        
        One of these components is described by the following union type, where a Component is one of:
        
        * A str field representing renderable text for a student
        * An object with a "message (str)" field of renderable text for a student, along with whatever other fields are useful (e.g., the line number of the error)
        * A list of Components
        
        Additionally, a given Feedback object has the following metadata:
        
        * label (str): An internal name for this specific piece of feedback. This is particularly useful for us for research purposes (we currently show it in italics as part of the message)
        * tool (str): An internal name for indicating the tool that created this feedback (e.g., "tifa" or "source")
        * category (str): A human-presentable name showable to a student (this is like the "Analyzer Error" message in the top left of our BlockPy boxes).
        * priority (str): An indication of how important this feedback is. Might be "high/medium/low" or the name of a category to supersede.
        
        Tools
        =====
        
        Source
        ------
        
        .. code:: python
        
          from pedal.source import set_source
          STUDENT_CODE = "message='Hello World'\nprint(message)"
          set_source(STUDENT_CODE)
        
        One of the simplest tools, the Source tool provides a function for attaching source code to a Report. It is a requirement for any tool that wants to do code analysis. But notice that this tool is not required in general - you could find other ways to attach code (e.g., a History tool that attaches all previous code written) or other aspects of the students' performance (e.g., a Demographics tool to attach bio-data about the student).
        
        TIFA
        ----
        
        .. code:: python
        
            from pedal.tifa import tifa_analysis
            tifa_analysis()
        
        Tifa is a Type Inferencer and Flow Analyzer. Its goal is not to be a general purpose tool for doing so, but to be focused on simplistic code written in pedagogical settings. This means that it can make a lot of assumptions and forbid a lot of features. Further, it's primary job is not just to collect type information, but to detect issues in the code (e.g., a variable changes type, a variable is not read, a variable is defined in one scope then used in another).
        
        CAIT
        ----
        
        .. code:: python
        
            from pedal.cait import parse_program, find_matches
            root = parse_program()
            # ... or ...
            matches = find_matches("_var_ = __expr__")
        
        Capturer for AST Inclusion Trees. Its goal is to take a a desired AST and a target AST, and captures trees in the target ast that include the desired AST. A metaphor might be "Regular Expressions for source code".
        
        Mistakes
        --------
        
        .. code:: python
        
            from pedal.mistakes.instructor_iteration import *
            missing_for_slot_empty()
            # ...
        
        A collection of code configuration patterns that represent common mistakes for students. These mistakes are grouped together by topics.
        
        Toolkit
        -------
        
        .. code:: python
            
            from pedal.toolkit.utilities import *
            prevent_operation('+')
            ensure_literal(7)
            
            from pedal.toolkit.functions import function_signature
            function_signature('search', needle='str', haystack='list[str]',
                               returns='bool')
        
        A collection of helper functions to analyze student code, such as detecting incorrectly closed files, preventing the use of certain operators or literals, checking function signatures, and rudimentary unit testing functionality.
        
        Sandbox
        -------
        
        .. code:: python
        
            from pedal.sandbox import run
            student = run()
            result_should_be_6 = student.call('add3', 1, 2, 3)
        
        A sophisticated system for executing students' code under different circumstances. Relies on the `exec` and `patch` tools of Python to prevent students from escaping their namespace.
        
        However, you should be aware that true sandboxing is impossible in a dynamic language like Python. Be sure that your environment has multiple lines of defense, such as proper file system permissions.
        
        Resolvers
        =========
        
        Simple
        ------
        
        .. code:: python
            
            from pedal.resolvers import simple
            
            print(simple.resolve())
        
        This resolver finds the highest priority message to deliver to the student, depending on a pre-established bit of logic for tools.
        
        Others
        ------
        
        Other resolvers are possible - we could find the first, or deliver more than one (grouped using HTML formatting).
        
        Plugins
        =======
        
        Plugins can be used to better integration with external environments, or for utility scripts.
        
        VPL
        ---
        
        Strips out HTML
        
        Jupyter Notebooks
        -----------------
        
        Grade magic, tools for syncing problem with BlockPy
        
        BlockPy
        -------
        
        See BlockPy for more information
        
        Web-CAT
        -------
        
        No special connections anymore!
        
        Reference Checks
        ----------------
        
        Unit testing harness for verifying instructor tests produce the expected output when given various student files.
        
Keywords: feedback education teaching program analysis tifa cait sandbox pedal grading grader grade
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Education
Classifier: Topic :: Education
Requires-Python: >=3.5
