skidl.utilities module

Utility functions used by the rest of SKiDL.

class skidl.utilities.Rgx(s)

Bases: str

Same as a string but the class makes it recognizable as as a regular expression.

class skidl.utilities.TriggerDict(*args, **kwargs)

Bases: dict

This dict triggers a function when one of its entries changes.

skidl.utilities.add_quotes(s)

Return string with added quotes if it contains whitespace or parens.

skidl.utilities.add_unique_attr(obj, name, value, check_dup=False)

Create an attribute if the attribute name isn’t already used.

skidl.utilities.cnvt_to_var_name(s)

Convert a string to a legal Python variable name and return it.

skidl.utilities.debug_trace(fn, *args, **kwargs)

Decorator to print tracing info when debugging execution.

skidl.utilities.expand_buses(pins_nets_buses)

Take list of pins, nets, and buses and return a list of only pins and nets.

skidl.utilities.expand_indices(slice_min, slice_max, match_regex, *indices)

Expand a list of indices into a list of integers and strings.

This function takes the indices used to select pins of parts and lines of buses and returns a flat list of numbers and strings. String and integer indices are put in the list unchanged, but slices are expanded into a list of integers before entering the final list.

Parameters:

• slice_min – The minimum possible index.

• slice_max – The maximum possible index (used for slice indices).

• match_regex – If true,

• indices – A list of indices made up of numbers, slices, text strings.

Returns:

A linear list of all the indices made up only of numbers and strings.

skidl.utilities.export_to_all(fn)

Add a function to the __all__ list of this module.

Parameters:

fn (function) – The function to be added to the __all__ list of this module.

Returns:

The function that was passed in.

Return type:

function

skidl.utilities.filter_list(lst, **criteria)

Return a list of objects whose attributes match a set of criteria.

Return a list of objects extracted from a list whose attributes match a set of criteria. The match is done using regular expressions. Example: filter_list(pins, name=’io[0-9]+’, direction=’bidir’) will return all the bidirectional pins of the component that have pin names starting with ‘io’ followed by a number (e.g., ‘IO45’).

If an attribute of the lst object is a list or tuple, each entry in the list/tuple will be checked for a match. Only one entry needs to match to consider the entire attribute a match. This feature is useful when searching for objects that contain a list of aliases, such as Part objects.

Parameters:

lst – The list from which objects will be extracted.

Keywords Args:

criteria: Keyword-argument pairs. The keyword specifies the attribute

name while the argument contains the desired value of the attribute. Regardless of what type the argument is, it is always compared as if it was a string. The argument can also be a regular expression that must match the entire string created from the attribute of the list object.

Returns:

A list of objects whose attributes match all the criteria.

skidl.utilities.find_and_open_file(filename, paths=None, ext=None, allow_failure=False, exclude_binary=False, descend=0)

Search for a file in list of paths, open it and return file pointer and full file name.

Parameters:

• filename – Base file name (e.g., “my_file”).

• paths – List of paths to search for the file.

• ext – The extension for the file (e.g., “.txt”).

• allow_failure – If false, failure to find file raises and exception.

• exclude_binary – If true, skip files that contain binary data.

• descend – If 0, don’t search lower-level directories. If positive, search that many levels down for the file. If negative, descend into subdirectories withcurrent_level limit.

Returns:

File pointer and file name or None, None if file could not be opened.

skidl.utilities.find_and_read_file(filename, paths=None, ext=None, allow_failure=False, exclude_binary=False, descend=0)

Search for a file in list of paths, open it and return its contents.

Parameters:

• filename – Base file name (e.g., “my_file”).

• paths – List of paths to search for the file.

• ext – The extension for the file (e.g., “.txt”).

• allow_failure – If false, failure to find file raises and exception.

• exclude_binary – If true, skip files that contain binary data.

• descend – If 0, don’t search lower-level directories. If positive, search that many levels down for the file. If negative, descend into subdirectories withcurrent_level limit.

Returns:

File contents and file name or None, None if file could not be opened.

skidl.utilities.find_num_copies(**attribs)

Return the number of copies to make based on the number of attribute values.

Keyword Arguments:

attribs – Dict of Keyword/Value pairs for setting object attributes. If the value is a scalar, then the number of copies is one. If the value is a list/tuple, the number of copies is the length of the list/tuple.

Returns:

The length of the longest value in the dict of attributes.

Raises:

• Exception if there are two or more list/tuple values with different –

• lengths that are greater than 1. (All attribute values must be scalars –

• or lists/tuples of the same length.) –

skidl.utilities.flatten(nested_list)

Return a flattened list of items from a nested list.

skidl.utilities.from_iadd(objs)

Return True if one or more objects have attribute iadd_flag set to True.

skidl.utilities.fullmatch(regex, string, flags=0)

Emulate python-3.4 re.fullmatch().

skidl.utilities.get_unique_name(lst, attrib, prefix, initial=None)

Return a name that doesn’t collide with another in a list.

This subrcurrent_leveline is used to generate unique part references (e.g., “R12”) or unique net names (e.g., “N$5”).

Parameters:

• lst – The list of objects containing names.

• attrib – The attribute in each object containing the name.

• prefix – The prefix attached to each name.

• initial – The initial setting of the name (can be None or empty string).

Returns:

A string containing the unique name.

skidl.utilities.is_binary_file(filename)

Return true if a file contains binary (non-text) characters.

skidl.utilities.list_or_scalar(lst)

Return a list if passed a multi-element list, otherwise return a single scalar.

Parameters:

lst – Either a list or a scalar.

Returns:

• A list if passed a multi-element list.

• The list element if passed a single-element list.

• None if passed an empty list.

• A scalar if passed a scalar.

skidl.utilities.merge_dicts(dct, merge_dct)

Dict merge that recurses through both dicts and updates keys.

Parameters:

• dct – The dict that will be updated.

• merge_dct – The dict whose values will be inserted into dct.

Returns:

Nothing.

skidl.utilities.norecurse(f)

Decorator that keeps a function from recursively calling itself.

Parameters:

f (function)

skidl.utilities.num_to_chars(num)

Return a string like ‘AB’ when given a number like 28.

skidl.utilities.opened(f_or_fn, mode)

Yields an opened file or file-like object.

Parameters:

• file_or_filename – Either an already opened file or file-like object, or a filename to open.

• mode – The mode to open the file in.

skidl.utilities.reset_get_unique_name()

Reset the heaps that store previously-assigned names.

skidl.utilities.rmv_attr(objs, attrs)

Remove a list of attributes from a list of objects.

skidl.utilities.rmv_iadd(objs)

Delete iadd_flag attribute from a list of objects.

skidl.utilities.rmv_quotes(s)

Remove starting and ending quotes from a string.

skidl.utilities.set_attr(objs, attr, value)

Set an attribute in a list of objects.

skidl.utilities.set_iadd(objs, value)

Set iadd_flag with T/F value for a list of objects.

skidl.utilities.sgn(x)

Return -1,0,1 if x<0, x==0, x>0.

skidl.utilities.to_list(x)

Return x if it is already a list, or return a list containing x if x is a scalar.