Metadata-Version: 1.0
Name: pyloader
Version: 0.1.5
Summary: Load python attributes from a string
Home-page: http://k0s.org/hg/pyloader
Author: Jeff Hammel
Author-email: k0scist@gmail.com
License: MPL
Description: pyloader
        ===========
        
        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: you can use a section name like ``[foo:bar]`` to
          override variables from the ``bar`` object with variables from
          ``foo``::
        
           [foo:bar]
           . = cats, dogs
           type = count
        
           [bar:%(here)s/some/path.py:MyObject]
           . = elephants
           type = concatenate
        
          The above results in a JSON blob for foo like::
        
           {'foo': {'args': ['elephants', 'cats', 'dogs'],
                    'kwargs': {'type': 'concatenate'},
                    'path': '/location/of/ini/file/some/path.py:MyObject'}}
        
          ``args`` is extended. ``kwargs`` will be overridden.
        
        - wrappers: in addition to the override pattern, you can also wrap an
          object::
        
           [foo:bar:baz]
        
          This will create an object, ``foo`` which wraps the object ``baz`` in
          by the pattern given by ``bar``.  In this case, ``bar`` is provided
          a special variable, `%(app)s`.
        
          You can also do::
        
           [foo:bar:hi,hello,x=1,y=2:%(here)/objects.py:MyClass]
        
        
        In addition, .ini files may include other .ini files.  This allows for
        encapsulation of intent of specific .ini files::
        
           [include:%(here)s/some/file.ini]
        
        INI files have a few convenience variables:
        
        - %(here)s : the location of the directory the .ini file lives in
        - %(object)s : used for wrappers
        
        Additional variables may be provided by the consumer.
        
        Summary of .ini decorator syntax
        --------------------------------
        
        1. ``[foo:%(here)s/objects.py:MyClass]``: create object ``foo`` of type
           ``MyClass`` using arguments given from the section
        
        2. ``[foo:bar]``: create object ``foo`` using the pattern from section
           ``bar`` but overriding any arguments in the ``bar`` section with
           those from this section 
        
        3. ``[foo:bar:%(here)s/objects.py:MyClass]``: create object ``foo``
           which is an instance of ``MyClass`` wrapped in the object created by
           the ``bar`` pattern. ``bar`` is passed a special argument,
           ``%(object)s`` which is the instance of the wrapped object (the
           ``MyClass`` instance). Internally, the wrapped object is known by
           the whole section name (``foo:bar:%(here)s/objects.py:MyClass``). The 
           arguments in this section apply to ``MyClass(...)``
        
        4. ``[foo:bar:app=%(object)s,value=1:%(here)s/objects.py:MyClass]``:
           the same as 3. but override the values in the ``bar`` section with
           ``app=%(object)s`` and ``value=1``
        
        Section Name Syntax
        -------------------
        
        - *[name:resource]* : create an object named *name* , where resource
          is either a section name or a *path* as described in `JSON Format`_ .
          In the case where *resouce* is another section name, the options
          will overide the options given in the *resource* section and a new
          object named *name* will be created.  In the case where *section* is
          a path, an object will be created as given by the *path* with the
          given options.
        - *[name:decorator:resource]* : create an object named *name* where
          the object given by *resource* is passed to *decorator*. Overrides
          and loading is as described for *[name:reource]* . An anonymous
          object is created of the whole section name for the wrapped
          object. So this form results in two sections for the `JSON Format`_ .
          *decorator* is a section in the same namespace as *name*.
        - *[name:decorator:overrides:resource]* : similar to
          *[name:decorator:resource]* , but apply *overides* to the
          *decorator* section.  *overrides* is a string of the format
          ``foo,bar,fleem=5``.
        
        ----
        
        Jeff Hammel
        http://k0s.org/
        
        
Platform: UNKNOWN
