From 38c64ff3518470ff668a06725abb4d2f2d5ab7ba Mon Sep 17 00:00:00 2001
From: Ryan Petrello <lists@ryanpetrello.com>
Date: Thu, 8 Aug 2013 11:31:10 -0400
Subject: Clarify the __force_dict__ configuration directive.

---
 docs/source/configuration.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

(limited to 'docs')

diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
index f578ab4..ea4d29d 100644
--- a/docs/source/configuration.rst
+++ b/docs/source/configuration.rst
@@ -177,3 +177,27 @@ if you need to prefix the keys in the returned dictionary.
     Config({'app': Config({'errors': {}, 'template_path': '', 'static_root': 'public', [...]
     >>> conf.as_dict('prefixed_')
     {'prefixed_app': {'prefixed_errors': {}, 'prefixed_template_path': '', 'prefixed_static_root': 'prefixed_public', [...]
+
+
+Dotted Keys and Native Dictionaries
+-----------------------------------
+
+Sometimes you want to specify a configuration option that includes dotted keys.
+This is especially common when configuring Python logging.  By passing
+a special key, ``__force_dict__``, individual configuration blocks can be
+treated as native dictionaries.
+
+::
+
+    logging = {
+        'loggers': {
+            'root': {'level': 'INFO', 'handlers': ['console']},
+            'sqlalchemy.engine': {'level': 'INFO', 'handlers': ['console']},
+            '__force_dict__': True
+        }
+    }
+
+    from myapp import conf
+    assert isinstance(conf.logging.loggers, dict)
+    assert isinstance(conf.logging.loggers['root'], dict)
+    assert isinstance(conf.logging.loggers['sqlalchemy.engine'], dict)
-- 
cgit v1.2.1