Commits

Jonathan Eunice committed 2771f06

About to clone

  • Participants
  • Parent commits c25bb0f

Comments (0)

Files changed (2)

File docs/index.rst

 layered stacking model (a.k.a. nested contexts).
 
 For most functions and many classes, ``options``
-is overkill and not recommended.
+is overkill.
 Python's already-flexible function arguments, ``*args``,
 ``**kwargs``, and inheritance patterns are elegant and sufficient
 for 99.9% of all development situations.
 ``options``
-is for the other 0.1%: 
+is for the other 0.1%:
 
-  * highly functional classes, 
-  * with many different features and options, 
+  * highly functional classes,
+  * with many different features and options,
   * which might be adjusted or overriden at any time,
   * yet that need "reasonable" or "intelligent" defaults, and
   * that yearn for a simple, unobtrusive API.
 For more backstory, see `this StackOverflow.com discussion of how to combat "configuration sprawl"
 <http://stackoverflow.com/questions/11702437/where-to-keep-options-values-paths-to-important-files-etc/11703813#11703813>`_.
 For examples of ``options``
-in use, see `say <https://pypi.python.org/pypi/say>`_ and `show <https://pypi.python.org/pypi/show>`_. (If you're using ``options`` in your own package, 
+in use, see `say <https://pypi.python.org/pypi/say>`_ and `show <https://pypi.python.org/pypi/show>`_. (If you're using ``options`` in your own package,
 `drop me a line <mailto:jonathan.eunice@gmail.com>`_!)
 
 Usage
 =====
 
-In a typical use, your highly-functional 
+In a typical use of ``options``, your highly-functional
 class defines default option values. Subclasses
 can add, remove, or override options. Instances
 use class defaults, but they can be overridden when each instance
             color  = kwargs.get('color',  self.color)
             height = kwargs.get('height', self.height)
             width  = kwargs.get('width',  self.width)
-            print "color='{0}', width={1}, name='{2}', height={3}".format(color, width, name, height)
+            print "color={0!r}, width={1}, name={2!r}, height={3}".format(color, width, name, height)
 
 One problem here is that we broke apart the values provided to
 ``__init__()`` into separate instance variables, now we need to
             color  = color  or self.color
             height = height or self.height
             width  = width  or self.width
-            print "color='{0}', width={1}, name='{2}', height={3}".format(color, width, name, height)
+            print "color={0!r}, width={1}, name={2!r}, height={3}".format(color, width, name, height)
 
 If we add just a few more instance variables, we have the `Mr. Creosote
-<http://en.wikipedia.org/wiki/Mr_Creosote>`_ of class design on our hands. Every
-possible setting has to be managed in every method. It's neither elegant nor
-scalable. Things get even worse if we want to set default values for all shapes in the
+<http://en.wikipedia.org/wiki/Mr_Creosote>`_ of class design on our hands. For
+every instance variable that might be overridden in a method call, that method
+needs one line of code to decide whether the override is, in fact, in effect.
+Suddenly dealing with parameters starts to be a full-time job, as every possible
+setting has to be managed in every method. That's neither elegant nor scalable.
+
+Things get even worse if we want to change the default value for all shapes in the
 class. We have to rework every method that uses values, the ``__init__`` method,
 *et cetera*. We've entered "just one more wafer-thin mint..." territory.
 

File options/core.py

                 child[key] = value
         return child
 
+    def parent(self, new_base):
+        raise ValueError("Cannot change parent of base Options")
+
     def magic(self, **kwargs):
         """
         Set some options as having 'magical' update properties. In a sense, this
                 child[key] = value
         return child
 
+    def parent(self, new_base):
+        """
+        Rebase the mapping (change its parent). Useful for implementing
+        "styles"
+        """
+        raise NotImplementedError()
+
     def set(self, **kwargs):
         newopts = self._process(self, kwargs)
         for k, v in newopts.items():