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: ExtendedConfigParser | None = None, filename: str | None = None, fileobj: TextIO | None = None, case_sensitive: bool = False, encoding: str = 'utf8')[source]
Represents a section within a config file.
- __init__(section: str, parser: ExtendedConfigParser | None = None, filename: str | None = None, fileobj: TextIO | None = None, case_sensitive: bool = False, encoding: str = 'utf8') None [source]
You must specify exactly one of
parser
,filename
, orfileobj
.- 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: bool | None = 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: int | None = None) int | None [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: int | None = None) int | None [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: int | None = None, maximum: int | None = None) List[int] [source]
Returns a list of integers within the specified range.
- opt_pyvalue_list(option: str, default: Any | None = None) Any [source]
Returns a list of evaluated Python values.
- opt_str(option: str, default: str | None = 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) ConfigSection [source]
Returns a
ConfigSection
attached to a different section of the same parser.- Parameters:
section – The new section name.
- 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: bool | None = 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) 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)with_session – create an SQLAlchemy Session?
with_conn – create an SQLAlchemy connection (via an Engine)?
reflect – read the database structure (when required)?
- Returns:
- get_env_dict(section: str, parent_env: Dict[str, str] | None = 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: int | None = None) int | None [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: int | None = None, maximum: int | None = 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: int | None = 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: int | None = None) int [source]
Like
get_int_default_if_failure()
, but if the default is given asNone
and no value is found, raises an exception.
- get_pyvalue_list(section: str, option: str, default: Any | None = 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: str | None = None) str | None [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
- crate_anon.common.extendedconfigparser.configfail(errmsg) None [source]
- Parameters:
errmsg – error message
- Raises:
ValueError –
- crate_anon.common.extendedconfigparser.gen_ints(words: Iterable[str], minimum: int | None = None, maximum: int | None = 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 –