pyloader 0.1.6

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/