14.2.7. crate_anon.common.extendedconfigparser

crate_anon/common/extendedconfigparser.py


Copyright (C) 2015, University of Cambridge, Department of Psychiatry. Created by Rudolf Cardinal (rnc1001@cam.ac.uk).

This file is part of CRATE.

CRATE is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

CRATE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with CRATE. If not, see <https://www.gnu.org/licenses/>.


Slightly extended ConfigParser.

class crate_anon.common.extendedconfigparser.ConfigSection(section: str, parser: Optional[crate_anon.common.extendedconfigparser.ExtendedConfigParser] = None, filename: Optional[str] = None, fileobj: Optional[TextIO] = None, case_sensitive: bool = False, encoding: str = 'utf8')[source]

Represents a section within a config file.

__init__(section: str, parser: Optional[crate_anon.common.extendedconfigparser.ExtendedConfigParser] = None, filename: Optional[str] = None, fileobj: Optional[TextIO] = None, case_sensitive: bool = False, encoding: str = 'utf8') None[source]

You must specify exactly one of parser, filename, or fileobj.

Parameters
  • section – The name of the section within the config file, e.g. main for the section marked by [main].

  • parser – Specify this, a ExtendedConfigParser, if you have already loaded the file into a parser.

  • filename – The name of a file to option. Specify also the encoding.

  • fileobj – A file-like object to open.

  • case_sensitive – If parser is used, make it case-sensitive for options?

  • encoding – If filename is used, the character encoding.

opt_bool(option: str, default: Optional[bool] = None) bool[source]

Reads a boolean option.

Parameters
  • option – parameter (option) name

  • default – default if not found (if None, the parameter is required)

opt_int(option: str, default: Optional[int] = None) Optional[int][source]

Reads an integer option.

Parameters
  • option – parameter (option) name

  • default – default if not found (if None, the parameter is required)

opt_int_positive(option: str, default: Optional[int] = None) Optional[int][source]

Reads an integer option that must be greater than or equal to 0.

Parameters
  • option – parameter (option) name

  • default – default if not found (if None, the parameter is required)

opt_multiline(option: str, required: bool = False, lower: bool = False, as_words: bool = True) List[str][source]

Reads a multiline string, returning a list of words or lines. Similar to opt_strlist(), but different defaults.

Parameters
  • option – parameter (option) name

  • required – is the parameter required?

  • lower – convert to lower case?

  • as_words – split as words, rather than as lines?

opt_multiline_csv_pairs(option: str) Dict[str, str][source]

Reads a dictionary of key-value pairs, specified as lines each of the format key, value.

Parameters

option – name of the config file option

opt_multiline_int(option: str, minimum: Optional[int] = None, maximum: Optional[int] = None) List[int][source]

Returns a list of integers within the specified range.

opt_pyvalue_list(option: str, default: Optional[Any] = None) Any[source]

Returns a list of evaluated Python values.

opt_str(option: str, default: Optional[str] = None, required: bool = False) str[source]

Reads a string option.

Parameters
  • option – parameter (option) name

  • default – default if not found and not required

  • required – is the parameter required?

opt_strlist(option: str, required: bool = False, lower: bool = False, as_words: bool = True) List[str][source]

Returns a list of strings from the config file. Similar to opt_multiline(), but different defaults.

Parameters
  • option – parameter (option) name

  • required – is the parameter required?

  • lower – convert to lower case?

  • as_words – split as words, rather than as lines?

other_section(section: str) crate_anon.common.extendedconfigparser.ConfigSection[source]

Returns a ConfigSection attached to a different section of the same parser.

Parameters

section – The new section name.

require_absent(option: str, msg: str) None[source]

If an option is present, print the message and raise an exception. Use this for deprecated option names.

class crate_anon.common.extendedconfigparser.ExtendedConfigParser(*args, case_sensitive: bool = False, **kwargs)[source]

A version of configparser.ConfigParser with assistance functions for reading parameters.

__init__(*args, case_sensitive: bool = False, **kwargs) None[source]
Parameters

case_sensitive – Make the parser case-sensitive for option names?

get_bool(section: str, option: str, default: Optional[bool] = None) bool[source]

Retrieves a boolean value from a parser.

Parameters
  • section – section name within config file

  • option – option (parameter) name within that section

  • default – Value to return if option is absent and not required. If the default if not specified, and the option is missing, raise an error.

Returns

Boolean value

Raises
  • NoSectionError – if the section is absent

  • NoOptionError – if the parameter is absent and required

get_database(section: str, dbname: str = None, srccfg: DatabaseSafeConfig = None, with_session: bool = False, with_conn: bool = False, reflect: bool = False) crate_anon.anonymise.dbholder.DatabaseHolder[source]

Gets a database description from the config file.

Parameters
  • section – config section name

  • dbname – name to give the database (if None, the section name will be used)

  • srccfgcrate_anon.anonymise.config.DatabaseSafeConfig

  • with_session – create an SQLAlchemy Session?

  • with_conn – create an SQLAlchemy connection (via an Engine)?

  • reflect – read the database structure (when required)?

Returns

a crate_anon.anonymise.dbholder.DatabaseHolder object

get_env_dict(section: str, parent_env: Optional[Dict[str, str]] = None) Dict[str, str][source]

Gets an operating system environment variable dictionary (variable: value mapping) from the config file.

Parameters
  • section – config section name

  • parent_env – optional starting point (e.g. parent OS environment)

Returns

a dictionary suitable for use as an OS environment

get_int_default_if_failure(section: str, option: str, default: Optional[int] = None) Optional[int][source]

Returns an integer parameter, or a default if we can’t read one.

Parameters
  • section – section name

  • option – parameter name

  • default – value to return if the parameter cannot be read (missing or not an integer)

Returns

an integer, or default

get_int_list(section: str, option: str, minimum: Optional[int] = None, maximum: Optional[int] = None, suppress_errors: bool = True) List[int][source]

Returns a list of integers from a parameter.

Parameters
  • section – config section name

  • option – parameter name

  • minimum – minimum permissible value, or None

  • maximum – maximum permissible value, or None

  • suppress_errors – suppress values that fail, rather than raising an exception

Returns

list of integers

get_int_positive_raise_if_no_default(section: str, option: str, default: Optional[int] = None) int[source]

Like get_int_default_if_failure(), but also requires that the result be greater than or equal to 0.

get_int_raise_if_no_default(section: str, option: str, default: Optional[int] = None) int[source]

Like get_int_default_if_failure(), but if the default is given as None and no value is found, raises an exception.

get_pyvalue_list(section: str, option: str, default: Optional[Any] = None) List[Any][source]

Returns a list of Python values, produced by applying ast.literal_eval() to the string parameter value, and checking that the result is a list.

Parameters
  • section – config section name

  • option – parameter name

  • default – value to return if no string is found for the parameter

Returns

a Python list of some sort

Raises
  • ValueError

  • a list

get_str(section: str, option: str, required: bool = False, default: Optional[str] = None) Optional[str][source]

Returns a string parameter.

Parameters
  • section – section name

  • option – parameter name

  • required – raise ValueError if the parameter is missing?

  • default – value to return if parameter is missing and not required

Returns

string parameter value, or default

get_str_list(section: str, option: str, as_words: bool = True, lower: bool = False, required: bool = False) List[str][source]

Returns a string list parameter.

Parameters
  • section – section name

  • option – parameter name

  • as_words – break the value into words (rather than lines)?

  • lower – force the return value into lower case?

  • required – raise ValueError if the parameter is missing?

Returns

list of strings

static raise_missing(section: str, option: str) None[source]

Raise ValueError to complain about a missing parameter.

Parameters
  • section – section name

  • option – parameter name

require_option_to_be_absent(section: str, option: str, msg: str) None[source]

Require that an option be absent in the specified section, or print a message and raise ValueError.

require_section(section: str) None[source]

Requires that a section be present, or raises ValueError.

Parameters

section – section name

crate_anon.common.extendedconfigparser.configfail(errmsg) None[source]
Parameters

errmsg – error message

Raises

ValueError

crate_anon.common.extendedconfigparser.gen_ints(words: Iterable[str], minimum: Optional[int] = None, maximum: Optional[int] = None, suppress_errors: bool = False) Generator[int, None, None][source]

Generate integers from words.

Parameters
  • words – iterable of word strings

  • minimum – minimum permissible value, or None

  • maximum – maximum permissible value, or None

  • suppress_errors – suppress values that fail, rather than raising an exception

Yields

integers

Raises
  • ValueError

  • suppress_errors` is set

crate_anon.common.extendedconfigparser.gen_lines(multiline: str) Generator[str, None, None][source]

Generate lines from a multi-line string. (Apply strip(), too.)

crate_anon.common.extendedconfigparser.gen_words(lines: Iterable[str]) Generator[str, None, None][source]

Generate words from lines.