From 7e58b29a92157fad40b50ef31f8c075b9dc363b7 Mon Sep 17 00:00:00 2001
From: Jason Gerard DeRose <jderose@redhat.com>
Date: Wed, 20 May 2009 15:19:09 -0600
Subject: Completed Param.use_in_context() functionality, which is now used by
 Command and Object

---
 ipalib/parameters.py | 54 ++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 42 insertions(+), 12 deletions(-)

(limited to 'ipalib/parameters.py')

diff --git a/ipalib/parameters.py b/ipalib/parameters.py
index 0c2748ee..2ecc6178 100644
--- a/ipalib/parameters.py
+++ b/ipalib/parameters.py
@@ -381,24 +381,54 @@ class Param(ReadOnly):
 
     def use_in_context(self, env):
         """
-        Return ``True`` if this param should be used in ``env.context``.
+        Return ``True`` if this parameter should be used in ``env.context``.
 
-        For example:
+        If a parameter is created with niether the ``include`` nor the
+        ``exclude`` kwarg, this method will always return ``True``.  For
+        example:
 
         >>> from ipalib.config import Env
-        >>> server = Env()
-        >>> server.context = 'server'
-        >>> client = Env()
-        >>> client.context = 'client'
-        >>> param = Param('my_param', include=['server', 'webui'])
-        >>> param.use_in_context(server)
+        >>> param = Param('my_param')
+        >>> param.use_in_context(Env(context='foo'))
+        True
+        >>> param.use_in_context(Env(context='bar'))
+        True
+
+        If a parameter is created with an ``include`` kwarg, this method will
+        only return ``True`` if ``env.context`` is in ``include``.  For example:
+
+        >>> param = Param('my_param', include=['foo', 'whatever'])
+        >>> param.include
+        frozenset(['foo', 'whatever'])
+        >>> param.use_in_context(Env(context='foo'))
         True
-        >>> param.use_in_context(client)
+        >>> param.use_in_context(Env(context='bar'))
+        False
+
+        If a paremeter is created with an ``exclude`` kwarg, this method will
+        only return ``True`` if ``env.context`` is not in ``exclude``.  For
+        example:
+
+        >>> param = Param('my_param', exclude=['foo', 'whatever'])
+        >>> param.exclude
+        frozenset(['foo', 'whatever'])
+        >>> param.use_in_context(Env(context='foo'))
         False
+        >>> param.use_in_context(Env(context='bar'))
+        True
+
+        Note that the ``include`` and ``exclude`` kwargs are mutually exclusive
+        and that at most one can be suppelied to `Param.__init__()`.  For
+        example:
+
+        >>> param = Param('nope', include=['foo'], exclude=['bar'])
+        Traceback (most recent call last):
+          ...
+        ValueError: Param('nope'): cannot have both include=frozenset(['foo']) and exclude=frozenset(['bar'])
 
-        So that a subclass can add additional logic basic on other environment
-        variables, the `config.Env` instance is passed in rather than just the
-        value of ``env.context``.
+        So that subclasses can add additional logic based on other environment
+        variables, the entire `config.Env` instance is passed in rather than
+        just the value of ``env.context``.
         """
         if self.include is not None:
             return (env.context in self.include)
-- 
cgit