# 14. `utils` — A collection of miscellaneous utility functions.

## 14.1. Classes defined in module utils

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: string: name 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: string: file open mode: ‘r’ for read, ‘w’ for write or ‘a’ for append mode. See also the documentation for Python’s open function. For compressed files, append mode is not yet available.
  - compr: string, one of ‘gz’ or ‘bz2’: identifies the compression algorithm to be used: gzip or bzip2. If the file name is ending with ‘.gz’ or ‘.bz2’, compr is set automatically from the extension.
  - level: an integer from 1..9: 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.
  - 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.

  The name is a string including a numeric part, which is incremented at each call of the ‘next()’ method.

  The constructor takes name template and a possible extension as arguments. If the name starts with a non-numeric part, it is taken as a constant part. If the name ends with a numeric part, the next generated names will be obtained by incrementing this part. If not, a string ‘-000’ will be appended and names will be generated by incrementing this part.

  If an extension is given, it will be appended as is to the names. This makes it possible to put the numeric part anywhere inside the names.

  Example:

      >>> 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']
      >>> next(NameSequence('abc','.png'))
      'abc-000.png'
      >>> N = NameSequence('/home/user/abc23','5.png')
      >>> [ next(N) for i in range(2) ]
      ['/home/user/abc235.png', '/home/user/abc245.png']

  `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.

  `files`(sort=<function hsorted>)

    Return a (sorted) list of files matching the name 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.

class `utils.``DictDiff`(current_dict, past_dict)

  A class to compute the difference between two dictionaries

  Parameters:

  - current_dict: dict
  - past_dict: dict

  The differences are reported as sets of keys: - 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

## 14.2. Functions defined in module utils

`utils.``filterWarning`(message, module='', category='U', action='ignore')

  Add a warning message to the warnings filter.

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

`utils.``warning`(message, level=<type 'exceptions.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 DeprecationWarning.

`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`(cmd, timeout=None, wait=True, verbose=False, raise_error=False, **kargs)

  Execute an external command.

  This (and the more user oriented `utils.command()`) are the prefered way to execute external commands from inside pyFormex.

  Parameters:

  - cmd: a string with the command to be executed
  - timeout: float. If specified and > 0.0, the command will time out and be terminated or killed after the specified number of seconds.
  - wait: bool. If True (default), the caller waits for the Process to terminate. Setting this value to False will allow the caller to continue, but it will not be able to retrieve the standard output and standard error of the process.
  - verbose: bool. If True, some extra informative message are printed: - the command that will be run - an occurring timeout condition, - in case of a nonzero exit, the full stdout, exit status and stderr
  - raise_error: bool. If True, and verbose is True, and the command fails to execute or returns with a nonzero return code other than one cause by a timeout, an error is raised.

  Additional parameters can be specified and will be passed to the Popen constructor. See the Python documentation for full info. Some typical examples:

  - shell: bool: default False. If True, the command is run in a new shell. The cmd should then be specified exactly as it would be entered in a shell.
  - stdout: an open file object. The standard output of the command will be written to that file.
  - stdin: an open file object. The standard input of the command will be read from that file.

  Returns the Process used to run the command. This gives access to all its info, like the exit code, stdout and stderr, and whether the command timed out or not. See `Process` for more info. This Process is also saved as the global variable `utils.last_command` to allow checking the outcome of the command from other places but the caller.

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

  Run an external command in a user friendly way.

  This is equivalent with the `system()` function but having verbose=True and raise_error=True by default.

`utils.``lastCommandReport`()

  Produce a report about the last command.

  This is mostly useful in interactive work, to find out why a command failed.

`utils.``killProcesses`(pids, signal=15)

  Send the specified signal to the processes in list

  - pids: a list of process ids.
  - signal: the signal to send to the processes. The default (15) will try to terminate the process. See ‘man kill’ for more values.

`utils.``execSource`(script, glob={})

  Execute Python code in another thread.

  - script: a string with executable Python code
  - glob: an optional gloabls dict specifying the environment in which the source code is executed.

`utils.``splitFileDescription`(fdesc, compr=False)

  Split a file descriptor.

  A file 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)’. The values of `utils.file_description` all have this format.

  This function splits the file descriptor in two parts: the leading text and a list of global patterns.

  Parameters:

  - ftype: a file descriptor string.
  - compr: bool. If True, the compressed file types are automatically added.

  Returns a tuple:

  - desc: the file type description text
  - ext: a list of strings each starting with a ‘.’.

      >>> splitFileDescription(file_description['img'])
      ('Images ', ['.png', '.jpg', '.jpeg', '.eps', '.gif', '.bmp'])
      >>> splitFileDescription(file_description['pgf'],compr=True)
      ('pyFormex geometry files ', ['.pgf', '.pgf.gz', '.pgf.bz2'])

`utils.``fileExtensionsFromFilter`(fdesc, compr=False)

  Return the list of file extensions from a given filter.

  Parameters:

  - fdesc: one of the values in `utils.file_description`.

  Returns a list of strings starting with a ‘.’.

      >>> fileExtensionsFromFilter(file_description['ccx'])
      ['.dat', '.inp']
      >>> fileExtensionsFromFilter(file_description['ccx'],compr=True)
      ['.dat', '.dat.gz', '.dat.bz2', '.inp', '.inp.gz', '.inp.bz2']

`utils.``fileExtensions`(ftype, compr=False)

  Return the list of file extensions from a given type.

  ftype is one of the keys in `utils.file_description`.

  Returns a list of strings starting with a ‘.’.

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

`utils.``fileTypes`(ftype, compr=False)

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

  This is like fileExtensions, but the strings do not have the leading dot and are guaranteed to be lower case.

  Returns a list of normalized file types.

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

`utils.``addCompressedTypes`(ext)

  Add the defined compress types to a list of extensions

      >>> addCompressedTypes(['.ccx','.inp'])
      ['.ccx', '.ccx.gz', '.ccx.bz2', '.inp', '.inp.gz', '.inp.bz2']

`utils.``fileDescription`(ftype, compr=False)

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

  Parameters:

  - ftype: a string or a list of strings. If it is a list, the return value will be a list of the corresponding return values for each of the strings in it. Each input string is converted to lower case and represents a file type. It can be one of the following:
    - a key in the `file_description` dict: the corresponding value will be returned (see Examples below).
    - a string of only alphanumerical characters: it will be 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:

      >>> print(formatDict(file_description))
      all = 'All files (*)'
      ccx = 'CalCuliX files (*.dat *.inp)'
      gz = 'Compressed files (*.gz *.bz2)'
      dcm = 'DICOM images (*.dcm)'
      dxf = 'AutoCAD .dxf files (*.dxf)'
      dxfall = 'AutoCAD .dxf or converted(*.dxf *.dxftext)'
      dxftext = 'Converted AutoCAD files (*.dxftext)'
      flavia = 'flavia results (*.flavia.msh *.flavia.res)'
      gts = 'GTS files (*.gts)'
      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 *.post)'
      pyformex = 'pyFormex scripts (*.py *.pye)'
      pyf = 'pyFormex projects (*.pyf)'
      smesh = 'Tetgen surface mesh files (*.smesh)'
      stl = 'STL files (*.stl)'
      stlb = 'Binary STL files (*.stl)'
      surface = 'Surface models (*.off *.gts *.stl *.neu *.smesh *.vtp *.vtk)'
      tetgen = 'Tetgen files (*.poly *.smesh *.ele *.face *.edge *.node *.neigh)'
      vtk = 'All VTK types (*.vtk *.vtp)'
      vtp = 'vtkPolyData file (*.vtp)'
      <BLANKLINE>
      >>> fileDescription('img')
      'Images (*.png *.jpg *.jpeg *.eps *.gif *.bmp)'
      >>> fileDescription(['stl','all'])
      ['STL files (*.stl)', 'All files (*)']
      >>> fileDescription('doc')
      'DOC files (*.doc)'
      >>> fileDescription('inp')
      'Abaqus or CalCuliX input files (*.inp)'
      >>> fileDescription('*.inp')
      '*.inp'
      >>> fileDescription(['stl','all'],compr=True)
      ['STL files  (*.stl *.stl.gz *.stl.bz2)', 'All files  (* *.gz *.bz2)']

`utils.``splitFilename`(filename, accept_ext=None, reject_ext=None)

  Split a file name in dir,base,ext tuple.

  Parameters:

  - filename: a filename, possibly including a directory path
  - accept_ext: optional list of acceptable extension strings. If specified, only extensions appearing in this list will be recognized as such, while other ones will be made part of the base name.
  - reject_ext: optional list of unacceptable extension strings. If specified, extensions appearing in this list will not be recognized as such, and be made part of the base name.

  Returns a tuple dir,base,ext:

  - dir: the directory path, not including the final path separator (unless it is the only one). If the filename starts with a single path separator, dir will consist of that single separator. If the filename does not contain a path separator, dir will be an empty string.
  - base: filename without the extension. It can only be empty if the input is an empty string.
  - ext: file extension: This is the part of the filename starting from the last ‘.’ character that is not the first character of the filename. If the filename does not contain a ‘.’ character or the only ‘.’ character is also the first character of the filename (after the last path separator), the extension is an empty string. If not empty, it always starts with a ‘.’. A filename with

  Examples

      >>> splitFilename("cc/dd/aa.bb")
      ('cc/dd', 'aa', '.bb')
      >>> splitFilename("cc/dd/aa.")
      ('cc/dd', 'aa', '.')
      >>> splitFilename("..//aa.bb")
      ('..', 'aa', '.bb')
      >>> splitFilename("aa.bb")
      ('', 'aa', '.bb')
      >>> splitFilename("aa/bb")
      ('aa', 'bb', '')
      >>> splitFilename("aa/bb/")
      ('aa/bb', '', '')
      >>> splitFilename("/aa/bb")
      ('/aa', 'bb', '')
      >>> splitFilename(".bb")
      ('', '.bb', '')
      >>> splitFilename("/")
      ('/', '', '')
      >>> splitFilename(".")
      ('', '.', '')
      >>> splitFilename("")
      ('', '', '')
      >>> splitFilename("cc/dd/aa.bb",accept_ext=['.aa','.cc'])
      ('cc/dd', 'aa.bb', '')
      >>> splitFilename("cc/dd/aa.bb",reject_ext=['.bb'])
      ('cc/dd', 'aa.bb', '')

`utils.``buildFilename`(dirname, basename, ext='')

  Build a filename from a directory path, filename and optional extension.

  The dirname and basename are joined using the system path separator, and the extension is added at the end. Note that no ‘.’ is added between the basename and the extension. While the extension will normally start with a ‘.’, this function can also be used to add another tail to the filename.

  This is a convenience function equivalent with:

      os.path.join(dirname,basename) + ext

`utils.``changeExt`(filename, ext, accept_ext=None, reject_ext=None)

  Change the extension of a file name.

  This function splits the specified file name in a base name and an extension, replaces the extension with the specified one, and returns the reassembled file name. If the filename has no extension part, the specified extension is just appended.

  Parameters:

  - fn: file name, possibly including a directory path and extension
  - ext: string: required extension of the output file name. The string should start with a ‘.’.
  - accept_ext, reject_ext: lists of strings starting with a ‘.’. These have the same meaning as in `splitFilename()`.

  Returns a file name with the specified extension.

  Example:

      >>> changeExt('image.png','.jpg')
      'image.jpg'
      >>> changeExt('image','.jpg')
      'image.jpg'
      >>> changeExt('image','jpg') # Deprecated
      'image.jpg'
      >>> changeExt('image.1','.jpg')
      'image.jpg'
      >>> changeExt('image.1','.jpg',reject_ext=['.1'])
      'image.1.jpg'

`utils.``tildeExpand`(fn)

  Perform tilde expansion on a filename.

  Bash, the most used command shell in Linux, expands a ‘~’ in arguments to the users home direction. This function can be used to do the same for strings that did not receive the bash tilde expansion, such as strings in the configuration file.

`utils.``normalizeFileType`(ftype)

  Normalize a filetype string.

  The string is converted to lower case and a leading dot is removed. This makes it fit for use with a filename extension.

  Example:

      >>> normalizeFileType('pdf')
      'pdf'
      >>> normalizeFileType('.pdf')
      'pdf'
      >>> normalizeFileType('PDF')
      'pdf'
      >>> normalizeFileType('.PDF')
      'pdf'

`utils.``splitExt`(fname)

  Split a file name in a=name and extension.

  The extension is the part of the file name starting from the last dot. However, if the file extension is ‘.gz’ or ‘.bz2’, and the filename contains another dot, the extension is set to the filename part after starting at the penultimate dot. This allows for transparent handling of compressed files.

  Returns a tuple (name,ext).

  Example:

      >>> splitExt('pyformex')
      ('pyformex', '')
      >>> splitExt('pyformex.pgf')
      ('pyformex', '.pgf')
      >>> splitExt('pyformex.pgf.gz')
      ('pyformex', '.pgf.gz')
      >>> splitExt('pyformex.gz')
      ('pyformex', '.gz')

`utils.``fileTypeFromExt`(fname)

  Derive the file type from the file name.

  The derived file type is the file extension part as obtained by `splitExt()` without the leading dot and in lower case.

  Example:

      >>> fileTypeFromExt('pyformex')
      ''
      >>> fileTypeFromExt('pyformex.pgf')
      'pgf'
      >>> fileTypeFromExt('pyformex.pgf.gz')
      'pgf.gz'
      >>> fileTypeFromExt('pyformex.gz')
      'gz'

`utils.``fileTypeComprFromExt`(fname)

  Derive the file type and compression from the file name.

  This derives the uncompressed file type and the compression type from the file name extension.

  It first computes fileTypeFromExt(fname) and then splits it in the pure filetype and the compression type.

  Returns a tuple:

  - filetype: the file type of the uncompressed file
  - compressed: the compression type: either ‘’, ‘.gz’ or ‘.bz2’. If the file was uncompressed, this is an empty string.

  Example:

      >>> fileTypeComprFromExt('pyformex')
      ('', '')
      >>> fileTypeComprFromExt('pyformex.pgf')
      ('pgf', '')
      >>> fileTypeComprFromExt('pyformex.pgf.gz')
      ('pgf', 'gz')
      >>> fileTypeComprFromExt('pyformex.gz')
      ('gz', '')

`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 splitFilename(fn)[1]

`utils.``fileSize`(fn)

  Return the size in bytes of the file fn

`utils.``findIcon`(name)

  Return the file name for an icon with given name.

  If no icon file is found, returns the question mark icon.

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

  Return the list of available icons by their name.

  - dirs: list of paths. If specified, only return names from these directories.
  - types: list of strings, each starting with a dot. If specified, only return names of icons matching any of these file types.

`utils.``prefixFiles`(prefix, files)

  Prepend a prefix path to a list of filenames.

`utils.``unPrefixFiles`(prefix, files)

  Remove a prefix path from a list of filenames.

  The given prefix path is removed from all filenames that start with the prefix. Other filenames are untouched. Only full path components are removed. The changed files are guaranteed not to start with a ‘/’.

  Returns the modified list.

  Examples:

      >>> unPrefixFiles('/home',['/home/user1','/home//user2','/home2/user','/root'])
      ['user1', 'user2', '/home2/user', '/root']

`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.``listDir`(path)

  List the contents of the specified directory path.

  Returns a tuple (dirs,files), where dirs is the list of subdirectories in the path, and files is the list of files. Either of the lists can be empty. If the path does not exist or is not accessible, two empty lists are returned.

`utils.``listDirs`(path)

  List the subdirectories in the specified directory path.

  Returns a list with the names of all directory type entries in the specified path. If there are no directories, or the path does not exist or is not accessible, returns an empty list.

  This is syntactic sugar for listDir(path)[0].

`utils.``listFiles`(path)

  Return the files of the specified directory path.

  Returns a list with the names of all file type entries in the specified path. If there are no files, or the path does not exist or is not accessible, returns an empty list.

  This is syntactic sugar for listDir(path)[0].

`utils.``listTree`(path, listdirs=True, topdown=True, sorted=False, excludedirs=[], excludefiles=[], includedirs=[], includefiles=[], symlinks=True)

  List all files in path.

  If `listdirs==False`, directories are not listed. By default the tree is listed top down and entries in the same directory are unsorted.

  exludedirs and excludefiles are lists of regular expressions with dirnames, resp. filenames to exclude from the result.

  includedirs and includefiles can be given to include only the directories, resp. files matching any of those patterns.

  Note that ‘excludedirs’ and ‘includedirs’ force top down handling.

  If symlinks is set False, symbolic links are removed from the list.

`utils.``removeFile`(filename)

  Remove a file, ignoring error when it does not exist.

`utils.``removeTree`(path, top=True)

  Remove all files below path. If top==True, also path is removed.

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

  Return a list of the pyFormex source .py files.

  - symlinks: if False, files that are symbolic links are retained in the list. The default is to remove them.
  - extended: if True, the .py files in all the paths in the configured appdirs and scriptdirs are also added.

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

  Finds pattern in the pyFormex source .py 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.``diskSpace`(path, units=None, ndigits=2)

  Returns the amount of diskspace of a file system.

  Parameters:

  - path: a path name inside the file system to be probed.
  - units,`ndigits`: if untis is specified, the sizes will be reported in this units. See `humanSize()` for details`. The default is to report the number of bytes.

  Returns the total, used and available disk space for the file system containing the given path.

  Notice that used + available does not necessarily equals 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: a number (integer or float)
  - units: 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: integer. If >= 0, the result is rounded to the specified number of decimal digits.

  Returns: a float value rounded to ndigits digits.

  Example:

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

`utils.``tempName`(*args, **kargs)

  Create a temporary file.

  Creates a temporary file by calling `tempfile.mkstemp()` with the specified arguments and returns the file name. It is equivalent with:

      tempfile.mkstemp(*args,**kargs)[1]

  The user is responsible for removing the temporary file.

  Example:

      >>> tmp = tempName('.txt')
      >>> s = open(tmp,'w').write('hallo')
      >>> s = open(tmp,'r').read()
      >>> os.remove(tmp)
      >>> print(s)
      hallo

`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.``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.``versaText`(obj)

  Versatile text creator

  This functions converts any input into a (multiline) string. Currently, different inputs are treated as follows:

  - string: return as is,
  - function: use the output of the function as input,
  - anything else: use str() or repr() on the object.

      >>> versaText("Me")
      'Me'
      >>> versaText(1)
      '1'
      >>> versaText(len("Me"))
      '2'
      >>> versaText({1:"Me"})
      "{1: 'Me'}"

`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: input file name
  - gzipped: output file name. If not specified, it will be set to the input file name + ‘.’ + compr. An existing output file will be overwritten.
  - remove: if True (default), the input file is removed after succesful compression
  - level: an integer from 1..9: 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’ or ‘bz2’: the compression algorithm to be used. The default is ‘gz’ for gzip compression. Setting to ‘bz2’ will use bzip2 compression.

  Returns the name of the compressed file.

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

  Uncompress a file in gzip/bzip2 format.

  Parameters:

  - filename: compressed input file name (usually ending in ‘.gz’ or ‘.bz2’)
  - unzipped: output file name. If not specified and filename ends with ‘.gz’ or ‘.bz2’, it will be set to the filename with the ‘.gz’ or ‘.bz2’ removed. If an empty string is specified or it is not specified and filename does not end in ‘.gz’ or ‘.bz2’, 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 he is ready with it.
  - remove: if True (default), the input file is removed after succesful decompression. You probably want to set this to False when decompressing to a temporary file.
  - compr: ‘gz’ or ‘bz2’: the compression algorithm used in the input file. If filename ends with either ‘.gz’ or ‘.bz2’, it is automatically set from the extension. Else, the default ‘gz’ is used.

  Returns the name of the decompressed file.

`utils.``mtime`(fn)

  Return the (UNIX) time of last change of file fn.

`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.``is_script`(appname)

  Checks whether an application name is rather a script name

`utils.``is_pyFormex`(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.``prefixDict`(d, prefix='')

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

  - d: a dict where all the keys are strings.
  - prefix: a string

  The return value is a dict with all the items of d, but where the keys have been prefixed with the given string.

  Example:

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

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

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

  - d: a dict where all the keys are strings.
  - prefix: a string
  - strip: if True (default), the prefix is stripped from the keys.

  The return value is 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.

  Example:

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

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

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

  - d: a dict.
  - keys: a set of key values, can be a list or another dict.
  - remove: if True, the selected keys are removed from the input dict.

  Returns a dict with all the items from d whose key is in keys. See `removeDict()` for the complementary operation.

  Example:

      >>> 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)

  Remove a set of keys from a dict.

  - d: a dict
  - keys: a set of key values

  The return value is a dict with all the items from d whose key is not in keys. This is the complementary operation of selectDict.

  Example:

      >>> 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.``stuur`(x, xval, yval, exp=2.5)

  Returns a (non)linear response on the input x.

  xval and yval should be lists of 3 values: `[xmin,x0,xmax], [ymin,y0,ymax]`. Together with the exponent exp, they define the response curve as function of x. With an exponent > 0, the variation will be slow in the neighbourhood of (x0,y0). For values x < xmin or x > xmax, the limit value ymin or ymax is returned.

`utils.``listAllFonts`()

  List all fonts known to the system.

  Returns a sorted list of path names to all the font files found on the system.

  This uses fontconfig and will produce a warning if fontconfig is not installed.

`utils.``is_valid_mono_font`(fontfile)

  Filter valid monotype fonts

`utils.``listMonoFonts`()

  List all monospace font files found on the system.

`utils.``defaultMonoFont`()

  Return a default monospace font for the system.

`utils.``currentScript`()

  Return the text of the script in execution, if any.

  If a script file is currently being executed, returns the text of that script, else returns an empty string.

`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/