The general module

A set of multi-purpose tools.

This module provides a handful of broadly-applicable functions for formatting, and parsing. It also provides some general-purpose classes which are not entirely necessary, but which are often helpful, for the functioning of the software.

Classes

Command

class src.tools.general.Command(method, *args, **kwargs)

A container for runtime-specified commands.

In many situations in this software, there arise situations in which one of the core classes needs to send output back to some graphical entity. This class provides a container in which the graphical objects can store some method or function which the core class will execute at the appropriate time.

Parameters :

method : method or function

A method (bound to some object) or a function which may be executed at some later specified time.

args : positional arguments

Comma-separated arguments which will be substituted into the method at execution time.

kwargs : keyword arguments

Keyword arguments which will be substituted into the method at execution time.

Methods

execute(*args, **kwargs)

Execute the command contained within this class.

Parameters :

kwargs : keyword arguments

Additional keyword arguments which will be passed to the method at the time it is executed.

toString()

Convert the command into an explicit string.

Print the function or method in a way which looks (in most cases) the way the command would look if printed explicitly (i.e. they way you would write it to execute it immediately), with the positional and keyword arguments written in.

Functions

src.tools.general.frange(start, end=None, inc=None, includeEnd=True)

Return a list representing a range where the inputs can be floats.

Parameters :

start : float

The first point in the list.

end : float

The value signaling the end of the list.

inc : float

The value by which to increment.

includeEnd : bool

Whether the end of the range is inclusive.

Returns :

list(float) :

A list of floats ranging from start to end in steps of inc.

src.tools.general.xfrange(start, end=None, inc=None)

Create a generator producing a range where the inputs can be floats.

src.tools.general.splitAtComma(text)

Split a comma-separated string of numbers into a list of floats.

Take a string consisting of floating-point or integer numbers separated by commas, split the string at the commas, and cast all of the numbers to floats. All segments which cannot be cast to a float will be ignored.

Parameters :

text : str

The string to split. It should consist of numbers separated by commas.

Returns :

list(float) :

A list of the numbers that were previously separated by commas.

src.tools.general.formatReSTHeading(heading, level=0)

Return a heading string formatted as reStructuredText.

Parameters :

heading : str

The text of the heading.

level : int

The nesting depth of the section labeled by the supplied heading.

Returns :

str :

The heading formatted using reStructuredText syntax.

src.tools.general.gridArrangement(num)

Return the number of rows and columns needed to display elements neatly.

Given a specified number of items, determine an acceptable way to arrange them in a grid. The algorithm attempts to keep the grid as square as possible, subject to the condition that the number of columns is always greater than or equal to the number of rows.

Parameters :

num : int

The number of elements which need to be arranged.

Returns :

tuple (int, int) :

A tuple consisting of the number of rows and the number of columns which would be a decent arrangement of num items.

src.tools.general.multilineStringToList(string, removeBlanks=True)

Convert a multi-line string to a list of strings.

Parameters :

string : str

The string to split.

removeBlanks : bool

Whether to remove all blank lines from the list.

Returns :

list of str :

A list of strings, each element being one line of the input string.

src.tools.general.prompt(string, choices=None)

Present a user with options.

Parameters :

string : str

A string to tell the user what he is choosing.

choices : list of str

A list of strings representing the available choices. If None, the default list will be [‘OK’, ‘Cancel’].

Returns :

int :

The index of the selected option within the choices list. Note that for this purpose, the list is zero-indexed.

src.tools.general.simpleLinearRegression(xPoints, yPoints)

Perform a simple linear regression on data.

Parameters :

xPoints : list of float

The list of x-values of the points to fit.

yPoints : list of float

The list of y-values of the points to fit.

Returns :

float :

The slope of the trend line.

float :

The y-intercept of the trend line.

float :

The correlation coefficient (usually denoted by R) of the trend line.

float :

The minimum y-value in the data set.

float :

The maximum y-value in the data set.