optini package

Submodules

optini.optini module

See top level package docstring for documentation

class optini.optini.Config(appname: str, description: Optional[str] = None, desc: Optional[str] = None, epilog: Optional[str] = None, file: bool = False, filename: Optional[str] = None, io: bool = False, logging: bool = False, skeleton: bool = True, spec: Optional[bool] = None)[source]

Bases: object

Class to get options from command line and config file

Examples

Define one boolean option, someopt, which defaults to false; users can specify -s at the command line, or put someopt = true in the config file.

import optini
optinispec.someopt.help = 'Set a flag'
# implies -s and --someopt command line options
optini.Config(spec=spec, file=True)
if optini.opt.someopt:
    print("someopt flag is set")

Config file defaults to ~/.<appname>.ini

Attributes

appnamestr

Application identifier (required)

descriptionstr

If not None, optini will use this in argparse usage message

descstr

Alias for description

epilogstr

Text to display after the argument help

filebool (default: False)

Enable config file

filenamestr (default: <appname>.ini)

If provided, optini will use this file as config file

loggingbool (default: False)
Incorporate logging config, with (mostly) conventional options

(-v, -d, -q, -L, -F LOGFILE)

iobool (default: False)
Incorporate file input/output with conventional options

(-i inputfile, -o outputfile; defaults: stdin/stdout)

skeletonbool (default: True)

Create default config file if using config files

specdotmap.DotMap or dict

Mapping of option names to option configuration

appname: str
desc: str
description: str
epilog: str
file: bool
filename: str
io: bool
logging: bool
merge_spec(spec)[source]

Procedure to add option specifications

  • On option name clash, new options override old options

  • This procedure also adds various defaults

Parameters

specdotmap.DotMap or dict

Option specification

skeleton: bool
skeleton_configfile()[source]

Generate sample config file showing default values

spec: bool
optini.optini.log_spec(spec)[source]

Procedure to log contents of spec, one message per item

optini.optini.opt = {'_unparsed': None}

opt : dotmap.DotMap Global data structure storing top-level config options

Example ini config file:

top_level_option = topthing

[some_section]
secondary_option = something

Results in opt being defined as:

DotMap(top_level_option='topthing')

To access:

print(optini.opt.top_level_option)
optini.optini.section = {}

Note: not supported yet

section : dotmap.DotMap Global data structure storing secondary config options (ini section)

Example ini config file:

top_level_option = something

[some_section]
secondary_option = something

Results in secion being defined as:

DotMap(some_section=DotMap(secondary_option='something'))

To access:

print(optini.section.some_section.secondary_option)
optini.optini.spec = {}

Empty dotmap object for ease of initialization

Module contents

Class to get options from command line and config file

Features

  • Aggressively conventional defaults

  • Collect configuration from command line, config file, and defaults

    • Configuration hierarchy: command line > config file > defaults

  • Interface is a module-level variable: optini.opt

    • Module-level interface allows libraries to access config

  • Access config options through module-level dotmap interface

    • Example: optini.opt.verbose

  • Derives command line options from option names

    • Example: “verbose” => -v and –verbose

  • Single flag to support (mostly) conventional logging options

    • (-v, -d, -q, -L, -F LOGFILE)

  • Single flag to support I/O options (-i input and -o output)

  • Supports top-level ini section without a header

  • Uses standard libraries under the hood (logging, argparse, configparser)

Limitations

  • Only top-level code (such as UI script) should initialize Config

Examples

Define one boolean option, someopt, which defaults to false; users can specify -s at the command line, or put someopt = true in the config file.

import optini
optini.spec.someopt.help = 'Set a flag'
# implies -s and --someopt command line options
desc = 'This code does a thing'
optini.Config(appname='myapp', file=True, desc=desc)
if optini.opt.someopt:
    print("someopt flag is set")

Config file defaults to ~/.<appname>.ini

Enable logging config:

import logging
import optini
optini.Config(appname='something', logging=True)
# the verbose (-v) option enables info messages
logging.info('this is an info message')
# the debug (-d) option enables debug messages
logging.debug('this is a debug message')
# the Log (-L) option writes logs to file (default: <appname>.log)

Option Specification Format

  • Nested data structure (either dict or dotmap is valid)

  • The top level key is the option name

  • To configure each option, specify second level keys:
    • helpstr, default=None

      • for argparse usage message, default config file comments

    • typetype, default=bool

      • type hint for parsers

      • Supported: bool, str, int, float

    • default, default=None

      • the default value for the option

    • required, default=False

      • Declare the option mandatory at the command line

    • shortstr

      • Short form command line option (example: -v)

    • longstr

      • Long form command line option (example: –verbose)

    • configfilebool

      • Specify False for command line only options

  • Second level keys, apart from configfile, are passed to argparse