Nestable, tab-able options for use in Python programs
Project description
Optioneer makes in-program options, that:
are nestable and groupable,
are tab-able in the REPL for easy options discoverability
give each option a optional doc string, for easily explaining the option
may deprecate according to a transparent deprecation cycle
may be validated upon change
can do custom callbacks
Optioneer is based on the core/config.py module in pandas.
Installation
Installing is easy using pip:
pip install optioneer
Usage guide
In a config.py file set up your options:
>>> from optioneer import Optioneer >>> opt_maker = Optioneer() >>> opt_maker.register_option('api_key', 'abcdefg') >>> opt_maker.register_option('display.width', 200, doc='Width of our display') >>> opt_maker.register_option('display.height', 200, doc='Height of our display') >>> opt_maker.register_option('color', 'red', validator=opt_maker.is_str) >>> options = opt_maker.options
Then, in the relevant location of your library, just do from config import options and you’re got your options set up.
Notice that the options allow options discovery using tab in the REPL:
>>> options.<TAB> option.api_key options.color options.display >>> options.display.<TAB> options.display.height options.display.width
You can also easily see the options and their values and docs in the repr string:
>>> options Options( api_key: No description available. [default: abcdefg] [currently: abcdefg] color: No description available. [default: red] [currently: red] display.height: Height of our display [default: 200] [currently: 200] display.width: Width of our display [default: 200] [currently: 200] ) >>> options.display Options( display.height: Height of our display [default: 200] [currently: 200] display.width: Width of our display [default: 200] [currently: 200] )
Callbacks
By providing a callback when registering options, changing options may trigger a desired actions. For example:
>>> opt_maker.register_option('shout', True, callback=lambda x: print("YEAH!")) >>> options.shout = False YEAH!
Of course, the callback can be more realistic than above, e.g. logging or setting some internal option on a class or something else.
Deprecating options
If you want to deprecate an option, optioneer allows you to do that:
>>> opt_maker.deprecate_option('api_key', msg='An api key is no longer needed')
Now your users get a deprecation warning, if they access this option:
>>> options.api_key An api key is no longer needed C:\Users\TP\Documents\Python\optioneer\optioneer\lib.py:677: FutureWarning: An api key is no longer needed warnings.warn(deprecated_option.msg, FutureWarning) Out[20]: 'abcdefg'
If an options should be renamed and/or a marker should be for when the option will be removed, that is also possible:
>>> opt_maker.register_option('display.length', 200, doc='Length of our display') >>> opt_maker.deprecate_option('display.height', redirect_key='display.length', ... removal_ver='1.3') >>> options.display.height C:\Users\TP\Documents\Python\optioneer\optioneer\lib.py:689: FutureWarning: 'display.height' is deprecated and will be removed in 1.3, please use 'display.length' instead. warnings.warn(msg, FutureWarning) Out[24]: 200
License
Optioneer is BSD 3-licensed.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for optioneer-1.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 18351bec4b991a32bbe6b03489d3195acf0ba7f3ba33c71db4407b8b89b0dca7 |
|
MD5 | d75481ea866b4e30ad8774d8ee10e1c0 |
|
BLAKE2b-256 | 479ceb2b5bcc9213710d7a6ef60151b6e2ce10298df5fa71d45fc0cdcaa72e80 |