DocTAPE

DocTAPE (Documentation Testing and Automated Placement of Expressions) is a collection of utility functions (and wrappers for Glue) that are useful for automating the process of building and testing documentation to ensure that documentation doesn’t get stale.

Our standard practice it to include a comment (# Testing Cell) at the begining of code cells as well as make use of the remove-cell tag.

“metadata”: { “tags”: [ “remove-cell” ] },

More info about adding cell tags

• Jupyter Book

• Visual Studio Code

Classes

• expected_error is an execption that can be used in try/except blocks to allow desired errors to pass while still raising unexpected errors.

Testing Functions

Functions that raise an error provide the option to specify an error type to use instead of the default. This allows users to change the error type that is raised which can be useful in try/except blocks, especially when combined with the expected_error class.

aviary.utils.doctape.check_value(val1, val2, error_type=<class 'ValueError'>)

Compares two values and raises a ValueError if they are not equal.

This method checks whether the provided values are equal. For primitive data types such as strings, integers, floats, lists, tuples, dictionaries, and sets, it uses the equality operator. For other types, it uses identity comparison.

Parameters:

• val1 (any) – The first value to be compared.

• val2 (any) – The second value to be compared.

• error_type (Exception, optional) – The exception to raise (default is ValueError)

Raises:

ValueError – If the values are not equal (or not the same object for non-primitive types).

aviary.utils.doctape.check_contains(expected_values, actual_values, error_string='{var} not in {actual_values}', error_type=<class 'RuntimeError'>)

Checks that all of the expected_values exist in actual_values (It does not check for missing values)

Parameters:

• expected_values (any iterable) – This can also be a single value, in which case it will be wrapped into a list

• actual_values (any iterable)

• error_string (str, optional) – The string to display as the error message, kwarg substitutions will be made using .format() for “var” and “actual_values”

• error_type (Exception, optional) – The exception to raise (default is RuntimeError)

Raises:

RuntimeError – If a value in expected_values is not present in actual_values

aviary.utils.doctape.check_args(func, expected_args: tuple[list, dict, str], args_to_ignore: tuple[list, tuple] = ['self'], exact=True, error_type=<class 'ValueError'>)

Checks that the expected arguments are valid for a given function.

This method verifies that the provided expected_args match the actual arguments of the given function func. If exact is True, the method checks for an exact match. If exact is False, it only checks that the provided expected_args are included in the actual arguments (it won’t fail if the function has additional arguments).

Parameters:

• func (function) – The function whose arguments are being checked.

• expected_args (list, dict, or str) – The expected arguments. If a dict, the values will be compared to the default values. If a string, it will be treated as a single argument of interest. (exact will be set to False)

• args_to_ignore (list or tuple, optional) – Arguments to ignore during the check (default is [‘self’]).

• exact (bool, optional) – Whether to check for an exact match of arguments (default is True).

• error_type (Exception, optional) – The exception to raise (default is ValueError)

Raises:

ValueError – If the expected arguments do not match the actual arguments of the function.

aviary.utils.doctape.run_command_no_file_error(command: str, verbose=False)

Executes a CLI command and handles FileNotFoundError separately.

This method runs a given command in a temporary directory and captures the output. If the command returns a non-zero exit code, it checks the error message. If the error is a FileNotFoundError, it prints the error name. For other errors, it prints the full error message.

Parameters:

• command (str) – The CLI command to be executed.

• verbose (bool) – Whether or not to include the error message if FileNotFoundError is raised

Raises:

CalledProcessError – If the command returns a non-zero exit code (except for FileNotFoundError).

Glue Functions

The glue functions provide a wrapper for the myst_nb glue function that provides a simplified interface.

aviary.utils.doctape.glue_variable(name: str, val=None, md_code=False, display=True)

Glue a variable for later use in markdown cells of notebooks

Note: glue_variable(get_variable_name(Aircraft.APU.MASS)) can be used to glue the name of the variable (Aircraft.APU.MASS) not the value of the variable (‘aircraft:apu:mass’)

Parameters:

• name (str) – The name the value will be glued to

• val (any) – The value to be displayed in the markdown cell (default is the value of name)

• md_code (Bool) – Whether to wrap the value in markdown code formatting (e.g. code)

aviary.utils.doctape.glue_keys(dict_of_dicts: dict, display=True) → list

Recursively glue all of the keys from a dict of dicts

Parameters:

dict_of_dicts (dict) – The dictionary who’s keys will be glued

Returns:

all_keys – A list of all the keys that were glued

Return type:

list

Utility Functions

Utility functions are provided that the user may find useful for generating or testing their documentation.

aviary.utils.doctape.gramatical_list(list_of_strings: list, cc='and', add_accents=False) → str

Combines the elements of a list into a string with proper punctuation

Parameters:

• list_of_strings (list) – A list of strings (or elements with a string representation)

• cc (str, optional) – The coordinating conjunction to use with the list (default is and)

• add_accents (bool, optional) – Whether or not to wrap each element with ` characters (default is False)

Returns:

A string that combines the elements of the list into a string with proper punctuation

Return type:

str

aviary.utils.doctape.get_variable_name(*variables) → str

returns the name of the variable passed to the function as a string

Parameters:

variables (any) – The variable(s) of interest

Returns:

A string that contains the name of variable passed to this function (or list of strings, if multiple arguments are passed)

Return type:

str

aviary.utils.doctape.get_previous_line(n=1) → str

returns the previous n line(s) of code as a string

Parameters:

n (int) – The number of lines to return (default is 1)

Returns:

A string that contains the previous line of code or a list that contains the previous n lines of code

Return type:

str

aviary.utils.doctape.get_attribute_name(object: object, attribute, error_type=<class 'AttributeError'>) → str

Gets the name of an object’s attribute based on it’s value

This is intended for use with Enums and other objects that have unique values. This method will return the name of the first attribute that has a value that matches the value provided.

Parameters:

• object (any) – The object whose attributes will be searched

• attribute (any) – The value of interest

• error_type (Exception, optional) – The exception to raise (default is AttributeError)

Returns:

name – The name of the attribute

Return type:

str

Raises:

AttributeError – If the object has no attributes with the provided value.

aviary.utils.doctape.get_all_keys(dict_of_dicts: dict, track_layers=False, all_keys=None) → list

Recursively get all of the keys from a dict of dicts Note: this will not add duplicates of keys, but will continue deeper even if a key is duplicated

Parameters:

• dict_of_dicts (dict) – The dictionary who’s keys will be gathered

• track_layers (Bool) – Whether or not to track where keys inside the dict of dicts came from. This will get every key, by ensuring that all keys have a unique name by tracking the path it took to get there.

• all_keys (list) – A list of the keys that have been found so far

Returns:

all_keys – A list of all the keys in the dict_of_dicts

Return type:

list

aviary.utils.doctape.get_value(dict_of_dicts: dict, comlpete_key: str)

Recursively get a value from a dict of dicts

Parameters:

• dict_of_dicts (dict)

• complete_key (str) – A string that contains the full path through the dict_of_dicts (i.e. dictkey1.dictkey2.keyofinterest)

Returns:

val – The value found

Return type:

any