kv Compilation

kivy.lang.compiler.compile.kv(kv_syntax='minimal', proxy=False, rebind=True, bind_on_enter=False, captures_are_readonly=True)[source]

Decorator factory function that returns a decorator that compiles a kv containing function. Typical usage:

class MyWidget(Widget):
    @kv()  # notice that it MUST be called
    def apply_kv(self):
        with KvContext():
            self.x @= self.y + 256
Parameters:
  • kv_syntax –

    The binding syntax to support. Default: “minimal” With “minimal”, it’s similar to traditional kv, and binds rules e.g. self.x @= self.widget.y and self.dict[self.name]. When None, it binds to a expanded set of syntax, e.g. (self.widget + self.widget2).width.

    The “minimal” syntax is recommended for most situations and None should only be used in exceptional circumstance.

  • proxy –

    glob pattern(s) describing the widgets that should not hold a direct reference to other widgets for garbage collection purposes. Defaults to False

    It is either False - when all widgets should hold direct references, or True - when no widgets should hold direct references, or a glob string describing the widget(s) that should not hold a reference, e.g. “*widget” will match self.widget and self.my_widget. Or it can be a list of glob strings and any that match will not hold a direct reference.

    This is to be used when binding widgets that have a very long life, and it’s not desirable that the widget prevent other widgets from being garbage collected. This is mostly encountered when binding to the global App, which never dies.

    This is used for widgets that are being bound to, e.g. in the rule self.x @= self.app.my_x, proxy may be set to “*app”, to prevent the self widget from being kept alive by app. But is not needed e.g. when binding to widgets that are not independently kept alive.

    Warning

    If all binding widgets are using proxies, no one will keep the kv rules alive, and the rules will not be executed once garbage collection runs. You can save a reference to the KvContext, and that will keep that context alive as long as the context is held.

  • rebind –

    glob pattern(s) describing the intermediate widgets that should be rebound when they change. Defaults to True.

    It is either True - when all widgets should rebind, or False - when no widgets should rebind, or a glob string describing the widget(s) that should rebind, e.g. “*widget” will match self.widget and self.my_widget and both widget and my_widget will rebind. Or it can be a list of glob strings and any that match will rebind.

    This is used in rule e.g. self.x @= self.widget.x, if self.widget is rebound, then when self.widget changes, the rulee rebind to x belonging to the new widget stored in self.widget.

  • bind_on_enter –

    Where kv binding should occur for the context. Defaults to False.

    For a rule such as:

    with KvContext():
    ...

    binding can occur when the context is entered or exited. When bind_on_enter is True, it occurs upon entrance, when False it occurs upon exit. The default is False. Binding upon entrance is not recommended because it’s unintuitive and doesn’t follow the typical python programmatic flow.

  • captures_are_readonly –

    Whether any variables that participate in a rule may be changed between rule execution and binding. Defaults to True.

    This parameter should not be changed to False except for debugging purposes or if you truly understand the internals of binding.
Returns:

The compiled function associated with the original function, or the original function if there was nothing to compile.

Once a function is decorated, calling kv again on it will not recompile the function, unless the source or the compile options changed. This means calling kv()(f) will not re-compile f (and it shouldn’t need to).

kivy.lang.compiler.compile.kv_apply_manual(ctx, callback, local_vars, global_vars, kv_syntax='minimal', proxy=False, rebind=True)[source]

Similar to kv(), except that is is called manually to compile bindings. Similalrly to kv(), the bindings are compiled once, and are only recompiled if any of the compile options or source code file containing the callback is modified.

This is meant to be used for debugging purposes, and may change in the future.

Typical usage:

class ManualkvWidget(Widget):

    def apply_kv(self):
        ctx = KvParserContext()

        def manage_val(*largs):
            self.x = self.y + 512
        manage_val()

        # will bind to `self.y`.
        rule = KvParserRule('self.y + 512')
        rule.callback = manage_val
        rule.callback_name = manage_val.__name__
        ctx.add_rule(rule)

        kv_apply_manual(ctx, self.apply_kv, locals(), globals())
Parameters:
  • ctx – a KvParserContext used for parsing the rules.
  • callback – The callback to call when any of the bindings change.
  • local_vars – locals() of the function where the bindings occur.
  • global_vars – globals() of the function where the bindings occur.
  • kv_syntax – See kv().
  • proxy – See kv().
  • rebind – See kv().
Returns:

None - it executes the compiled rule in the provided locals(), globals() environment.