authnzerver.confload module

This contains functions to load config from environ, command line params, or an envfile.

authnzerver.confload.get_conf_item(env_key: Union[str, Sequence[T_co]], environment, options_object, options_key: str = None, vartype=<class 'str'>, default=None, readable_from_file: bool = False, postprocess_value: str = None, raiseonfail: bool = True, basedir: str = None) → Any[source]

This loads a config item from the environment or command-line options.

The order of precedence is:

  1. environment or envfile if that is provided
  2. command-line option
Parameters:
  • env_key (str or list/tuple of strings) – The environment variable that specifies the item to get. This is either a string or a list of strings. In the first instance, the specified environment variable key will be searched for and used if available. In the latter instance, each environment variable key specified as a string in the list will be searched for, left to right, and the first one found will be used as the source of the environment variable’s value. This allows you to specify fallback environment variables, e.g., setting 'env': ['PORT', 'AUTHNZERVER_PORT'] in a conf_dict item will look for the environment variable key PORT first and fall back to AUTHNZERVER_PORT.
  • environment (environment object or ConfigParser object) – This is an object similar to that obtained from os.environ or a similar ConfigParser object.
  • options_object (Tornado options object) – If the environment variable isn’t defined, the next place this function will try to get the item value from a passed-in Tornado options object, which parses command-line options.
  • options_key (str) – This is the attribute to look up in the options object for the value of the conf item.
  • vartype (Python type object: float, str, int, etc.) – The type to use to coerce the input variable to a specific Python type.
  • default (Any) – The default value of the conf item.
  • readable_from_file ({'json','string', others, see below} or False) –

    If this is specified, and the conf item key (env_key or options_key above) is a valid filename or URL, will open it and read it in, cast to the specified variable type, and return the item. If this is set to False, will treat the config item pointed to by the key as a plaintext item and return it directly.

    There are several readable_from_file options. The first two below are strings, the rest are tuples.

    • 'string': read a file and use the resulting string as the value of the config item. The trailing \n character will be stripped. This is useful for simple text secret keys stored in a file on disk, etc.
    • 'json': read the entire file as JSON and return the loaded dict as the value of the config item.
    • ('json','path.to.item.or.listitem._arr_0'): read the entire file as JSON, resolve the JSON object path pointed to by the second tuple element, get the value there and return it as the value of the config item.
    • ('http',{method dict},'string'): HTTP GET/POST the URL pointed to by the config item key, assume the value returned is plain-text and return it as the value of the config item. This can be useful for things stored in AWS/GCP metadata servers.
    • ('http',{method dict},'json'): HTTP GET/POST the URL pointed to by the config item key, load it as JSON, and return the loaded dict as the value of the config item.
    • ('http',{method dict},'json','path.to.item.or.listitem._arr_0'): HTTP GET the URL pointed to by the config key, load it as JSON, resolve the JSON object path pointed to by the fourth element of the tuple, get the value there and return it as the value of the config item.

    The {method dict} is a dict of the following form:

    {'method':'post' or 'get',
 'headers':dict of header keys and values to send or None,
 'data':data dict to attach to the POST request or param dict to
        attach to the GET request or None,
 'timeout': time in seconds to wait for a response}

    Using the method dict allows you to add in authentication headers and data needed to gain access to the URL indicated by the config item key.

    If an item in the ‘headers’ or ‘data’ dicts requires something from an environment variable or .env file, indicate this by using '[[NAME OF ENV VAR]]' in the value of that key. For example, to get a bearer token to use in the ‘Authorization’ header:

    method_dict['headers'] = {'Authorization': 'Bearer [[API_KEY]]'}

    This will look up the environment variable ‘API_KEY’ and substitute that value in.

  • postprocess_value (str) –

    This is a string pointing to a Python function to apply to the config item that was retrieved. The function must take one argument and return one item. The function is specified as either a fully qualified Python module name and function name, e.g.:

    'base64.b64decode'

    or a path to a Python module on disk and the function name separated by ‘::’

    '~/some/directory/mymodule.py::custom_b64decode'
  • raiseonfail (bool) – If this is set to True, the function will raise a ValueError for any missing config items that can’t be set from the environment, the envfile or the command-line options. If this is set to False, the function won’t immediately raise an exception, but will return None. This latter behavior is useful for indicating which configuration items are missing (e.g. when a server is being started for the first time.)
  • basedir (str) – The directory where the server will do its work. This is used to fill in '[[basedir]]' template values in any conf item. By default, this is the current working directory.
Returns:

The value of the configuration item.
Return type:

Any
authnzerver.confload.item_from_file(file_path: str, file_spec: Union[tuple, str], basedir: str = None) → Any[source]

Reads a conf item from a file.

Parameters:
  • file_path (str) –

    The file to open. Here you can use the following substitutions as necessary:

    • [[homedir]]: points to the home directory of the user running the server.
    • [[basedir]]: points to the base directory of the server.
  • file_spec (str or tuple) –

    This specifies how to read the conf item from the file:

    • 'string': read a file and use the resulting string as the value of the config item. The trailing \n character will be stripped. This is useful for simple text secret keys stored in a file on disk, etc.
    • 'json': read the entire file as JSON and return the loaded dict as the value of the config item.
    • ('json','path.to.item.or.listitem._arr_0'): read the entire file as JSON, resolve the JSON object path pointed to by the second tuple element, get the value there and return it as the value of the config item.
  • basedir (str or None) – The base directory of the server. If None, the current working directory is used.
Returns:

conf_value – Returns the value of the conf item. The calling function is responsible for casting to the correct type.
Return type:

Any
authnzerver.confload.item_from_url(url: str, url_spec: tuple, environment, timeout: Union[float, int] = 5.0)[source]

Reads a conf item from a URL.

Parameters:
  • url (str) – The URL to fetch.
  • url_spec (tuple) –

    This specifies how to get the conf item from the URL:

    • ('http',{method dict},'string'): HTTP GET/POST the URL pointed to by the config item key, assume the value returned is plain-text and return it as the value of the config item. This can be useful for things stored in AWS/GCP metadata servers.
    • ('http',{method dict},'json'): HTTP GET/POST the URL pointed to by the config item key, load it as JSON, and return the loaded dict as the value of the config item.
    • ('http',{method dict},'json','path.to.item.or.listitem._arr_0'): HTTP GET the URL pointed to by the config key, load it as JSON, resolve the JSON object path pointed to by the fourth element of the tuple, get the value there and return it as the value of the config item.

    The {method dict} is a dict of the following form:

    {'method':'post' or 'get',
 'headers':dict of header keys and values to send or None,
 'data':data dict to attach to the POST request or param dict to
        attach to the GET request or None,
 'timeout': time in seconds to wait for a response}

    Using the method dict allows you to add in authentication headers and data needed to gain access to the URL indicated by the config item key.

    If an item in the ‘headers’ or ‘data’ dicts requires something from an environment variable or .env file, indicate this by using '[[NAME OF ENV VAR]]' in the value of that key. For example, to get a bearer token to use in the ‘Authorization’ header:

    method_dict['headers'] = {'Authorization': 'Bearer [[API_KEY]]'}

    This will look up the environment variable ‘API_KEY’ and substitute that value in.

  • environment (environment object or ConfigParser object) – This is an object similar to that obtained from os.environ or a similar ConfigParser object.
  • timeout (int or float) – The default timeout in seconds to use for the HTTP request if one is not provided in the method dict in url_spec.
Returns:

conf_value – Returns the value of the conf item. The calling function is responsible for casting to the correct type.
Return type:

Any
authnzerver.confload.load_config(conf_dict: dict, options_object, envfile: str = None) → types.SimpleNamespace[source]

Loads all the config items in config_dict.

Parameters:
  • conf_dict (dict) –

    This is a dict containing information on each config item to load and return. Each key in this dict serves as the name of the config item and the value for each key is a dict of the following form:

    'conf_item_name':{
    'env':'The environmental variable to check',
    'cmdline':'The command-line option to check',
    'type':the Python type of the config item,
    'default':a default value for the config item or None,
    'help':'The help string to use for the command-line option',
    'readable_from_file':how to retrieve the item (see below),
    'postprocess_value': 'func to postprocess the item (see below)',
},

    The env key in each config item is either a string or a list of strings. In the first instance, the specified environment variable key will be searched for and used if available. In the latter instance, each environment variable key specified as a string in the list will be searched for, left to right, and the first one found will be used as the source of the environment variable’s value. This allows you to specify fallback environment variables, e.g., setting 'env': ['PORT', 'AUTHNZERVER_PORT'] in a conf_dict item will look for the environment variable key PORT first and fall back to AUTHNZERVER_PORT.

    The 'readable_from_file' key in each config item’s dict indicates how the value present in either the environment variable or the command-line option will be used to retrieve the config item. This is one of the following:

    • 'string': read a file and use the resulting string as the value of the config item. The trailing \n character will be stripped. This is useful for simple text secret keys stored in a file on disk, etc.
    • 'json': read the entire file as JSON and return the loaded dict as the value of the config item.
    • ('json','path.to.item.or.listitem._arr_0'): read the entire file as JSON, resolve the JSON object path pointed to by the second tuple element, get the value there and return it as the value of the config item.
    • ('http',{method dict},'string'): HTTP GET/POST the URL pointed to by the config item key, assume the value returned is plain-text and return it as the value of the config item. This can be useful for things stored in AWS/GCP metadata servers.
    • ('http',{method dict},'json'): HTTP GET/POST the URL pointed to by the config item key, load it as JSON, and return the loaded dict as the value of the config item.
    • ('http',{method dict},'json','path.to.item.or.listitem._arr_0'): HTTP GET the URL pointed to by the config key, load it as JSON, resolve the JSON object path pointed to by the fourth element of the tuple, get the value there and return it as the value of the config item.

    The {method dict} is a dict of the following form:

    {'method':'post' or 'get',
 'headers':dict of header keys and values to send or None,
 'data':data dict to attach to the POST request or param dict to
        attach to the GET request or None,
 'timeout': time in seconds to wait for a response}

    Using the method dict allows you to add in authentication headers and data needed to gain access to the URL indicated by the config item key.

    If an item in the ‘headers’ or ‘data’ dicts requires something from an environment variable or .env file, indicate this by using '[[NAME OF ENV VAR]]' in the value of that key. For example, to get a bearer token to use in the ‘Authorization’ header:

    method_dict['headers'] = {'Authorization': 'Bearer [[API_KEY]]'}

    This will look up the environment variable ‘API_KEY’ and substitute that value in.

    The 'postprocess_value' key in each config item’s dict is used to point to a Python function to post-process the config item after it has been retrieved. The function must take one argument and return one item. The function is specified as either a fully qualified Python module name and function name, e.g.:

    'base64.b64decode'

    or a path to a Python module on disk and the function name separated by ‘::’

    '~/some/directory/mymodule.py::custom_b64decode'
  • options_object (Tornado options object) –

    If the environment variable isn’t defined for a config item, the next place this function will try to get the item value from a passed-in Tornado options object, which parses command-line options.

  • envfile (str or None) – The path to a file containing key=value pairs in the same manner as environment variables. This serves as an override to any environment variables that this function looks up to find config items.
Returns:

loaded_config – This returns an object with the parsed final values of each of the config items as object attributes.
Return type:

SimpleNamespace object