* Make hook names easier to discover for IDEs

* Docs update

Author: jbasko

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 1.29.0
+current_version = 1.29.1
 commit = true
 tag = false
 

configmanager/__init__.py

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

configmanager/managers.py

@@ -178,6 +178,10 @@ def settings(self):
         return self._settings
 
     def tracking_context(self):
+        """
+        Returns:
+            _TrackingContext
+        """
         return _TrackingContext(self)
 
     @property
@@ -187,7 +191,7 @@ def configparser(self):
         ``ConfigParser`` (or the backported configparser module in Python 2).
         
         Returns:
-            :class:`.ConfigPersistenceAdapter`
+            ConfigPersistenceAdapter
         """
         if self._configparser_adapter is None:
             self._configparser_adapter = ConfigPersistenceAdapter(
@@ -204,7 +208,7 @@ def json(self):
         Adapter to dump/load JSON format strings and files.
         
         Returns:
-            :class:`.ConfigPersistenceAdapter`
+            ConfigPersistenceAdapter
         """
         if self._json_adapter is None:
             self._json_adapter = ConfigPersistenceAdapter(
@@ -219,7 +223,7 @@ def yaml(self):
         Adapter to dump/load YAML format strings and files.
         
         Returns:
-            :class:`.ConfigPersistenceAdapter`
+            ConfigPersistenceAdapter
         """
         if self._yaml_adapter is None:
             self._yaml_adapter = ConfigPersistenceAdapter(
@@ -232,6 +236,9 @@ def yaml(self):
     def click(self):
         """
         click extension
+
+        Returns:
+            ClickExtension
         """
         if self._click_extension is None:
             from .click_ext import ClickExtension

configmanager/sections.py

@@ -22,6 +22,15 @@
 }
 
 
+class _SectionHooks(HookRegistry):
+    def __init__(self, section):
+        super(_SectionHooks, self).__init__(section)
+        self.not_found = self.register_event('not_found')
+        self.item_added_to_section = self.register_event('item_added_to_section')
+        self.section_added_to_section = self.register_event('section_added_to_section')
+        self.item_value_changed = self.register_event('item_value_changed')
+
+
 class Section(BaseSection):
     """
     Represents a section consisting of items (instances of :class:`.Item`) and other sections
@@ -43,12 +52,8 @@ def __init__(self, schema=None, section=None):
         #: Alias of this section with which it was added to its parent section
         self._section_alias = None
 
-        #: Hooks registry
-        self._hooks = HookRegistry(self)
-        self._hooks.not_found = self._hooks.register_event('not_found')
-        self._hooks.item_added_to_section = self._hooks.register_event('item_added_to_section')
-        self._hooks.section_added_to_section = self._hooks.register_event('section_added_to_section')
-        self._hooks.item_value_changed = self._hooks.register_event('item_value_changed')
+        # Hooks registry
+        self._hooks = _SectionHooks(self)
 
         # Listen for hook registration so we can enable per-section hooks only when they
         # are actually used.
@@ -257,7 +262,7 @@ def get_proxy(self, *key):
     def hooks(self):
         """
         Returns:
-            HookRegistry
+            _SectionHooks
         """
         return self._hooks
 

docs/index.rst

@@ -326,10 +326,14 @@ to be called when this exception is raised:
 
 If this function returns anything other than ``None``, the exception will not be raised.
 
-How can I track changes of config values?
------------------------------------------
+How do I manage changesets of config values?
+--------------------------------------------
 
 .. code-block:: python
+    :emphasize-lines: 4,7,10,13,14
+
+    >>> config.greeting.value
+    'Hello, world!'
 
     >>> with config.tracking_context() as ctx:
     ...     config.greeting.value = 'Hey, what is up!'
@@ -339,3 +343,11 @@ How can I track changes of config values?
 
     >>> ctx.changes[config.greeting]
     'Hey, what is up!'
+
+    >>> ctx.reset_changes()
+    >>> ctx.changes
+    {}
+
+    >>> config.greeting.value
+    'Hello, world!'
+