28. utils — A collection of miscellaneous utility functions.

The pyformex.utils module contains a wide variety of utilitary functions. Because there are so many and they are so widely used, the utils module is imported in the environment where scripts and apps are executed, so that users can always call the utils functions without explicitely importing the module.

28.1. Module attributes

utils.FileTypes

A collection of FileType records. Each FileType instance holds the definition of a file type, and is accessible from this dict with a simple mnemonic key. These are the ones that are commonly used in pyFormex. But users can add their own definitions too, just by creating an instance of FileType.

Type:OrderedDict

Examples

>>> for k,v in FileTypes.items(): print(f"{k} = '{v}'")
all = 'All files (*)'
ccx = 'CalCuliX files (*.dat *.inp)'
dcm = 'DICOM images (*.dcm)'
dxf = 'AutoCAD DXF files (*.dxf)'
dxftext = 'Converted AutoCAD files (*.dxftext)'
flavia = 'flavia results (*.flavia.msh *.flavia.res)'
gts = 'GTS files (*.gts)'
gz = 'Compressed files (*.gz *.bz2)'
html = 'Web pages (*.html)'
icon = 'Icons (*.xpm)'
img = 'Images (*.png *.jpg *.jpeg *.eps *.gif *.bmp)'
inp = 'Abaqus or CalCuliX input files (*.inp)'
neu = 'Gambit Neutral files (*.neu)'
obj = 'Wavefront OBJ files (*.obj)'
off = 'Geomview object files (*.off)'
pgf = 'pyFormex geometry files (*.pgf)'
ply = 'Stanford Polygon File Format files (*.ply)'
png = 'PNG images (*.png)'
postproc = 'Postproc scripts (*.post.py)'
pyformex = 'pyFormex scripts (*.py *.pye)'
pyf = 'pyFormex projects (*.pyf)'
pzf = 'pyFormex zip files (*.pzf)'
smesh = 'Tetgen surface mesh files (*.smesh)'
stl = 'STL files (*.stl)'
stlb = 'Binary STL files (*.stl)'
surface = 'Surface models (*.off *.gts *.stl)'
tetsurf = 'Tetgen surface (*.smesh)'
tetgen = 'Tetgen files (*.poly *.smesh *.ele *.face *.edge *.node *.neigh)'
vtk = 'VTK types (*.vtk *.vtp)'
vtp = 'vtkPolyData file (*.vtp)'

28.2. Classes defined in module utils

class utils.FileType(key, text, *suffixes)

A class for holding file types and the related filename patterns.

Parameters:

• key (str) – A short and unique mnemonic string, by preference lower case, that wil be used as lookup key for this FileType definition in the global FileTypes collection.
• text (str) – A textual description of the file type.
• *suffixes (sequence of str) – All remaining parameters are file suffixes that should be used to filter files that are supposed to be of this type. Any number of suffixes is allowed. If None are provided, all files will match the file type.

See also

FileTypes

the set of FileType’s knownd by pyFormex

suffixes(compr=False)

Return a list of file suffixes for the FileType.

Parameters:compr (bool) – If True, the file suffixes for compressed files of this type are automatically added.

Examples

>>> FileTypes['pgf'].suffixes()
['pgf']
>>> FileTypes['pgf'].suffixes(compr=True)
['pgf', 'pgf.gz', 'pgf.bz2']
>>> FileTypes['all'].suffixes()
[]

patterns(compr=False)

Return a list with the file patterns matching the FileType.

Parameters:compr (bool) – If True, the file suffixes for compressed files of this type are automatically added.

Examples

>>> FileTypes['pgf'].patterns()
['*.pgf']
>>> FileTypes['pgf'].patterns(compr=True)
['*.pgf', '*.pgf.gz', '*.pgf.bz2']
>>> FileTypes['all'].patterns()
['*']

desc(compr=False)

Create a filetype description compatible with Qt Widgets.

Parameters:compr (bool) – If True, the file patterns for compressed files are automatically added. Returns:str – A string that can be directly used in the Qt File Dialog widgets to filter the selectable files. This string has the format:

file type text (*.ext1 *.ext2)

Examples

>>> FileTypes['img'].desc()
'Images (*.png *.jpg *.jpeg *.eps *.gif *.bmp)'
>>> fileDescription('inp')
'Abaqus or CalCuliX input files (*.inp)'
>>> fileDescription('doc')
'DOC files (*.doc)'
>>> fileDescription('*.inp')
'*.inp'
>>> fileDescription('pgf',compr=True)
'pyFormex geometry files (*.pgf *.pgf.gz *.pgf.bz2)'

class utils.TempDir(suffix=None, prefix='pyf_', dir=None)

A temporary directory that can be used as a context manager.

This is a wrapper around Python’s tempfile.TemporaryDirectory, with the following differences:

• the default value for prefix is set to ‘pyf_’,
• it has an extra attribute ‘.path’ returning the directory name as a Path,
• the context manager returns a Path instead of a str.

class utils.File(filename, mode, compr=None, level=5, delete_temp=True)

Transparent file compression.

This class is a context manager providing transparent file compression and decompression. It is commonly used in a with statement, as follows:

with File('filename.ext','w') as f:
    f.write('something')
    f.write('something more')

This will create an uncompressed file with the specified name, write some things to the file, and close it. The file can be read back similarly:

with File('filename.ext','r') as f:
    for line in f:
        print(f)

Because File is a context manager, the file is closed automatically when leaving the with block.

By specifying a filename ending with ‘.gz’ or ‘.bz2’, the file will be compressed (on writing) or decompressed (on reading) automatically. The code can just stay the same as above.

Parameters:

• filename (path_like) – Path of the file to open. If the filename ends with ‘.gz’ or ‘.bz2’, transparent (de)compression will be used, with gzip or bzip2 compression algorithms respectively.
• mode (str) – File open mode: ‘r’ for read, ‘w’ for write or ‘a’ for append mode. See also the Python documentation for the open() builtin function. For compressed files, append mode is not yet available.
• compr ('gz' | 'bz2') – The compression algorithm to be used: gzip or bzip2. If not provided and the file name ends with ‘.gz’ or ‘.bz2’, compr is set automatically from the extension.
• level (int (1..9)) – Compression level for gzip/bzip2. Higher values result in smaller files, but require longer compression times. The default of 5 gives already a fairly good compression ratio.
• delete_temp (bool) – If True (default), the temporary files needed to do the (de)compression are deleted when the File instance is closed.

The File class can also be used outside a with statement. In that case the user has to open and close the File himself. The following are more or less equivalent with the above examples (the with statement is better at handling exceptions):

fil = File('filename.ext','w')
f = fil.open()
f.write('something')
f.write('something more')
fil.close()

This will create an uncompressed file with the specified name, write some things to the file, and close it. The file can be read back similarly:

fil = File('filename.ext','r')
f = fil.open()
for line in f:
    print(f)
fil.close()

open()

Open the File in the requested mode.

This can be used to open a File object outside a with statement. It returns a Python file object that can be used to read from or write to the File. It performs the following:

• If no compression is used, ope the file in the requested mode.
• For reading a compressed file, decompress the file to a temporary file and open the temporary file for reading.
• For writing a compressed file, open a tem[porary file for writing.

See the documentation for the File class for an example of its use.

close()

Close the File.

This can be used to close the File if it was not opened using a with statement. It performs the following:

• The underlying file object is closed.
• If the file was opened in write or append mode and compression is requested, the file is compressed.
• If a temporary file was in use and delete_temp is True, the temporary file is deleted.

See the documentation for the File class for an example of its use.

reopen(mode='r')

Reopen the file, possibly in another mode.

This allows e.g. to read back data from a just saved file without having to destroy the File instance.

Returns the open file object.

class utils.NameSequence(name, ext='')

A class for autogenerating sequences of names.

Sequences of names are autogenerated by combining a fixed part with a numeric part. The latter is incremented at each creation of a new name (by the next() function).

Parameters:

• name (str) – Base of the names to be generated. The name is split in three parts (prefix, numeric, suffix), where numeric only contains digits and suffix does not contain any digits. Thus, numeric is the last numeric part in the string. The prefix and suffix are invariable parts, while the numeric part will be incremented starting from the value in the provided name. Use ext if the variable part is not the last numeric part of name. If name does not contain any numeric part, it is split as a file name in stem and suffix, and ‘-0’ is appended to the stem. If name is empty, it will be replaced with ‘0’.
• ext (str, optional) – If provided, this is an invariable string added to the suffix from name to construct the full name template. This may contain numeric parts, allowing the variable numeric part at any place in the full template.

Examples

>>> N = NameSequence('obj')
>>> [ next(N) for i in range(3) ]
['obj-0', 'obj-1', 'obj-2']
>>> N.peek()
'obj-3'
>>> next(N), next(N)
('obj-3', 'obj-4')
>>> N.template
'obj-%d'
>>> N = NameSequence('obj-005')
>>> [ next(N) for i in range(3) ]
['obj-005', 'obj-006', 'obj-007']
>>> N = NameSequence('abc.98')
>>> [ next(N) for i in range(3) ]
['abc.98', 'abc.99', 'abc.100']
>>> N = NameSequence('abc-8x.png')
>>> [ next(N) for i in range(3) ]
['abc-8x.png', 'abc-9x.png', 'abc-10x.png']
>>> N.template
'abc-%01dx.png'
>>> N.glob()
'abc-*x.png'
>>> next(NameSequence('abc','.png'))
'abc-0.png'
>>> next(NameSequence('abc.png'))
'abc-0.png'
>>> N = NameSequence('/home/user/abc23','5.png')
>>> [ next(N) for i in range(2) ]
['/home/user/abc235.png', '/home/user/abc245.png']
>>> N = NameSequence('')
>>> next(N), next(N)
('0', '1')
>>> N = NameSequence('12')
>>> next(N), next(N)
('12', '13')

next()

Return the next name in the sequence

peek()

Return the next name in the sequence without incrementing.

glob()

Return a UNIX glob pattern for the generated names.

A NameSequence is often used as a generator for file names. The glob() method returns a pattern that can be used in a UNIX-like shell command to select all the generated file names.

class utils.DictDiff(current_dict, past_dict)

A class to compute the difference between two dictionaries

Parameters:

• current_dict (dict) –
• past_dict (dict) –
• differences are reported as sets of keys (The) –
• items added (-) –
• items removed (-) –
• keys same in both but changed values (-) –
• keys same in both and unchanged values (-) –

added()

Return the keys in current_dict but not in past_dict

removed()

Return the keys in past_dict but not in current_dict

changed()

Return the keys for which the value has changed

unchanged()

Return the keys with same value in both dicts

equal()

Return True if both dicts are equivalent

report()

Create a reports of the differences

28.3. Functions defined in module utils

utils.rev_lookup(dictionary, value, default=None)

Reverse lookup in a dict

Lookup a value in a dict, and return its key (the first match).

Parameters:

• dictionary (dict) – The dict in which to lookup a value
• value (anything) – The value to lookup in the dict
• default (anything) – The key to return if the value was not found

Returns:

key (anything) – The first key in the dict whose value matches the given value, or default if no match was found.

utils.warningCategory(category)

Return a warning category and its alias

The input can be a category or an alias. Returns both as a tuple (alias, category). Invalid values return the default category (‘W’, Warning).

utils.warningAction(action)

Return a warning action and its alias

The input can be an action string or an alias. Returns both as a tuple (alias, action). Invalid values return the default action (‘i’, ‘ignore’).

utils.filterWarning(message, module='', category='U', action='i', save=False)

Add a warning message to the warnings filter.

category can be a Warning subclass or a key in the _warn_category dict

If save is True, the filter is saved in the user settings for future sessions.

utils.resetWarningFilters()

Reset the warning filters

Reset the warning filters to the Python defaults plus the ones listed in the ‘warnings/filters’ configuration variable.

utils.warning(message, level=<class 'UserWarning'>, stacklevel=3)

Decorator to add a warning to a function.

Adding this decorator to a function will warn the user with the supplied message when the decorated function gets executed for the first time in a session. An option is provided to switch off this warning in future sessions.

Decorating a function is done as follows:

@utils.warning('This is the message shown to the user')
def function(args):
    ...

utils.deprecated(message, stacklevel=4)

Decorator to deprecate a function

This is like warning(), but the level is set to FutureWarning.

utils.deprecated_by(old, new, stacklevel=4)

Decorator to deprecate a function by another one.

Adding this decorator to a function will warn the user with a message that the old function is deprecated in favor of new, at the first execution of old.

See also: deprecated().

utils.deprecated_future()

Decorator to warn that a function may be deprecated in future.

See also: deprecated().

utils.system(args, *, wait=True, verbose=False, **kargs)

Execute a command through the operating system.

This is a wrapper around the process.run and process.start functions, aimed particularly at the pyFormex GUI user:

• there is a common interface for both functions,
• the verbose option provides effortless extra feedback,
• the outcome of the last command is saved for later consultation.

Parameters:

• args (string or sequence of program arguments.) – The command to be executed. It is passed together with **kargs to process.run or process.start.
• wait (bool) – If True (default) the command is executed by process.run, waiting for the outcome. If False, the command is executed by process.start, returning immediately and not waiting for the result
• verbose (bool) – If True, the command and (in case of failure, timeout or error exit) a report of its outcome, are written to stdout.
• **kargs (keyword arguments) – Any keyword arguments accepted by process.run() (if wait is True) or process.start() (if wait is False). See the Python documentation for subprocess.run() for full info.

Returns:

DoneProcess or subprocess.Popen – If wait is True, returns a DoneProcess with the ourcome of the command. If wait is False, returns a subprocess.Popen which can be used to communicate with the started subprocess.

See also

process.run()

run a command and wait for its outcome

process.start()

start a subprocess but do not wait for its outcome

command()

call system() with some other defaults

Examples

>>> P = system("pwd")
>>> P.stdout.strip('\n') == os.getcwd()
True

>>> P = system('true')
>>> P
DoneProcess(args=['true'], returncode=0, stdout='', stderr='')
>>> P = system('false', capture_output=False)
>>> P
DoneProcess(args=['false'], returncode=1)
>>> P = system('False', verbose=True)
Running command: False
DoneProcess report
args: ['False']
Command failed to run!
returncode: 127
<BLANKLINE>

>>> P = system("sleep 5", timeout=1, verbose=True)
Running command: sleep 5
DoneProcess report
args: ['sleep', '5']
returncode: -1
timedout: True
<BLANKLINE>

utils.command(cmd, verbose=True, check=True, **kargs)

Run an external command in a user friendly way.

This is equivalent with the system() function but has verbose=True and check=True options on by default.

utils.killProcesses(pids, signal=15)

Send the specified signal to the processes in list

Parameters:

• pids (list of int) – List of process ids to be killed.
• signal (int) – Signal to be send to the processes. The default (15) will try to terminate the process in a friendly way. See man kill for more values.

utils.execSource(script, glob={})

Execute Python code in another thread.

Parameters:

• script (str) – A string containing some executable Python/pyFormex code.
• glob (dict, optional) – A dict with globals specifying the environment in which the source code is executed.

utils.matchMany(regexps, target)

Return multiple regular expression matches of the same target string.

utils.matchCount(regexps, target)

Return the number of matches of target to regexps.

utils.matchAny(regexps, target)

Check whether target matches any of the regular expressions.

utils.matchNone(regexps, target)

Check whether target matches none of the regular expressions.

utils.matchAll(regexps, target)

Check whether targets matches all of the regular expressions.

utils.fileDescription(ftype, compr=False)

Return a description of the specified file type(s).

Parameters:ftype (str or list of str) – The file type (or types) for which a description is requested. The case of the string(s) is ignored: it is converted to lower case. Returns:str of list of str – The file description(s) corresponding with the specified file type(s). The return value(s) depend(s) on the value of the input string(s) in the the following way (see Examples below):

• if it is a key in the file_description dict, the corresponding value is returned;
• if it is a string of only alphanumerical characters: it is interpreted as a file extension and the corresponding return value is FTYPE files (*.ftype);
• any other string is returned as as: this allows the user to compose his filters himself.

Examples

>>> fileDescription('img')
'Images (*.png *.jpg *.jpeg *.eps *.gif *.bmp)'
>>> fileDescription(['stl','all'])
['STL files (*.stl)', 'All files (*)']
>>> fileDescription('inp')
'Abaqus or CalCuliX input files (*.inp)'
>>> fileDescription('doc')
'DOC files (*.doc)'
>>> fileDescription('*.inp')
'*.inp'
>>> fileDescription('pgf',compr=True)
'pyFormex geometry files (*.pgf *.pgf.gz *.pgf.bz2)'

utils.fileTypes(ftype, compr=False)

Return the list of file extension types for a given type.

Parameters:

• ftype (str) – The file type (see fileDescription().
• compr (bool,optional) – If True, the compressed file types are automatically added.

Returns:

list of str – A list of the normalized matching extensions for this type. Normalized extension do not have the leading dot and are lower case only.

Examples

>>> fileTypes('pgf')
['pgf']
>>> fileTypes('pgf',compr=True)
['pgf', 'pgf.gz', 'pgf.bz2']

utils.fileTypesFromFilter(fdesc)

Extract the filetypes from a file type descriptor.

A file type descriptor is a string consisting of an initial part followed by a second part enclosed in parentheses. The second part is a space separated list of glob patterns. An example file descriptor is ‘file type text (*.ext1 *.ext2)’. This is the format as returned by FileType.desc().

Parameters:

• fdesc (str) – A file descriptor string.
• compr (bool,optional) – If True, the compressed file types are automatically added.

Returns:

• desc (str) – The file type description text.
• ext (list of str) – A list of the matching extensions for this type. Each string starts with a ‘.’.

Examples

>>> fileTypesFromFilter(FileTypes['img'].desc())
['png', 'jpg', 'jpeg', 'eps', 'gif', 'bmp']
>>> fileTypesFromFilter(FileTypes['pgf'].desc(compr=True))
['pgf', 'pgf.gz', 'pgf.bz2']

utils.projectName(fn)

Derive a project name from a file name.

The project name is the basename of the file without the extension. It is equivalent with Path(fn).stem

Examples

>>> projectName('aa/bb/cc.dd')
'cc'
>>> projectName('cc.dd')
'cc'
>>> projectName('cc')
'cc'

utils.findIcon(name)

Return the file name for an icon with given name.

Parameters:name (str) – Name of the icon: this is the stem fof the filename. Returns:str – The full path name of an icon file with the specified name, found in the pyFormex icon folder, or the question mark icon file, if no match was found.

Examples

>>> print(findIcon('view-xr-yu').relative_to(pf.cfg['pyformexdir']))
icons/view-xr-yu.xpm
>>> print(findIcon('right').relative_to(pf.cfg['pyformexdir']))
icons/64x64/right.png
>>> print(findIcon('xyz').relative_to(pf.cfg['pyformexdir']))
icons/question.xpm

utils.listIconNames(dirs=None, types=None)

Return the list of available icons by their name.

Parameters:

• dirs (list of paths, optional) – If specified, only return icons names from these directories.
• types (list of strings, optional) – List of file suffixes, each starting with a dot. If specified, Only names of icons having one of these suffixes are returned.

Returns:

list of str – A sorted list of the icon names available in the pyFormex icons folder.

Examples

>>> listIconNames()[:4]
['clock', 'dist-angle', 'down', 'down']
>>> listIconNames([pf.cfg['icondir'] / '64x64'])[:4]
['down', 'ff', 'info', 'lamp']
>>> listIconNames(types=['.xpm'])[:4]
['clock', 'dist-angle', 'down', 'far']

utils.sourceFiles(relative=False, symlinks=True, extended=False)

Return the list of pyFormex .py source files.

Parameters:

• relative (bool) – If True, returned filenames are relative to the current directory.
• symlinks (bool) – If False, files that are symbolic links are retained in the list. The default is to remove them.
• extended (bool) – If True, also return the .py files in all the paths in the configured appdirs and scriptdirs.

Returns:

list of str – A list of filenames of .py files in the pyFormex source tree, and, if extended is True, .py files in the configured app and script dirs as well.

utils.grepSource(pattern, options='', relative=True)

Finds pattern in the pyFormex source files.

Uses the grep program to find all occurrences of some specified pattern text in the pyFormex source .py files (including the examples). Extra options can be passed to the grep command. See man grep for more info.

Returns the output of the grep command.

utils.moduleList(package='all')

Return a list of all pyFormex modules in a subpackage.

This is like sourceFiles(), but returns the files in a Python module syntax.

utils.findModuleSource(module)

Find the path of the source file of a module

module is either an imported module (pkg.mod) or a string with the module name (‘pkg.mod’), imported or not. Returns the source file from which the module was/would be loaded when imported. Raises an error if the module can not be imported or does not have a source file.

utils.diskSpace(path, units=None, ndigits=2)

Returns the amount of diskspace of a file system.

Parameters:

• path (path_like) – A path name inside the file system to be probed.
• units (str) – If provided, results are reported in this units. See humanSize() for possible values. The default is to return the number of bytes.
• ndigits (int) – If provided, and also units is provided, specifies the number of decimal digits to report. See humanSize() for details.

Returns:

• total (int | float) – The total disk space of the file system containing path.
• used (int | float) – The used disk space on the file system containing path.
• available (int | float) – The available disk space on the file system containing path.

Notes

The sum used + available does not necessarily equal total, because a file system may (and usually does) have reserved blocks.

utils.humanSize(size, units, ndigits=-1)

Convert a number to a human size.

Large numbers are often represented in a more human readable form using k, M, G prefixes. This function returns the input size as a number with the specified prefix.

Parameters:

• size (int or float) – A number to be converted to human readable form.
• units (str) – A string specifying the target units. The first character should be one of k,K,M,G,T,P,E,Z,Y. ‘k’ and ‘K’ are equivalent. A second character ‘i’ can be added to use binary (K=1024) prefixes instead of decimal (k=1000).
• ndigits (int, optional) – If provided and >=0, the result will be rounded to this number of decimal digits.

Returns:

float – The input value in the specified units and possibly rounded to ndigits.

Examples

>>> humanSize(1234567890,'k')
1234567.89
>>> humanSize(1234567890,'M',0)
1235.0
>>> humanSize(1234567890,'G',3)
1.235
>>> humanSize(1234567890,'Gi',3)
1.15

utils.TempFile(*args, **kargs)

Return a temporary file that can be used as a context manager.

This is a wrapper around Python’s tempfile.NamedTemporaryFile, with the difference that the returned object has an extra attribute ‘.path’, returning the file name as a Path.

utils.zipList(filename)

List the files in a zip archive

Returns a list of file names

utils.zipExtract(filename, members=None)

Extract the specified member(s) from the zip file.

The default extracts all.

utils.setSaneLocale(localestring='')

Set a sane local configuration for LC_NUMERIC.

localestring is the locale string to be set, e.g. ‘en_US.UTF-8’ or ‘C’ for no locale.

Sets the LC_ALL locale to the specified string if that is not empty, and (always) sets LC_NUMERIC and LC_COLLATE to ‘C’.

Changing the LC_NUMERIC setting is a very bad idea! It makes floating point values to be read or written with a comma instead of a the decimal point. Of course this makes input and output files completely incompatible. You will often not be able to process these files any further and create a lot of troubles for yourself and other people if you use an LC_NUMERIC setting different from the standard.

Because we do not want to help you shoot yourself in the foot, this function always sets LC_NUMERIC back to a sane ‘C’ value and we call this function when pyFormex is starting up.

utils.to_str(s)

Silently convert bytes to str.

The input is either str or bytes. The output is always str.

utils.strNorm(s)

Normalize a string.

Text normalization removes all ‘&’ characters and converts it to lower case.

>>> strNorm("&MenuItem")
'menuitem'

utils.slugify(text, delim='-')

Convert a string into a URL-ready readable ascii text.

Example: >>> slugify(“http://example.com/blog/[Some] _ Article’s Title–”) ‘http-example-com-blog-some-article-s-title’ >>> slugify(“&MenuItem”) ‘menuitem’

utils.forceReST(text, underline=False)

Convert a text string to have it recognized as reStructuredText.

Returns the text with two lines prepended: a line with ‘..’ and a blank line. The text display functions will then recognize the string as being reStructuredText. Since the ‘..’ starts a comment in reStructuredText, it will not be displayed.

Furthermore, if underline is set True, the first line of the text will be underlined to make it appear as a header.

utils.underlineHeader(s, char='-')

Underline the first line of a text.

Adds a new line of text below the first line of s. The new line has the same length as the first, but all characters are equal to the specified char.

>>> print(underlineHeader("Hello World"))
Hello World
-----------

utils.framedText(text, padding=[0, 2, 0, 2], border=[1, 2, 1, 2], margin=[0, 0, 0, 0], borderchar='####', cornerchar=None, width=None, adjust='l')

Create a text with a frame around it.

• adjust: ‘l’, ‘c’ or ‘r’: makes the text lines be adjusted to the left, center or right.

>>> print(framedText("Hello World,\nThis is me calling",adjust='c'))
##########################
##     Hello World,     ##
##  This is me calling  ##
##########################

utils.prefixText(text, prefix)

Add a prefix to all lines of a text.

• text: multiline string
• prefix: string: prefix to insert at the start of all lines of text.

>>> print(prefixText("line1\nline2","** "))
** line1
** line2

utils.dos2unix(infile)

Convert a text file to unix line endings.

utils.unix2dos(infile, outfile=None)

Convert a text file to dos line endings.

utils.gzip(filename, gzipped=None, remove=True, level=5, compr='gz')

Compress a file in gzip/bzip2 format.

Parameters:

• filename (path_like) – The input file name.
• gzipped (path_like, optional) – The output file name. If not specified, it will be set to the input file name + ‘.’ + compr. An existing output file will be overwritten.
• remove (bool) – If True (default), the input file is removed after successful compression.
• level (int 1..9) – The gzip/bzip2 compression level. Higher values result in smaller files, but require longer compression times. The default of 5 gives already a fairly good compression ratio.
• compr ('gz' | 'bz2') – The compression algorithm to be used. The default is ‘gz’ for gzip compression. Setting to ‘bz2’ will use bzip2 compression.

Returns:

Path – The path of the compressed file.

Examples

>>> f = Path('./test_gzip.out')
>>> f.write_text('This is a test\n'*100)
1500
>>> print(f.size())
1500
>>> g = gzip(f)
>>> print(g)
test_gzip.out.gz
>>> print(g.size())
60
>>> f.exists()
False
>>> f = gunzip(g)
>>> f.exists()
True
>>> print(f.read_text().split('\n')[50])
This is a test
>>> g.exists()
False

utils.gunzip(filename, unzipped=None, remove=True, compr='gz')

Uncompress a file in gzip/bzip2 format.

Parameters:

• filename (path_like) – The compressed input file name (usually ending in ‘.gz’ or ‘.bz2’).
• unzipped (path_like, optional) – The output file name. If not provided and filename ends with ‘.gz’ or ‘.bz2’, it will be set to the filename with the ‘.gz’ or ‘.bz2’ removed. If not provided and filename does not end in ‘.gz’ or ‘.bz2’, or if an empty string is provided, the name of a temporary file is generated. Since you will normally want to read something from the decompressed file, this temporary file is not deleted after closing. It is up to the user to delete it (using the returned file name) when the file has been dealt with.
• remove (bool) – If True (default), the input file is removed after successful decompression. You probably want to set this to False when decompressing to a temporary file.
• compr ('gz' | 'bz2') – The compression algorithm used in the input file. If not provided, it is automatically set from the extension of the filename if that is either ‘.gz’ or ‘.bz2’, or else the default ‘gz’ is used.

Returns:

Path – The name of the uncompressed file.

Examples

See gzip.

utils.timeEval(s, glob=None)

Return the time needed for evaluating a string.

s is a string with a valid Python instructions. The string is evaluated using Python’s eval() and the difference in seconds between the current time before and after the evaluation is printed. The result of the evaluation is returned.

This is a simple method to measure the time spent in some operation. It should not be used for microlevel instructions though, because the overhead of the time calls. Use Python’s timeit module to measure microlevel execution time.

utils.countLines(fn)

Return the number of lines in a text file.

utils.userName()

Find the name of the user.

utils.isString(o)

Test if an object is a string (ascii or unicode)

utils.isFile(o)

Test if an object is a file

utils.is_script(appname)

Checks whether an application name is rather a script name

utils.getDocString(scriptfile)

Return the docstring from a script file.

This actually returns the first multiline string (delimited by triple double quote characters) from the file. It does relies on the script file being structured properly and indeed including a doctring at the beginning of the file.

utils.hsorted(l)

Sort a list of strings in human order.

When human sort a list of strings, they tend to interprete the numerical fields like numbers and sort these parts numerically, instead of the lexicographic sorting by the computer.

Returns the list of strings sorted in human order.

Example: >>> hsorted([‘a1b’,’a11b’,’a1.1b’,’a2b’,’a1’]) [‘a1’, ‘a1.1b’, ‘a1b’, ‘a2b’, ‘a11b’]

utils.numsplit(s)

Split a string in numerical and non-numerical parts.

Returns a series of substrings of s. The odd items do not contain any digits. The even items only contain digits. Joined together, the substrings restore the original.

The number of items is always odd: if the string ends or starts with a digit, the first or last item is an empty string.

Example:

>>> print(numsplit("aa11.22bb"))
['aa', '11', '.', '22', 'bb']
>>> print(numsplit("11.22bb"))
['', '11', '.', '22', 'bb']
>>> print(numsplit("aa11.22"))
['aa', '11', '.', '22', '']

utils.splitDigits(s, pos=-1)

Split a string at a sequence of digits.

The input string is split in three parts, where the second part is a contiguous series of digits. The second argument specifies at which numerical substring the splitting is done. By default (pos=-1) this is the last one.

Returns a tuple of three strings, any of which can be empty. The second string, if non-empty is a series of digits. The first and last items are the parts of the string before and after that series. Any of the three return values can be an empty string. If the string does not contain any digits, or if the specified splitting position exceeds the number of numerical substrings, the second and third items are empty strings.

Example:

>>> splitDigits('abc123')
('abc', '123', '')
>>> splitDigits('123')
('', '123', '')
>>> splitDigits('abc')
('abc', '', '')
>>> splitDigits('abc123def456fghi')
('abc123def', '456', 'fghi')
>>> splitDigits('abc123def456fghi',0)
('abc', '123', 'def456fghi')
>>> splitDigits('123-456')
('123-', '456', '')
>>> splitDigits('123-456',2)
('123-456', '', '')
>>> splitDigits('')
('', '', '')

utils.globFiles(pattern, sort=<function hsorted>)

Return a (sorted) list of files matching a filename pattern.

A function may be specified to sort/filter the list of file names. The function should take a list of filenames as input. The output of the function is returned. The default sort function will sort the filenames in a human order. This will sort numeric fields in order of increasing numbers instead of alphanumerically.

Examples

>>> globFiles('pyformex/o*.py')
['pyformex/olist.py', 'pyformex/options.py']

utils.autoName(clas)

Return the autoname class instance for objects of type clas.

This allows for objects of a certain class to be automatically named throughout pyFormex.

Parameters:clas (str or class or object) – The object class name. If a str, it is the class name. If a class, the name is found from it. If an object, the name is taken from the object’s class. In all cases the name is converted to lower case Returns:NameSequence instance – A NameSequence that will generate subsequent names corresponding with the specified class.

Examples

>>> from pyformex.formex import Formex
>>> F = Formex()
>>> print(next(autoName(Formex)))
formex-0
>>> print(next(autoName(F)))
formex-1
>>> print(next(autoName('Formex')))
formex-2

utils.prefixDict(d, prefix='')

Prefix all the keys of a dict with the given prefix.

Parameters:

• d (dict) – A dict where all keys are strings.
• prefix (str) – A string to prepend to all keys in the dict.

Returns:

dict – A dict with the same contents as the input, but where all keys have been prefixed with the given prefix string.

Examples

>>> prefixDict({'a':0,'b':1},'p_')
{'p_a': 0, 'p_b': 1}

utils.subDict(d, prefix='', strip=True)

Return a dict with the items whose key starts with prefix.

Parameters:

• d (dict) – A dict where all the keys are strings.
• prefix (str) – The string that is to be found at the start of the keys.
• strip (bool) – If True (default), the prefix is stripped from the keys.

Returns:

dict – A dict with all the items from d whose key starts with prefix. The keys in the returned dict will have the prefix stripped off, unless strip=False is specified.

Examples

>>> subDict({'p_a':0,'q_a':1,'p_b':2}, 'p_')
{'a': 0, 'b': 2}
>>> subDict({'p_a':0,'q_a':1,'p_b':2}, 'p_', strip=False)
{'p_a': 0, 'p_b': 2}

utils.selectDict(d, keys, remove=False)

Return a dict with the items whose key is in keys.

Parameters:

• d (dict) – The dict to select items from.
• keys (set of str) – The keys to select from d. This can be a set or list of key values, or another dict, or any object having the key in object interface.
• remove (bool) – If True, the selected keys are removed from the input dict.

Returns:

dict – A dict with all the items from d whose key is in keys.

See also

removeDict()

the complementary operation, returns items not in keys.

Examples

>>> d = dict([(c,c*c) for c in range(4)])
>>> selectDict(d,[2,0])
{0: 0, 2: 4}
>>> print(d)
{0: 0, 1: 1, 2: 4, 3: 9}
>>> selectDict(d,[2,0,6],remove=True)
{0: 0, 2: 4}
>>> print(d)
{1: 1, 3: 9}

utils.removeDict(d, keys)

Return a dict with the specified keys removed.

Parameters:

• d (dict) – The dict to select items from.
• keys (set of str) – The keys to select from d. This can be a set or list of key values, or another dict, or any object having the key in object interface.

Returns:

dict – A dict with all the items from d whose key is not in keys.

See also

selectDict()

the complementary operation returning the items in keys

Examples

>>> d = dict([(c,c*c) for c in range(6)])
>>> removeDict(d,[4,0])
{1: 1, 2: 4, 3: 9, 5: 25}

utils.refreshDict(d, src)

Refresh a dict with values from another dict.

The values in the dict d are update with those in src. Unlike the dict.update method, this will only update existing keys but not add new keys.

utils.inverseDict(d)

Return the inverse of a dictionary.

Returns a dict with keys and values interchanged.

Example:

>>> inverseDict({'a':0,'b':1})
{0: 'a', 1: 'b'}

utils.selectDictValues(d, values)

Return the keys in a dict which have a specified value

• d: a dict where all the keys are strings.
• values: a list/set of values.

The return value is a list with all the keys from d whose value is in keys.

Example:

>>> d = dict([(c,c*c) for c in range(6)])
>>> selectDictValues(d,range(10))
[0, 1, 2, 3]

utils.dictStr(d, skipkeys=[])

Convert a dict to a string.

This is much like dict.__str__, but formats all keys as strings and prints the items with the keys sorted.

This function is can be used as replacement for the __str__ method od dict-like classes.

A list of strings skipkeys kan be specified, to suppress the printing of some special key values.

Example:

>>> dictStr({'a':0, 'b':1, 'c':2}, ['b'])
"{'a': 0, 'c': 2}"

utils.listFonts(mono=False)

List the fonts known to the system.

Parameters:mono (bool) – If True, only returns the monospace fonts. Default is to return all fonts. Returns:list of Path – A list of the font files found on the system.

Notes

This uses the ‘fc-list’ command from the fontconfig package and will produce a warning if fontconfig is not installed.

utils.is_valid_mono_font(fontfile)

Filter valid monotype fonts

Parameters:fontfile (Path) – Path of a font file. Returns:bool – True if the provided font file has a .ttf suffix, is a fixed width font and the font basename is not listed in the ‘fonts/ignore’ configuration variable.

utils.defaultMonoFont()

Return a default monospace font for the system.

utils.listMonoFonts()

List only the monospace fonts

See also

listFonts()

utils.interrogate(item)

Print useful information about item.

utils.memory_report(keys=None)

Return info about memory usage

utils.totalMemSize(o, handlers={}, verbose=False)

Return the approximate total memory footprint of an object.

This function returns the approximate total memory footprint of an object and all of its contents.

Automatically finds the contents of the following builtin containers and their subclasses: tuple, list, deque, dict, set and frozenset. To search other containers, add handlers to iterate over their contents:

handlers = {SomeContainerClass: iter,

OtherContainerClass: OtherContainerClass.get_elements}

Adapted from http://code.activestate.com/recipes/577504/

utils.is_pyFormex(appname)

Checks whether an application name is rather a script name