pyloader
view README.txt @ 81:9203ca3a5182
comment
| author | Jeff Hammel <jhammel@mozilla.com> |
|---|---|
| date | Sat Jun 25 11:05:06 2011 -0700 (10 months ago) |
| parents | 0b2019d0af98 |
| children |
line source
1 pyloader
2 ===========
4 Load python attributes from strings
6 JSON Format
7 -----------
9 pyloader uses a JSON-serializable format for the canonical
10 (serializable) form of python objects::
12 {'foo': # (arbitrary) object name,
13 {'args': ['positional', 'arguments'],
14 'kwargs': {'keyword': 'arguments},
15 'path': 'dotted.or.file.path:ObjectName'},
16 'bar': ... } # etc
18 Objects are instantiated like::
20 ObjectName(*args, **kwargs)
22 In the case that the object is not to be instantiated (e.g. a
23 standalone function, ``args`` and ``kwargs`` will either not be
24 present or will be None (``null`` in JSON).
27 INI Format
28 ----------
30 pyloader also features an INI format which is translated to the JSON
31 Format but adds a few convenience features. A simple object is
32 expressed as::
34 [foo:dotted.or.file.path:ObjectName]
35 . = positional, arguments
36 keyword = arguments
38 ``.`` expresses positional arguments which is a comma-separated
39 list. The remaining (key, value) pairs become keyword arguments. The
40 section name contains the object name (e.g. ``foo``) followed by a
41 ``:`` followed by a loading path. Like JSON, a dotted path or a file
42 path may be used. In addition, other (pluggable) loading paths are
43 available:
45 - override loader: you can use a section name like ``[foo:bar]`` to
46 override variables from the ``bar`` object with variables from
47 ``foo``::
49 [foo:bar]
50 . = cats, dogs
51 type = count
53 [bar:%(here)s/some/path.py:MyObject]
54 . = elephants
55 type = concatenate
57 The above results in a JSON blob for foo like::
59 {'foo': {'args': ['elephants', 'cats', 'dogs'],
60 'kwargs': {'type': 'concatenate'},
61 'path': '/location/of/ini/file/some/path.py:MyObject'}}
63 ``args`` is extended. ``kwargs`` will be overridden.
65 - wrappers: in addition to the override pattern, you can also wrap an
66 object::
68 [foo:bar:baz]
70 This will create an object, ``foo`` which wraps the object ``baz`` in
71 by the pattern given by ``bar``. In this case, ``bar`` is provided
72 a special variable, `%(app)s`.
74 You can also do::
76 [foo:bar:hi,hello,x=1,y=2:%(here)/objects.py:MyClass]
79 In addition, .ini files may include other .ini files. This allows for
80 encapsulation of intent of specific .ini files::
82 [include:%(here)s/some/file.ini]
84 INI files have a few convenience variables:
86 - %(here)s : the location of the directory the .ini file lives in
87 - %(object)s : used for wrappers
89 Additional variables may be provided by the consumer.
91 Summary of .ini decorator syntax
92 --------------------------------
94 1. ``[foo:%(here)s/objects.py:MyClass]``: create object ``foo`` of type
95 ``MyClass`` using arguments given from the section
97 2. ``[foo:bar]``: create object ``foo`` using the pattern from section
98 ``bar`` but overriding any arguments in the ``bar`` section with
99 those from this section
101 3. ``[foo:bar:%(here)s/objects.py:MyClass]``: create object ``foo``
102 which is an instance of ``MyClass`` wrapped in the object created by
103 the ``bar`` pattern. ``bar`` is passed a special argument,
104 ``%(object)s`` which is the instance of the wrapped object (the
105 ``MyClass`` instance). Internally, the wrapped object is known by
106 the whole section name (``foo:bar:%(here)s/objects.py:MyClass``). The
107 arguments in this section apply to ``MyClass(...)``
109 4. ``[foo:bar:app=%(object)s,value=1:%(here)s/objects.py:MyClass]``:
110 the same as 3. but override the values in the ``bar`` section with
111 ``app=%(object)s`` and ``value=1``
113 Section Name Syntax
114 -------------------
116 - *[name:resource]* : create an object named *name* , where resource
117 is either a section name or a *path* as described in `JSON Format`_ .
118 In the case where *resouce* is another section name, the options
119 will overide the options given in the *resource* section and a new
120 object named *name* will be created. In the case where *section* is
121 a path, an object will be created as given by the *path* with the
122 given options.
123 - *[name:decorator:resource]* : create an object named *name* where
124 the object given by *resource* is passed to *decorator*. Overrides
125 and loading is as described for *[name:reource]* . An anonymous
126 object is created of the whole section name for the wrapped
127 object. So this form results in two sections for the `JSON Format`_ .
128 *decorator* is a section in the same namespace as *name*.
129 - *[name:decorator:overrides:resource]* : similar to
130 *[name:decorator:resource]* , but apply *overides* to the
131 *decorator* section. *overrides* is a string of the format
132 ``foo,bar,fleem=5``.
134 ----
136 Jeff Hammel
137 http://k0s.org/