5.4. yapydata.datatree.synini

5.4.1. Module

The YapyData.ini module provides the extended INI file syntax access with optional extended syntax features. The core syntax is defined by the standard library configparser.ConfigParser, YapyData.data supports Python2.7, and Python3.5+.

Sources: yapydata/datatree/synini.py

5.4.2. Functions

5.4.2.1. grow_branch

yapydata.datatree.synini.grow_branch(*subpath, **kargs)

Creates a new branch including the assigned value to the last node. The node types are defined by the types of the subpath entries.

Supports a single linear branch only, no sub-branching.

The created path is validated for permitted types. The derived types such as JSON have to support their own branch method. Thus provided as a static method.

Parameters

• subpath – Variable list/tuple of path keys and indexes.

• kargs –

  value:

  Value to be assigned to the final node.

Returns

A created branch.

Raises

pass-through –

5.4.2.2. readout_data

yapydata.datatree.synini.readout_data(xval, **kargs)

Scan tree into JSON representation. Uses recursive calls to readout_data through the logical tree spanned by ConfigParser.

Parameters

xval –

The loaded input tree as received from ConfigDataINIX, which is defined by ConfigParser.read_file().

For example a node cf:

datafile = os.path.abspath(fpname)
cf = ConfigDataINIX(datafile)
cf.load_parser()
cf.import_data(datafile)

is read out as

datatree = readout_data(cf)

Returns

The resulting scanned data structure.

Raises

pass-through –

5.4.3. DataTreeINI

class yapydata.datatree.synini.DataTreeINI(data={}, **kargs)

The the supported in-memory data tree representation of the INI syntax supports a JSON compatible in memory data structure. The supported structure relies on the standard ConfigParser - of Python2 and Python3 - with a minimum set of custom addons. For a full set of extensions refer to the package multiconf.

The basic scheme of the stored syntax is:

ini-for-in-memory-json := {
    <sections>
}
sections := <section> [, <sections>]
section := <section-attributes>
section-attributes := <attr-value-pairs> [, <section-attributes>]
attr-value-pairs :=  <attr-value-pair> [, <attr-value-pairs>]
attr-value-pair := <attr-name> <separator> <attr-value>
attr-name := "any valid ConfigParser string compatible to a JSON string"
attr-value := (
      <integer>   | <integer-as-string>
    | <float>     | <float-as-string>
    | <string>
    | <list>
    | <dict>
    | <boolean>   | <boolean-as-string>
    | <null>      | <null-as-string>
)

integer-as-string := '"' <integer> '"'                  # treated as string
integer := "any non-quoted valid integer value"         # treated as integer
float-as-string := '"' <float> '"'                      # treated as string
float := "any non-quoted valid integer value"           # treated as float
string := "any valid string"
boolean := (true | false)
boolean-as-string := '"' <boolean> '"'                  # treated as string
null := null
null-as-string := '"' <null> '"'                        # treated as string
separator := ( ':' | '=' )

The following derived proprietary container types are provided. These are compatible with the basic representation of the higher layer multiconf package, which also provides command line compilation and cross-conversion utilies.

The list entries are represented as multiple lines of entries with leading white-spaces and a comma.

list := <proprietary-basic-multiline-list-syntax>
proprietary-basic-multiline-list-syntax := <attr-name> <separator> <list-item> <CR> <list-items-multiline> <CR>
list-items-multiline := <ws> ',' <list-item> <CR> [<list-items-multiline>]
list-item := attr-value
ws := "arbitrary whitespace - <SPACE>, <tab>"
CR := "new line"

The dict entries are represented as multiple lines of entries with leading white-spaces and a comma:

dict := <proprietary-basic-multiline-dict-syntax>
proprietary-basic-multiline-dict-syntax := <attr-name> <separator> <attr-dict-item> <CR> <dict-items-multiline> <CR>
dict-items-multiline := <ws> ',' <dict-item> <CR> [<dict-items-multiline>]
dict-item := attr-value-pair
ws := "arbitrary whitespace - <SPACE>, <tab>"
CR := "new line"

The data tree is compatible with the standard packas json.

5.4.3.1. __init__

DataTreeINI.__init__(data={}, **kargs)

Parameters

• data –

  A JSON compliant in-memory data tree in accordance to RFC-7159:

  json-value := (
        object | array
      | number
      | string
      | false  | true
      | null
  )
  

  The equivalent Python types are - based on JSON-RFC7159 as canonical in-memory data:

  RFC-7159-type-for-json := (
        dict | list            # see: object, array
      | int  | float           # see: number
      | str                    # see: unicode / for Python: ISSTR = (str(3) | unicode(2))
      | None | True  | False   # see: null, true, false
  )
  

  The initial data defines the permitted type of the first item within the subpath of the spanned data tree.

  Thus atomic data types define a single node data tree only - new in RFC-7159.

• kargs –

  syntax:

  Defines the syntax variant:

  syntax := (
        'base'  # base core syntax for multi-syntax environments with global types
      | 'ext'   # extended syntax with specific extension for this module
      | 'auto'  # for now enables all choices - basically the same as 'ext'
  )
  
  default := 'base'  # maximum compatibility for multi-syntax environments
  

Returns

None / initialized object

Raises

• YapyDataDataTreeError –

• pass-through –

5.4.3.2. __setattr__

DataTreeINI.__setattr__(name, value)

Validates types of own data attributes.

Parameters

• name –

  Name of the attribute. Following are reserved and treated special:

  • type: str - ‘data’ The value is treated as the replacement of the internal data attribute. Replaces or creates the complete data of teh current instance.

• value – The value of the attribute. This by default superposes present values by replacement. Non-present are created.

Returns:

Raises

YapyDataINIError –

5.4.3.3. isvalid_top

static DataTreeINI.isvalid_top(value, **kargs)

Validate compliance of top-node.

5.4.3.4. import_data

DataTreeINI.import_data(fpname, key=None, node=None, **kargs)

Reads an INI file. This is a simple basic method for the application on the lower layers of the software stack. It is designed for minimal dependencies. The used library is the standard configparser package.

Parameters

• fpname –

  File path name of the INI file.

  fpname := <ini-file-path-name>
  ini-file-path-name := (
        <file-path-name>           # with extension
      | <file-path-name> '.ini'    # without extension, for multiple syntaxes
  )
  

• key –

  The key for the insertion point:

  node[key] = <file-data>
  
  default := None - replace self.data,
  

  The caller is responsible for the containment of the provided node within the data structure represented by this object. No checks are performed.

• node –

  The node for the insertion of the read data.:

  default := <top>
  

Returns

Reference to read data structure.

Raises

• YapyDataConfigError –

• pass-through –

5.4.4. ConfigDataINIX

class yapydata.datatree.synini.ConfigDataINIX(conf, **kargs)

A simple configuration file parser based on the standard ConfigParser class.

The final resulting data with completely applied syntax-extensions is available by the method readout_data().

Supports the data types:

int, float, str

multi-line lists,
multi-line search-paths

null
true, false

The optional structure:

global-attributes-without-section

The standard file extensions are:

'.ini'

The supported stnadard features of ConfigParser include:

interpolation

For detailed information refer to the parameters of the __init__ method.

5.4.4.1. __init__

ConfigDataINIX.__init__(conf, **kargs)

Parameters

**conf** –

The file path name of the configuration file.

kargs:

For additional parameters see ConfigData.

allow_no_value:

Enables the support for keys without values of INI format files. Supported by the standard library based configparser . The value could be applied to derived custom parser:

default := False

See parameter allow_no_value of configparser.ConfigParser.

casesens:

Preserves case of keys:

default := False

comment_prefixes:

Defines the comment prefixes:

default := ('#', ';')

delimiters:

Defines the delimiters for INI format based files. Supported by the standard library based configparser . The value could be applied to derived custom parser:

default := ('=', ':',)

dict_type:

The type of dictionary to be used by the parent class:

default := None

empty_lines_in_values:

default := False

inline_comment_prefixes:

Defines the inline comment prefixes:

default := None

interpolation:

Enables the creation and replacement of variables within configuration files. Depends on the derived class, when not supported simply ignored:

default := True

See parameter interpolation of configparser.ConfigParser.

sectionpaths:

Enables the conversion and interpretation of section names as path entries. This is required, when the versatility of the converted and/or merged syntaxes are of different degree, and the actual used syntax data path elements could not be converted. In this case an intermediate sub-syntax is supported by a dotted path notation, which could be converted between the applied syntaxes:

sectionpaths := (
     True         # long data paths e.g. from *JSON* are
                  # converted to dotted section names
                  # and vice versa
   | False        # requires compatible versatility,
                  # else raises exception
)

default := True

sectionpaths=True:

The section names of the native INIX syntax by default constitute a one-level-only depth of data structures for the complexity of structure definition.

sectionpaths=False:

sectionpathsep:

Defines the character used in section names as path separator. The character has to be valid as provided by the config parser of the syntax, in particular a valid character for section names of INI files, and has to be semantically suitable as a special separator character:

sectionpathsep := []

default := '.'

Valid only when sectionpaths is active.

strict:

Controls the verification of duplicate sections when these are used:

strict := (
      True    # raise an exception for duplicates
    | False   # accept
)

default := False

See strict option of ConfigParser.

quiet:

Suppresses display of non-errors:

default := False

Returns

None/object

Raises

pass-through –

5.4.4.2. __bool__

ConfigDataINIX.__bool__()

5.4.4.3. __getitem__

ConfigDataINIX.__getitem__(key)

Get the section object. Requires for Python2 the backport from Python3 “configparser”, see PyPI

5.4.4.4. __nonzero__

ConfigDataINIX.__nonzero__()

5.4.4.5. get

ConfigDataINIX.get(key)

Get the section object - compatible to Python3 and the backport of the configparser.

5.4.4.6. import_data

ConfigDataINIX.import_data(conf, **kargs)

Reads the configuration file and imports data. Supported standard types are:

'cfg', 'conf', 'ini',

The imported data for the suported standard syntax is interpreted as:

syntax of imported config	sections as	keys as	path as	insertion position	remark
conf	sections	keys to <section>	–	top, <section>, DEFAULT	no rename and no nested sections, no globals
ini	sections	keys by section	–	top, <section>, DEFAULT	no rename and no nested sections, no globals
inix	sections	keys by section	–	top, <section>, DEFAULT	no rename and no nested sections, no globals

Parameters

conf –

The file path name of the configuration file.

kargs:

Unknown options are passed through to the configuration parser.

anchor:

The insertion point for the imported data:

anchor := (
     <section>
   | 'DEFAULT'
   | <top>
)

top := "imports valid INIX/INI/CONF files with sections only"
section := "the name of the section"
'DEFAULT' := "keyword defined by the standard library as
              global defaults for interpolation"

default := <top>

strict:

Activates validation. The boolean value is mapped to the corresponding option of the called import parser:

parser	option	True	False
conf	strict	True	False
ini	strict	True	False
inix	strict	True	False

syntax:

Force the provided syntax. For available values refer to syntax multiplexer self.synmux.

Returns

True for success, else False or raises an exception.

Raises

pass-through –

5.4.4.7. keys

ConfigDataINIX.keys()

5.4.4.8. load_parser

ConfigDataINIX.load_parser(**kargs)

Loads the syntax parser configparser.ConfigParser and patches the behaviour for common ‘conf’ and ‘cfg’ format. Supports the most of the files in ‘/etc’ of POSIX based OS.

Parameters

kargs –

For the description of the options refer to the method header of multiconf.data.load_parser(). Unknown are passed through to the loaded configuration parser.

For the following parameters see __init__:

• allow_no_value

• casesens

• comment_prefixes

• inline_comment_prefixes

• delimiters

• dict_type

• empty_lines_in_values

• interpolation

• strict

• quiet

Returns

True, or raises an exception.

Raises

pass-through –

5.4.4.9. readout_data

ConfigDataINIX.readout_data(**kargs)

Returns the configuration as JSON compatible format. Removes the special dummy section header ‘globaldummy’, see import_data.

Parameters

kargs –

stronly:

Scans all as str only.

stronly := (
      True    # int and float are
              # converted to str
    | False   # numeric values are kept
)

default := False

Returns

In-memory JSON compatible data.

Raises

pass-through –

5.4.4.10. set

ConfigDataINIX.set(section, option, value)

5.4.5. MultiOrderedDict

class yapydata.datatree.synini.MultiOrderedDict

Add lists for multi-key items.

5.4.5.1. __setitem__

MultiOrderedDict.__setitem__(key, value)

Intercept keys which are already present.

5.4.6. CaseSensitiveConfigParser

class yapydata.datatree.synini.CaseSensitiveConfigParser(defaults=None, dict_type=<class 'dict'>, allow_no_value=False, *, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section='DEFAULT', interpolation=<object object>, converters=<object object>)

Preserves case of all keys - including DEFAULT section. Suppress formatting of optionstr, preserves upper case characters.

5.4.6.1. optionxform

CaseSensitiveConfigParser.optionxform(optionstr)

5.4.7. Exceptions

exception yapydata.datatree.synini.YapyDataINIError

Generic INI syntax error.