Navigation

LCONF.main_code

Overview

This module is the main LCONF code module

Constants

LCONF.main_code.LCONF_BASE_INDENT
(int) the lconf base indentation (number of spaces for one indentation level)

Important

This MUST be kept at 3

LCONF.main_code.SECTION_START_TAG

(str) ___SECTION The Lconf-Section Start TAG

LCONF.main_code.SECTION_END_TAG

(str) ___END The Lconf-Section End TAG

LCONF.main_code.LCONF_NO

(int) used for arguments instead of a bool if there are more options than 2

LCONF.main_code.LCONF_YES

(int) used for arguments instead of a bool if there are more options than 2

LCONF.main_code.LCONF_DEFAULT

(int) used for arguments instead of a bool if there are more options than 2

Functions

LCONF.main_code.lconf_extract_all_sections(source)

Extracts all LCONF-Sections from the raw string.

Parameters:source – (raw str) which contains one or more LCONF-Sections
Returns:(list) of LCONF-Sections text each inclusive the ___SECTION, ___END TAG these are not split by line but each in one txt
Raises Err:project error
LCONF.main_code.lconf_extract_one_section_by_name(source, section_name)

Extracts one LCONF-Sections from the raw string.

This will immediately return if the given section is found and not scan the whole source

Parameters:
  • source – (raw str) which contains one or more LCONF-Sections
  • section_name – (str) section name: which one wants to extract from the source
Returns:

(str) Extracted LCONF-Sections text inclusive the ___SECTION, ___END TAG these are not split by line but all in one txt
Raises Err:

project error e.g: if a section with section_name is not found
LCONF.main_code.lconf_section_splitlines(lconf_section_raw_str, validate_first_line=False)

Split a section raw string into lines and validate the first line

Parameters:
  • lconf_section_raw_str – (raw str) which contains one LCONF-Section
  • validate_first_line – (bool) if true the first line is validated
Returns:

(tuple) section_lines, section_name
Raises Err:
LCONF.main_code.lconf_validate_one_section_str(lconf_section_raw_str)

Validates one LCONF-Section raw string: the section must be already correctly extracted

Warning

does not validate

This does not validate correct names for Keys, Repeated Block Identifiers ect.. as implemented in the corresponding LCONF-Default-Template-Structure

It does also not validate for unique keys: Restrictions: Unique names

Validates/Checks for:

Parameters:lconf_section_raw_str – raw str) which contains one extracted LCONF-Sections inclusive the Start/End Tags
Returns:(bool) True if success else raises an error
Raises Err:
LCONF.main_code.lconf_validate_source(lconf_source)

Validates a LCONF-Section raw string containing one or more LCONF-Sections This does not validate with the corresponding Section-Template classes: like correct names for: Keys, Repeated Block Identifiers ect..

IMPORTANT NOTE: this uses the function: lconf_extract_all_sections() to extract valid LCONF-Sections. If a code extracts sections in an other way the first/last line might differ

Validates/Checks for:

  • No Trailing Spaces

  • Most Indentation Errors: inclusive indent of Comment lines

  • if a line is a Key/Value separator line: :
    • only one space before and one space after the double colon
      • for empty string values no space after the double colon

    • MISSING characters after <::>

    • WRONG CHAR/SPACES after <::>

    • WRONG CHAR/SPACES before <::>

Parameters:lconf_source – (raw str) which contains one or more LCONF-Sections
Returns:(bool) True if success else raises an error
LCONF.main_code.lconf_validate_file(path_to_lconf_file)

Validates a file containing one or more LCONF-Sections This does not validate with the corresponding Section-Template classes: like correct names for: Keys, Repeated Block Identifiers ect..

IMPORTANT NOTE: this uses the function: lconf_extract_all_sections() to extract valid LCONF-Sections. If code extracts sections in an other way the first/last line might differ

Validates/Checks for:

  • No Trailing Spaces

  • Most Indentation Errors

  • if a line is a Key/Value separator line
    • only one space before and one space after the double colon
    • for empty string values no space after the double colon
    • MISSING characters after <::>
    • WRONG CHAR/SPACES after <::>
    • WRONG CHAR/SPACES before <::>
Parameters:path_to_lconf_file – (str) path to a file
Returns:(bool) True if success else raises an error
Raises Err:
LCONF.main_code.lconf_prepare_default_obj(lconf_section__template_obj, with_comments=False)

Returns a recursively copy of the lconf_section__template_obj: with the same key_order but without Default Comment/Empty Line

SeeAlso

_prepare_default_obj__with_comments(), _prepare_default_obj__no_comments()

Important

Empty-KeyValuePair-ReplacementValues

if a default Key :: Value Pair has an empty value (empty string) and a Empty-KeyValuePair-ReplacementValue is defined the lconf_prepare_default_obj will have the supplied Empty-KeyValuePair-ReplacementValue

Parameters:
  • lconf_section__template_obj – (obj) instance of main section template object which has all the info: inclusive any l_transform func type-conversion and any optional Empty-KeyValuePair-ReplacementValues
  • with_comments –

    (bool) option to parse also any defined: default empty or comment line

    • if True: any Default-Comment/Empty Lines are parse
    • if False: any Default-Comment/Empty Lines` are not parse
Returns:

(lconf_default_obj obj) prepared copy of the lconf_section__template_obj
LCONF.main_code.lconf_prepare_and_parse_section(lconf_section_raw_str, lconf_section__template_obj, with_comments=False, validate=False)

Returns a new parsed lconf obj. Basically it does lconf_prepare_default_obj() and lconf_parse_section

Parameters:
  • lconf_section_raw_str – (raw str) which contains one LCONF-Section
  • lconf_section__template_obj – (obj) instance of main section template object which has all the info
  • with_comments –

    (bool) option to parse also any defined: default empty or comment line

    • if True: any Default-Comment/Empty Lines are parse
    • if False: any Default-Comment/Empty Lines` are not parse
  • validate –

    (bool)

    • if True the lconf_section_raw_str is first validated and only afterwards parsed
    • if False: no validation is done
Returns:

(obj) copy of the lconf_section__template_obj: attributes updated by the data in lconf_section_raw_str.

  • additionally updated: attributes

    • section_name: updated with the LCONF-SectionName
    • is_parsed: set to True; so one can know if this obj was already parsed
LCONF.main_code.lconf_prepare_and_parse_section_lines(section_lines, section_name, lconf_section__template_obj, with_comments=False)

Returns a new parsed lconf obj. Basically it does lconf_prepare_default_obj() and lconf_parse_section_lines()

Parameters:
  • section_lines – (list) which contains one LCONF-Section raw string already split into lines
  • section_name – (str) already extracted section name
  • lconf_section__template_obj – (obj) instance of main section template object which has all the info: inclusive any l_transform func type-conversion and any optional Empty-KeyValuePair-ReplacementValues
  • with_comments –

    (bool) option to parse also any defined: default empty or comment line

    • if True: any Default-Comment/Empty Lines are parse
    • if False: any Default-Comment/Empty Lines` are not parse
Returns:

(obj) copy of the lconf_section__template_obj: attributes updated by the data in lconf_section_raw_str.

  • additionally updated: attributes

    • section_name: updated with the LCONF-SectionName
    • is_parsed: set to True; so one can know if this obj was already parsed
LCONF.main_code.lconf_parse_section_lines(lconf_default_obj, section_lines, section_name, lconf_section__template_obj)

Parses a LCONF-Section raw string already split into lines and updates the section object

SeeAlso

lconf_extract_all_sections()

Note

Does not validate the section_lines for correct LCONF: e.g. indentation

Parameters:
  • lconf_default_obj – (obj) a prepared copy of lconf_section__template_obj: see function: lconf_prepare_default_obj()
  • section_lines – (list) which contains one LCONF-Section raw string already split into lines
  • section_name – (str) already extracted section name
  • lconf_section__template_obj – (obj) instance of main section template object which has all the info: inclusive any l_transform func type-conversion and any optional Empty-KeyValuePair-ReplacementValues
Returns:

(obj) updated lconf_default_obj attributes updated by the data in section_lines

  • additionally updated: attributes

    • section_name: updated with the LCONF-SectionName
    • is_parsed: set to True; so one can know if this obj was already parsed
Raises Err:

Todo

maybe try to speed up checking correct number of blocks without looping through all again

LCONF.main_code.lconf_parse_section(lconf_default_obj, lconf_section_raw_str, lconf_section__template_obj, validate=False)

Parses a LCONF-Section raw string and updates the section object

Parameters:
  • lconf_default_obj – (obj) a prepared copy of lconf_section__template_obj: see function: lconf_prepare_default_obj()
  • lconf_section_raw_str – (raw str) which contains one LCONF-Section
  • lconf_section__template_obj – (obj) instance of main section template object which has all the info
  • validate –

    (bool)

    • if True the lconf_section_raw_str is first validated and only afterwards parsed
    • if False: no validation is done
Returns:

(obj) updated lconf_default_obj: attributes updated by the data in lconf_section_raw_str.

  • additionally updated: attributes

    • section_name: updated with the LCONF-SectionName
    • is_parsed: set to True; so one can know if this obj was already parsed
LCONF.main_code.lconf_parse_section_extract_by_name(source, section_name, lconf_section__template_obj, with_comments=False, validate=False)

Parses/Extracts one LCONF-Sections from the raw string by name and returns an updated copy of the the section object

Similar to lconf_prepare_and_parse_section() but also extract the session by name - Basically it does lconf_extract_one_section_by_name(), lconf_prepare_default_obj() and lconf_parse_section()

Main usage: if one needs only one known section from the source:

  • if one needs multiple sections it might be better to use lconf_extract_all_sections()
Parameters:
  • source – (raw str) which contains one or more LCONF-Sections
  • section_name – (str) section name one wants to extract from the source
  • lconf_section__template_obj – (obj) instance of main section template object which has all the info
  • with_comments –

    (bool) option to parse also any defined: default empty or comment line

    • if True: any Default-Comment/Empty Lines are parse
    • if False: any Default-Comment/Empty Lines` are not parse
  • validate –

    (bool)

    • if True the extracted section is first validated and only afterwards parsed
    • if False: no validation is done after the section text is extracted
Returns:

(obj) copy of the lconf_section__template_obj: attributes updated by the data in lconf_section_raw_str.

  • additionally updated: attributes

    • section_name: updated with the LCONF-SectionName
    • is_parsed: set to True; so one can know if this obj was already parsed
LCONF.main_code.lconf_emit(lconf_section_obj, onelinelists=-1, empty_key_value_pair=True)

Return a section_string from a lconf_section_obj

Note

  • if the lconf_section_obj was parsed/prepared with Default-Comment/Empty Lines it will emit it with such
  • if the lconf_section_obj was parsed/prepared without Default-Comment/Empty Lines it will not emit any
Parameters:
  • lconf_section_obj – (obj) instance of main section object which will be dumped
  • onelinelists –

    (CONSTANTS) defines how list (Key :: Value-Lists and Key-Value-Lists) items are emitted

    Used CONSTANTS
    CONSTANTS  
    LCONF_NO all list items are dumped on separate lines using indentation
    LCONF_YES all list items are dumped on the same line as the key separated by ` :: ` in an comma separated list
    LCONF_DEFAULT uses one of the two above for each list the option defined in the LCONF-Default-Template-Structure

    LCONF-Example

    LCONF output using: LCONF_NO

    - KEY1
     - listitem1
     - listitem2

    LCONF-Example

    LCONF output using: LCONF_YES

    - KEY1 :: [listitem1,listitem2]
  • empty_key_value_pair –

    (bool)

    This is used when the LCONF-Default-Template-Structure has implemented an Empty-KeyValuePair-ReplacementValue

    if the actual value of the lconf_section_obj is the same as the defined Empty-KeyValuePair-ReplacementValue

    • if empty_key_value_pair is True: an Empty Key :: Value Pair` is emitted
    • if empty_key_value_pair is False: the actual value of the lconf_section_obj is emitted
Returns:

(str) a LCONF text string
Raises Err:
LCONF.main_code.lconf_emit_default_obj(lconf_section__template_obj, section_name, onelinelists=-1, with_comments=True)

Return a section_string from a none parsed lconf_section_obj

Parameters:
  • lconf_section__template_obj – (obj) instance of main section template object which has all the info: inclusive any l_transform func type-conversion and any optional Empty-KeyValuePair-ReplacementValues
  • section_name – (str) section name: to use
  • onelinelists –

    (CONSTANTS) defines how list (Key :: Value-Lists and Key-Value-Lists) items are emitted

    uses the CONSTANTS:

    • LCONF_NO: all list items are dumped on separate lines using indentation
      • KEY1
        • listitem1
        • listitem2
    • LCONF_YES: all list items are dumped on the same line as the key separated by ` :: ` in an comma separated list
      • KEY1 :: [listitem1,listitem2]
    • LCONF_DEFAULT: uses one of the two above for each list the option defined in the: LCONF-Default-Template-Structure
  • with_comments – (str) a LCONF text string
Returns:
LCONF.main_code.lconf_dict_to_lconf(in_dict, section_name, onelinelists=True, skip_none_value=True)

Return a section_string from a regular dictionary as well as OrderedDict.

  • if the dict contains a: LCONF START-TAG (only direct keys (root keys) are checked)

    it is used instead of the supplied section_name

Known Limitations:
  • in_dict supports only simple lists: may not contain other dict, lists
  • there won’t be any Repeated-Block Identifier but only nested Key-Value-Mapping if required
Parameters:
  • in_dict – (obj) dictionary of section which will be converted to a LCONF-Section string
  • section_name – (str) section name: in normal cases a json will not have such
  • onelinelists –

    (bool) defines how list items are emitted

    • if True list items are dumped on the same line as the key separated by ` :: ` in an comma separated list
      • KEY1 :: [listitem1,listitem2]
    • if False list items are dumped on separate lines using indentation
      • KEY1
        • listitem1
        • listitem2
  • skip_none_value –

    (bool)

    • if True: json null/python None is transformed to a python empty string (value skipped)
    • else it is transformed to python None
Returns:

(str) a LCONF text string.
LCONF.main_code.lconf_to_ordered_native_type(lconf_section_obj)

Return a recursive copy of the lconf_section_obj with Lconf objs replaced by python native objs keeping order - e.g. uses OrderedDict

e.g. useful for dumping ordered json

  • LconfRoot, LconfKVMap, LconfBlkI, LconfBlk will be recursively copied the types will be cast to: OrderedDict
  • LconfKVList, LconfListOT: will be cast to: list
Parameters:lconf_section_obj – (obj) instance of lconf section object
Returns:(OrderedDict) recursive copy of the lconf_section_obj with Lconf objs replaced by python native objs
LCONF.main_code.lconf_to_native_type(lconf_section_obj)

Return a recursive copy of the lconf_section_obj with Lconf objs replaced by python native objs

e.g. useful for dumping yaml

  • LconfRoot, LconfKVMap, LconfBlkI, LconfBlk will be recursively copied the types will be cast to: dict

  • LconfKVList, LconfListOT: will be cast to: list

    • LconfListOT tuple items will be cast to lists
Parameters:lconf_section_obj – (obj) instance of lconf section object
Returns:(dict) recursive copy of the lconf_section_obj with Lconf objs replaced by python native objs

Page contents

This Page

Navigation

© Copyright (c) 2014 `peter1000` https://github.com/peter1000. Last updated on Oct 08, 2014. Created using Sphinx 1.2.3.