Commits

Jonathan Eunice  committed ea8ff33

Primarily doc tweaks.

  • Participants
  • Parent commits c07ce02

Comments (0)

Files changed (9)

 Change Log
 ==========
 
+1.0.7 (October 25, 2103)
+''''''''''''''''''''''''
+
+  * Mainly doc tweaks.
 
 1.0.4 - 1.0.6 (October 24, 2013)
 ''''''''''''''''''''''''''''''''
 code spreads through many individual methods. This is where
 ``options``'s delegation-based approach begins to shine.
 
-.. image:: http://d.pr/i/TFFh+
+.. image:: http://d.pr/i/6JI4+
     :align: center
 
 

File compare.pptx

Binary file modified.

File docs/CHANGES.rst

 Change Log
 ==========
 
+1.0.7 (October 25, 2103)
+''''''''''''''''''''''''
+
+  * Mainly doc tweaks.
 
 1.0.4 - 1.0.6 (October 24, 2013)
 ''''''''''''''''''''''''''''''''

File docs/conf.py

 # The short X.Y version.
 version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.6'
+release = '1.0.7'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

File docs/index.rst

 code spreads through many individual methods. This is where
 ``options``'s delegation-based approach begins to shine.
 
-.. image:: http://d.pr/i/TFFh+
+.. image:: http://d.pr/i/6JI4+
     :align: center
 
 For more backstory, see `this StackOverflow.com discussion of how to combat "configuration sprawl"
 Design Considerations
 =====================
 
+``options`` is not intened to replace every class's or method's 
+parameter
+passing mechanism--just the one or 
+few most highly-optioned ones that multiplex a package's functionality
+to a range of use cases. 
+These are generally the highest-level, most outward-facing classes/objects.
+They will generally have at least five configuration
+variables (e.g. kwargs used to create, configure, and define 
+each instance). 
+
 In general, classes will define a set of methods that are "outwards
 facing"--methods called by external code when consuming the class's
 functionality. Those methods should generally expose their options through
 Choosing Option Names
 =====================
 
-You can choose pretty much any option name that is a legitimate Python
-keyword argument. The exceptions: Names that are already defined by
-methods of ``Options`` or ``OptionsChain``. These are mapping-style
-objects, so many of the method names of ``dict`` such as ``items``,
-``values``, ``get``, and ``setdefault`` are off-limits. If you try
-to define options with verboten names, a ``BadOptionName`` exception
-will be raised. This will save you grief down the road.
+You can choose pretty much any option name that is a legitimate
+Python keyword argument. The exceptions: Names that are already
+defined by methods of ``Options`` or ``OptionsChain``. To wit:
+``add``, ``addflat``, ``clear``, ``copy``, ``fromkeys``, ``get``,
+``items``, ``iteritems``, ``iterkeys``, ``itervalues``, ``keys``,
+``magic``, ``magical``, ``new_child``, ``parents``, ``pop``,
+``popitem``, ``push``, ``read``, ``set``, ``setdefault``, ``update``,
+``values``, and ``write`` are off-limits.
+
+If you try to define options with verboten names, a ``BadOptionName``
+exception will be raised. This will save you grief down the road;
+getting back a wrong thing at runtime is vastly harder to debug
+than fielding an early exception.
 
 Related Work
 ============
    `@jeunice on Twitter <http://twitter.com/jeunice>`_
    welcomes your comments and suggestions.
 
-Recent Changes
-==============
 
 Installation
 ============

File options/chainstuf.py

 
 
 class chainstuf(ChainMap):
+
     """
     A stuf-like surfacing of the ChainMap collection
     (multi-layer dict) introduced in Python 3. Uses a
     workalike replacement under Python 2.
     """
+
     def __init__(self, *maps):
         ChainMap.__init__(self, *maps)
 

File options/core.py

     """
     pass
 
+
 def attrs(m, first=[], underscores=False):
     """
     Given a mapping m, return a string listing its values in a
         # still exists in PyPy 2.1 with stuf 0.9.12 in Sept 2013. Patch
         # retained.)
 
-
     def set(self, **kwargs):
         # To set values at the base options level, create a temporary next level,
         # which will have the magical option interpretation. Then copy the resulting

File options/version.py

-__version__ = '1.0.6'
+__version__ = '1.0.7'