Metadata-Version: 2.1
Name: confect
Version: 0.1.1
Summary: Python configuration library that provides pleasant configuration definition and access interface, and it reads unrestricted python configuration file.
Home-page: https://github.com/d2207197/confect
License: Apache-2.0
Keywords: setting,configuration,config
Author: 顏孜羲
Author-email: joseph.yen@gmail.com
Requires-Python: >=3.6,<4.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Description-Content-Type: text/x-rst

Confect
=======

``confect`` is a Python configuration library.

It provides a pleasant configuration definition and access interface, and it reads unrestricted python configuration file.

Basic Usage
-----------

Calling ``confect.Conf()`` creates a new configuration manager object. All
configuration properties resides in it. It is possible to create multiple
``Conf`` object, but normally, one ``Conf`` object per application. Initialize
it in some module, then import and use it anywhere in your package.

Put following lines in your application package. For example ``package_name.__init__.py``.

>>> from confect import Conf
>>> conf = Conf()

Configuration properties should be declared with a default value and group name
before using it. Default value can be any type as long as it can be deepcopy.
Group name shuold be a valid attribute name.

Put your configuration group declaration code in the module which you need it
and before all lines that access these properties. Normally, the group name is
your module name or subpackage name.

>>> from your_package import conf
>>> with conf.add_group('yummy') as yummy:
...     yummy.kind = 'seafood'
...     yummy.name = 'fish'
...     yummy.weight = 10
>>> conf.yummy.name
'fish'
>>> conf.yummy.weight
10

Configuration properties and groups are immutable. You can only globally change
it by loading configuration files. Otherwise, they are always default values.

>>> conf.yummy.name = 'octopus'
Traceback (most recent call last):
   ...
confect.error.FrozenConfPropError: Configuration properties are frozen.
Configuration properties can only be changed globally by loading configuration file through ``Conf.load_conf_file()`` and ``Conf.load_conf_module()``.
And it can be changed locally in the context created by `Conf.local_env()`.

Use ``Conf.load_conf_file(path)`` or ``Conf.load_conf_module(module_name)`` to
load configuration files. No matter it is loaded before or after
groups/properties declaration, property values in configuration file always
override default values. Loading multiple files is possible, the latter one
would replace old values. Be aware, you should access your configuration
property values after load configuration file. If not, you might get
wrong/old/default value.

>>> conf.load_conf_file('path/to/conf.py')

The default configuration file is in Python. That makes your configuration file
programmable and unrestricted. Here's an example of configuration file.

.. code-block:: python

   from confect import c

   c.yummy.kind = 'poultry'
   c.yummy.name = 'chicken'
   c.yummy.weight = 25

   import os
   c.cache.expire = 60 * 60 # one hour
   c.cache.key = os.environ['CACHE_KEY']

   DEBUG = True
   if DEBUG:
       c.cache.disable = True

If it's hard for you to specify the path of configuration file. You can load it
through the import system of Python. Put your configuration file somewhere under
your package or make ``PYTHONPATH`` pointing to the directory it resides. Then
load it with ``Conf.load_conf_module(module_name)``.

.. code-block:: bash

   $ edit my_conf.py
   $ export PYTHONPATH=.
   $ python your_application.py

>>> from confect import Conf
>>> conf = Conf()
>>> conf.load_conf_module('my_conf')

