Python's already-flexible function arguments, ``*args``,
``**kwargs``, and inheritance patterns are elegant and sufficient
for 99.9% of all development situations.
-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+
-.. 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"
+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 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 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
+.. image:: https://pypip.in/d/options/badge.png
+ :target: https://crate.io/packages/options/
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.
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.
-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):