API du module capytale

The Capytale module should be used only with the Basthon’s Python 3 kernel on the Capytale server.

Look at the sub-modules” documentation for specific details.

capytale.random

Coherent randomness across multiple activities.

capytale.random.user_seed()

Get a user attached seed to pass to Python’s random.seed. This is useful to reproduce the same randomness across multiple activities (e.g. correction).

It takes care of the user status in the sens that when a teacher runs the student’s activity, it gets the student’s seed.

Usage:

import random
from capytale.random import user_seed

random.seed(a=user_seed())

Return type:

None

capytale.autoeval

The module autoeval is often use in the context of a sequenced notebook but this is not mandatory.

All the machinery to manage autoevalutation in Capytale.

capytale.autoeval.equality(a, b, rel_tol=1e-09, abs_tol=0.0)

Test the equality between a and b by carrefuly looking at the type. Float equality is done by math.isclose() using rel_tol and abs_tol.

Parameters:

• a (TypeVar(T)) – fist value to compare.

• b (TypeVar(T)) – second value to compare.

• rel_tol (float) – used only for float comparison, see math.isclose().

• abs_tol (float) – used only for float comparison, see math.isclose().

Return type:

bool

capytale.autoeval.validationclass(theclass)

Use this decorator on all your validation classes.

It makes it work in the context of a sequenced notebook, automatically implements the trial counter, verify it inherit from Validate, …

Return type:

Type[Validate]

class capytale.autoeval.Validate(ignore_breakpoint=False, label=None)

Bases: object

The base class for auto-evaluation.

You should use the @validationclass decorator to implement your own validation process. It automatically makes your class derives from :class`Validate`. Otherwise, you could directly use a dedicated class like ValidateFunction or ValidateVariables.

In the context of a sequenced notebooks, it implements the breakpoint cell validation process in the __call__() method. This method should return True in order to validate a cell and display all the cells until the next breakpoint cell.

It is important to create a new Validate object for each breakpoint code cell. Two breakpoint code cells can’t share the same Validate object.

The default implementation of __call__() returns True. This is useful for automatic breakpoint validation.

Parameters:

• ignore_breakpoint (bool) – if set to True in the context of a sequenced notebook, we do not go to the next breakpoint after a success. Useful to have several tests in the same cell.

• label (Optional[str]) – an (optional) id to identify the validation.

ignore_breakpoint(value=True)

Enable/disable the pass through breakpoint process in a sequenced notebook.

trial_count()

Number of validation attempts i.e. number of call to __call__().

Return type:

int

class capytale.autoeval.ValidateSequences(values, targets, **kwargs)

Bases: Generic[V, T], Validate

Validate the equality between targets and results associated with values. This is the base class for ValidateFunction and ValidateVariables. It is not intended to be used directly but to be derived.

The testing process is launched by calling the object.

Initialise inputs and disered outputs. Raise ValueError if values and targets differ in length.

Parameters:

• values (Iterable[TypeVar(V)]) – input values used to compute results using compute_result()

• targets (Iterable[TypeVar(T)]) – the corresponding target results

• **kwargs – passed to parent constructor.

equality(a, b, rel_tol=1e-09, abs_tol=0.0)

Test the equality by carrefuly looking at the type. Default implementation uses equality().

Return type:

bool

handle_failure(value, target, result)

This method is called when the result computed by compute_result() using value is different from the target. It is intended to be overridden.

Parameters:

• value (TypeVar(V)) – the value that caused the error

• target (TypeVar(T)) – the corresponding target

• result (TypeVar(T)) – the computed result

Return type:

bool

Returns:

Indicate whether we continue the testing process or not. If the return value is True, the testing process continue, otherwise, it stops.

handle_exception(exc, value, target)

This method is called when the call of compute_result() on value raises an exception. It is intended to be overridden.

Parameters:

• exc (Exception) – the raised exception

• value (TypeVar(V)) – the value that caused the error

• target (TypeVar(T)) – the corresponding target

Return type:

bool

Returns:

Indicate whether we continue the testing process or not. If the return value is True, the testing process continue, otherwise, it stops.

handle_partial_success()

This method is called at the end of the testing process, when at least one error occurred (different target and result or exception raised). It is intended to be overridden.

handle_success(value, target, result)

This method is called when the result computed by compute_result() using value is equal to the target (wrt. equality()). It is intended to be overridden.

Parameters:

• value (TypeVar(V)) – the value used to compute the result

• target (TypeVar(T)) – the corresponding target

• result (TypeVar(T)) – the computed result

Return type:

None

handle_full_success()

This method is called at the end of the testing process, when all tests succeeded. It is intended to be overridden.

precompute()

Precompute data before a test session. It is intended to be overridden.

Return type:

Any

Returns:

Any precomputed data that should be passed to compute_result().

handle_precompute_exception(exc)

Handle an exception occurring during the precompute process.

Parameters:

exc (Exception) – the exception raise by the call to precompute.

Return type:

None

compute_result(value, precomputed_data)

Computes the result corresponding to value.

Parameters:

• value (TypeVar(V)) – the value used to compute the desired result

• precomputed_data (Any) – data returned by precompute()

Return type:

TypeVar(T)

Returns:

The result corresponding to value.

class capytale.autoeval.ValidateVariables(names_and_values, **kwargs)

Bases: ValidateSequences[str, Any]

A class to validate user defined variables.

To customize this class, have a look at ValidateSequences.

Parameters:

• names_and_values (dict[str, Any]) – a dict with variable names as key and desired values as values to test against variables defined in the user namespace (top-level).

• **kwargs – passed to parent constructor.

class capytale.autoeval.ValidateFunction(func_name, test_values, target_values=None, valid_function=None, argcount=None, check_signature=False, ignore_names_in_signature=False, **kwargs)

Bases: ValidateSequences[V, T]

A class to validate a function. The tested function could had any number of parameters.

To customize this class, have a look at ValidateSequences.

Parameters:

• func_name (str) – the name of the function to test in the user namespace (top-level)

• test_values (Iterable[TypeVar(V)]) – values to test the function on ; for function with several parameters, use list or tuple

• return_values – target values that can be computed from valid_function if return_values is omitted.

• valid_function (Optional[Callable[..., TypeVar(T)]]) – a function to compute target values if target_values is None.

• argcount (Optional[int]) – the number of arguments given to the function ; if None, it is guessed from the test values

• check_signature (Union[bool, Signature]) – indicate if we have to check the signature in the validation process ; the signature is taken from valid_function or directly passed through check_signature

• ignore_names_in_signature (bool) – indicate if we have to worry about wrong parameter name in the function’s signature

• **kwargs – passed to parent constructor.

class capytale.autoeval.ValidateFunctionPretty(func_name, test_values, target_values=None, valid_function=None, argcount=None, check_signature=False, ignore_names_in_signature=False, **kwargs)

Bases: ValidateFunction[V, T]

Similar to ValidateFunction but with all test results sumurized in a pretty html table.

To customize this class, have a look at ValidateSequences.

Parameters:

• func_name (str) – the name of the function to test in the user namespace (top-level)

• test_values (Iterable[TypeVar(V)]) – values to test the function on ; for function with several parameters, use list or tuple

• return_values – target values that can be computed from valid_function if return_values is omitted.

• valid_function (Optional[Callable[..., TypeVar(T)]]) – a function to compute target values if target_values is None.

• argcount (Optional[int]) – the number of arguments given to the function ; if None, it is guessed from the test values

• check_signature (Union[bool, Signature]) – indicate if we have to check the signature in the validation process ; the signature is taken from valid_function or directly passed through check_signature

• ignore_names_in_signature (bool) – indicate if we have to worry about wrong parameter name in the function’s signature

• **kwargs – passed to parent constructor.