Merge pull request #8 from meowklaski/develop

2.0.2

CHANGELOG.md

@@ -1,3 +1,7 @@
+### 2.0.2
+- custom_inherit.store no longer inherits from `dict`. Fixes bug in which `store.update` could be used
+to circumvent the type-checking that the store enforces.
+
 ### 2.0.1
 - Numpy-style section delimiters was fixed so that they are the appropriate length, and thus compatible with the numpy-style for sphinx.
 

README.md

@@ -182,7 +182,8 @@ Documentation is available via `help(custom_inherit)`.
 
 ```python
 custom_inherit.DocInheritMeta(style="parent", abstract_base_class=False)
-    """ Returns the DocInheritor metaclass of the specified style.
+    """ A metaclass that merges the respective docstrings of a parent class and of its child, along with their
+        properties, methods (including classmethod, staticmethod, decorated methods).
 
         Parameters
         ----------
@@ -204,7 +205,7 @@ custom_inherit.DocInheritMeta(style="parent", abstract_base_class=False)
 
 custom_inherit.doc_inherit(parent, style="parent"):
     """ Returns a function/method decorator that, given `parent`, updates the docstring of the decorated
-        function/method based on the specified style and `parent`.
+        function/method based on the specified style and the corresponding attribute of `parent`.
 
         Parameters
         ----------

custom_inherit/__init__.py

@@ -12,12 +12,30 @@
 
 
 __all__ = ["DocInheritMeta", "doc_inherit", "store", "add_style", "remove_style"]
-__version__ = "2.0.1"
+__version__ = "2.0.2"
 
 
-class _Store(dict):
-    """ A dictionary that stores the styles available for the doc-inheritance metaclass and decorator,
-       respectively."""
+def _check_style_function(style_func):
+    out = style_func("", "")
+    if not isinstance(out, basestring) and out is not None:
+        raise TypeError
+    return None
+
+
+class _Store(object):
+    """ A dictionary-like object that stores the styles available for the doc-inheritance metaclass and decorator,
+       respectively.
+
+       Only callable objects with the signature: f(Optional[str], Optional[str]) -> Optional[str]
+       can be stored. If f is a valid callable, then _Store()[f] -> f."""
+
+    def __init__(self, *args, **kwargs):
+        self._store = dict()
+        self.update(*args, **kwargs)
+
+    def __repr__(self):
+        return repr(self._store)
+
     def __str__(self):
         out_str = "The available stored styles are: "
         styles = "\n".join("\t- " + style for style in sorted(self.keys()))
@@ -33,11 +51,11 @@ def __setitem__(self, style_name, style_func):
             style_func: Callable[[Optional[str], Optional[str]], Optional[str]]
                 The style function that merges two docstrings into a single docstring."""
         try:
-            style_func("", "")
+            _check_style_function(style_func)
         except TypeError:
-            raise TypeError("The style store only stores functions (callables) of the form:\
-             \n\tstyle_func(Optional[str], Optional[str]) -> Optional[str]")
-        super(_Store, self).__setitem__(style_name, style_func)
+            raise TypeError("The style store only stores callables of the form: "
+                            "\n\tstyle_func(Optional[str], Optional[str]) -> Optional[str]")
+        self._store[style_name] = style_func
 
     def __getitem__(self, item):
         """ Given a valid style-ID, retrieve a stored style. If a valid function (callable) is
@@ -48,13 +66,42 @@ def __getitem__(self, item):
             item : Union[Any, Callable[Optional[str], Optional[str]], Optional[str]]
                 A valid style-ID or style-function."""
         try:
-            return super(_Store, self).__getitem__(item)
+            return self._store[item]
         except KeyError:
             try:
-                item("", "")
+                _check_style_function(item)
+                return item
             except TypeError:
                 raise TypeError("Either a valid style name or style-function must be specified")
-        return item
+
+    def keys(self):
+        """  D.keys() -> a set-like object providing a view on D's keys"""
+        return self._store.keys()
+
+    def pop(self, *args):
+        """ D.pop(k[,d]) -> v, remove specified key and return the corresponding value.
+            If key is not found, d is returned if given, otherwise KeyError is raised. """
+        if len(args) < 3:
+            return self._store.pop(*args)
+        else:
+            raise TypeError("pop expected at most 2 arguments, got {}".format(len(args)))
+
+    def update(self, *args, **kwargs):
+        """ D.update([E, ]**F) -> None.  Update D from dict/iterable E and F.
+            If E is present and has a .keys() method, then does:  for k in E: D[k] = E[k]"""
+        if len(args) > 1:
+            raise TypeError("update expected at most 1 arguments, got %d" % len(args))
+
+        for key, value in dict(*args, **kwargs).items():
+            self[key] = value
+
+    def values(self):
+        """ D.values() -> an object providing a view on D's values."""
+        return self._store.values()
+
+    def items(self):
+        """ D.items() -> a set-like object providing a view on D's items"""
+        return self._store.items()
 
 store = _Store([(key, getattr(style_store, key)) for key in style_store.__all__])
 
@@ -83,7 +130,8 @@ def remove_style(style):
 
 
 def DocInheritMeta(style="parent", abstract_base_class=False):
-    """ Returns the DocInheritor metaclass of the specified style.
+    """ A metaclass that merges the respective docstrings of a parent class and of its child, along with their
+        properties, methods (including classmethod, staticmethod, decorated methods).
 
         Parameters
         ----------
@@ -112,7 +160,7 @@ def DocInheritMeta(style="parent", abstract_base_class=False):
 
 def doc_inherit(parent, style="parent"):
     """ Returns a function/method decorator that, given `parent`, updates the docstring of the decorated
-        function/method based on the specified style and `parent`.
+        function/method based on the specified style and the corresponding attribute of `parent`.
 
         Parameters
         ----------