configirl

The MIT License (MIT)

Copyright 2022 Sanhe Hu <https://github.com/MacHu-GWU/configirl-project>

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This is a python config management tool to manage config parameter in centralized place. The purpose of this tool is to avoid maintain complex config/paramater handling logic in shell script, cloudformation, terraform and any other devops tools. Instead, we manage that in Python.

Since Python is a full featured general programming language and it is available on any Mac / Linux machine.

It allows different DevOps tools to easily talk to each other via JSON.

This library implemented in pure Python with no dependencies.

configirl.strip_comment_line_with_symbol(line, start)

Strip comments from line string.

configirl.strip_comments(string, comment_symbols=frozenset({'//', '#'}))

Strip comments from json string.

Parameters:

• string – A string containing json with comments started by comment_symbols.
• comment_symbols – Iterable of symbols that start a line comment (default # or //).

Returns:

The string with the comments removed.

configirl.read_text(abspath, encoding='utf-8')

Read string from a file.

Return type:str

configirl.write_text(text, abspath, encoding='utf-8')

Write string to a file.

configirl.json_loads(text)

Load data from json, ignoring comments.

Return type:dict

configirl.json_dumps(data)

Dump data to string.

Return type:str

configirl.json_load(path)

Load data from a json file, ignoring comments.

configirl.json_dump(data, path, overwrite=False)

Dump data to a json file.

configirl.add_metaclass(metaclass)

Class decorator for creating a class with a metaclass.

This method is copied from six.py

exception configirl.ValueNotSetError

Raises when trying to get value of a field that have not set value before.

exception configirl.DerivableSetValueError

Raises when trying to set value for Derivable Field.

class configirl.Field(default=<NOTHING>, dont_dump=False, printable=True, cache=False)

Base class for config value field.

Parameters:

• default (typing.Any) – default value for this field. can be a callable function.
• dont_dump (bool) – if true, then you can’t get the value if check_dont_dump = True in BaseConfigClass.to_dict() and BaseConfigClass.to_json(). this prevent from writing sensitive information to file.
• printable (bool) – if False, then it will not be displayed with print function. this prevent from displaying sensitive information to the console.
• cache (bool) – A flag indicates that whether the cache is enabled. only available for Derivable if True, then it will cache computation expensive derived value.

set_value(value)

An abstract method that set value to this field.

get_value(check_dont_dump=False, check_printable=False, **kwargs)

Returns the value for this field.

Parameters:

• check_dont_dump (bool) –
• check_printable (bool) –

Returns:

CN Doc

对于 Constant Field:

• 如果: self.value = NOTHING, 同时 .set_value(…) 方法从来没有被调用过.

• 如果: self.value 不等于 NOTHING, 说明 .set_value(…) 方法被吊用过, 则

  返回 self.value

对于 Derivable Field:

• 如果: self._getter_method() 没有成功

get_value_from_env(prefix='')

Use config value stored in environment variables. This usually used for computation server that doesn’t come with the config file. Since config file with sensitive information may not easy to manage. A common use case is AWS Lambda Function.

Parameters:prefix – a prefix append left to the config field name. For exmaple, if the config field is PROJECT_NAME, and the prefix is MY_PROJECT_, then it will read value from MY_PROJECT_PROJECT_NAME.

get_value_for_lbd(prefix='')

Smartly decide where should read config value from.

validator(method)

A decorator to bind validate method.

Parameters:method (callable) – a callable function like method(self, value) that take self as first parameters representing the config object. value as second parameters to represent the value you want to validate.

validate(*args, **kwargs)

An abstract method executes the validator method.

exception configirl.DontDumpError

Raises when trying to dump a dont_dump=True config value.

class configirl.Constant(default=<NOTHING>, dont_dump=False, printable=True, cache=False)

Constant Value Field.

set_value(value)

Set value to this Constant field.

class configirl.Derivable(default=<NOTHING>, dont_dump=False, printable=True, cache=False)

Derivable Value Field.

set_value(value)

Derivable field doesn’t allow to set value manually!

getter(method)

A decorator to bind getter method.

configirl.is_instance_or_subclass(val, class_)

Return True if val is either a subclass or instance of class_.

class configirl.ConfigMeta

Config class meta class. Collect declared Field, assign field name.

class configirl.BaseConfigClass(**kwargs)

Config class base class.

• BaseConfigClass._declared_fields:
• BaseConfigClass._constant_fields:
• BaseConfigClass._deriable_fields:

classmethod from_dict(dct)

A factory classmethod construct config object from dict. Only loads constant field. If a key is an undefined field, it automatically been ignored.

Return type:BaseConfigClass

classmethod from_json_str(json_str)

A factory classmethod construct config object from json string. json string can includes comments. Only loads constant field. If a key is an undefined field, it automatically been ignored.

Return type:BaseConfigClass

classmethod from_json_file(json_file)

A factory classmethod construct config object from a json file. json string can includes comments. Only loads constant field. If a key is an undefined field, it automatically been ignored.

Return type:BaseConfigClass

classmethod from_env_var(prefix)

A factory classmethod construct config object from environment variables. Only loads constant field. If a key is an undefined field, it automatically been ignored.

Return type:BaseConfigClass

update(dct)

Update constant config values from a dictionary. Only those fields defines as Constant value will be loaded. If a key is an undefined field, it automatically been ignored.

Return type:dict Returns:loaded data

update_from_raw_json_file()

Update constant config values from the BaseConfigClass.CONFIG_RAW_JSON_FILE.

Return type:dict Returns:loaded data

update_from_env_var(prefix)

Update constant config values from environment variables.

Parameters:prefix (str) – a prefix used in all related environment variable. Return type:dict Returns:loaded data

to_dict(check_dont_dump=True, check_printable=False, ignore_na=False, prefix='')

Dump config values to dictionary.

Parameters:

• check_dont_dump (bool) – if True, then it will check if a field has a True value dont_dump flag, then DontDumpError error is raised.
• check_printable (bool) – if True, then it will check if a field has a False value printable flag, then it returns HIDDEN.
• ignore_na (bool) – if True, then ValueNotSetError error will be ignored.
• prefix (str) – a prefix that appended to the left of every field

Return type:

dict

to_json(check_dont_dump=True, check_printable=False, ignore_na=False, prefix='')

Dump config values to json.

Parameters:

• check_dont_dump (bool) – if True, then it will check if a field has a True value dont_dump flag, then DontDumpError error is raised.
• check_printable (bool) – if True, then it will check if a field has a False value printable flag, then it returns HIDDEN.
• ignore_na (bool) – if True, then ValueNotSetError error will be ignored.
• prefix (str) – a prefix that appended to the left of every field

Return type:

str

classmethod is_aws_ec2_amz_linux_runtime()

Check whether it is Amazon Linux EC2 runtime.

Return type:bool

classmethod is_aws_ec2_redhat_runtime()

Check whether it is RedHat AWS EC2 runtime.

Return type:bool

classmethod is_aws_ec2_freebsd_runtime()

Check whether it is FreeBSD AWS EC2 runtime.

Return type:bool

classmethod is_aws_lambda_runtime()

Check whether it is Amazon Lambda Function runtime.

Ref: https://docs.aws.amazon.com/lambda/latest/dg/lambda-environment-variables.html

Return type:bool

classmethod is_aws_code_build_runtime()

Check whether it is AWS Code Build runtime.

Ref: https://docs.aws.amazon.com/codebuild/latest/userguide/build-env-ref-env-vars.html

Return type:bool

classmethod is_ci_runtime()

Check whether it is CI runtime.

Return type:bool

classmethod is_circle_ci_runtime()

Check whether it is CircleCI runtime.

Ref: https://circleci.com/docs/2.0/env-vars/#built-in-environment-variables

Return type:bool

classmethod is_travis_ci_runtime()

Check whether it is TravisCI runtime.

Ref: https://docs.travis-ci.com/user/environment-variables/#default-environment-variables

Return type:bool

classmethod is_gitlab_ci_runtime()

Check whether it is Gitlab CI runtime.

Ref: https://docs.gitlab.com/ee/ci/variables/

Return type:bool

class configirl.ConfigClass(**kwargs)

configirl.read_json_value(path, field)

Return a value of a field from a Json file, ignoring the comments

configirl.get_config_value(module, field)

Initialize a Config Class defined in a python module, and get the value of a field. The module has to be able to be import.

configirl.import_config_value(sys_path, module, field)

Initialize a Config Class defined in a python module, and get the value of a field. The module has to be able to be import when arg sys_path been add to sys.path.

configirl.main()

Command Line Interface entry point.

sub packages and modules