example

#!/usr/bin/env python

from __future__ import print_function

import zdeskcfg

# Here we annotate the main function arguments. The annotations should match
# the pattern expected by plac_ini and plac:
# (help, kind, abbrev, type, choices, metavar)

@zdeskcfg.configure(
    ex_var=('example variable showing zdeskcfg usage',
              'option', 'x', None, None, 'EX')
    )
def main(ex_var='ex_val'):
    """\
The function docstring is used as help message usage description.

Plac uses the argparse.RawDescriptionHelpFormatter class, which means that
you have the freedom to format your docstrings however you'd like.
Unfortunately, this means that it can be a challenge to make both the
help output and your source look good. See the source for the compromise
I struck in my own code: triple quote, two backslashes, don't indent the
text in the source.

You could also make your source look nice, and then use textwrap.dedent
to (re)assign __doc__ on your function before using zdeskcfg.call. Another
option is to keep your description short, sweet, and single line.\
    """
    print('ex_var', ex_var)

    # Since main is decorated by zdeskcfg.configure, it becomes not only a
    # function but an object with a getconfig() method that returns the
    # Zendesk configuration information.

    print('\n[zdesk]')
    zdesk_config = main.getconfig()

    # The contents of the config are always the following items:
    #     zdesk_email
    #     zdesk_password
    #     zdesk_url
    #     zdesk_token

    for key in zdesk_config.keys():
        print(key, zdesk_config[key])

    # Any section of the ini file can contain email, password, url, and token.
    # You can use the optional section parameter to getconfig to get these
    # values. Any missing values will be provided by the zdesk section, and any
    # values specified on the command line using, e.g., --zdesk-email, etc,
    # will still take effect.

    print('\n[sandbox]')
    zdesk_config = main.getconfig(section='sandbox')

    for key in zdesk_config.keys():
        print(key, zdesk_config[key])

if __name__ == '__main__':
    # We use the call method of zdeskcfg the way one would if they
    # were using plac_ini or plac. This does the work of preparing
    # an argument parser from the annotations, reading the config
    # file, reading the command line arguments, then actually calling
    # the main function.

    zdeskcfg.call(main, section='example')

    # Note that the section should correspond to the section being
    # used by the script, typically. That is, when defined like this:
    #
    #     def main(ex_var='ex_val')):
    #
    # And called like this:
    #
    #     zdeskcfg.call(main, section='example')
    #
    # ex_var will be in a section like this:
    #
    #     [example]
    #     ex_var = zdeskcfg_value
    #
    # and will be received by the decorated function as:
    #
    #     ex_var
    #
    # and zdesk variables are reported as:
    #
    #     zdesk_email
    #     zdesk_password
    #     zdesk_url
    #     zdesk_token


    # When defined like this (note the name is now example_ex_var):
    #
    #     def main(example_ex_var='ex_val')):
    #
    # And called like this:
    #
    #     zdeskcfg.call(main)
    #
    # the default section will be None, and so ex_var will be
    # parsed as and provided to the main function as:
    #
    #     example_ex_var
    #
    # and other variables are still reported as:
    #
    #     zdesk_email
    #     zdesk_password
    #     zdesk_url
    #     zdesk_token
    #
    # In this way it is possible to share variables in the config files
    # between scripts. Beware this can become confusing for end users,
    # since the name on the command line (example_ex_var) differs from
    # the name in the config file (section example, variable ex_var).
    #
    # The main purpose of zdeskcfg is to share the [zdesk] section and
    # provide one default location for all zdesk related configuration.


    # Finally, you should not call your function like this:
    #
    #     zdeskcfg.call(main, section='zdesk')
    #
    # because the default section will be zdesk, and so ex_var will be
    # parsed as and provided to the main function as:
    #
    #     example_ex_var
    #
    # while the other variables are reported as:
    #
    #     email
    #     password
    #     url
    #     token
    #
    # however this does not match up with what the wrapper looks for,
    # so their values will be the defaults of None, None, None, and False.
    # You could possibly receive them in named arguments to the function
    # such as 'email'. Why you'd want to do this I don't know, but I'm not
    # going to stop you if it might be useful.