Package: script-args-parser
Script Arguments ParserThis library is meant to provide an easy way to consume arguments for scripts in more complex scenarios without writing too much code.Why something more?In Python there are a lot of ways to consume cli parameters, starting from built-in parsers finishing at libraries like docopt. But unfortunately during my adventure I encountered a few problems that were not solvable just by using one of them. Few of those problems:get values from multiple sources: cli, config file, environment variable, default;convert given variable according to argument definition;all argument information (cli option, fallback env var, conversion type, default value etc.) defined in one place;definitions written outside the code, so the script is kept clean and simple;more complex conversion types build in.Main featuresParameters defined in both human- and computer-readable format outside of the code, in one placeArgument values converted to given format (predefined or custom)Config file fallbackEnvironmental variable fallbackDefault valuesHuman readable errorsUsageOne of the goals of this library was to minimize amount of the code. Therefore whole usage looks like this:fromscript_args_parserimportArgumentsParserargs=ArgumentsParser.from_files('example-parameters.toml',yaml_config='example-config.yaml')print(args.name)print(args.age)Above script will read arguments definition fromexample-parameters.tomland try to read their values in following order:from cli options,from config file (example-config.yamlin example),from environment variables,default values.If any argument does not have value defined it will be None, unless it is required, so it will raise an exception.When all values are established, parser will convert them to specified type.Arguments definitionThe list of script arguments is provided in toml file. Example argument can look like this:[name]description="Some fancy description"# requiredtype="str"# requiredcli_arg="--cli-opt"# requiredenv_var="ENV_VAR_NAME"required=falsedefault_value="I got you"description(mandatory)Human readable description of an argument.type(mandatory)Parser will use this field to convert value of the argument from string to one that is specified.Some more complex types are also changing the way cli options are parsed.For detailed description of possible values and their meaning, seeTypes section.cli_arg(mandatory)Name of the cli option throught which value can be set.env_varName of environment variable that will be used to read value if not specified by CLI or config file.For the format used by more complex types seeTypes section.requiredBy default False. If set to true, the parser will raise an error if value will not be found anywhere.Can be specified as boolean value (true, false) or by string ('true', 'false', 'yes', 'no', '1', '0').default_valueValue that will be used if not specified by CLI, config file or environment variable.For the format used by more complex types seeTypes section.TypesThis is the list of built-in types supported.StringType field value:strNo special operations are performed.IntegerType field value:intValue will be parsed to integer, if not possible, exception will be raised.Post operationsAdditional parameterpost_operationscan be used. It stores the expression that will be evaluated after the value is read. The result of evaluation will be used as a value. The{value}token in expression will be substituted with the value provided by the user.For example when a program requires value in seconds, but the user will always want to specify minutes thepost_operationscan be:"{value} * 60".BooleanType field value:boolSome strings has been defined to be matched to specific values (case insensitive):True can be specified as: true, yes, 1;False can be specified as: false, no, 0;All other values will be converted to bool using Python rules.SwitchType field value:switchBehaves in the same way asboolbut additionaly cli option can be passed without an argument and will be considered True.PathType field value:pathWill be converted intopathlib.Pathobject. Worth noticing is that empty string will be equivalent of current directory.Parent pathAdditional parameterparent_pathcan be used. It shall contain a name of another path argument. Current path will be prepended with the value ofparent_path.With given toml file the default value ofpicture_namewill be'images/beautiful.jpg'.[pictures_folder]description="Path to folder with pictures"type="path"cli_arg="--pictures-folder"default="./images"[picture_name]description="Name of a picture file"type="path"cli_arg="--picture-name"parent_path="pictures_folder"default="beautiful.jpg"It is possible to make a hierarchy of paths, but keep in mind that the arguments are evaluated in order that they are defined in toml file, so with below toml file thepicture_namewill have value'the_best_user\beautiful.jpg'even thoughuser_folderwill bepictures_folder\user_folder.[pictures_folder]description="Path to folder with pictures"type="path"cli_arg="--pictures-folder"default="./images"[picture_name]description="Name of a picture file"type="path"cli_arg="--picture-name"parent_path="user_folder"default="beautiful.jpg"[user_folder]description="Name of a user folder file"type="path"cli_arg="--user-folder"parent_path="pictures_folder"default="the_best_user"ListType field value:list[<simple type>]Will produce a list of elements with given simple types (any that was described above).When this type is specified, multiple cli options should be used to pass list elements:script.py --child-name John --child-name DavidIn default value or environment variable use semicolon to split values:default_value = "John; David; 'Some;Very;Strange;Name'"TupleType field value:tuple[<simple type>, <optional simple type>, ...]Example type field value:tuple[str],tuple[int, str, bool].Will produce a list with given amount of values of simple types elements.When this type is specified, cli options should be used once but with multiple values. Fortuple[str, str, str]script.py --all-my-names John Maria "De'naban"In default value or environment variable separate values with space:default_value = "John Maria "De'naban"List of tuplesType field value:list[tuple[<simple type>, <optional simple type>, ...]]Combining list and tuple types. Will produce a list of lists.For cli use:script.py --child John 16 --child David 18 --child Maria 21For default values and enviroment variables use:default_value = "John 16; David 18; Maria 21"Above examples forlist[tuple[str, int]]will produce:[['John',16],['David',18],['Maria',21]]Dataclass argumentType field value:<name of the dataclass>Parses a list or a dict to user defined dataclass.In order for the dataclass to be used it has to be decorated withscript_args_parser.decorators.dataclass_argument.With given Python code and toml definition:@dataclass_argument@dataclassclassMyDataClass:value_1:strvalue_2:str[two_values]description="Some two string values"type="MyDataClass"cli_arg="--two-values"The following yaml input files can be usedtwo_values:-first_value-second valueortwo_values:value_1:first_valuevalue_2:second valueThe type can also be used as a list type argument like:[two_values]description="Some two string values"type="list[MyDataClass]"cli_arg="--two-values"NOTE: Currently cli or env values are not supported for this type.Planned workWork that still need to be done prior to v1.0Default and envs for listDefault and envs for tupleDefault and envs for list of tuplesAdd more list of tuples testsAdd path type (with tests)Create from pathSupport config fileDocument possible typesAdd support for env and cli values for dataclass typeWrite some complex test casesAllow non-cli argumentsAdd loggingAllow custom argument typesGenerate usageError handlingTOML file validationCI/CDContributingRight now I would like to finish what I planned by myself and release version 1.0. If you have any suggestions or you have found bugs, feel free to submit an issue and I will take a look at it as soon as possible.DevelopmentDevelopment documentation can be foundhere