3. qcobj Package

3.1. qconfigobj Module

Validator errors classes:

Validator class:

QConfigObj classes:

class qcobj.qconfigobj.Certifier(*args, **kargs)

Bases: validate.Validator

A Validator for Quantities

See also

Validator class

__init__(*args, **kargs)

>>> vtri = Validator()

quantity_chek(value, *args, **kargs)

Check if value has the right dimensions and is in the allowed range.

Quantity MUST be specified in configspec like:

>>> quantity(units='Pa / s', min=0, max=100, default=50 Pa /s)

where:

• min and max CAN be positional arguments

• default value can be specified in any dimensionally correct unit after the first blank

Parameters

value (instance) – the value we are checking

Returns

validated quantity (or quantities)

Raises

• VdtUnitsError if no units are specified –

• ValueError if value is not a quantity –

• SyntaxError if quantity specification uses a wrong syntax –

• VdtDimensionalityError if value has the wrong physical – dimension

• VdtRangeError if value (converted to the units defined – in configspec) is not in range [vmin, vmax]

quantity_list_chek(value, *args, **kargs)

Check if value has the right dimensions and is in the allowed range.

Quantity MUST be specified in configspec like:

>>> quantity_list(units='Pa / s', min=0, max=100, nmin=1,
        nmax=2, default=list('50 Pa/s', '75 Pa/s'))

where:

• min, max, nmin, nmax CAN be positional arguments

• default value can be specified in any dimensionally correct unit after the first blank

Parameters

value (instance) – the value we are checking

Returns

validated quantity (or quantities)

Raises

• VdtUnitsError if no units are specified –

• ValueError if value is not a quantity –

• SyntaxError if quantity specification uses a wrong syntax –

• VdtDimensionalityError if value has the wrong physical – dimension

• VdtRangeError if value (converted to the units defined – in configspec) is not in range [vmin, vmax]

class qcobj.qconfigobj.QConfigObj(*args, **kargs)

Bases: qcobj.qconfigobj._QConfigObj

A Quantity aware ConfigObj class with CONFIGFILES_KEY support

__init__(*args, **kargs)

Create a new instance. kargs are from configobj.ConfigObj

Keyword Arguments

• infile (file instance) – Input file (None)

• configspec (list of strings) – configspec (None)

• encoding (string) – encoding (None)

• interpolation (bool) – True

• raise_errors (bool) – False

• list_values (bool) – True

• create_empty (bool) – False

• file_error (bool) – False

• stringify (bool) – True,

• indent_type (string) – None

• default_encoding (string) – None

• unrepr (bool) – False

• write_empty_values (bool) – False

• _inspec (bool) – False

• strict (bool) – True

• noextra (bool) – True

exception qcobj.qconfigobj.QConfigObjExtra(value)

Bases: configobj.ConfigObjError

Extra value / section error

__init__(value)

Initialize self. See help(type(self)) for accurate signature.

exception qcobj.qconfigobj.QConfigObjInvalid(value)

Bases: configobj.ConfigObjError

Invalid value error

__init__(value)

Initialize self. See help(type(self)) for accurate signature.

class qcobj.qconfigobj.Q_(*args, **kargs)

Bases: pint.quantity.build_quantity_class.<locals>.Quantity

A Quantity class with user settable preferred units for representation

static __new__(cls, *args, **kargs)

Create and return a new object. See help(type) for accurate signature.

__reduce__()

Allow pickling quantities. Since UnitRegistries are not pickled, upon unpickling the new object is always attached to the application registry.

__repr__()

Return UnitRegistry Quantity representation

__str__()

Return qcobj.qconfigobj.eng_string() representation of magnitude rounded at 6 decimals with units

exception qcobj.qconfigobj.VdtDimensionalityError(dim1, dim2)

Bases: validate.ValidateError

Dimensionality error class

__init__(dim1, dim2)

Initialize self. See help(type(self)) for accurate signature.

exception qcobj.qconfigobj.VdtLengthError(value, nmin, nmax)

Bases: validate.ValidateError

List length error class

__init__(value, nmin, nmax)

Initialize self. See help(type(self)) for accurate signature.

exception qcobj.qconfigobj.VdtRangeError(value, vmin, vmax, units)

Bases: validate.ValidateError

Range error class

__init__(value, vmin, vmax, units)

Initialize self. See help(type(self)) for accurate signature.

exception qcobj.qconfigobj.VdtUnitsError(value)

Bases: validate.ValidateError

Missing units keyword in quantity type specifier

__init__(value)

Initialize self. See help(type(self)) for accurate signature.

class qcobj.qconfigobj._QConfigObj(*args, **kargs)

Bases: configobj.ConfigObj

A Quantity aware ConfigObj class

__init__(*args, **kargs)

Create a new instance. kargs are from configobj.ConfigObj

Keyword Arguments

• infile (file instance) – Input file (None)

• configspec (list of strings) – configspec (None)

• encoding (string) – encoding (None)

• interpolation (bool) – True

• raise_errors (bool) – False

• list_values (bool) – True

• create_empty (bool) – False

• file_error (bool) – False

• stringify (bool) – True,

• indent_type (string) – None

• default_encoding (string) – None

• unrepr (bool) – False

• write_empty_values (bool) – False

• _inspec (bool) – False

• strict (bool) – True

• noextra (bool) – True

_extra()

Save extra values / sections in instance

_saveErrors()

Save errors in a configuration file in terse format

_specAtPath(path)

Return configspec section at path

Parameters

path (list) – list of section names

Returns

configspec section at path

comment(path, key)

Return comment from configspec for key at path

Parameters

• path (list) – list of section names

• key (string) – valid key in section at path

Returns

comment from configspec for key at path

configUnits(section, key)

Return units string for key in section or None

Parameters

• section (qcobj.qconfigobj.QConfigObj.Section) – instance

• key (string) – valid key in section

Returns

Return units string for key in section or None

pretty()

Return pretty string representation for report attribute

Returns

pretty string representation for report attribute

reference_quantity(section, key)

Return reference quantity for section[key]

Parameters

• section (qcobj.qconfigobj.QConfigObj.Section) – instance

• key (string) – valid key in section

Returns

Return reference quantity for section[key]

Note

At present USED ONLY IN GMOD2.boundaryCondition

val_to_default(section, key, value)

Set section[key] with value converted to default units (if any)

Parameters

• section (qcobj.qconfigobj.QConfigObj.Section) – instance

• key (string) – valid key in section

• value (float or int) – new value

Note

At present used only in addMag and setMag

validRange(path, key)

Return valid range for quantity key at path

Parameters

• path (list) – list of section names

• key (string) – valid key in section at path

Returns

valid range for quantity key at path

write_to_string()

Return write content in a string

Returns

Return write content in a string

qcobj.qconfigobj.colorize(*args)

qcobj.qconfigobj.eng_string(x, fmt='%s', si=False, doround=None)

Returns float/int value <x> formatted in a simplified engineering format using an exponent that is a multiple of 3.

Parameters

• fmt (string) – printf-style string used to format the value before the exponent.

• si (boolean) – if True, use SI suffix for exponent, e.g. k instead of e3, n instead of e-9 etc.

• doround (boolean) – if not None round the number to doround decimal digits

Returns: float/int value <x> formatted in a simplified engineering

format using an exponent that is a multiple of 3.

E.g. with fmt='%.2f':
    1.23e-08 => 12.30e-9
        123 => 123.00
    1230.0 => 1.23e3
-1230000.0 => -1.23e6

and with si=True:
    1230.0 => 1.23k
-1230000.0 => -1.23M

and with doround=6
0.30000000000000004 => 0.3

qcobj.qconfigobj.errors(cobj, ok)

Return errors in a configuration file in terse format

Parameters

• cobj (qcobj.qconfigobj.QConfigObj instance) – instance

• ok (dict) – results dictionary returned by validate

Returns

error messages string

qcobj.qconfigobj.extract(string, start='(', stop=')', firststop=True)

Return substring between start and first/last stop characters

Parameters

• string (string) – the string to extract from

• start (string) – the left delimiter string

• stop (string) – the right delimiter string

• firststop (bool) – if True extract to the rightmost stop

Returns

the extracted string

qcobj.qconfigobj.isStringLike(s)

Returns True if s acts “like” a string, i.e. is str or unicode.

Parameters

s (string) – instance to inspect

Returns

True if s acts like a string

qcobj.qconfigobj.makeSpec(name, params, level=0)

Create ConfigObj configspec string definition for section name

Parameters

• name (string) – name of the section we are building

• params (Odict) –

  ordered dict instance with the directives: The directives are (key, value) where value is a dictionary with the keywords:

  • comments: a comment string or a list of comment strings

  • units: a string with the units of measure

  • default: a default value (optional)

  • min: minimum value accepted (optional)

  • max: maximum value accepted (optional)

• OLD (deprecated) –

• params – ordered dict instance with the directives: The directives are (key, value) where value is a tuple of (comment, comment, … comment, ‘units, min, max’, default). In case of int and float optional minimum or min and max values can be specified separated by ONE SINGLE blank char

• level (int) – indentation level

Returns

configSpec string

qcobj.qconfigobj.makeSpecEntry(key, spec)

Accept new syntax suggested by Reviewer #1

Parameters

• key (string) – keyword

• spec (dict) –

  dictionary defining the quantity and valid range. Valid keywords:

  • comments: a comment string or a list of comment strings

  • units: a string with the units of measure

  • default: a default value (optional)

  • min: minimum value accepted (optional)

  • max: maximum value accepted (optional)

Returns

configSpec string for key

qcobj.qconfigobj.msec2cmyear(ms)

Return m/s converted to cm/year Quantity

Parameters

ms (float) – meters per second

Returns

cm / year

qcobj.qconfigobj.qLike(value, section, key)

Return value converted to a quantity like key in section

Parameters

• value (float or int) – value to convert

• section (qcobj.qconfigobj.QConfigObj.Section) – instance

• key (string) – an existing key in section

Returns

A qcobj.qconfigobj.Q_ instance like the one at

section[key] with magnitude value

qcobj.qconfigobj.reindent(s, numSpaces=4, no_empty_lines=False)

Return string s reindented by numSpaces spaces

Parameters

• s (string) – string to reindent

• numSpaces (int) – number of spaces to shift to the right

• no_empty_lines (bool) – if True remove empty lines

Returns

reindented string

qcobj.qconfigobj.setVal(section, key, value)

Set value to section[key] converted to default units

Parameters

• section (qcobj.qconfigobj.QConfigObj.Section) – instance

• key (string) – valid key for section

• value (float or int) – value to set at section[key] converted to Quantity

qcobj.qconfigobj.splitPolygons(s)

Return a list of polygons from s. Separator is a blank line. Separation lines with blanks are digested as well.

Parameters

s (string) – string defining polygon(s) separated by a blank line. One vertex per line

Returns

list with polygons

qcobj.qconfigobj.sumVal(section, key, value)

Add value to section[key] converted to default units

Parameters

• section (qcobj.qconfigobj.QConfigObj.Section) – instance

• key (string) – valid key for section

• value (float or int) – value to add to section[key]

qcobj.qconfigobj.toBaseUnits(q)

Return magnitude of quantity q converted to base units * * Used for polygons * *

Parameters

q (qcobj.qconfigobj.Q_) – instance

Returns

magnitude of q in base units

qcobj.qconfigobj.val(section, key)

Return value of section[key] in units specified in configspec

Parameters

• section (qcobj.qconfigobj.QConfigObj.Section) – instance

• key (string) – valid key for section

Returns

values in section[key] converted to units defined in configspec

qcobj.qconfigobj.vval(d, k)

Return magnitude in units specified in configspec for key k’ in qconfigobj section `d or simply magnitude if d is a dict instance

Parameters

• d (dict or qcobj.qconfigobj.QConfigObj.Section instance) – dict_like

• k (string) – key in d

Returns

result of qcobj.qconfigobj.val() (d, k) or simply the magnitude of d[k]

3.2. utils Module

qcobj.utils.makeDoc(configSpecLines)

Return dictionary with sphinx documentation for configspecLines

Parameters

configSpecLines (list) – configspec file lines for ConfigObj

Returns

dictionary with sphinx documentation for configspecLines

Return type

dict

qcobj.utils.makeSphinxDoc(configSpecLines, docsource, header)

Create Sphinx documentation for configspecLines at directory docsource.

Parameters

• configSpecLines (list) – configspec file lines for ConfigObj

• docsource (Path) – root directory for documentation.

• header (str) – header text for the documentation

qcobj.utils.saveSection(section, name, docsource, subpath, header='')

Recursively save configobject section and subsections documentation into separate files, one for each section, in a nested folder structure starting at docsource.

Parameters

• section (dict) – dictionary with the sections documentation

• name (str) – .rst file name of the document

• docsource (Path) – write .rst file starting from this directory

• subpath (Path) – subdirctory to which write the .rst document

• header (str) – header for the first level (root) of the document

3.3. cfggui Module

class qcobj.cfggui.CfgGui(opts)

Bases: PySide2.QtWidgets.QWidget

__init__(opts)

Initialize self. See help(type(self)) for accurate signature.

_loadQCobjs(pn)

Load all QConfigObj instances form file(s) in pn Remove blanks in polygons and create the widgets for every instance.

closeEvent(self, event: PySide2.QtGui.QCloseEvent)

openFile()

saveFile()

setFileChanged(filename)

staticMetaObject = <PySide2.QtCore.QMetaObject object>

toggleExpand(*args)

class qcobj.cfggui.QuantityDialog(text, parent=None)

Bases: PySide2.QtWidgets.QDialog

__init__(text, parent=None)

Initialize self. See help(type(self)) for accurate signature.

staticMetaObject = <PySide2.QtCore.QMetaObject object>

class qcobj.cfggui.TreeItem(name='', parent=None, data=None)

Bases: PySide2.QtCore.QObject

__init__(name='', parent=None, data=None)

Initialize self. See help(type(self)) for accurate signature.

appendChild(item)

child(row)

childCount()

columnCount()

data()

name()

parent(self) → PySide2.QtCore.QObject

row()

setData(value, validRange, column)

Set node data with value converted to appropriate units as stated in validRange and return it or return None

staticMetaObject = <PySide2.QtCore.QMetaObject object>

class qcobj.cfggui.TreeModel(parent, qcobj=None)

Bases: PySide2.QtCore.QAbstractItemModel

__init__(parent, qcobj=None)

Initialize self. See help(type(self)) for accurate signature.

columnCount(self, parent: PySide2.QtCore.QModelIndex = Invalid(PySide2.QtCore.QModelIndex)) → int

data(self, index: PySide2.QtCore.QModelIndex, role: int = PySide2.QtCore.Qt.ItemDataRole.DisplayRole) → typing.Any

flags(index)

Must be implemented

headerData(self, section: int, orientation: PySide2.QtCore.Qt.Orientation, role: int = PySide2.QtCore.Qt.ItemDataRole.DisplayRole) → typing.Any

index(self, row: int, column: int, parent: PySide2.QtCore.QModelIndex = Invalid(PySide2.QtCore.QModelIndex)) → PySide2.QtCore.QModelIndex

parent(self) → PySide2.QtCore.QObject

parent(self, child: PySide2.QtCore.QModelIndex) -> PySide2.QtCore.QModelIndex

rowCount(self, parent: PySide2.QtCore.QModelIndex = Invalid(PySide2.QtCore.QModelIndex)) → int

setComparison(qcobj)

Set comparison qcobj for highlighting differences

setData(self, index: PySide2.QtCore.QModelIndex, value: typing.Any, role: int = PySide2.QtCore.Qt.ItemDataRole.EditRole) → bool

setupModelData(qcobj)

Populate model with data from QCconfigObj instance

staticMetaObject = <PySide2.QtCore.QMetaObject object>

class qcobj.cfggui.TreeView(*args)

Bases: PySide2.QtWidgets.QTreeView

__init__(*args)

Initialize self. See help(type(self)) for accurate signature.

resizeColumns()

staticMetaObject = <PySide2.QtCore.QMetaObject object>

qcobj.cfggui.colorize(s, color)

Return an HTML colorized string for s

qcobj.cfggui.deBlank(section, key, wordsPerLine=2)

Remove blanks and format with wordsPerLine words per line every value with the key == ‘polygon’

qcobj.cfggui.getPath(index)

Return section path at index

qcobj.cfggui.noBlanks(withblanks, wordsPerLine=2)

Remove blanks and format with wordsPerLine words per line

qcobj.cfggui.split_list(L, n, stringify=True)

Return a generator with the list L splitted in groups of n elements. If stringify evaluates as true, the groups of n elements are joined and terminated by

qcobj.cfggui.valueAtPath(cobj, path, name)

Return cobj value at path or raise RuntimeError

3.4. qtCompat Module

The main initialization of our PySide2/PyQt5 Package.

Warning

This module tries to import PySide2 if available, otherwise defaults to PyQt5 for the GUI. To change this behaviour set TRY_PYSIDE to False.

Author

• 2009-2011 Nicola Creati

• 2009-2020 Roberto Vidmar

Copyright

2011-2020 Nicola Creati <ncreati@inogs.it> Roberto Vidmar <rvidmar@inogs.it>

License

MIT/X11 License (see license.txt)

qcobj.qtCompat.getOpenFileName(*args, **kargs)

Wrap to PySide QtWidgets.QFileDialog.getOpenFileName

qcobj.qtCompat.getOpenFileNames(*args, **kargs)

Wrap to PySide QtWidgets.QFileDialog.getOpenFileNames

qcobj.qtCompat.getSaveFileName(*args, **kargs)

Wrap to PySide QtWidgets.QFileDialog.getSaveFileName