Click config file
=================
Easily add configuration file support to your
`Click <http://click.pocoo.org/5/>`_ applications by adding a single
no-arguments decorator.
.. image:: https://img.shields.io/pypi/v/click-config-file.svg?style=flat-square
:target: https://pypi.org/project/click-config-file/
.. image:: https://img.shields.io/conda/vn/conda-forge/click-config-file.svg?style=flat-square
:target: https://anaconda.org/conda-forge/click-config-file
.. image:: https://img.shields.io/travis/phha/click_config_file/master.svg?style=flat-square
:target: https://travis-ci.org/phha/click_config_file
.. image:: https://img.shields.io/codacy/grade/a5f6262609314683bf2b2bc546bdaffe/master.svg?style=flat-square
:target: https://www.codacy.com/app/phha/click_config_file
Basic usage
-----------
click-config-file is designed to be a usable by simply adding the
appropriate decorator to your command without having to supply any
mandatory arguments. It comes with a set of sensible defaults that
should just work for most cases.
Given this application:
.. code-block:: python
@click.command()
@click.option('--name', default='World', help='Who to greet.')
@click_config_file.configuration_option()
def hello(name):
click.echo('Hello {}!'.format(name))
Running ``hello --help`` will give you this::
Usage: hello [OPTIONS]
Options:
--name TEXT Who to greet.
--config PATH Read configuration from PATH.
--help Show this message and exit.
If the configuration file does not exist, running ``hello`` will do what
you expect::
Hello World!
With this configuration file::
name="Universe"
Calling ``hello`` will also do what you expect::
Hello Universe!
Calling ``hello --name Multiverse`` will override the configuration file
setting, as it should::
Hello Multiverse!
The default name for the configuration file option is ``--config``.
Command line and environment options will override the configuration
file options. Configuration file options override default options. So
the resolution order for a given option is: CLI > Environment >
Configuration file > Default.
Options
-------
Although ``configuration_option`` is designed to work without any mandatory
arguments, some optional parameters are supported:
``implicit``
Default: ``True``
By default ``configuration_option`` will look for a configuration file
even if no value for the configuration option was provided either via
a CLI argument or an environment variable. In this case the value will
be set implicitly from ``cmd_name`` and ``config_file_name`` as
described below.
If set to ``False`` the configuration file settings will only be applied
when a configuration file argument is provided.
``cmd_name``
Default: ``ctx.cmd_info``
The name of the decorated command. When implicitly creating a
configuration file argument, the application directory containing the
configuration file is resolved by calling ``click.get_app_dir(cmd_name)``.
This defaults to the name of the command as determined by click.
``config_file_name``
Default: ``config``
When ``implicit`` is set to ``True``, this argument provides the name of the
configuration file inside the application directory.
In addition to the arguments above, all arguments for ``click.option()`` and
``click.File()`` are supported.
Supported file formats
----------------------
By default click-config-file supports files formatted according to
`Configobj's unrepr
mode <http://configobj.readthedocs.io/en/latest/configobj.html#unrepr-mode>`_.
You can add support for additional configuration providers by setting
the ``provider`` keyword argument. This argument expects a callable that
will take the configuration file path and command name as arguments and
returns a dictionary with the provided configuration options.
The command name is passed in order to allow for a shared configuration
file divided by sections for each command.
For example, this will read the configuration options from a shared JSON
file:
.. code-block:: python
def myprovider(file_path, cmd_name):
with open(file_path) as config_data:
return json.load(config_data)[cmd_name]
@click.command()
@click.option('--name', default='World')
@click_config_file.configuration_option(provider=myprovider)
def hello(name):
click.echo('Hello {}!'.format(name))
Installation
------------
``pip install click-config-file``
Why?
----
There are several existing implementations of config file support for
Click, however they seem to lack one or more of the following features:
- Sensible defaults
- Proper handling of resolution order
- Support for multi value options, multiple options or a combination
of both
In contrast this module may lack some more sophisticated features of the
other implementations. This is a deliberate choice as this module is
intended to be a simple option that Just Works with sensible defaults.
Raw data
{
"_id": null,
"home_page": "http://github.com/phha/click_config_file",
"name": "click-config-file",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Philipp Hack",
"author_email": "philipp.hack@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/13/09/dfee76b0d2600ae8bd65e9cc375b6de62f6ad5600616a78ee6209a9f17f3/click_config_file-0.6.0.tar.gz",
"platform": "",
"description": "Click config file\n=================\n\nEasily add configuration file support to your\n`Click <http://click.pocoo.org/5/>`_ applications by adding a single\nno-arguments decorator.\n\n.. image:: https://img.shields.io/pypi/v/click-config-file.svg?style=flat-square\n :target: https://pypi.org/project/click-config-file/\n.. image:: https://img.shields.io/conda/vn/conda-forge/click-config-file.svg?style=flat-square\n :target: https://anaconda.org/conda-forge/click-config-file\n.. image:: https://img.shields.io/travis/phha/click_config_file/master.svg?style=flat-square\n :target: https://travis-ci.org/phha/click_config_file\n.. image:: https://img.shields.io/codacy/grade/a5f6262609314683bf2b2bc546bdaffe/master.svg?style=flat-square\n :target: https://www.codacy.com/app/phha/click_config_file\n\nBasic usage\n-----------\n\nclick-config-file is designed to be a usable by simply adding the\nappropriate decorator to your command without having to supply any\nmandatory arguments. It comes with a set of sensible defaults that\nshould just work for most cases.\n\nGiven this application:\n\n.. code-block:: python\n\n @click.command()\n @click.option('--name', default='World', help='Who to greet.')\n @click_config_file.configuration_option()\n def hello(name):\n click.echo('Hello {}!'.format(name))\n\nRunning ``hello --help`` will give you this::\n\n Usage: hello [OPTIONS]\n\n Options:\n --name TEXT Who to greet.\n --config PATH Read configuration from PATH.\n --help Show this message and exit.\n\nIf the configuration file does not exist, running ``hello`` will do what\nyou expect::\n\n Hello World!\n\nWith this configuration file::\n\n name=\"Universe\"\n\nCalling ``hello`` will also do what you expect::\n\n Hello Universe!\n\nCalling ``hello --name Multiverse`` will override the configuration file\nsetting, as it should::\n\n Hello Multiverse!\n\nThe default name for the configuration file option is ``--config``.\n\nCommand line and environment options will override the configuration\nfile options. Configuration file options override default options. So\nthe resolution order for a given option is: CLI > Environment >\nConfiguration file > Default.\n\nOptions\n-------\n\nAlthough ``configuration_option`` is designed to work without any mandatory\narguments, some optional parameters are supported:\n\n``implicit``\n Default: ``True``\n\n By default ``configuration_option`` will look for a configuration file\n even if no value for the configuration option was provided either via\n a CLI argument or an environment variable. In this case the value will\n be set implicitly from ``cmd_name`` and ``config_file_name`` as\n described below.\n\n If set to ``False`` the configuration file settings will only be applied\n when a configuration file argument is provided.\n\n``cmd_name``\n Default: ``ctx.cmd_info``\n\n The name of the decorated command. When implicitly creating a\n configuration file argument, the application directory containing the\n configuration file is resolved by calling ``click.get_app_dir(cmd_name)``.\n\n This defaults to the name of the command as determined by click.\n\n``config_file_name``\n Default: ``config``\n\n When ``implicit`` is set to ``True``, this argument provides the name of the\n configuration file inside the application directory.\n\nIn addition to the arguments above, all arguments for ``click.option()`` and\n``click.File()`` are supported.\n\nSupported file formats\n----------------------\n\nBy default click-config-file supports files formatted according to\n`Configobj's unrepr\nmode <http://configobj.readthedocs.io/en/latest/configobj.html#unrepr-mode>`_.\n\nYou can add support for additional configuration providers by setting\nthe ``provider`` keyword argument. This argument expects a callable that\nwill take the configuration file path and command name as arguments and\nreturns a dictionary with the provided configuration options.\n\nThe command name is passed in order to allow for a shared configuration\nfile divided by sections for each command.\n\nFor example, this will read the configuration options from a shared JSON\nfile:\n\n.. code-block:: python\n\n def myprovider(file_path, cmd_name):\n with open(file_path) as config_data:\n return json.load(config_data)[cmd_name]\n\n @click.command()\n @click.option('--name', default='World')\n @click_config_file.configuration_option(provider=myprovider)\n def hello(name):\n click.echo('Hello {}!'.format(name))\n\n\nInstallation\n------------\n\n``pip install click-config-file``\n\nWhy?\n----\n\nThere are several existing implementations of config file support for\nClick, however they seem to lack one or more of the following features:\n\n- Sensible defaults\n- Proper handling of resolution order\n- Support for multi value options, multiple options or a combination\n of both\n\nIn contrast this module may lack some more sophisticated features of the\nother implementations. This is a deliberate choice as this module is\nintended to be a simple option that Just Works with sensible defaults.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Configuration file support for click applications.",
"version": "0.6.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "b8db66db7a2f8e6d4ab2f65110a44bf3",
"sha256": "3c5802dec437ed596f181efc988f62b1069cd48a912e280cd840ee70580f39d7"
},
"downloads": -1,
"filename": "click_config_file-0.6.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "b8db66db7a2f8e6d4ab2f65110a44bf3",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 5964,
"upload_time": "2020-04-28T07:09:14",
"upload_time_iso_8601": "2020-04-28T07:09:14.063668Z",
"url": "https://files.pythonhosted.org/packages/28/16/c71980d10b75cf4ee2c71bb946c3326a18585254399aac64a5e79cfba5a5/click_config_file-0.6.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "f4a28e41585b7392fd75e016fdc28f87",
"sha256": "ded6ec1a73c41280727ec9c06031e929cdd8a5946bf0f99c0c3db3a71793d515"
},
"downloads": -1,
"filename": "click_config_file-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "f4a28e41585b7392fd75e016fdc28f87",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5800,
"upload_time": "2020-04-29T10:35:22",
"upload_time_iso_8601": "2020-04-29T10:35:22.195972Z",
"url": "https://files.pythonhosted.org/packages/13/09/dfee76b0d2600ae8bd65e9cc375b6de62f6ad5600616a78ee6209a9f17f3/click_config_file-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-04-29 10:35:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "phha",
"github_project": "click_config_file",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "click-config-file"
}
JSON
