Mercurial > hg > pyloader

annotate README.txt @ 47:2384ab3999b7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
get wrapper section
author Jeff Hammel <jhammel@mozilla.com>
date Wed, 08 Jun 2011 21:19:22 -0700
parents 0b2019d0af98
children c852ff04c940
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
0
6fa6d987b3af initial commit of pyloader
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
1 pyloader
6fa6d987b3af initial commit of pyloader
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
2 ===========
6fa6d987b3af initial commit of pyloader
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
3
7
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
4 Load python attributes from strings
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
5
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
6 JSON Format
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
7 -----------
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
8
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
9 pyloader uses a JSON-serializable format for the canonical
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
10 (serializable) form of python objects::
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
11
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
12 {'foo': # (arbitrary) object name,
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
13 {'args': ['positional', 'arguments'],
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
14 'kwargs': {'keyword': 'arguments},
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
15 'path': 'dotted.or.file.path:ObjectName'},
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
16 'bar': ... } # etc
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
17
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
18 Objects are instantiated like::
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
19
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
20 ObjectName(*args, **kwargs)
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
21
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
22 In the case that the object is not to be instantiated (e.g. a
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
23 standalone function, ``args`` and ``kwargs`` will either not be
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
24 present or will be None (``null`` in JSON).
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
25
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
26
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
27 INI Format
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
28 ----------
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
29
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
30 pyloader also features an INI format which is translated to the JSON
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
31 Format but adds a few convenience features. A simple object is
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
32 expressed as::
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
33
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
34 [foo:dotted.or.file.path:ObjectName]
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
35 . = positional, arguments
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
36 keyword = arguments
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
37
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
38 ``.`` expresses positional arguments which is a comma-separated
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
39 list. The remaining (key, value) pairs become keyword arguments. The
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
40 section name contains the object name (e.g. ``foo``) followed by a
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
41 ``:`` followed by a loading path. Like JSON, a dotted path or a file
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
42 path may be used. In addition, other (pluggable) loading paths are
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
43 available:
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
44
8
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
45 - override loader: you can use a section name like ``[foo:bar]`` to
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
46 override variables from the ``bar`` object with variables from
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
47 ``foo``::
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
48
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
49 [foo:bar]
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
50 . = cats, dogs
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
51 type = count
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
52
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
53 [bar:%(here)s/some/path.py:MyObject]
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
54 . = elephants
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
55 type = concatenate
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
56
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
57 The above results in a JSON blob for foo like::
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
58
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
59 {'foo': {'args': ['elephants', 'cats', 'dogs'],
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
60 'kwargs': {'type': 'concatenate'},
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
61 'path': '/location/of/ini/file/some/path.py:MyObject'}}
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
62
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
63 ``args`` is extended. ``kwargs`` will be overridden.
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
64
9
ff634cc2e62b unfinished sketch of an abstract factory
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
65 - wrappers: in addition to the override pattern, you can also wrap an
ff634cc2e62b unfinished sketch of an abstract factory
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
66 object::
ff634cc2e62b unfinished sketch of an abstract factory
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
67
ff634cc2e62b unfinished sketch of an abstract factory
Jeff Hammel <jhammel@mozilla.com>
parents: 8
diff changeset
68 [foo:bar:baz]
7
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
69
39
db095765807d update decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 9
diff changeset
70 This will create an object, ``foo`` which wraps the object ``baz`` in
db095765807d update decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 9
diff changeset
71 by the pattern given by ``bar``. In this case, ``bar`` is provided
db095765807d update decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 9
diff changeset
72 a special variable, `%(app)s`.
db095765807d update decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 9
diff changeset
73
db095765807d update decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 9
diff changeset
74 You can also do::
db095765807d update decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 9
diff changeset
75
db095765807d update decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 9
diff changeset
76 [foo:bar:hi,hello,x=1,y=2:%(here)/objects.py:MyClass]
db095765807d update decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 9
diff changeset
77
db095765807d update decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 9
diff changeset
78
7
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
79 In addition, .ini files may include other .ini files. This allows for
8
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
80 encapsulation of intent of specific .ini files::
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
81
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
82 [include:%(here)s/some/file.ini]
7
79676a48f6d8 begin porting and modernizing instructions from wsgiblob to pyloader
Jeff Hammel <jhammel@mozilla.com>
parents: 0
diff changeset
83
8
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
84 INI files have a few convenience variables:
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
85
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
86 - %(here)s : the location of the directory the .ini file lives in
40
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
87 - %(object)s : used for wrappers
8
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
88
4d3ea44fd813 further spec out
Jeff Hammel <jhammel@mozilla.com>
parents: 7
diff changeset
89 Additional variables may be provided by the consumer.
0
6fa6d987b3af initial commit of pyloader
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
90
40
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
91 Summary of .ini decorator syntax
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
92 --------------------------------
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
93
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
94 1. ``[foo:%(here)s/objects.py:MyClass]``: create object ``foo`` of type
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
95 ``MyClass`` using arguments given from the section
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
96
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
97 2. ``[foo:bar]``: create object ``foo`` using the pattern from section
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
98 ``bar`` but overriding any arguments in the ``bar`` section with
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
99 those from this section
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
100
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
101 3. ``[foo:bar:%(here)s/objects.py:MyClass]``: create object ``foo``
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
102 which is an instance of ``MyClass`` wrapped in the object created by
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
103 the ``bar`` pattern. ``bar`` is passed a special argument,
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
104 ``%(object)s`` which is the instance of the wrapped object (the
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
105 ``MyClass`` instance). Internally, the wrapped object is known by
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
106 the whole section name (``foo:bar:%(here)s/objects.py:MyClass``). The
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
107 arguments in this section apply to ``MyClass(...)``
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
108
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
109 4. ``[foo:bar:app=%(object)s,value=1:%(here)s/objects.py:MyClass]``:
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
110 the same as 3. but override the values in the ``bar`` section with
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
111 ``app=%(object)s`` and ``value=1``
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
112
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
113 * ``[name:path]``
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
114 * ``[name:decorator:path]``
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
115 * ``[name:decorator:overrides:path]``
0b2019d0af98 finalize (hopefully) decorator syntax
Jeff Hammel <jhammel@mozilla.com>
parents: 39
diff changeset
116
0
6fa6d987b3af initial commit of pyloader
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
117 ----
6fa6d987b3af initial commit of pyloader
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
118
6fa6d987b3af initial commit of pyloader
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
119 Jeff Hammel
6fa6d987b3af initial commit of pyloader
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
120 http://k0s.org/
6fa6d987b3af initial commit of pyloader
Jeff Hammel <jhammel@mozilla.com>
parents:
diff changeset
121