/usr/share/pyshared/martian/README.txt is in python-martian 0.14-0ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 | Martian tutorial
****************
Introduction
============
"There was so much to grok, so little to grok from." -- Stranger in a
Strange Land, by Robert A. Heinlein
Martian provides infrastructure for declarative configuration of
Python code. Martian is especially useful for the construction of
frameworks that need to provide a flexible plugin
infrastructure. Martian doesn't actually provide infrastructure for
plugin registries (except for itself). Many frameworks have their own
systems for this, and if you need a generic one, you might want to
consider ``zope.component``. Martian just allows you to make the
registration of plugins less verbose.
You can see Martian as doing something that you can also solve with
metaclasses, with the following advantages:
* the developer of the framework doesn't have to write a lot of ad-hoc
metaclasses anymore; instead we offer an infrastructure to make life
easier.
* configuration doesn't need to happen at import time, but can happen at
program startup time. This also makes configuration more tractable for
a developer.
* we don't bother the developer that *uses* the framework with the
surprising behavior that metaclasses sometimes bring. The classes
the user has to deal with are normal classes.
Why is this package named ``martian``? In the novel "Stranger in a
Strange Land", the verb *grok* is introduced:
Grok means to understand so thoroughly that the observer becomes a
part of the observed -- to merge, blend, intermarry, lose identity
in group experience.
In the context of this package, "grokking" stands for the process of
deducing declarative configuration actions from Python code. In the
novel, grokking is originally a concept that comes from the planet
Mars. Martians *grok*. Since this package helps you grok code, it's
called Martian.
Martian provides a framework that allows configuration to be expressed
in declarative Python code. These declarations can often be deduced
from the structure of the code itself. The idea is to make these
declarations so minimal and easy to read that even extensive
configuration does not overly burden the programmers working with the
code.
The ``martian`` package is a spin-off from the `Grok project`_, in the
context of which this codebase was first developed. While Grok uses
it, the code is completely independent of Grok.
.. _`Grok project`: http://grok.zope.org
Motivation
==========
"Deducing declarative configuration actions from Python code" - that
sounds very abstract. What does it actually mean? What is
configuration? What is declarative configuration? In order to explain
this, we'll first take a look at configuration.
Larger frameworks often offer a lot of points where you can modify
their behavior: ways to combine its own components with components you
provide yourself to build a larger application. A framework offers
points where it can be *configured* with plugin code. When you plug
some code into a plugin point, it results in the updating of some
registry somewhere with the new plugin. When the framework uses a
plugin, it will first look it up in the registry. The action of
registering some component into a registry can be called
*configuration*.
Let's look at an example framework that offers a plugin point. We
introduce a very simple framework for plugging in different template
languages, where each template language uses its own extension. You
can then supply the framework with the template body and the template
extension and some data, and render the template.
Let's look at the framework::
>>> import string
>>> class templating(FakeModule):
...
... class InterpolationTemplate(object):
... "Use %(foo)s for dictionary interpolation."
... def __init__(self, text):
... self.text = text
... def render(self, **kw):
... return self.text % kw
...
... class TemplateStringTemplate(object):
... "PEP 292 string substitutions."
... def __init__(self, text):
... self.template = string.Template(text)
... def render(self, **kw):
... return self.template.substitute(**kw)
...
... # the registry, we plug in the two templating systems right away
... extension_handlers = { '.txt': InterpolationTemplate,
... '.tmpl': TemplateStringTemplate }
...
... def render(data, extension, **kw):
... """Render the template at filepath with arguments.
...
... data - the data in the file
... extension - the extension of the file
... keyword arguments - variables to interpolate
...
... In a real framework you could pass in the file path instead of
... data and extension, but we don't want to open files in our
... example.
...
... Returns the rendered template
... """
... template = extension_handlers[extension](data)
... return template.render(**kw)
Since normally we cannot create modules in a doctest, we have emulated
the ``templating`` Python module using the ``FakeModule``
class. Whenever you see ``FakeModule`` subclasses, imagine you're
looking at a module definition in a ``.py`` file. Now that we have
defined a module ``templating``, we also need to be able to import
it. Fake modules are always placed automatically into the
``martiantest.fake`` namespace so you can import them from there::
>>> from martiantest.fake import templating
Now let's try the ``render`` function for the registered template
types, to demonstrate that our framework works::
>>> templating.render('Hello %(name)s!', '.txt', name="world")
'Hello world!'
>>> templating.render('Hello ${name}!', '.tmpl', name="universe")
'Hello universe!'
File extensions that we do not recognize cause a ``KeyError`` to be
raised::
>>> templating.render('Hello', '.silly', name="test")
Traceback (most recent call last):
...
KeyError: '.silly'
We now want to plug into this filehandler framework and provide a
handler for ``.silly`` files. Since we are writing a plugin, we cannot
change the ``templating`` module directly. Let's write an extension
module instead::
>>> class sillytemplating(FakeModule):
... class SillyTemplate(object):
... "Replace {key} with dictionary values."
... def __init__(self, text):
... self.text = text
... def render(self, **kw):
... text = self.text
... for key, value in kw.items():
... text = text.replace('{%s}' % key, value)
... return text
...
... templating.extension_handlers['.silly'] = SillyTemplate
>>> from martiantest.fake import sillytemplating
In the extension module, we manipulate the ``extension_handlers``
dictionary of the ``templating`` module (in normal code we'd need to
import it first), and plug in our own function. ``.silly`` handling
works now::
>>> templating.render('Hello {name}!', '.silly', name="galaxy")
'Hello galaxy!'
Above we plug into our ``extension_handler`` registry using Python
code. Using separate code to manually hook components into registries
can get rather cumbersome - each time you write a plugin, you also
need to remember you need to register it.
Doing template registration in Python code also poses a maintenance
risk. It is tempting to start doing fancy things in Python code such
as conditional configuration, making the configuration state of a
program hard to understand. Another problem is that doing
configuration at import time can also lead to unwanted side effects
during import, as well as ordering problems, where you want to import
something that really needs configuration state in another module that
is imported later. Finally, it can also make code harder to test, as
configuration is loaded always when you import the module, even if in
your test perhaps you don't want it to be.
Martian provides a framework that allows configuration to be expressed
in declarative Python code. Martian is based on the realization that
what to configure where can often be deduced from the structure of
Python code itself, especially when it can be annotated with
additional declarations. The idea is to make it so easy to write and
register a plugin so that even extensive configuration does not overly
burden the developer.
Configuration actions are executed during a separate phase ("grok
time"), not at import time, which makes it easier to reason about and
easier to test.
Configuration the Martian Way
=============================
Let's now transform the above ``templating`` module and the
``sillytemplating`` module to use Martian. First we must recognize
that every template language is configured to work for a particular
extension. With Martian, we annotate the classes themselves with this
configuration information. Annotations happen using *directives*,
which look like function calls in the class body.
Let's create an ``extension`` directive that can take a single string
as an argument, the file extension to register the template class
for::
>>> import martian
>>> class extension(martian.Directive):
... scope = martian.CLASS
... store = martian.ONCE
... default = None
We also need a way to easily recognize all template classes. The normal
pattern for this in Martian is to use a base class, so let's define a
``Template`` base class::
>>> class Template(object):
... pass
We now have enough infrastructure to allow us to change the code to use
Martian style base class and annotations::
>>> class templating(FakeModule):
...
... class InterpolationTemplate(Template):
... "Use %(foo)s for dictionary interpolation."
... extension('.txt')
... def __init__(self, text):
... self.text = text
... def render(self, **kw):
... return self.text % kw
...
... class TemplateStringTemplate(Template):
... "PEP 292 string substitutions."
... extension('.tmpl')
... def __init__(self, text):
... self.template = string.Template(text)
... def render(self, **kw):
... return self.template.substitute(**kw)
...
... # the registry, empty to start with
... extension_handlers = {}
...
... def render(data, extension, **kw):
... # this hasn't changed
... template = extension_handlers[extension](data)
... return template.render(**kw)
>>> from martiantest.fake import templating
As you can see, there have been very few changes:
* we made the template classes inherit from ``Template``.
* we use the ``extension`` directive in the template classes.
* we stopped pre-filling the ``extension_handlers`` dictionary.
So how do we fill the ``extension_handlers`` dictionary with the right
template languages? Now we can use Martian. We define a *grokker* for
``Template`` that registers the template classes in the
``extension_handlers`` registry::
>>> class meta(FakeModule):
... class TemplateGrokker(martian.ClassGrokker):
... martian.component(Template)
... martian.directive(extension)
... def execute(self, class_, extension, **kw):
... templating.extension_handlers[extension] = class_
... return True
>>> from martiantest.fake import meta
What does this do? A ``ClassGrokker`` has its ``execute`` method
called for subclasses of what's indicated by the ``martian.component``
directive. You can also declare what directives a ``ClassGrokker``
expects on this component by using ``martian.directive()`` (the
``directive`` directive!) one or more times.
The ``execute`` method takes the class to be grokked as the first
argument, and the values of the directives used will be passed in as
additional parameters into the ``execute`` method. The framework can
also pass along an arbitrary number of extra keyword arguments during
the grokking process, so we need to declare ``**kw`` to make sure we
can handle these.
All our grokkers will be collected in a special Martian-specific
registry::
>>> reg = martian.GrokkerRegistry()
We will need to make sure the system is aware of the
``TemplateGrokker`` defined in the ``meta`` module first, so let's
register it first. We can do this by simply grokking the ``meta``
module::
>>> reg.grok('meta', meta)
True
Because ``TemplateGrokker`` is now registered, our registry now knows
how to grok ``Template`` subclasses. Let's grok the ``templating``
module::
>>> reg.grok('templating', templating)
True
Let's try the ``render`` function of templating again, to demonstrate
we have successfully grokked the template classes::
>>> templating.render('Hello %(name)s!', '.txt', name="world")
'Hello world!'
>>> templating.render('Hello ${name}!', '.tmpl', name="universe")
'Hello universe!'
``.silly`` hasn't been registered yet::
>>> templating.render('Hello', '.silly', name="test")
Traceback (most recent call last):
...
KeyError: '.silly'
Let's now register ``.silly`` from an extension module::
>>> class sillytemplating(FakeModule):
... class SillyTemplate(Template):
... "Replace {key} with dictionary values."
... extension('.silly')
... def __init__(self, text):
... self.text = text
... def render(self, **kw):
... text = self.text
... for key, value in kw.items():
... text = text.replace('{%s}' % key, value)
... return text
>>> from martiantest.fake import sillytemplating
As you can see, the developer that uses the framework has no need
anymore to know about ``templating.extension_handlers``. Instead we can
simply grok the module to have ``SillyTemplate`` be register appropriately::
>>> reg.grok('sillytemplating', sillytemplating)
True
We can now use the ``.silly`` templating engine too::
>>> templating.render('Hello {name}!', '.silly', name="galaxy")
'Hello galaxy!'
Admittedly it is hard to demonstrate Martian well with a small example
like this. In the end we have actually written more code than in the
basic framework, after all. But even in this small example, the
``templating`` and ``sillytemplating`` module have become more
declarative in nature. The developer that uses the framework will not
need to know anymore about things like
``templating.extension_handlers`` or an API to register things
there. Instead the developer can registering a new template system
anywhere, as long as he subclasses from ``Template``, and as long as
his code is grokked by the system.
Finally note how Martian was used to define the ``TemplateGrokker`` as
well. In this way Martian can use itself to extend itself.
Grokking instances
==================
Above we've seen how you can grok classes. Martian also supplies a way
to grok instances. This is less common in typical frameworks, and has
the drawback that no class-level directives can be used, but can still
be useful.
Let's imagine a case where we have a zoo framework with an ``Animal``
class, and we want to track instances of it::
>>> class Animal(object):
... def __init__(self, name):
... self.name = name
>>> class zoo(FakeModule):
... horse = Animal('horse')
... chicken = Animal('chicken')
... elephant = Animal('elephant')
... lion = Animal('lion')
... animals = {}
>>> from martiantest.fake import zoo
We define an ``InstanceGrokker`` subclass to grok ``Animal`` instances::
>>> class meta(FakeModule):
... class AnimalGrokker(martian.InstanceGrokker):
... martian.component(Animal)
... def execute(self, instance, **kw):
... zoo.animals[instance.name] = instance
... return True
>>> from martiantest.fake import meta
Let's create a new registry with the ``AnimalGrokker`` in it::
>>> reg = martian.GrokkerRegistry()
>>> reg.grok('meta', meta)
True
We can now grok the ``zoo`` module::
>>> reg.grok('zoo', zoo)
True
The animals will now be in the ``animals`` dictionary::
>>> sorted(zoo.animals.items())
[('chicken', <Animal object at ...>),
('elephant', <Animal object at ...>),
('horse', <Animal object at ...>),
('lion', <Animal object at ...>)]
More information
================
For many more details and examples of more kinds of grokkers, please
see ``src/martian/core.txt``. For more information on directives see
``src/martian/directive.txt``.
|