doc/build/namespaces.rst - third_party/mako - Git at Google

 .. _namespaces_toplevel:

 ==========
 Namespaces
 ==========

 Namespaces are used to organize groups of defs into
 categories, and also to "import" defs from other files.

 If the file ``components.html`` defines these two defs:

 .. sourcecode:: mako

     ## components.html
     <%def name="comp1()">
         this is comp1
     </%def>

     <%def name="comp2(x)">
         this is comp2, x is ${x}
     </%def>

 you can make another file, for example ``index.html``, that
 pulls those two defs into a namespace called ``comp``:

 .. sourcecode:: mako

     ## index.html
     <%namespace name="comp" file="components.html"/>

     Here's comp1:  ${comp.comp1()}
     Here's comp2:  ${comp.comp2(x=5)}

 The ``comp`` variable above is an instance of
 :class:`.Namespace`, a **proxy object** which delivers
 method calls to the underlying template callable using the
 current context.

 ``<%namespace>`` also provides an ``import`` attribute which can
 be used to pull the names into the local namespace, removing the
 need to call it via the "``.``" operator. When ``import`` is used, the
 ``name`` attribute is optional.

 .. sourcecode:: mako

     <%namespace file="components.html" import="comp1, comp2"/>

     Heres comp1:  ${comp1()}
     Heres comp2:  ${comp2(x=5)}

 ``import`` also supports the "``*``" operator:

 .. sourcecode:: mako

     <%namespace file="components.html" import="*"/>

     Heres comp1:  ${comp1()}
     Heres comp2:  ${comp2(x=5)}

 The names imported by the ``import`` attribute take precedence
 over any names that exist within the current context.

 .. note:: In current versions of Mako, usage of ``import='*'`` is
    known to decrease performance of the template. This will be
    fixed in a future release.

 The ``file`` argument allows expressions -- if looking for
 context variables, the ``context`` must be named explicitly:

 .. sourcecode:: mako

     <%namespace name="dyn" file="${context['namespace_name']}"/>

 Ways to Call Namespaces
 =======================

 There are essentially four ways to call a function from a
 namespace.

 The "expression" format, as described previously. Namespaces are
 just Python objects with functions on them, and can be used in
 expressions like any other function:

 .. sourcecode:: mako

     ${mynamespace.somefunction('some arg1', 'some arg2', arg3='some arg3', arg4='some arg4')}

 Synonymous with the "expression" format is the "custom tag"
 format, when a "closed" tag is used. This format, introduced in
 Mako 0.2.3, allows the usage of a "custom" Mako tag, with the
 function arguments passed in using named attributes:

 .. sourcecode:: mako

     <%mynamespace:somefunction arg1="some arg1" arg2="some arg2" arg3="some arg3" arg4="some arg4"/>

 When using tags, the values of the arguments are taken as
 literal strings by default. To embed Python expressions as
 arguments, use the embedded expression format:

 .. sourcecode:: mako

     <%mynamespace:somefunction arg1="${someobject.format()}" arg2="${somedef(5, 12)}"/>

 The "custom tag" format is intended mainly for namespace
 functions which recognize body content, which in Mako is known
 as a "def with embedded content":

 .. sourcecode:: mako

     <%mynamespace:somefunction arg1="some argument" args="x, y">
         Some record: ${x}, ${y}
     </%mynamespace:somefunction>

 The "classic" way to call defs with embedded content is the ``<%call>`` tag:

 .. sourcecode:: mako

     <%call expr="mynamespace.somefunction(arg1='some argument')" args="x, y">
         Some record: ${x}, ${y}
     </%call>

 For information on how to construct defs that embed content from
 the caller, see :ref:`defs_with_content`.

 .. _namespaces_python_modules:

 Namespaces from Regular Python Modules
 ======================================

 Namespaces can also import regular Python functions from
 modules. These callables need to take at least one argument,
 ``context``, an instance of :class:`.Context`. A module file
 ``some/module.py`` might contain the callable:

 .. sourcecode:: python

     def my_tag(context):
         context.write("hello world")
         return ''

 A template can use this module via:

 .. sourcecode:: mako

     <%namespace name="hw" module="some.module"/>

     ${hw.my_tag()}

 Note that the ``context`` argument is not needed in the call;
 the :class:`.Namespace` tag creates a locally-scoped callable which
 takes care of it. The ``return ''`` is so that the def does not
 dump a ``None`` into the output stream -- the return value of any
 def is rendered after the def completes, in addition to whatever
 was passed to :meth:`.Context.write` within its body.

 If your def is to be called in an "embedded content" context,
 that is as described in :ref:`defs_with_content`, you should use
 the :func:`.supports_caller` decorator, which will ensure that Mako
 will ensure the correct "caller" variable is available when your
 def is called, supporting embedded content:

 .. sourcecode:: python

     from mako.runtime import supports_caller

     @supports_caller
     def my_tag(context):
         context.write("<div>")
         context['caller'].body()
         context.write("</div>")
         return ''

 Capturing of output is available as well, using the
 outside-of-templates version of the :func:`.capture` function,
 which accepts the "context" as its first argument:

 .. sourcecode:: python

     from mako.runtime import supports_caller, capture

     @supports_caller
     def my_tag(context):
         return "<div>%s</div>" % \
                 capture(context, context['caller'].body, x="foo", y="bar")

 Declaring Defs in Namespaces
 ============================

 The ``<%namespace>`` tag supports the definition of ``<%def>``\ s
 directly inside the tag. These defs become part of the namespace
 like any other function, and will override the definitions
 pulled in from a remote template or module:

 .. sourcecode:: mako

     ## define a namespace
     <%namespace name="stuff">
         <%def name="comp1()">
             comp1
         </%def>
     </%namespace>

     ## then call it
     ${stuff.comp1()}

 .. _namespaces_body:

 The ``body()`` Method
 =====================

 Every namespace that is generated from a template contains a
 method called ``body()``. This method corresponds to the main
 body of the template, and plays its most important roles when
 using inheritance relationships as well as
 def-calls-with-content.

 Since the ``body()`` method is available from a namespace just
 like all the other defs defined in a template, what happens if
 you send arguments to it? By default, the ``body()`` method
 accepts no positional arguments, and for usefulness in
 inheritance scenarios will by default dump all keyword arguments
 into a dictionary called ``pageargs``. But if you actually want
 to get at the keyword arguments, Mako recommends you define your
 own argument signature explicitly. You do this via using the
 ``<%page>`` tag:

 .. sourcecode:: mako

     <%page args="x, y, someval=8, scope='foo', **kwargs"/>

 A template which defines the above signature requires that the
 variables ``x`` and ``y`` are defined, defines default values
 for ``someval`` and ``scope``, and sets up ``**kwargs`` to
 receive all other keyword arguments. If ``**kwargs`` or similar
 is not present, the argument ``**pageargs`` gets tacked on by
 Mako. When the template is called as a top-level template (i.e.
 via :meth:`~.Template.render`) or via the ``<%include>`` tag, the
 values for these arguments will be pulled from the ``Context``.
 In all other cases, i.e. via calling the ``body()`` method, the
 arguments are taken as ordinary arguments from the method call.
 So above, the body might be called as:

 .. sourcecode:: mako

     ${self.body(5, y=10, someval=15, delta=7)}

 The :class:`.Context` object also supplies a :attr:`~.Context.kwargs`
 accessor, for cases when you'd like to pass along the top level context
 arguments to a ``body()`` callable:

 .. sourcecode:: mako

     ${next.body(**context.kwargs)}

 The usefulness of calls like the above become more apparent when
 one works with inheriting templates. For more information on
 this, as well as the meanings of the names ``self`` and
 ``next``, see :ref:`inheritance_toplevel`.

 .. _namespaces_builtin:

 Built-in Namespaces
 ===================

 The namespace is so great that Mako gives your template one (or
 two) for free. The names of these namespaces are ``local`` and
 ``self``. Other built-in namespaces include ``parent`` and
 ``next``, which are optional and are described in
 :ref:`inheritance_toplevel`.

 .. _namespace_local:

 ``local``
 ---------

 The ``local`` namespace is basically the namespace for the
 currently executing template. This means that all of the top
 level defs defined in your template, as well as your template's
 ``body()`` function, are also available off of the ``local``
 namespace.

 The ``local`` namespace is also where properties like ``uri``,
 ``filename``, and ``module`` and the ``get_namespace`` method
 can be particularly useful.

 .. _namespace_self:

 ``self``
 --------

 The ``self`` namespace, in the case of a template that does not
 use inheritance, is synonymous with ``local``. If inheritance is
 used, then ``self`` references the topmost template in the
 inheritance chain, where it is most useful for providing the
 ultimate form of various "method" calls which may have been
 overridden at various points in an inheritance chain. See
 :ref:`inheritance_toplevel`.

 Inheritable Namespaces
 ======================

 The ``<%namespace>`` tag includes an optional attribute
 ``inheritable="True"``, which will cause the namespace to be
 attached to the ``self`` namespace. Since ``self`` is globally
 available throughout an inheritance chain (described in the next
 section), all the templates in an inheritance chain can get at
 the namespace imported in a super-template via ``self``.

 .. sourcecode:: mako

     ## base.html
     <%namespace name="foo" file="foo.html" inheritable="True"/>

     ${next.body()}

     ## somefile.html
     <%inherit file="base.html"/>

     ${self.foo.bar()}

 This allows a super-template to load a whole bunch of namespaces
 that its inheriting templates can get to, without them having to
 explicitly load those namespaces themselves.

 The ``import="*"`` part of the ``<%namespace>`` tag doesn't yet
 interact with the ``inheritable`` flag, so currently you have to
 use the explicit namespace name off of ``self``, followed by the
 desired function name. But more on this in a future release.

 Namespace API Usage Example - Static Dependencies
 ==================================================

 The ``<%namespace>`` tag at runtime produces an instance of
 :class:`.Namespace`.   Programmatic access of :class:`.Namespace` can be used
 to build various kinds of scaffolding in templates and between templates.

 A common request is the ability for a particular template to declare
 "static includes" - meaning, the usage of a particular set of defs requires
 that certain Javascript/CSS files are present.   Using :class:`.Namespace` as the
 object that holds together the various templates present, we can build a variety
 of such schemes.   In particular, the :class:`.Context` has a ``namespaces``
 attribute, which is a dictionary of all :class:`.Namespace` objects declared.
 Iterating the values of this dictionary will provide a :class:`.Namespace`
 object for each time the ``<%namespace>`` tag was used, anywhere within the
 inheritance chain.


 .. _namespace_attr_for_includes:

 Version One - Use :attr:`.Namespace.attr`
 -----------------------------------------

 The :attr:`.Namespace.attr` attribute allows us to locate any variables declared
 in the ``<%! %>`` of a template.

 .. sourcecode:: mako

     ## base.mako
     ## base-most template, renders layout etc.
     <html>
     <head>
     ## traverse through all namespaces present,
     ## look for an attribute named 'includes'
     % for ns in context.namespaces.values():
         % for incl in getattr(ns.attr, 'includes', []):
             ${incl}
         % endfor
     % endfor
     </head>
     <body>
     ${next.body()}
     </body
     </html>

     ## library.mako
     ## library functions.
     <%!
         includes = [
             '<link rel="stylesheet" type="text/css" href="mystyle.css"/>',
             '<script type="text/javascript" src="functions.js"></script>'
         ]
     %>

     <%def name="mytag()">
         <form>
             ${caller.body()}
         </form>
     </%def>

     ## index.mako
     ## calling template.
     <%inherit file="base.mako"/>
     <%namespace name="foo" file="library.mako"/>

     <%foo:mytag>
         a form
     </%foo:mytag>


 Above, the file ``library.mako`` declares an attribute ``includes`` inside its global ``<%! %>`` section.
 ``index.mako`` includes this template using the ``<%namespace>`` tag.  The base template ``base.mako``, which is the inherited parent of ``index.mako`` and is reponsible for layout, then locates this attribute and iterates through its contents to produce the includes that are specific to ``library.mako``.

 Version Two - Use a specific named def
 -----------------------------------------

 In this version, we put the includes into a ``<%def>`` that
 follows a naming convention.

 .. sourcecode:: mako

     ## base.mako
     ## base-most template, renders layout etc.
     <html>
     <head>
     ## traverse through all namespaces present,
     ## look for a %def named 'includes'
     % for ns in context.namespaces.values():
         % if hasattr(ns, 'includes'):
             ${ns.includes()}
         % endif
     % endfor
     </head>
     <body>
     ${next.body()}
     </body
     </html>

     ## library.mako
     ## library functions.

     <%def name="includes()">
         <link rel="stylesheet" type="text/css" href="mystyle.css"/>
         <script type="text/javascript" src="functions.js"></script>
     </%def>

     <%def name="mytag()">
         <form>
             ${caller.body()}
         </form>
     </%def>


     ## index.mako
     ## calling template.
     <%inherit file="base.mako"/>
     <%namespace name="foo" file="library.mako"/>

     <%foo:mytag>
         a form
     </%foo:mytag>

 In this version, ``library.mako`` declares a ``<%def>`` named ``includes``.   The example works
 identically to the previous one, except that ``base.mako`` looks for defs named ``include``
 on each namespace it examines.

 API Reference
 =============

 .. autoclass:: mako.runtime.Namespace
     :show-inheritance:
     :members:

 .. autoclass:: mako.runtime.TemplateNamespace
     :show-inheritance:
     :members:

 .. autoclass:: mako.runtime.ModuleNamespace
     :show-inheritance:
     :members:

 .. autofunction:: mako.runtime.supports_caller

 .. autofunction:: mako.runtime.capture
	.. _namespaces_toplevel:

	==========
	Namespaces
	==========

	Namespaces are used to organize groups of defs into
	categories, and also to "import" defs from other files.

	If the file ``components.html`` defines these two defs:

	.. sourcecode:: mako

	## components.html
	<%def name="comp1()">
	this is comp1
	</%def>

	<%def name="comp2(x)">
	this is comp2, x is ${x}
	</%def>

	you can make another file, for example ``index.html``, that
	pulls those two defs into a namespace called ``comp``:

	.. sourcecode:: mako

	## index.html
	<%namespace name="comp" file="components.html"/>

	Here's comp1: ${comp.comp1()}
	Here's comp2: ${comp.comp2(x=5)}

	The ``comp`` variable above is an instance of
	:class:`.Namespace`, a proxy object which delivers
	method calls to the underlying template callable using the
	current context.

	``<%namespace>`` also provides an ``import`` attribute which can
	be used to pull the names into the local namespace, removing the
	need to call it via the "``.``" operator. When ``import`` is used, the
	``name`` attribute is optional.

	.. sourcecode:: mako

	<%namespace file="components.html" import="comp1, comp2"/>

	Heres comp1: ${comp1()}
	Heres comp2: ${comp2(x=5)}

	``import`` also supports the "``*``" operator:

	.. sourcecode:: mako

	<%namespace file="components.html" import="*"/>

	Heres comp1: ${comp1()}
	Heres comp2: ${comp2(x=5)}

	The names imported by the ``import`` attribute take precedence
	over any names that exist within the current context.

	.. note:: In current versions of Mako, usage of ``import='*'`` is
	known to decrease performance of the template. This will be
	fixed in a future release.

	The ``file`` argument allows expressions -- if looking for
	context variables, the ``context`` must be named explicitly:

	.. sourcecode:: mako

	<%namespace name="dyn" file="${context['namespace_name']}"/>

	Ways to Call Namespaces
	=======================

	There are essentially four ways to call a function from a
	namespace.

	The "expression" format, as described previously. Namespaces are
	just Python objects with functions on them, and can be used in
	expressions like any other function:

	.. sourcecode:: mako

	${mynamespace.somefunction('some arg1', 'some arg2', arg3='some arg3', arg4='some arg4')}

	Synonymous with the "expression" format is the "custom tag"
	format, when a "closed" tag is used. This format, introduced in
	Mako 0.2.3, allows the usage of a "custom" Mako tag, with the
	function arguments passed in using named attributes:

	.. sourcecode:: mako

	<%mynamespace:somefunction arg1="some arg1" arg2="some arg2" arg3="some arg3" arg4="some arg4"/>

	When using tags, the values of the arguments are taken as
	literal strings by default. To embed Python expressions as
	arguments, use the embedded expression format:

	.. sourcecode:: mako

	<%mynamespace:somefunction arg1="${someobject.format()}" arg2="${somedef(5, 12)}"/>

	The "custom tag" format is intended mainly for namespace
	functions which recognize body content, which in Mako is known
	as a "def with embedded content":

	.. sourcecode:: mako

	<%mynamespace:somefunction arg1="some argument" args="x, y">
	Some record: ${x}, ${y}
	</%mynamespace:somefunction>

	The "classic" way to call defs with embedded content is the ``<%call>`` tag:

	.. sourcecode:: mako

	<%call expr="mynamespace.somefunction(arg1='some argument')" args="x, y">
	Some record: ${x}, ${y}
	</%call>

	For information on how to construct defs that embed content from
	the caller, see :ref:`defs_with_content`.

	.. _namespaces_python_modules:

	Namespaces from Regular Python Modules
	======================================

	Namespaces can also import regular Python functions from
	modules. These callables need to take at least one argument,
	``context``, an instance of :class:`.Context`. A module file
	``some/module.py`` might contain the callable:

	.. sourcecode:: python

	def my_tag(context):
	context.write("hello world")
	return ''

	A template can use this module via:

	.. sourcecode:: mako

	<%namespace name="hw" module="some.module"/>

	${hw.my_tag()}

	Note that the ``context`` argument is not needed in the call;
	the :class:`.Namespace` tag creates a locally-scoped callable which
	takes care of it. The ``return ''`` is so that the def does not
	dump a ``None`` into the output stream -- the return value of any
	def is rendered after the def completes, in addition to whatever
	was passed to :meth:`.Context.write` within its body.

	If your def is to be called in an "embedded content" context,
	that is as described in :ref:`defs_with_content`, you should use
	the :func:`.supports_caller` decorator, which will ensure that Mako
	will ensure the correct "caller" variable is available when your
	def is called, supporting embedded content:

	.. sourcecode:: python

	from mako.runtime import supports_caller

	@supports_caller
	def my_tag(context):
	context.write("<div>")
	context['caller'].body()
	context.write("</div>")
	return ''

	Capturing of output is available as well, using the
	outside-of-templates version of the :func:`.capture` function,
	which accepts the "context" as its first argument:

	.. sourcecode:: python

	from mako.runtime import supports_caller, capture

	@supports_caller
	def my_tag(context):
	return "<div>%s</div>" % \
	capture(context, context['caller'].body, x="foo", y="bar")

	Declaring Defs in Namespaces
	============================

	The ``<%namespace>`` tag supports the definition of ``<%def>``\ s
	directly inside the tag. These defs become part of the namespace
	like any other function, and will override the definitions
	pulled in from a remote template or module:

	.. sourcecode:: mako

	## define a namespace
	<%namespace name="stuff">
	<%def name="comp1()">
	comp1
	</%def>
	</%namespace>

	## then call it
	${stuff.comp1()}

	.. _namespaces_body:

	The ``body()`` Method
	=====================

	Every namespace that is generated from a template contains a
	method called ``body()``. This method corresponds to the main
	body of the template, and plays its most important roles when
	using inheritance relationships as well as
	def-calls-with-content.

	Since the ``body()`` method is available from a namespace just
	like all the other defs defined in a template, what happens if
	you send arguments to it? By default, the ``body()`` method
	accepts no positional arguments, and for usefulness in
	inheritance scenarios will by default dump all keyword arguments
	into a dictionary called ``pageargs``. But if you actually want
	to get at the keyword arguments, Mako recommends you define your
	own argument signature explicitly. You do this via using the
	``<%page>`` tag:

	.. sourcecode:: mako

	<%page args="x, y, someval=8, scope='foo', **kwargs"/>

	A template which defines the above signature requires that the
	variables ``x`` and ``y`` are defined, defines default values
	for ``someval`` and ``scope``, and sets up ``**kwargs`` to
	receive all other keyword arguments. If ``**kwargs`` or similar
	is not present, the argument ``**pageargs`` gets tacked on by
	Mako. When the template is called as a top-level template (i.e.
	via :meth:`~.Template.render`) or via the ``<%include>`` tag, the
	values for these arguments will be pulled from the ``Context``.
	In all other cases, i.e. via calling the ``body()`` method, the
	arguments are taken as ordinary arguments from the method call.
	So above, the body might be called as:

	.. sourcecode:: mako

	${self.body(5, y=10, someval=15, delta=7)}

	The :class:`.Context` object also supplies a :attr:`~.Context.kwargs`
	accessor, for cases when you'd like to pass along the top level context
	arguments to a ``body()`` callable:

	.. sourcecode:: mako

	${next.body(**context.kwargs)}

	The usefulness of calls like the above become more apparent when
	one works with inheriting templates. For more information on
	this, as well as the meanings of the names ``self`` and
	``next``, see :ref:`inheritance_toplevel`.

	.. _namespaces_builtin:

	Built-in Namespaces
	===================

	The namespace is so great that Mako gives your template one (or
	two) for free. The names of these namespaces are ``local`` and
	``self``. Other built-in namespaces include ``parent`` and
	``next``, which are optional and are described in
	:ref:`inheritance_toplevel`.

	.. _namespace_local:

	``local``
	---------

	The ``local`` namespace is basically the namespace for the
	currently executing template. This means that all of the top
	level defs defined in your template, as well as your template's
	``body()`` function, are also available off of the ``local``
	namespace.

	The ``local`` namespace is also where properties like ``uri``,
	``filename``, and ``module`` and the ``get_namespace`` method
	can be particularly useful.

	.. _namespace_self:

	``self``
	--------

	The ``self`` namespace, in the case of a template that does not
	use inheritance, is synonymous with ``local``. If inheritance is
	used, then ``self`` references the topmost template in the
	inheritance chain, where it is most useful for providing the
	ultimate form of various "method" calls which may have been
	overridden at various points in an inheritance chain. See
	:ref:`inheritance_toplevel`.

	Inheritable Namespaces
	======================

	The ``<%namespace>`` tag includes an optional attribute
	``inheritable="True"``, which will cause the namespace to be
	attached to the ``self`` namespace. Since ``self`` is globally
	available throughout an inheritance chain (described in the next
	section), all the templates in an inheritance chain can get at
	the namespace imported in a super-template via ``self``.

	.. sourcecode:: mako

	## base.html
	<%namespace name="foo" file="foo.html" inheritable="True"/>

	${next.body()}

	## somefile.html
	<%inherit file="base.html"/>

	${self.foo.bar()}

	This allows a super-template to load a whole bunch of namespaces
	that its inheriting templates can get to, without them having to
	explicitly load those namespaces themselves.

	The ``import="*"`` part of the ``<%namespace>`` tag doesn't yet
	interact with the ``inheritable`` flag, so currently you have to
	use the explicit namespace name off of ``self``, followed by the
	desired function name. But more on this in a future release.

	Namespace API Usage Example - Static Dependencies
	==================================================

	The ``<%namespace>`` tag at runtime produces an instance of
	:class:`.Namespace`. Programmatic access of :class:`.Namespace` can be used
	to build various kinds of scaffolding in templates and between templates.

	A common request is the ability for a particular template to declare
	"static includes" - meaning, the usage of a particular set of defs requires
	that certain Javascript/CSS files are present. Using :class:`.Namespace` as the
	object that holds together the various templates present, we can build a variety
	of such schemes. In particular, the :class:`.Context` has a ``namespaces``
	attribute, which is a dictionary of all :class:`.Namespace` objects declared.
	Iterating the values of this dictionary will provide a :class:`.Namespace`
	object for each time the ``<%namespace>`` tag was used, anywhere within the
	inheritance chain.


	.. _namespace_attr_for_includes:

	Version One - Use :attr:`.Namespace.attr`
	-----------------------------------------

	The :attr:`.Namespace.attr` attribute allows us to locate any variables declared
	in the ``<%! %>`` of a template.

	.. sourcecode:: mako

	## base.mako
	## base-most template, renders layout etc.
	<html>
	<head>
	## traverse through all namespaces present,
	## look for an attribute named 'includes'
	% for ns in context.namespaces.values():
	% for incl in getattr(ns.attr, 'includes', []):
	${incl}
	% endfor
	% endfor
	</head>
	<body>
	${next.body()}
	</body
	</html>

	## library.mako
	## library functions.
	<%!
	includes = [
	'<link rel="stylesheet" type="text/css" href="mystyle.css"/>',
	'<script type="text/javascript" src="functions.js"></script>'
	]
	%>

	<%def name="mytag()">
	<form>
	${caller.body()}
	</form>
	</%def>

	## index.mako
	## calling template.
	<%inherit file="base.mako"/>
	<%namespace name="foo" file="library.mako"/>

	<%foo:mytag>
	a form
	</%foo:mytag>


	Above, the file ``library.mako`` declares an attribute ``includes`` inside its global ``<%! %>`` section.
	``index.mako`` includes this template using the ``<%namespace>`` tag. The base template ``base.mako``, which is the inherited parent of ``index.mako`` and is reponsible for layout, then locates this attribute and iterates through its contents to produce the includes that are specific to ``library.mako``.

	Version Two - Use a specific named def
	-----------------------------------------

	In this version, we put the includes into a ``<%def>`` that
	follows a naming convention.

	.. sourcecode:: mako

	## base.mako
	## base-most template, renders layout etc.
	<html>
	<head>
	## traverse through all namespaces present,
	## look for a %def named 'includes'
	% for ns in context.namespaces.values():
	% if hasattr(ns, 'includes'):
	${ns.includes()}
	% endif
	% endfor
	</head>
	<body>
	${next.body()}
	</body
	</html>

	## library.mako
	## library functions.

	<%def name="includes()">
	<link rel="stylesheet" type="text/css" href="mystyle.css"/>
	<script type="text/javascript" src="functions.js"></script>
	</%def>

	<%def name="mytag()">
	<form>
	${caller.body()}
	</form>
	</%def>


	## index.mako
	## calling template.
	<%inherit file="base.mako"/>
	<%namespace name="foo" file="library.mako"/>

	<%foo:mytag>
	a form
	</%foo:mytag>

	In this version, ``library.mako`` declares a ``<%def>`` named ``includes``. The example works
	identically to the previous one, except that ``base.mako`` looks for defs named ``include``
	on each namespace it examines.

	API Reference
	=============

	.. autoclass:: mako.runtime.Namespace
	:show-inheritance:
	:members:

	.. autoclass:: mako.runtime.TemplateNamespace
	:show-inheritance:
	:members:

	.. autoclass:: mako.runtime.ModuleNamespace
	:show-inheritance:
	:members:

	.. autofunction:: mako.runtime.supports_caller

	.. autofunction:: mako.runtime.capture