Kv Compiler

class kivy.lang.compiler.KvContext(reinit_after=False)

Bases: builtins.object

Manages kv rules created under the context.

Parameters:reinit_after –

Whether all the rules that are not KvRule.triggered_only should be executed again after the bindings are complete when the KvContext exits. Defaults to False.

This is only useful when bind_on_enter in kv() is False, because then the rules are executed before the bindings occur, and it may be desirable for the rules to be executed again, once all the bindings occurs.

This is particularly useful for circular rules. It is False by default for performance reasons.

Class attributes:

Variables:

• rules –

  List of KvRule Contains all the kv rules created under the context, ignoring rules created under a second context within this context. E.g.:

  with KvContext() as my_ctx:
      self.x @= self.y
      with KvContext() as my_ctx2:
          self.y @= self.height + 10
      with KvRule(name='my_rule'):
          self.width @= self.height
  

  then my_ctx will contain 2 rules, and my_ctx2 will contain 1 rule. The rules are ordered and numbered in the order they occur in the function.

• named_rules – dictionary with all the rules that are named. Similarly to rules, but contains the rules that have been given names. In the example above, my_ctx.named_rules contains one rule with name/key value “my_rule”.
• bind_store – (internal): Maintains a reference to the list that stores all the bindings created for all the rules in the context.
• rebind_functions – (internal): Maintains a reference to all the callbacks used in all the context’s rules.

add_rule(rule)

Adds the rule to the context.

It is called automatically by the compiler and should only be called when manually compiling kv.

unbind_all_rules()

Calls KvRule.unbind_rule() for all the rules in the context to unbind all the rules.

class kivy.lang.compiler.KvRule(*binds, delay=None, name=None, triggered_only=False)

Bases: builtins.object

Describes a kv rule.

Parameters:

• *binds –

  captures all positional arguments and add them to the bind list. E.g.:

  with KvRule():
      self.x @= self.y
  

  does the same things as:

  with KvRule(self.y):
      self.x = self.y
  

  and you can add as many positional args there as you like, and the rule will bind to all fo them. The args can be actual variable names, e.g. self.y, or as a string, e.g. “self.y” - they will do the same thing.

• delay –

  the rule type: can be None (default), “canvas”, or a number. Describes the rule type. * If None, it’s a normal kv rule * If “canvas”, it’s meant to be used with a canvas instruction and

  the rule will be scheduled to be executed with other graphics after the frame, rather than every time it is called.

  • If a number, a Clock trigger event will be created with the given delay and when the rule dispatches, the event will be triggered, rather than be executed immediately.
• name – a optional name for the rule. Defaults to None

Class attributes:

Variables:

• largs – The largs provided when the rule is dispatched.
• bind_store – (internal): Maintains a reference to the list that stores all the bindings created for the rule.
• bind_store_leaf_indices – (internal): The list of all the indices in bind_store that store the leaf bindings created for the rule.
• callback – (internal): The callback function that is called by the rule whenever it is dispatched.
• _callback – (internal): If it’s a clock or canvas rule, contains the underlying callback that actually executed the rule. In that case, callback contains the clock trigger or function that schedules the canvas update.

unbind_rule()

Unbinds the rule, so that it will not be triggered by any of the properties that the rule is bound to.

If the rule is already scheduled, e.g. with a canvas instruction or clock trigger, it may still execute (this may change in the future to immediately cancel that as well), but it won’t be scheduled again.

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

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).

class kivy.lang.compiler.KvException

Bases: builtins.Exception

Raised when something goes wrong with kv compilation or loading.

• NO DOCUMENTATION (module kivy.uix.recycleview)
• kv Compilation
• Kv Compiler Contexts and Rules
• Kv Compiler Runtime Functions
• Kv Compiler Source Code Generation
• Kv Parser