Sandbox

reset(report=<pedal.core.report.Report object>)

Resets (or initializes) the Sandbox instance for this report. Completely destroys the existing Sandbox instance attached to this report; if you want to just clear out its data, then instead use pedal.sandbox.commands.clear_sandbox().

Parameters:

report – The report to reset the Sandbox for.

File containing the Sandbox class.

TODO: Handle sys.argv

class Sandbox(report=<pedal.core.report.Report object>)

Parameters:

report (Report) – The report that this Sandbox is attached to.

data

The namespace that the context are occurring in. Note that this is mutable.

Type:

dict[str, Any]

result

TODO

output

The list of strings that have been printed to the console by print(). Note that line endings have been removed using string.rstrip().

Type:

list[str]

inputs

The list of strings that will be passed to input().

Type:

list[str]

raw_output

A concatenated string of all the text that was printed to console. No changes have been made to the text.

Type:

str

exception

The exception that occurred during the most recent execution, or None if nothing happened.

Type:

Exception or None

feedback

TODO

modules.plots

TODO

modules.turtles

TODO

target

TODO

allowed_time

How long to allow before stopping execution.

Type:

int

tracer_style

TODO

Type:

str

_context

The history of executions made in this sandbox.

Type:

list[SandboxContext]

_next_context_id

The ID of the next execution context.

Type:

int

_current_patches

A stack of patches that are currently being used. This allows recursive patching behavior.

Type:

list[Patch]

MAXIMUM_TEMPORARY_LENGTH

How long to allow arguments to be before turning them into temporary variables.

Type:

int

allow_module(module_name)

Parameters:

module_name (str)

Returns:

append_output(raw_output, context)

Adds the string of raw_output to the current raw_output attribute. The added string will be split on newlines and rstripped to append to the output attribute.

Parameters:

• raw_output (str) – The new raw_output for the sandbox. To compute the output attribute, the system splits and rstrips at newlines.

• context (pedal.sandbox.data.SandboxContext) – The currently executing context, where this output will be recorded.

block_module(module_name, friendly_name=None)

Prevent the module from being loaded in student code. Also unloads the module if it has been imported previously by destroying the variable in the current student data.

Parameters:

• module_name (str) – The name of the module to prevent, as it would be used by import (e.g., "matplotlib.pyplot").

• friendly_name (str) – A more human-readable name for the module. When accessing the module from the Sandbox, this will be the name to use.

Returns:

This sandbox.

Return type:

Sandbox

call(function, *args, target='_', threaded=None, inputs=None, function_kwargs=None, args_locals=None, kwargs_locals=None, **kwargs)

Execute the given function from the student’s namespace.

The args_locals and kwargs_locals values allow you to use student’s local variables as arguments, instead of literal values. They actually support any arbitrary Python code, it will be injected without modification.

Parameters:

• function (str) – The name of the function to call.

• *args (Any) – Any number of positional arguments to be passed to the called function.

• target (str) – The variable to assign the result of this call to. Defaults to "_".

• threaded (bool) – Whether or not to run this code in a threaded environment, which allows for timeouts.

• inputs (str or list[str])

• function_kwargs (dict[str, Any]) – Additional keyword arguments that could not be passed in directly via **kwargs (perhaps because they conflict with an existing parameter like target).

• args_locals (list[str]) – A list of names (or any valid Python expression) that will be passed as positional arguments to the function (as opposed to actual values). If any value is None (or if the list is too short), then the corresponding position argument from *args will be used instead.

• kwargs_locals (dict[str, str]) – A dictionary of keyword argument names mapped to local names (or any valid Python expression), that will be used as keyword parameters similar to args_locals.

• () (**kwargs) – Additional keyword arguments passed to the called function.

Returns:

The

result of calling the function will be returned, proxied behind a SandboxResult (which attempts to perfectly emulate that value). If the function call failed, the exception will be returned instead.

Return type:

Exception or SandboxResult

clear()

Removes any existing data in this sandbox.

clear_context()

Removes the history of any previous executions.

clear_exception()

Removes the latest exception information

clear_input()

Removes any inputs queued.

clear_mocked_function(function_name)

Removes the mocking associated with the given function name.

Parameters:

function_name (str) – The name of the function to be mocked.

clear_mocks(reset_default_mocks=True)

Removes any module or builtin overrides currently in effect.

Parameters:

reset_default_mocks (bool) – If True, also resets the default mocks (e.g., open, __import__).

clear_output()

Remove any output currently attached to this sandbox.

clear_tracer()

Stop tracing in this sandbox.

evaluate(code, target='_', threaded=None)

Evaluates the given code and assigns the result to the given target. Will cause an error if code is not a valid expression.

# TODO: Clean up syntax error.

Parameters:

• code (str or CaitNode) – The code to execute. If a CaitNode, then that will be executed directly instead of being compiled.

• target (str) – The name of the variable to assign the result to. Note that the result is also returned by this function.

• threaded (bool) – Whether or not to run this code in a threaded environment, which allows for timeouts.

Returns:

The

result of evaluating the code will be returned, proxied behind a SandboxResult (which attempts to perfectly emulate that value). If the function call failed, the exception will be returned instead.

Return type:

Exception or SandboxResult

property functions

Retrieve a list of all the callable names in the students’ namespace. In other words, get a list of all the functions the student defined.

Returns:

list of callables

get_context(context_id: int | None = None)

Retrieve the most recent contexts.

Returns:

The

most recent execution, or executions if currently in a group.

Return type:

list[pedal.sandbox.sandbox_mixins.SandboxContext]

get_function(by_name)

Creates an executable function from the given name, based on the student’s namespace. This will be executed using the call method.

get_names_by_type(type, exclude_builtins=True)

Parameters:

• type

• exclude_builtins

Returns:

get_values_by_type(type, exclude_builtins=True)

Parameters:

• type

• exclude_builtins

Returns:

get_variables_by_type(type, exclude_builtins=True)

Parameters:

• type

• exclude_builtins

Returns:

make_safe_variable(name)

Tries to construct a safe variable name in the current namespace, based off the given one. This is accomplished by appending a “_” and a number of increasing value until no comparable name exists in the namespace. This is particularly useful when you want to create a variable name to assign to, but you are concerned that the user might have a variable with that name already, which their code relies on.

Parameters:

name (str) – A desired target name.

Returns:

A safe target name, based off the given one.

Return type:

str

mock_module(module_name, new_version, friendly_name=None)

Create a mocked version of this module.

reset_default_overrides()

Resets the list of blocked functions and modules to its starting state. This blocks compile, eval, exec, globals, and provides mocked versions of open and import that are more restricted. It also blocks the pedal module.

run(code=None, filename=None, inputs=None, threaded=None, after=None, before=None, real_io=False)

If both code and filename are None, then the submission’s main file will be executed. If code is given but filename is not, then it is assumed to be instructor code.

TODO: This should actually return the ExecutionContext that was generated, right?

But the user should be able to treat that as if it were the Sandbox…

Parameters:

• real_io – If True, makes print and input actually write to stdout.

• code (str or CaitNode or None) – The code to execute.

• filename (str or None) – The filename to use for this code.

• inputs (list[str]) – Optional inputs to be passed to set_input().

• threaded (bool) – Whether or not to run this code in a threaded environment, which allows for timeouts.

• after (str) – Code to run after this code (without a filename).

• before (str) – Code to run before this code (without a filename).

Returns:

This sandbox instance.

Return type:

Sandbox

set_input(inputs, clear=True)

Queues the given value as the next arguments to the input function.

set_student_data(new_data)

Overwrites the existing student data with the keys and values from the new_data. This copies the data over, but does not modify the reference to data’s dictionary.

Parameters:

new_data (dict[str, Any]) – The new data.

Returns:

start_grouping_context()

Any subsequent executions will be grouped.

stop_grouping_context()

Stop grouping subsequent executions.

property var

Returns:

Generic runtime exception feedback class.

TODO: Use the FeedbackRegistry to properly dispatch the appropriate runtime_error type, instead of reusing the base object

class attribute_error(exception, context, traceback, location, **kwargs)

Runtime AttributeError

class import_error(exception, context, traceback, location, **kwargs)

Runtime ImportError

class indentation_error(exception, context, traceback, location, **kwargs)

Syntax IndentationError

class index_error(exception, context, traceback, location, **kwargs)

Runtime IndexError

class io_error(exception, context, traceback, location, **kwargs)

Runtime IOError

class key_error(exception, context, traceback, location, **kwargs)

Runtime KeyError

class memory_error(exception, context, traceback, location, **kwargs)

Runtime MemoryError

class name_error(exception, context, traceback, location, **kwargs)

Runtime NameError

class runtime_error(exception, context, traceback, location, **kwargs)

Used to create all runtime errors.

exception

The original exception.

Type:

Exception

exception_name

The original name of the exception.

Type:

str

exception_message

the original error message from the exception.

Type:

str

traceback

An enhanced version of the builtin Traceback object. Has a number of additional fields.

Type:

ExpandedTraceback

traceback_message

A nicely formatted version of the traceback.

Type:

str

context

The history of inputs, outputs, executed code, and other information from when this runtime error occurred. Usually just a single element, but sometimes longer if created in a grouping context. If the code was run from a file, then the filename is given.

Type:

list[SandboxContext]

class timeout_error(exception, context, traceback, location, **kwargs)

Runtime TimeoutError

class type_error(exception, context, traceback, location, **kwargs)

Type Error

class value_error(exception, context, traceback, location, **kwargs)

Runtime ValueError

class zero_division_error(exception, context, traceback, location, **kwargs)

Runtime ZeroDivisionError

The collection of top-level commands for the Sandbox module. Note that most of these simply act on the current MAIN_REPORT’s Sandbox instance, without doing any logic themselves.

class CommandBlock(report=<pedal.core.report.Report object>)

Context Manager for creating instructor blocks of code that will be shown together to the student.

TODO: What about named points where you can “rewind” the state to?

allow_function(function_name, report=<pedal.core.report.Report object>)

Explicitly allow students to use the given function.

allow_module(module_name, report=<pedal.core.report.Report object>)

Explicitly allow students to use the given module.

allow_real_io(report=<pedal.core.report.Report object>)

Allow the input() and print() functions to actually write to the real stdout. By default, Pedal will block this kind of writing/reading normally (although students can still use those functions).

block_function(function_name, report=<pedal.core.report.Report object>)

Cause an error if students call the given function.

block_module(module_name, report=<pedal.core.report.Report object>)

Cause an error if students use the given module.

block_real_io(report=<pedal.core.report.Report object>)

Explicitly block students from using the input() and print() functions to write/read to the real stdout. This does not prevent them from using the functions, but it does prevent the output from appearing in the real console.

call(function, *args, target='_', threaded=None, inputs=None, function_kwargs=None, args_locals=None, kwargs_locals=None, report=<pedal.core.report.Report object>, **kwargs)

Execute the given function from the student’s namespace.

The args_locals and kwargs_locals values allow you to use student’s local variables as arguments, instead of literal values. They actually support any arbitrary Python code, it will be injected without modification.

Parameters:

• function (str) – The name of the function to call.

• *args (Any) – Any number of positional arguments to be passed to the called function.

• target (str) – The variable to assign the result of this call to. Defaults to "_".

• threaded (bool) – Whether or not to run this code in a threaded environment, which allows for timeouts.

• inputs (str or list[str])

• function_kwargs (dict[str, Any]) – Additional keyword arguments that could not be passed in directly via **kwargs (perhaps because they conflict with an existing parameter like target).

• args_locals (list[str]) – A list of names (or any valid Python expression) that will be passed as positional arguments to the function (as opposed to actual values). If any value is None (or if the list is too short), then the corresponding position argument from *args will be used instead.

• kwargs_locals (dict[str, str]) – A dictionary of keyword argument names mapped to local names (or any valid Python expression), that will be used as keyword parameters similar to args_locals.

• () (**kwargs) – Additional keyword arguments passed to the called function.

• report (pedal.core.report.Report) – The report with the sandbox instance.

Returns:

The

result of calling the function will be returned, proxied behind a SandboxResult (which attempts to perfectly emulate that value). If the function call failed, the exception will be returned instead.

Return type:

Exception or SandboxResult

check_coverage(report=<pedal.core.report.Report object>)

Checks that all the statements in the program have been executed. This function only works when a tracer_style has been set in the sandbox, or you are using an environment that automatically traces calls (e.g., BlockPy).

Parameters:

report (Report) – The Report to draw source code from; if not given, defaults to MAIN_REPORT.

Returns:

If the source file was not parsed, None is returned.

Otherwise, returnes the set of unexecuted lines.

float: The ratio of unexected to total executable lines.

Return type:

set[int]

clear_input(report=<pedal.core.report.Report object>)

Removes any existing inputs set up for the sandbox.

Parameters:

report (pedal.core.report.Report) – The report to clear inputs for

clear_mocks(report=<pedal.core.report.Report object>)

Reset mocked modules and functions to their defaults.

clear_output(report=<pedal.core.report.Report object>)

Removes any existing outputs associated with the sandbox.

Parameters:

report (pedal.core.report.Report) – The report to clear outputs for.

clear_sandbox(report=<pedal.core.report.Report object>)

Removes any existing data within the current sandbox instance.

clear_student_data(report=<pedal.core.report.Report object>)

Removes any data in the student namespace.

Parameters:

report (pedal.core.report.Report) – The report to clear the data for.

count_unique_calls(function_name, report=<pedal.core.report.Report object>)

Counts how many times the given function was called with unique arguments. TODO: What about also tracking the number of “top-level” calls? So we know

whether they were actually testing it explicitly or not.

Parameters:

• function_name (str) – The name of the function to check for calls.

• report (pedal.core.report.Report) – The report with the sandbox instance.

Returns:

The number of unique calls

Return type:

int

evaluate(code, target='_', threaded=None, report=<pedal.core.report.Report object>)

Evaluates the given code and assigns the result to the given target. Will cause an error if code is not a valid expression.

Parameters:

• code (str or CaitNode) – The code to execute. If a CaitNode, then that will be executed directly instead of being compiled.

• target (str) – The name of the variable to assign the result to. Note that the result is also returned by this function.

• threaded (bool) – Whether or not to run this code in a threaded environment, which allows for timeouts.

• report (pedal.core.report.Report) – The report with the sandbox instance.

Returns:

The

result of evaluating the code will be returned, proxied behind a SandboxResult (which attempts to perfectly emulate that value). If the function call failed, the exception will be returned instead.

Return type:

Exception or SandboxResult

get_call_arguments(function_name, report=<pedal.core.report.Report object>)

Retrieves all the arguments that were passed into the given function when it was called.

Parameters:

• function_name (str) – The name of the function to check.

• report (pedal.core.report.Report) – The report with the sandbox instance.

Returns:

The outer list will have any entry for each function call.

The inner list will be the arguments passed into that call. Pretty sure that any *args and **kwargs are the last elements of that list, if they exist.

Return type:

list[dict[str, any]]

get_exception(report=<pedal.core.report.Report object>)

Returns an exception if one occurred during the last execution, otherwise returns None.

Parameters:

report (pedal.core.report.Report) – The report to get the exception for.

Returns:

The exception that occurred, or None if no exception

Return type:

Exception or None

get_function(function_name, report=<pedal.core.report.Report object>)

Creates an executable function from the given name, based on the students’ namespace. This will be executed using the call method.

get_input(report=<pedal.core.report.Report object>)

Retrieves the current inputs that are available for execution.

Parameters:

report (pedal.core.report.Report) – The report with the sandbox instance.

Returns:

The current list of inputs available for execution. The first

element of this list is the next string that will be passed to the next student call of input().

Return type:

list[str]

get_module(module_name, report=<pedal.core.report.Report object>)

Loads the data for the given mocked module, if available (otherwise raises exception)

get_output(report=<pedal.core.report.Report object>)

Retrieves the current output (whatever the student has printed) since execution began.

Parameters:

report (pedal.core.report.Report) – The report to get the output for.

Returns:

The current output.

Return type:

list[str]

get_python_errors(report=<pedal.core.report.Report object>)

Retrieves any runtime or syntax errors from the report. :param report:

Returns:

A list of runtime and syntax errors that were detected

Return type:

list[Feedback]

get_raw_output(report=<pedal.core.report.Report object>)

Retrieves the current output (whatever the student has printed) since execution began, without any formatting. The result is a single string.

Parameters:

report (pedal.core.report.Report) – The report to get the output for.

Returns:

The current output.

Return type:

str

get_sandbox(report=<pedal.core.report.Report object>)

Retrieves the current sandbox instance attached to this report. Typically, this is used to retrieve the sandbox without running the students’ code.

Parameters:

report (pedal.core.report.Report) – The report with the sandbox instance.

Returns:

The sandbox instance.

Return type:

pedal.sandbox.Sandbox

get_student_data(report=<pedal.core.report.Report object>)

Retrieves the current data in the student namespace. Note that this is the data itself - modifying the dictionary will modify the data in the students’ namespace for subsequent executions!

Parameters:

report (pedal.core.report.Report) – The report with the sandbox instance.

Returns:

The student’s data namespace, mapping names to the

values themselves.

Return type:

dict[str, Any]

get_trace(report=<pedal.core.report.Report object>)

Retrieves the list of line numbers that have been traced (recognized as executed).

Parameters:

report (pedal.core.report.Report) – The report with the sandbox instance.

Returns:

The list of lines that have been executed in the student’s

code.

Return type:

list[int]

mock_function(function_name, new_version, report=<pedal.core.report.Report object>)

Provide a custom version of the built-in function.

mock_module(module_name, new_version, friendly_name=None, report=<pedal.core.report.Report object>)

Provide an alternative version of the given module.

Parameters:

• module_name (str) – The importable name of the module.

• new_version (dict | pedal.sandbox.mocked.MockModule) – The new version of the module, either as a dictionary of fields/values or a fully created MockModule.

• friendly_name (str) – The internal name to use to store the data for this module, accessible via Sandbox’s modules field.

• report (pedal.core.report.Report) – The report with the sandbox instance.

queue_input(*inputs, report=<pedal.core.report.Report object>)

Adds the given *inputs to be used as input during subsequent

executions (e.g., pedal.sandbox.commands.run()) if the student’s code calls input(). This does not remove existing inputs.

Parameters:

• *inputs (str) – One or more strings that will be set. The first string passed in is the first string that will be passed in as input.

• report (pedal.core.report.Report) – The report with the sandbox instance.

reset_output(report=<pedal.core.report.Report object>)

Removes any existing outputs associated with the sandbox.

Parameters:

report (pedal.core.report.Report) – The report to clear outputs for.

run(code=None, filename=None, inputs=None, threaded=None, after=None, before=None, report=<pedal.core.report.Report object>)

If both code and filename are None, then the submission’s main file will be executed. If code is given but filename is not, then it is assumed to be instructor code.

Parameters:

• code (str or CaitNode or None) – The code to execute.

• filename (str or None) – The filename to use for this code.

• inputs (list[str]) – Optional inputs to be passed to set_input().

• threaded (bool) – Whether to run this code in a threaded environment, which allows for timeouts.

• after (str) – Code to run after this code (without a filename).

• before (str) – Code to run before this code (without a filename).

• report (pedal.core.report.Report) – The report with the sandbox instance.

Returns:

The sandbox instance that this was run in.

Return type:

Sandbox

set_input(inputs, clear=True, report=<pedal.core.report.Report object>)

Sets the given inputs to be used as input during subsequent

executions (e.g., pedal.sandbox.commands.run()) if the student’s code calls input(). Unless the clear parameter is set to False, this removes existing inputs.

Parameters:

• inputs (str or list[str]) – One or more strings that will be set. The first string passed in is the first string that will be passed in as input.

• clear (bool) – Whether or not to remove any existing inputs set up in the sandbox.

• report (pedal.core.report.Report) – The report with the sandbox instance.

start_trace(tracer_style='native', report=<pedal.core.report.Report object>)

Start tracing using the coverage module.

stop_trace(report=<pedal.core.report.Report object>)

Stop whatever tracing is going on.