Library

The algoesup library provides support for testing, timing and linting code. This documentation is for version 0.4.

Testing

Simplified testing for Python functions, see the examples.

test

test(
    function: Callable,
    test_table: list | tuple,
    min: int = 1,
    max: int = 0,
) -> None

Test function with test_table. Report errors in the table and failed tests.

This function checks that:

• the table is a list or tuple with at least min tests
• the table has at most max tests (if max is greater than 0)
• each test is a list or tuple with a string followed by one or more values
• each test has the expected number of inputs (if function has fixed arguments).

Parameters:

Name	Type	Description	Default
function	Callable	The function or method to be tested.	required
test_table	list | tuple	The sequence of tests, each one a list or tuple with: a string (the test name); zero or more values (the inputs to the function); the expected output value.	required
min	int	Minimum number of tests in the table. Default is 1.	1
max	int	Maximum number of tests in the table. Default is 0 (no maximum).	0

check_tests

check_tests(
    test_table: list | tuple,
    types: list = [],
    min: int = 1,
    max: int = 0,
) -> None

Check the structure of test_table and print any error messages.

Use this instead of test() if the function to be tested is not yet implemented or if you want to provide specific input and output types.

This function calls check_table and prints the returned error messages.

Parameters:

Name	Type	Description	Default
test_table	list | tuple	The sequence of tests, each one a list or tuple with: a string (the test name); zero or more values (the inputs to the function); the expected output value.	required
types	list	Expected types of the inputs and output. Set this argument only if the number and order of inputs are fixed.	[]
min	int	Minimum number of tests in the table. Default is 1.	1
max	int	Maximum number of tests in the table. Default is 0 (no maximum).	0

check_table

check_table(
    test_table: list | tuple,
    types: list = [],
    min: int = 1,
    max: int = 0,
) -> list[str]

Check the structure of test_table and return a list of error messages.

This auxiliary function does the checks for check_tests and test:

• the table is a list or tuple with at least min tests
• the table has at most max tests (if max is greater than 0)
• each test is a list or tuple with a string followed by one or more values
• each input and output value has the expected type (if types is given).

Parameters:

Name	Type	Description	Default
test_table	list | tuple	The sequence of tests, each one a list or tuple with: a string (the test name); zero or more values (the inputs to the function); the expected output value.	required
types	list	Expected types of the inputs and output. Set this argument only if the number and order of inputs are fixed.	[]
min	int	Minimum number of tests in the table. Default is 1.	1
max	int	Maximum number of tests in the table. Default is 0 (no maximum).	0

Returns:

Type	Description
list[str]	list[str]: The error messages. The list is empty if the table is well defined.

Timing

Tools for measuring and plotting run-times, see the examples.

time_functions

time_functions(
    functions: list[Callable],
    inputs: Callable,
    start: int,
    double: int,
    text: bool = True,
    chart: bool = False,
    value: bool = False,
) -> None

Print or plot the run-times of different functions for the same inputs.

time_functions prints or plots the run-times given list of functions and an input generator. Inputs are generated based on a starting size and are doubled a specified number of times.

Parameters:

Name	Type	Description	Default
functions	list[Callable]	A list of functions whose run-times will be measured. Must be 1 to 6 functions.	required
inputs	Callable	A function to generate inputs when given a specific size.	required
start	int	The starting size for the inputs. Must be positive.	required
double	int	The number of times to double the input size. Must be non-negative.	required
text	bool	If True, print the run-times in text format	True
chart	bool	If True plot the run-times using a chart.	False
value	bool	If True x-axis is labelled “Input value” otherwise “Input size”.	False

Raises:

Type	Description
AssertionError	If input conditions are not satisfied.

time_cases

time_cases(
    function: Callable,
    cases: list[Callable],
    start: int,
    double: int,
    text: bool = True,
    chart: bool = False,
) -> None

Print or plot the run-times of function for different input cases.

time_cases prints or plots the run-times of a single function using a list of different input generators. Inputs are generated based on a starting size and are doubled a specified number of times.

Parameters:

Name	Type	Description	Default
function	Callable	A function whose run-times will be measured.	required
cases	list[Callable]	A list of 1 to 6 functions to generate inputs of different cases, e.g. best-, normal- and worst-case.	required
start	int	The starting size for the inputs. Must be positive.	required
double	int	The number of times to double the input size. Must be non-negative.	required
text	bool	If True, print the run-times in text format.	True
chart	bool	If True, plot the run-times using a chart.	False

Raises:

Type	Description
AssertionError	If input conditions are not satisfied.

time_functions_int

time_functions_int(
    functions: list[Callable],
    generator: Callable = int_value,
    start: int = 1,
    double: int = 10,
    text: bool = True,
    chart: bool = True,
) -> None

Time functions that take a single integer as input.

time_functions_int uses time_functions to measure and display the run-times of a given list of functions that accept a single integer input. The integer inputs are generated starting from a specified value that defaults to 1, and are doubled a specified number of times that defaults to 10.

Parameters:

Name	Type	Description	Default
functions	list[Callable]	A list of functions whose run-times will be measured. Each function must accept a single integer argument. Must be 1 to 6 functions.	required
generator	Callable	A function to generate integer inputs. Defaults to int_value, which returns a tuple containing the input integer.	int_value
start	int	The starting integer value for inputs. Defaults to 1. Must be positive.	1
double	int	The number of times to double the input integer value. Defaults to 10. Must be non-negative.	10
text	bool	If True, print the run-times in text format.	True
chart	bool	If True, plot the run-times using a chart.	True

Linting

Linting tools for Jupyter Notebook environments.

See the type checking and linting examples.

allowed

allowed

Activate/deactivate the allowed linter.

When active, the linter checks each code cell that is executed for any Python constructs that are not listed in the given configuration file.

• %allowed on ... activates the linter with any command options given after on
• %allowed on is equal to %allowed on --config m269.json
• %allowed off deactivates the linter
• %allowed shows the current status of the linter
• %allowed? shows this documentation and the command’s options

For a list of possible options ..., enter !allowed -h in a code cell. Some options may not be appropriate when running allowed within a notebook.

The --config option expects m269.json, tm112.json or the name of a JSON file with your own configuration.

pytype

pytype

Activate/deactivate the pytype linter.

When active, the linter checks each code cell that is executed for type errors.

• %pytype on ... activates the linter with the command options given after on
• %pytype on is equal to %pytype on --disable name-error,import-error
• %pytype off deactivates the linter
• %pytype shows the current status of the linter
• %pytype? shows this documentation and the command’s options

For a list of possible options ..., enter !pytype -h in a code cell. Some options may not be appropriate when running pytype within a notebook.

The --disable option expects a list of errors to ignore, without spaces. By default, %pylint ignores these errors:

• name-error: cells often use names defined in previous cells
• import-error: pytype doesn’t find local modules

ruff

ruff

Activate/deactivate the Ruff linter.

When active, the linter checks each code cell that is executed against the selected code style rules.

• %ruff on ... activates the linter with any command options given after on
• %ruff on is equal to %ruff on --select A,B,C90,D,E,W,F,N,PL --ignore D100,W292,F401,F821,D203,D213,D415
• %ruff off deactivates the linter
• %ruff shows the current status of the linter
• %ruff? shows this documentation

The command %ruff on ... will run ruff check --output-format json ... on each cell. For a list of the possible options ..., enter !ruff help check in a code cell. Some options may not be appropriate when running Ruff within a notebook.

By default, %ruff enables the rules from flake8-builtins (A), flake8-annotations (ANN), flake8-bugbear (B), mccabe (C90), pydocstyle (D), pycodestyle (E, W), pyflakes (F), pep8-naming (N), pylint error (PLE).

By default, %ruff ignores these rules:

• D100: Missing docstring in public module (notebooks aren’t modules)
• W292: No newline at end of file (cells don’t have a trailing blank line)
• F401: Imported but unused (cells often import modules that are used later)
• F821: Undefined name (cells often use names defined in previous cells)
• D203: use D211 instead (no blank line before class docstring)
• D213: use D212 instead (docstring starts right after “”“)
• D415: use D400 instead (first line of docstring must end in .)

To ignore or select rules on top of the defaults, use option --extend-ignore or --extend-select. To ignore or select rules instead of the defaults, use option --ignore or --select. These four options expect a list of rule codes, without spaces. For example, %ruff on --ignore D203,D213 --select D,E,W will only check pydocstyle and pycodestyle rules, except the two given rules, i.e it will check W292.