<commit_before>Namespaces
=============

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

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

    # components.html
    <%def name="comp1()">
        this is comp1
    </%def>
    
    <%def name="comp2()">
        this is comp2
    </%def>
    
You can make another file, for example `index.html`, that pulls those two components into a namespace called `comp`:

    # index.html
    <%namespace name="comp" file="components.html"/>
    
    Heres comp1:  ${comp.comp1()}
    Heres comp2:  ${comp.comp2()}

The `comp` variable above is an instance of `mako.runtime.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 ".".  When `import` is used, the `name` attribute is optional.

    <%namespace file="components.html" import="comp1, comp2"/>
    
    Heres comp1:  ${comp1()}
    Heres comp2:  ${comp2()}
    
`import` also supports the "*" operator:

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

    Heres comp1:  ${comp1()}
    Heres comp2:  ${comp2()}

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

### Namespaces from Regular Python Modules {@name=frommodules}

Namespaces can also import regular Python functions from modules.  These callables need to take at least one argument, `context`:

A module file `some/module.py` might contain the callable:

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

A template can use this module via:
    
    <%namespace name="hw" module="some.module"/>

    ${hw.my_tag()}
    
Note that the `context` argument is not needed in the call; the `namespace` tag creates a locally-scoped callable which takes care of it.

### Declaring defs in namespaces.

The `<%namespace>` tag supports the definition of `<%defs>` 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:
    
    # define a namespace
    <%namespace name="stuff">
        <%def name="comp1()">
            comp1
        </%def>
    </%namespace>
    
    # then call it
    ${stuff:comp1()}

### The "body()" method {@name=body}

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:

    <%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 `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:

    ${self.body(5, y=10, someval=15, delta=7)}
    
The `Context` object also supplies a `kwargs` accessor, for cases when youd like to pass along whatever is in the context to a `body()` callable:

    ${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 [inheritance](rel:inheritance).

### Namespace methods and properties {@name=properties}

The `Namespace` class includes helpful accessors and methods:
<commit_msg>fixed typo<commit_after>Namespaces
=============

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

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

    # components.html
    <%def name="comp1()">
        this is comp1
    </%def>
    
    <%def name="comp2()">
        this is comp2
    </%def>
    
You can make another file, for example `index.html`, that pulls those two components into a namespace called `comp`:

    # index.html
    <%namespace name="comp" file="components.html"/>
    
    Heres comp1:  ${comp.comp1()}
    Heres comp2:  ${comp.comp2()}

The `comp` variable above is an instance of `mako.runtime.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 ".".  When `import` is used, the `name` attribute is optional.

    <%namespace file="components.html" import="comp1, comp2"/>
    
    Heres comp1:  ${comp1()}
    Heres comp2:  ${comp2()}
    
`import` also supports the "*" operator:

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

    Heres comp1:  ${comp1()}
    Heres comp2:  ${comp2()}

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

### Namespaces from Regular Python Modules {@name=frommodules}

Namespaces can also import regular Python functions from modules.  These callables need to take at least one argument, `context`:

A module file `some/module.py` might contain the callable:

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

A template can use this module via:
    
    <%namespace name="hw" module="some.module"/>

    ${hw.my_tag()}
    
Note that the `context` argument is not needed in the call; the `namespace` tag creates a locally-scoped callable which takes care of it.

### Declaring defs in namespaces.

The `<%namespace>` tag supports the definition of `<%defs>` 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:
    
    # define a namespace
    <%namespace name="stuff">
        <%def name="comp1()">
            comp1
        </%def>
    </%namespace>
    
    # then call it
    ${stuff.comp1()}

### The "body()" method {@name=body}

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:

    <%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 `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:

    ${self.body(5, y=10, someval=15, delta=7)}
    
The `Context` object also supplies a `kwargs` accessor, for cases when youd like to pass along whatever is in the context to a `body()` callable:

    ${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 [inheritance](rel:inheritance).

### Namespace methods and properties {@name=properties}

The `Namespace` class includes helpful accessors and methods:

{'fraction_non_alphanumeric': 0.09624027184040337, 'fraction_numerical': 0.006138331689137345, 'mean_word_length': 3.8869844670594538, 'pattern_counts': {'":': 0, '<': 39, '<?xml version=': 0, '>': 39, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1188355', 'n_tokens_mistral': 2447, 'n_tokens_neox': 2354, 'n_words': 1213}