Commits

Jonathan Eunice  committed c07ce02

Updated docs.

  • Participants
  • Parent commits 0e64def

Comments (0)

Files changed (2)

 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%: 
 
-``options``
-is intended for the 0.1%: highly
-functional classes that have many different options, that
-aim for "reasonable" or "intelligent" defaults and
-behaviors, that allow users to override those defaults at any time, and yet that
-aim for a simple, unobtrusive API.
+  * highly functional classes, 
+  * with many different 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.
 
-In those cases, Python's simpler built-in, inheritance-based
-model leads to fairly complex code as non-trivial options and argument-management
+In those cases, Python's simpler built-in, inheritance-based model
+adds complexity as non-trivial options and argument-management
 code spreads through many individual methods. This is where
 ``options``'s delegation-based approach begins to shine.
 

File docs/index.rst

 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%: 
 
-``options``
-is intended for the 0.1%: highly
-functional classes that have many different options, that
-aim for "reasonable" or "intelligent" defaults and
-behaviors, that allow users to override those defaults at any time, and yet that
-aim for a simple, unobtrusive API.
+  * highly functional classes, 
+  * with many different 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.
 
-In those cases, Python's simpler built-in, inheritance-based
-model leads to fairly complex code as non-trivial options and argument-management
+In those cases, Python's simpler built-in, inheritance-based model
+adds complexity as non-trivial options and argument-management
 code spreads through many individual methods. This is where
 ``options``'s delegation-based approach begins to shine.
 
 .. image:: http://d.pr/i/TFFh+
     :align: center
 
-
-.. image:: https://pypip.in/d/options/badge.png
-    :target: https://crate.io/packages/options/
+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, 
+drop me a line!)
 
 Usage
 =====
 
-In a typical use, your class defines default option values. Subclasses
+In a typical use, 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
 is created. For any option an instance doesn't override, the class
 value, its class default applies (and so on, to its superclasses, if any).
 
 One step further, Python's ``with`` statement can be used to
-set option values for essentially arbitrary duration. As soon as the
+set option values for just a specific duration. As soon as the
 ``with`` block exists, the option values automagically fall back to
 what they were before the with block. (In general, if any option is unset,
 its value falls back to what it was in the next higher layer.)
 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
+
 Unfortunately, because this is a capability designed for high-end, edge-case
 situations, it's hard to demonstrate its virtues with
 simple code. But we'll give it a shot.
 handling.
 
 For richly-featured classes, ``options``'s delegation pattern is
-simpler. As the number of options grows, almost no additional
-code is required. More options
-impose no additional complexity and introduce no additional failure modes.
-Consolidating
-options into one place, and providing
-neat attribute-style access, keeps everything
+simpler. As the number of options grows, almost no additional code
+is required. More options impose no additional complexity and
+introduce no additional failure modes.  Consolidating options into
+one place, and providing neat attribute-style access, keeps everything
 tidy. We can add new options or methods with confidence::
 
     def is_tall(self, **kwargs):