# HG changeset patch
# User Franz Glasner <fzglas.hg@dom66.de>
# Date 1637310529 -3600
# Node ID 727ec2fc8e7e97ca75481bd46ac35a933d93de7a
# Parent  b45403d175a03ca222e3522cced2019dfdf8b8c7
Docs

diff -r b45403d175a0 -r 727ec2fc8e7e configmix/config.py
--- a/configmix/config.py	Fri Nov 19 01:59:42 2021 +0100
+++ b/configmix/config.py	Fri Nov 19 09:28:49 2021 +0100
@@ -696,6 +696,8 @@
     - Not all access-methods of :class:`Configuration` are implemented
       yet.
 
+    .. seealso:: :ref:`jailed-configuration`
+
     .. note:: There is no namespace support.
 
     .. note:: Do not call the constructor directly. Instantiate a jailed
diff -r b45403d175a0 -r 727ec2fc8e7e docs/introduction.rst
--- a/docs/introduction.rst	Fri Nov 19 01:59:42 2021 +0100
+++ b/docs/introduction.rst	Fri Nov 19 09:28:49 2021 +0100
@@ -241,7 +241,7 @@
 
 And with :py:meth:`.Configuration.getfirstvar`,
 :py:meth:`.Configuration.getfirstvar_s`,
-:py:meth:`.Configuration.getfirstintvar_s`, 
+:py:meth:`.Configuration.getfirstintvar_s`,
 :py:meth:`.Configuration.getfirstboolvar_s` and
 :py:meth:`.Configuration.getfirstfloatvar_s` there exist variants that
 accept a *list* of possible variables names and return the first one
@@ -539,6 +539,49 @@
           used in variable interpolation syntax.
 
 
+.. _jailed-configuration:
+
+Jailed Configurations
+---------------------
+
+With :meth:`configmix.config.Configuration.jailed` you get a `jailed`
+(or `restricted`) configuration from a "normal" configuration.
+
+Restriction is two-fold:
+
+- The access to configuration variables in `config` is restricted
+  to the configuration sub-tree that is configured in `path`.
+
+- Not all access-methods of :class:`Configuration` are implemented
+  yet.
+
+This is somewhat analogous to a `chroot` environment for filesystems.
+
+.. note:: The word "jail" is shamelessly stolen from FreeBSD jails.
+
+Usage example::
+
+    import configmix
+
+    config = configmix.load("conf10.py")
+    value = config.getvar_s("tree1.tree2.key4")
+
+    jailed_config1 = config.jailed(rootpath="tree1.tree2")
+    jvalue1 = jailed_config1.getvar_s("key4")
+
+    jailed_config2 = config.jailed(root=("tree1", "tree2"))
+    jvalue2 = jailed_config.getvarl_s("key4")
+
+    assert value == jvalue1 == jvalue2 == "get this as `tree1.tree2.key4'"
+
+`jvalue1` and `jvalue2` (and `value`) yield the very same value
+``get this as `tree1.tree2.key4'`` from the configuration.
+
+All access methods in a jailed configuration automatically prepend the
+given `root path` in order to get the effective key into the base
+configuration.
+
+
 Custom filename extensions and custom loaders
 ---------------------------------------------