README.rst
1Confuse: painless YAML config files
2===================================
3
4.. image:: https://github.com/beetbox/confuse/workflows/Build/badge.svg?branch=master
5 :target: https://github.com/beetbox/confuse/actions
6
7.. image:: http://img.shields.io/pypi/v/confuse.svg
8 :target: https://pypi.python.org/pypi/confuse
9
10**Confuse** is a configuration library for Python that uses `YAML`_. It takes
11care of defaults, overrides, type checking, command-line integration,
12environment variable support, human-readable errors, and standard OS-specific
13locations.
14
15What It Does
16------------
17
18Here’s what Confuse brings to the table:
19
20- An **utterly sensible API** resembling dictionary-and-list structures
21 but providing **transparent validation** without lots of boilerplate
22 code. Type ``config['num_goats'].get(int)`` to get the configured
23 number of goats and ensure that it’s an integer.
24
25- Combine configuration data from **multiple sources**. Using
26 *layering*, Confuse allows user-specific configuration to seamlessly
27 override system-wide configuration, which in turn overrides built-in
28 defaults. An in-package ``config_default.yaml`` can be used to
29 provide bottom-layer defaults using the same syntax that users will
30 see. A runtime overlay allows the program to programmatically
31 override and add configuration values.
32
33- Look for configuration files in **platform-specific paths**. Like
34 ``$XDG_CONFIG_HOME`` or ``~/.config`` on Unix; "Application Support" on
35 macOS; ``%APPDATA%`` on Windows. Your program gets its own
36 directory, which you can use to store additional data. You can
37 transparently create this directory on demand if, for example, you
38 need to initialize the configuration file on first run. And an
39 environment variable can be used to override the directory's
40 location.
41
42- Integration with **command-line arguments** via `argparse`_ or `optparse`_
43 from the standard library. Use argparse's declarative API to allow
44 command-line options to override configured defaults.
45
46- Include configuration values from **environment variables**. Values undergo
47 automatic type conversion, and nested dicts and lists are supported.
48
49Installation
50------------
51
52Confuse is available on `PyPI <https://pypi.org/project/confuse/>`_ and can be installed
53using :code:`pip`:
54
55.. code-block:: sh
56
57 pip install confuse
58
59Using Confuse
60-------------
61
62`Confuse's documentation`_ describes its API in detail.
63
64Credits
65-------
66
67Confuse was made to power `beets`_.
68Like beets, it is available under the `MIT license`_.
69
70.. _ConfigParser: http://docs.python.org/library/configparser.html
71.. _YAML: http://yaml.org/
72.. _optparse: http://docs.python.org/dev/library/optparse.html
73.. _argparse: http://docs.python.org/dev/library/argparse.html
74.. _logging: http://docs.python.org/library/logging.html
75.. _Confuse's documentation: http://confuse.readthedocs.org/en/latest/usage.html
76.. _MIT license: http://www.opensource.org/licenses/mit-license.php
77.. _beets: https://github.com/beetbox/beets
78
