Commits

Jonathan Eunice committed c25bb0f

Updated docs.

Comments (0)

Files changed (5)

 is for the other 0.1%: 
 
   * highly functional classes, 
-  * with many different options, 
+  * 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.
 # The short X.Y version.
 version = '1.0'
 # The full version, including alpha/beta/rc tags.
-release = '1.0.7'
+release = '1.0.8'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 is for the other 0.1%: 
 
   * highly functional classes, 
-  * with many different options, 
+  * 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.
 <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, 
-drop me a line!)
+`drop me a line <mailto:jonathan.eunice@gmail.com>`_!)
 
 Usage
 =====
 they immediately fall back to their prior value (at whatever higher level it
 was last set).
 
-.. image:: https://pypip.in/d/options/badge.png
-    :target: https://crate.io/packages/options/
-    :align: center
+An Example
+==========
 
 Unfortunately, because this is a capability designed for high-end, edge-case
 situations, it's hard to demonstrate its virtues with
 we'd also define ``Shape.set()`` to transparently forward
 to ``Shape.options.set()`` for an even simpler resulting API.)
 
-The more options and settings a class has, the more unwieldy the class and
-instance variable approach becomes, and the more desirable the delegation
-alternative. Inheritance is a great software pattern for many kinds of data and
-program structures--but it's a bad, or at least incomplete,
-pattern for complex option and configuration
+The more options and settings a class has, the more unwieldy the
+class and instance variable approach becomes, and the more desirable
+the delegation alternative. Inheritance is a great software pattern
+for many kinds of data and program structures--but it's not a
+particularly good pattern for complex option and configuration
 handling.
 
 For richly-featured classes, ``options``'s delegation pattern is
     if is_tall(one):    # nope, not here!
         ...
 
-Full disclosure: Doing temporary settings took more class setup code
-than is shown above. Four lines of code, to be precise.
+Full disclosure: Doing temporary settings took slightly more class
+setup code than is shown above. Four lines of code, to be precise.
 
 As one final feature, consider "magical" parameters. Add the following
 code::
 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). 
+``options`` is not intened to replace every class's or method's
+parameter passing mechanisms--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
 single variable (say ``opts`` again) that the externally-facing methods will
 provide.
 
-For example, if ``options`` didn't provide the nice formatting function ``attrs``,
-we might have designed our own::
+For example, if ``options`` didn't provide the nice formatting
+function ``attrs``, we might have designed our own::
 
     def _attrs(self, opts):
         nicekeys = [ k for k in opts.keys() if not k.startswith('_') ]
 Define the ``__call__`` method, and you have a very nice analog of
 function calls.
 
-``options`` has broad utility, but it's not for every class or module. It best
-suits high-level front-end APIs that multiplex lots of potential functionality,
-and wish/need to do it in a clean/simple way. Classes for which the set of
-instance variables is small, or functions/methods for which the set of
-known/possible parameters is limited--these work just fine with classic Python
-calling conventions. For those, ``options`` is overkill. "Horses for courses."
+``options`` has broad utility, but it's not for every class or
+module. It best suits high-level front-end APIs that multiplex lots
+of potential functionality, and wish/need to do it in a clean/simple
+way. Classes for which the set of instance variables is small, or
+functions/methods for which the set of known/possible parameters
+is limited--these work just fine with classic Python calling
+conventions. For those, ``options`` is overkill. "Horses for courses."
 
 Setting and Unsetting
 =====================
 Any options set "further down" such as when an instance is created or a method
 called should set keys that were already-defined at the class level.
 
-However, there are cases where "extra" ``**kwargs`` values may be provided and
-make sense. Your object might be a very high level entry point, for example,
-representing very large buckets of functionality, with many options. Some of
-those options are relevant to the current instance, while others are intended as
-pass-throughs for lower-level modules/objects. This may seem a doubly rarefied
+However, there are cases where "extra" ``**kwargs`` values may be
+provided and make sense. Your object might be a very high level
+entry point, for example, representing very large buckets of
+functionality, with many options. Some of those options are relevant
+to the current instance, while others are intended as pass-throughs
+for lower-level modules/objects. This may seem a doubly rarefied
 case--and it is, relatively speaking. But `it does happen
-<https://pypi.python.org/pypi/show>`_--and when you need
-multi-level processing, it's really, really super amazingly handy to
-have it.
+<https://pypi.python.org/pypi/show>`_--and when you need multi-level
+processing, it's really, really super amazingly handy to have it.
 
-``options`` supports this in its core ``push()`` method by taking the values
-that are known to be part of the class's options, and deleting those from
-``kwargs``. Any values left over in the ``kwargs`` ``dict`` are either errors,
-or intended for other recipients.
+``options`` supports this in its core ``push()`` method by taking
+the values that are known to be part of the class's options, and
+deleting those from ``kwargs``. Any values left over in the ``kwargs``
+``dict`` are either errors, or intended for other recipients.
 
 As yet, there is no automatic check for leftovers.
 
-__version__ = '1.0.7'
+__version__ = '1.0.8'
     version=metadata['__version__'],
     author='Jonathan Eunice',
     author_email='jonathan.eunice@gmail.com',
-    description='Container for flexible class, instance, and function call options',
+    description='Simple, super-flexible options. Does magic upon request.',
     long_description=open('README.rst').read(),
     url='https://bitbucket.org/jeunice/options',
     packages=['options'],