Source

options / README.rst

Diff from to

File README.rst

 Subclassing
 ===========
 
-Subclasses may have a different set of options than the superclass. In this case,
-the subclass should ``add()`` to the superclass's options. This creates a layered
+Subclass options may differ from superclass options. Usually they will share
+many options, but some may be added, and others removed. To modify the set of
+available options, the subclass defines its options with the ``add()`` method to
+the superclass options. This creates a layered
 effect, just like ``push()`` for an instance. The difference is, ``push()`` does
 not allow new options (keys) to be defined; ``add()`` does. It is also possible to
 assign the special null object ``Prohibited``, which will disallow instances of the
         prefix = Prohibited,  # was available in superclass, but not here
         suffix = Prohibited,  # ditto
     )
+    
+Because some of the "additions" can be prohibitions (i.e. removing
+particular options from being set or used), this is"adding to" the superclass's
+options in the sense of "adding a layer onto" rather than strict "adding
+options."
 
-An alternative is to copy (or restart) the superclass's options. That suits cases
-where changes to the superclass's options should not effect the subclass's options.
+An alternative is to copy (or restate) the superclass's options. That suits
+cases where the subclass is highly independent, and where changes to the
+superclass's options should not effect the subclass's options.
 With ``add()``, they remain linked in the same way as instances and classes are.
 
 Flat Arguments
 
 Sometimes it's more elegant to provide some arguments as flat, sequential values
 rather than by keyword. In this case, use the ``addflat()`` method::
-
+    
     def __init__(self, *args, **kwargs):
         self.options = Quoter.options.push(kwargs)
-        self.options.addflat(args, ['prefix', 'suffix'])
+        if args:
+            self.options.addflat(args, ['prefix', 'suffix'])
         
-to consume optional ``prefix`` and ``suffix`` flat arguments.
+to consume optional ``prefix`` and ``suffix`` flat arguments. This makes the following
+equivalent::
+
+    q1 = Quoter('[', ']')
+    q2 = Quoter(prefix='[', suffix=']')
+
+As a design
+decision, an explicit ``addflat()`` method is provided not as much for Zen of
+Python reasons ("Explicit is better than implicit."), but because flat arguments
+are commonly combined with abbreviation/shorthand conventions, which may require
+some logic to implement. For example, if only a ``prefix`` is given as a flat
+argument, you meay want to use the same value to implicitly set the ``suffix``.
+To this end, addflat returns the set of keys that it consumed::
+
+        if args:
+            used = self.options.addflat(args, ['prefix', 'suffix'])
+            if 'suffix' not in used:
+                self.options.suffix = self.options.prefix
 
 Notes
 =====
    `classproperty <http://pypi.python.org/pypi/classproperty>`_, and `realproperty <http://pypi.python.org/pypi/rwproperty>`_.
    
  * Open question: Should "magic" parameter setters be allow to change
-   multiple options at once? Discovered use case for this: "Abbreviation"
+   multiple options at once? A use case for this: "Abbreviation"
    options that combine multiple changes into one compact option. These would
    probably not have stored values themselves. It would require setting the
    "dependent" option values via side-effect rather than functional return values.
    
+ * The author, `Jonathan Eunice <mailto:jonathan.eunice@gmail.com>`_ or
+   `@jeunice on Twitter <http://twitter.com/jeunice>`_
+   welcomes your comments and suggestions.
+
+Recent Changes
+==============
+
  * Commenced automated multi-version testing with
    `pytest <http://pypi.python.org/pypi/pytest>`_
    and `tox <http://pypi.python.org/pypi/tox>`_. Now
    
  * Versions subsequent to 0.200 require a late-model version of ``stuf`` to
    avoid a problem its earlier iterations had with file objects.
+   
+ * Now packaged as a package, not a set of modules. ``six`` module now required only for testing.
  
- * The author, `Jonathan Eunice <mailto:jonathan.eunice@gmail.com>`_ or
-   `@jeunice on Twitter <http://twitter.com/jeunice>`_
-   welcomes your comments and suggestions.
-
+ * API for ``push()`` and ``addflat()`` cleaned up to explicitly delink those methods.
+ 
 Installation
 ============