Table Of Contents

• Utils
  • QueryDict
  • SafeList
    • SafeList.clear()
  • boundary()
  • deprecated()
  • difference()
  • escape_markup()
  • format_bytes_to_human()
  • get_color_from_hex()
  • get_hex_from_color()
  • get_random_color()
  • interpolate()
  • intersection()
  • is_color_transparent()
  • platform
  • reify
  • rgba()
  • strtotuple()

Utils

The Utils module provides a selection of general utility functions and classes that may be useful for various applications. These include maths, color, algebraic and platform functions.

Changed in version 1.6.0: The OrderedDict class has been removed. Use collections.OrderedDict instead.

class kivy.utils.QueryDict

Bases: builtins.dict

QueryDict is a dict() that can be queried with dot.

d = QueryDict()
# create a key named toto, with the value 1
d.toto = 1
# it's the same as
d['toto'] = 1

New in version 1.0.4.

class kivy.utils.SafeList(*args, **kwargs)

Bases: builtins.list

List with a clear() method.

Warning

Usage of the iterate() function will decrease your performance.

clear()

Remove all items from list.

kivy.utils.boundary(value, minvalue, maxvalue)

Limit a value between a minvalue and maxvalue.

kivy.utils.deprecated(func=None, msg='')

This is a decorator which can be used to mark functions as deprecated. It will result in a warning being emitted the first time the function is used.

kivy.utils.difference(set1, set2)

Return the difference between 2 lists.

kivy.utils.escape_markup(text)

Escape markup characters found in the text. Intended to be used when markup text is activated on the Label:

untrusted_text = escape_markup('Look at the example [1]')
text = '[color=ff0000]' + untrusted_text + '[/color]'
w = Label(text=text, markup=True)

New in version 1.3.0.

kivy.utils.format_bytes_to_human(size, precision=2)

Format a byte value to a human readable representation (B, KB, MB…).

New in version 1.0.8.

Parameters:

size: int

Number that represents the bytes value

precision: int, defaults to 2

Precision after the comma

Examples:

>>> format_bytes_to_human(6463)
'6.31 KB'
>>> format_bytes_to_human(646368746541)
'601.98 GB'

kivy.utils.get_color_from_hex(s)

Transform a hex string color to a kivy Color.

kivy.utils.get_hex_from_color(color)

Transform a kivy Color to a hex value:

>>> get_hex_from_color((0, 1, 0))
'#00ff00'
>>> get_hex_from_color((.25, .77, .90, .5))
'#3fc4e57f'

New in version 1.5.0.

kivy.utils.get_random_color(alpha=1.0)

Returns a random color (4 tuple).

Parameters:

alpha: float, defaults to 1.0

If alpha == ‘random’, a random alpha value is generated.

kivy.utils.interpolate(value_from, value_to, step=10)

Interpolate between two values, by providing the reciprocal of the proportion between two points.

Deprecated since version 2.3.0: For animations, consider using the AnimationTransition.linear() for a similar purpose.

Warning

These interpolations work only on lists/tuples/doubles with the same dimensions. No test is done to check the dimensions are the same.

kivy.utils.intersection(set1, set2)

Return the intersection of 2 lists.

kivy.utils.is_color_transparent(c)

Return True if the alpha channel is 0.

kivy.utils.platform = 'linux'

A string identifying the current operating system. It is one of: ‘win’, ‘linux’, ‘android’, ‘macosx’, ‘ios’ or ‘unknown’. You can use it as follows:

from kivy.utils import platform
if platform == 'linux':
    do_linux_things()

New in version 1.3.0.

Changed in version 1.8.0: platform is now a variable instead of a function.

class kivy.utils.reify(func)

Bases: builtins.object

Put the result of a method which uses this (non-data) descriptor decorator in the instance dict after the first call, effectively replacing the decorator with an instance variable.

It acts like @property, except that the function is only ever called once; after that, the value is cached as a regular attribute. This gives you lazy attribute creation on objects that are meant to be immutable.

Taken from the Pyramid project.

To use this as a decorator:

@reify
def lazy(self):
     ...
     return hard_to_compute_int
first_time = self.lazy   # lazy is reify obj, reify.__get__() runs
second_time = self.lazy  # lazy is hard_to_compute_int

kivy.utils.rgba(s, *args)

Return a Kivy color (4 value from 0-1 range) from either a hex string or a list of 0-255 values.

New in version 1.10.0.

kivy.utils.strtotuple(s)

Convert a tuple string into a tuple with some security checks. Designed to be used with the eval() function:

a = (12, 54, 68)
b = str(a)         # return '(12, 54, 68)'
c = strtotuple(b)  # return (12, 54, 68)

« Support

Vector »