Config is now a callable -- it returns an auto-resetting changeset

context which is handy for unittests and other times when you need
to set temporary configuration.

Bump version: 1.31.0 → 1.32.0

Author: jbasko

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.31.0
+current_version = 1.32.0
 commit = true
 tag = false
 

configmanager/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '1.31.0'
+__version__ = '1.32.0'
 
 from .managers import Config
 from .items import Item

configmanager/changesets.py

@@ -7,16 +7,19 @@
 
 
 class _ChangesetContext(object):
-    def __init__(self, config):
+    def __init__(self, config, auto_reset=False, **unsupported_options):
         self.config = config
         self.hook = None
         self._changes = collections.defaultdict(list)
+        self._auto_reset = auto_reset
 
     def __enter__(self):
         return self.push()
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         self.pop()
+        if self._auto_reset:
+            self.reset()
 
     def _value_changed(self, item, old_value, new_value, old_raw_str_value, new_raw_str_value):
         if old_value != new_value or old_raw_str_value != new_raw_str_value:

configmanager/managers.py

@@ -121,16 +121,32 @@ def __init__(self, schema=None, **configmanager_settings):
     def __repr__(self):
         return '<{cls} {alias} at {id}>'.format(cls=self.__class__.__name__, alias=self.alias, id=id(self))
 
+    def __call__(self, values=None):
+        """
+        Returns a changeset context which auto-resets itself on exit.
+        This allows creation of temporary changes of configuration.
+
+        Do not use this in combination with non-resetting changeset contexts:
+        the behaviour under such conditions is undefined.
+
+        If ``values`` dictionary is supplied, the specified configuration values will be set
+        for the duration of the changeset context.
+        """
+        context = self.changeset_context(auto_reset=True)
+        if values is not None:
+            self.load_values(values)
+        return context
+
     @property
     def settings(self):
         return self._settings
 
-    def changeset_context(self):
+    def changeset_context(self, **options):
         """
         Returns:
             configmanager.changesets._ChangesetContext
         """
-        return _ChangesetContext(self)
+        return _ChangesetContext(self, **options)
 
     @property
     def configparser(self):

docs/index.rst

@@ -326,9 +326,45 @@ to be called when this exception is raised:
 
 If this function returns anything other than ``None``, the exception will not be raised.
 
+How to set temporary configuration?
+-----------------------------------
+
+When writing unit tests, or in other scenarios when you need to change configuration briefly just to
+execute some particular part of your code, you can create an auto-resetting configuration context by
+calling your ``Config`` instance as a function.
+
+.. code-block:: python
+
+    with config():
+        config.greeting.value = 'Bon jour!'
+
+        # do some French things here
+        pass
+
+    # French settings have been reset:
+    assert config.greeting.get() == 'Hello, world!'
+
+If you prefer to set the temporary configuration on initialisation of the context, you can do so
+by passing a values dictionary:
+
+.. code-block:: python
+
+    with config({'greeting': 'Bon jour!'}):
+        # do some French things here
+        pass
+
+Note that you cannot pass keyword arguments there, just a dictionary.
+
+
 How do I manage changesets of config values?
 --------------------------------------------
 
+The previous example used a special case of what we call a *changeset context*.
+You can explicitly create one with :meth:`.Config.changeset_context`.
+
+Unlike the special context demonstrated above, a default changeset context does not
+reset changes made while program control was inside it.
+
 .. code-block:: python
     :emphasize-lines: 4,7,10,13,14
 
@@ -353,3 +389,6 @@ How do I manage changesets of config values?
 
     >>> config.greeting.get()
     'Hello, world!'
+
+A changeset context comes handy when you want to create a sub-context of changes which you want to be able
+to export or persist separately from the rest of configuration changes.

tests/test_changesets.py

@@ -362,3 +362,28 @@ def test_length_of_changeset_is_the_number_of_changes_and_truth_value_respects_i
         config.a.set('off')
         assert len(ctx) == 2
         assert ctx
+
+
+def test_calling_config_returns_changeset_context_which_resets_itself_on_exit():
+    from configmanager import Config
+
+    config = Config({
+        'uploads': {
+            'threads': 1,
+            'enabled': True,
+            'db': {
+                'user': 'root',
+                'password': 'secret',
+            }
+        }
+    })
+
+    with config():
+        config.uploads.threads.value = 2
+        config.uploads.db.user.value = 'admin'
+
+        assert config.uploads.threads.value == 2
+        assert config.uploads.db.user.value == 'admin'
+
+    assert config.uploads.threads.value == 1
+    assert config.uploads.db.user.value == 'root'