# HG changeset patch
# User Jeff Hammel <jhammel@mozilla.com>
# Date 1306289529 25200
# Node ID 79676a48f6d8b305c6326634e59293c7345a46bf
# Parent  886009132409f5e019dc3452d702bcfb72a85839
begin porting and modernizing instructions from wsgiblob to pyloader

diff -r 886009132409 -r 79676a48f6d8 README.txt
--- a/README.txt	Thu May 12 08:23:10 2011 -0700
+++ b/README.txt	Tue May 24 19:12:09 2011 -0700
@@ -1,7 +1,52 @@
 pyloader
 ===========
 
-Load python attributes from a string
+Load python attributes from strings
+
+JSON Format
+-----------
+
+pyloader uses a JSON-serializable format for the canonical
+(serializable) form of python objects::
+
+ {'foo': # (arbitrary) object name,
+  {'args': ['positional', 'arguments'],
+   'kwargs': {'keyword': 'arguments},
+   'path': 'dotted.or.file.path:ObjectName'},
+  'bar': ... } # etc 
+
+Objects are instantiated like::
+
+ ObjectName(*args, **kwargs)
+
+In the case that the object is not to be instantiated (e.g. a
+standalone function, ``args`` and ``kwargs`` will either not be
+present or will be None (``null`` in JSON).
+
+
+INI Format
+----------
+
+pyloader also features an INI format which is translated to the JSON
+Format but adds a few convenience features.  A simple object is
+expressed as::
+
+ [foo:dotted.or.file.path:ObjectName]
+ . = positional, arguments
+ keyword = arguments
+
+``.`` expresses positional arguments which is a comma-separated
+list. The remaining (key, value) pairs become keyword arguments. The
+section name contains the object name (e.g. ``foo``) followed by a
+``:`` followed by a loading path.  Like JSON, a dotted path or a file
+path may be used. In addition, other (pluggable) loading paths are
+available:
+
+- override loader: [TODO]
+
+In addition, .ini files may include other .ini files.  This allows for
+encapsulation of intent of specific .ini files.
+
 
 ----