Kivy-examples 2.3.1.dev0__py3-none-any.whl

kivy/parser.py

@@ -0,0 +1,154 @@
+'''
+Parser utilities
+================
+
+Helper functions used for CSS parsing.
+'''
+
+__all__ = ('parse_color', 'parse_int', 'parse_float',
+           'parse_string', 'parse_bool', 'parse_int2',
+           'parse_float4', 'parse_filename')
+
+import re
+from kivy.logger import Logger
+from kivy.resources import resource_find
+
+
+class ColorException(Exception):
+    pass
+
+
+def parse_filename(filename):
+    '''Parse a filename and search for it using `resource_find()`.
+    If found, the resource path is returned, otherwise return the unmodified
+    filename (as specified by the caller).'''
+    filename = parse_string(filename)
+    result = resource_find(filename)
+    if result is None:
+        Logger.error('Resource: unable to find <%s>' % filename)
+    return result or filename
+
+
+def color_error(text):
+    # show warning and return a sane value
+    Logger.warning(text)
+    return (0, 0, 0, 1)
+
+
+def parse_color(text):
+    '''Parse a string to a kivy color. Supported formats:
+
+        * rgb(r, g, b)
+        * rgba(r, g, b, a)
+        * rgb
+        * rgba
+        * rrggbb
+        * rrggbbaa
+
+    For hexadecimal values, you case also use:
+
+        * #rgb
+        * #rgba
+        * #rrggbb
+        * #rrggbbaa
+    '''
+    value = [1, 1, 1, 1]
+    if text.startswith('rgb'):
+        res = re.match(r'rgba?\((.*)\)', text)
+        if res:
+            try:
+                # default r/g/b values to 1 if greater than 255 else x/255
+                value = [1 if int(x) > 255. else (int(x) / 255.)
+                         for x in re.split(', ?', res.groups()[0])]
+                if len(value) < 3:
+                    # in case of invalid input like rgb()/rgb(r)/rgb(r, g)
+                    raise ValueError
+            except ValueError:
+                return color_error('ColorParser: Invalid color for %r' % text)
+            except AttributeError:
+                return color_error('ColorParser: Invalid color for %r' % text)
+        else:
+            return color_error('ColorParser: Invalid color for %r' % text)
+        if len(value) == 3:
+            value.append(1.)
+    elif len(text):
+        res = text
+        if text[0] == '#':
+            res = text[1:]
+        lres = len(res)
+        if lres == 3 or lres == 4:
+            res = ''.join([x + x for x in res])
+        elif lres != 6 and lres != 8:
+            # raise ColorException('Invalid color format for %r' % text)
+            return color_error(
+                'ColorParser: Invalid color format for %r' % text)
+        try:
+            value = [int(res[i:i + 2], 16) / 255.
+                     for i in range(0, len(res), 2)]
+        except ValueError:
+            return color_error('ColorParser: Invalid color for %r' % text)
+        if lres == 6 or lres == 3:
+            value.append(1.)
+    return value
+
+
+def parse_bool(text):
+    '''Parse a string to a boolean, ignoring case. "true"/"1" is True,
+    "false"/"0" is False. Anything else throws an exception.'''
+    if text.lower() in ('true', '1'):
+        return True
+    elif text.lower() in ('false', '0'):
+        return False
+    raise Exception('Invalid boolean: %s' % text)
+
+
+def parse_string(text):
+    '''Parse a string to a string (removing single and double quotes).'''
+    if len(text) >= 2 and text[0] in ('"', "'") and text[-1] in ('"', "'"):
+        text = text[1:-1]
+    return text.strip()
+
+
+def parse_int2(text):
+    '''Parse a string to a list of exactly 2 integers.
+
+        >>> print(parse_int2("12 54"))
+        12, 54
+
+    '''
+    texts = [x for x in text.split(' ') if x.strip() != '']
+    value = list(map(parse_int, texts))
+    if len(value) < 1:
+        raise Exception('Invalid int2 format: %s' % text)
+    elif len(value) == 1:
+        return [value[0], value[0]]
+    elif len(value) > 2:
+        raise Exception('Too many values in %s: %s' % (text, str(value)))
+    return value
+
+
+def parse_float4(text):
+    '''Parse a string to a list of exactly 4 floats.
+
+        >>> parse_float4('54 87. 35 0')
+        54, 87., 35, 0
+
+    '''
+    texts = [x for x in text.split(' ') if x.strip() != '']
+    value = list(map(parse_float, texts))
+    if len(value) < 1:
+        raise Exception('Invalid float4 format: %s' % text)
+    elif len(value) == 1:
+        return [value[0] for x in range(4)]
+    elif len(value) == 2:
+        return [value[0], value[1], value[0], value[1]]
+    elif len(value) == 3:
+        # ambiguous case!
+        return [value[0], value[1], value[0], value[2]]
+    elif len(value) > 4:
+        raise Exception('Too many values in %s' % text)
+    return value
+
+
+parse_int = int
+parse_float = float

kivy/resources.py

@@ -0,0 +1,102 @@
+'''
+Resources management
+====================
+
+Resource management can be a pain if you have multiple paths and projects.
+Kivy offers 2 functions for searching for specific resources across a list
+of paths.
+
+Resource lookup
+---------------
+
+When Kivy looks for a resource e.g. an image or a kv file, it searches through
+a predetermined set of folders. You can modify this folder list using the
+:meth:`resource_add_path` and :meth:`resource_remove_path` functions.
+
+Customizing Kivy
+----------------
+
+These functions can also be helpful if you want to replace standard Kivy
+resources with your own. For example, if you wish to customize or re-style
+Kivy, you can force your *style.kv* or *data/defaulttheme-0.png* files to be
+used in preference to the defaults simply by adding the path to your preferred
+alternatives via the :meth:`resource_add_path` method.
+
+As almost all Kivy resources are looked up using the :meth:`resource_find`, so
+you can use this approach to add fonts and keyboard layouts and to replace
+images and icons.
+
+'''
+
+__all__ = ('resource_find', 'resource_add_path', 'resource_remove_path')
+
+from os.path import join, dirname, exists, abspath
+from kivy import kivy_data_dir
+from kivy.cache import Cache
+from kivy.utils import platform
+from kivy.logger import Logger
+import sys
+import os
+import kivy
+
+resource_paths = ['.', dirname(sys.argv[0])]
+if platform == 'ios':
+    resource_paths += [join(dirname(sys.argv[0]), 'YourApp')]
+resource_paths += [dirname(kivy.__file__), join(kivy_data_dir, '..')]
+
+Cache.register('kv.resourcefind', timeout=60)
+
+
+def resource_find(filename, use_cache=("KIVY_DOC_INCLUDE" not in os.environ)):
+    '''Search for a resource in the list of paths.
+    Use resource_add_path to add a custom path to the search.
+    By default, results are cached for 60 seconds.
+    This can be disabled using use_cache=False.
+
+    .. versionchanged:: 2.1.0
+        `use_cache` parameter added and made True by default.
+    '''
+    if not filename:
+        return
+    found_filename = None
+    if use_cache:
+        found_filename = Cache.get('kv.resourcefind', filename)
+        if found_filename:
+            return found_filename
+    if filename[:8] == 'atlas://':
+        found_filename = filename
+    else:
+        abspath_filename = abspath(filename)
+        if exists(abspath_filename):
+            found_filename = abspath(filename)
+        else:
+            for path in reversed(resource_paths):
+                abspath_filename = abspath(join(path, filename))
+                if exists(abspath_filename):
+                    found_filename = abspath_filename
+                    break
+        if not found_filename and filename.startswith("data:"):
+            found_filename = filename
+    if use_cache and found_filename:
+        Cache.append('kv.resourcefind', filename, found_filename)
+    return found_filename
+
+
+def resource_add_path(path):
+    '''Add a custom path to search in.
+    '''
+    if path in resource_paths:
+        return
+    Logger.debug('Resource: add <%s> in path list' % path)
+    resource_paths.append(path)
+
+
+def resource_remove_path(path):
+    '''Remove a search path.
+
+    .. versionadded:: 1.0.8
+    '''
+    if path not in resource_paths:
+        return
+    Logger.debug('Resource: remove <%s> from path list' % path)
+    resource_paths.remove(path)

kivy/storage/__init__.py

@@ -0,0 +1,405 @@
+'''
+Storage
+=======
+
+.. versionadded:: 1.7.0
+
+.. warning::
+
+    This module is still experimental, and the API is subject to change in a
+    future version.
+
+Usage
+-----
+
+The idea behind the Storage module is to be able to load/store any number of
+key-value pairs via an indexed key. The default model is abstract so you
+cannot use it directly. We provide some implementations such as:
+
+- :class:`kivy.storage.dictstore.DictStore`: use a python dict as a store
+- :class:`kivy.storage.jsonstore.JsonStore`: use a
+  `JSON <https://en.wikipedia.org/wiki/JSON>`_ file as a store
+- :class:`kivy.storage.redisstore.RedisStore`: use a `Redis <http://redis.io>`_
+  database with `redis-py <https://github.com/andymccurdy/redis-py>`_
+
+
+Examples
+--------
+
+For example, let's use a JsonStore::
+
+    from kivy.storage.jsonstore import JsonStore
+
+    store = JsonStore('hello.json')
+
+    # put some values
+    store.put('tito', name='Mathieu', org='kivy')
+    store.put('tshirtman', name='Gabriel', age=27)
+
+    # using the same index key erases all previously added key-value pairs
+    store.put('tito', name='Mathieu', age=30)
+
+    # get a value using a index key and key
+    print('tito is', store.get('tito')['age'])
+
+    # or guess the key/entry for a part of the key
+    for item in store.find(name='Gabriel'):
+        print('tshirtmans index key is', item[0])
+        print('his key value pairs are', str(item[1]))
+
+Because the data is persistent, you can check later to see if the key exists::
+
+    from kivy.storage.jsonstore import JsonStore
+
+    store = JsonStore('hello.json')
+    if store.exists('tito'):
+        print('tite exists:', store.get('tito'))
+        store.delete('tito')
+
+
+Synchronous / Asynchronous API
+------------------------------
+
+All the standard methods (:meth:`~AbstractStore.get`,
+:meth:`~AbstractStore.put` , :meth:`~AbstractStore.exists`,
+:meth:`~AbstractStore.delete`, :meth:`~AbstractStore.find`) have an
+asynchronous version.
+
+For example, the *get* method has a `callback` parameter. If set, the
+`callback` will be used to return the result to the user when available:
+the request will be asynchronous. If the `callback` is None, then the
+request will be synchronous and the result will be returned directly.
+
+
+Without callback (Synchronous API)::
+
+    entry = mystore.get('tito')
+    print('tito =', entry)
+
+With callback (Asynchronous API)::
+
+    def my_callback(store, key, result):
+        print('the key', key, 'has a value of', result)
+    mystore.get('plop', callback=my_callback)
+
+
+The callback signature (for almost all methods) is::
+
+    def callback(store, key, result):
+        """
+        store: the `Store` instance currently used.
+        key: the key sought for.
+        result: the result of the lookup for the key.
+        """
+
+
+Synchronous container type
+--------------------------
+
+The storage API emulates the container type for the synchronous API::
+
+    store = JsonStore('hello.json')
+
+    # original: store.get('tito')
+    store['tito']
+
+    # original: store.put('tito', name='Mathieu')
+    store['tito'] = {'name': 'Mathieu'}
+
+    # original: store.delete('tito')
+    del store['tito']
+
+    # original: store.count()
+    len(store)
+
+    # original: store.exists('tito')
+    'tito' in store
+
+    # original: for key in store.keys()
+    for key in store:
+        pass
+
+'''
+
+from kivy.clock import Clock
+from kivy.event import EventDispatcher
+
+
+class AbstractStore(EventDispatcher):
+    '''Abstract class used to implement a Store
+    '''
+
+    def __init__(self, **kwargs):
+        super(AbstractStore, self).__init__(**kwargs)
+        self.store_load()
+
+    def exists(self, key):
+        '''Check if a key exists in the store.
+        '''
+        return self.store_exists(key)
+
+    def async_exists(self, callback, key):
+        '''Asynchronous version of :meth:`exists`.
+
+        :Callback arguments:
+            `store`: :class:`AbstractStore` instance
+                Store instance
+            `key`: string
+                Name of the key to search for
+            `result`: boo
+                Result of the query, None if any error
+        '''
+        self._schedule(self.store_exists_async,
+                       key=key, callback=callback)
+
+    def get(self, key):
+        '''Get the key-value pairs stored at `key`. If the key is not found, a
+        `KeyError` exception will be thrown.
+        '''
+        return self.store_get(key)
+
+    def async_get(self, callback, key):
+        '''Asynchronous version of :meth:`get`.
+
+        :Callback arguments:
+            `store`: :class:`AbstractStore` instance
+                Store instance
+            `key`: string
+                Name of the key to search for
+            `result`: dict
+                Result of the query, None if any error
+        '''
+        self._schedule(self.store_get_async, key=key, callback=callback)
+
+    def put(self, key, **values):
+        '''Put new key-value pairs (given in *values*) into the storage. Any
+        existing key-value pairs will be removed.
+        '''
+        need_sync = self.store_put(key, values)
+        if need_sync:
+            self.store_sync()
+        return need_sync
+
+    def async_put(self, callback, key, **values):
+        '''Asynchronous version of :meth:`put`.
+
+        :Callback arguments:
+            `store`: :class:`AbstractStore` instance
+                Store instance
+            `key`: string
+                Name of the key to search for
+            `result`: bool
+                Indicate True if the storage has been updated, or False if
+                nothing has been done (no changes). None if any error.
+        '''
+        self._schedule(self.store_put_async,
+                       key=key, value=values, callback=callback)
+
+    def delete(self, key):
+        '''Delete a key from the storage. If the key is not found, a `KeyError`
+        exception will be thrown.'''
+        need_sync = self.store_delete(key)
+        if need_sync:
+            self.store_sync()
+        return need_sync
+
+    def async_delete(self, callback, key):
+        '''Asynchronous version of :meth:`delete`.
+
+        :Callback arguments:
+            `store`: :class:`AbstractStore` instance
+                Store instance
+            `key`: string
+                Name of the key to search for
+            `result`: bool
+                Indicate True if the storage has been updated, or False if
+                nothing has been done (no changes). None if any error.
+        '''
+        self._schedule(self.store_delete_async, key=key,
+                       callback=callback)
+
+    def find(self, **filters):
+        '''Return all the entries matching the filters. The entries are
+        returned through a generator as a list of (key, entry) pairs
+        where *entry* is a dict of key-value pairs ::
+
+            for key, entry in store.find(name='Mathieu'):
+                print('key:', key, ', entry:', entry)
+
+        Because it's a generator, you cannot directly use it as a list. You can
+        do::
+
+            # get all the (key, entry) availables
+            entries = list(store.find(name='Mathieu'))
+            # get only the entry from (key, entry)
+            entries = list((x[1] for x in store.find(name='Mathieu')))
+        '''
+        return self.store_find(filters)
+
+    def async_find(self, callback, **filters):
+        '''Asynchronous version of :meth:`find`.
+
+        The callback will be called for each entry in the result.
+
+        :Callback arguments:
+            `store`: :class:`AbstractStore` instance
+                Store instance
+            `key`: string
+                Name of the key to search for, or None if we reach the end of
+                the results
+            `result`: bool
+                Indicate True if the storage has been updated, or False if
+                nothing has been done (no changes). None if any error.
+        '''
+        self._schedule(self.store_find_async,
+                       callback=callback, filters=filters)
+
+    def keys(self):
+        '''Return a list of all the keys in the storage.
+        '''
+        return self.store_keys()
+
+    def async_keys(self, callback):
+        '''Asynchronously return all the keys in the storage.
+        '''
+        self._schedule(self.store_keys_async, callback=callback)
+
+    def count(self):
+        '''Return the number of entries in the storage.
+        '''
+        return self.store_count()
+
+    def async_count(self, callback):
+        '''Asynchronously return the number of entries in the storage.
+        '''
+        self._schedule(self.store_count_async, callback=callback)
+
+    def clear(self):
+        '''Wipe the whole storage.
+        '''
+        return self.store_clear()
+
+    def async_clear(self, callback):
+        '''Asynchronous version of :meth:`clear`.
+        '''
+        self._schedule(self.store_clear_async, callback=callback)
+
+    #
+    # Operators
+    #
+
+    def __setitem__(self, key, values):
+        if not isinstance(values, dict):
+            raise Exception('Only dict are accepted for the store[key] = dict')
+        self.put(key, **values)
+
+    def __getitem__(self, key):
+        return self.get(key)
+
+    def __delitem__(self, key):
+        return self.keys()
+
+    def __contains__(self, key):
+        return self.exists(key)
+
+    def __len__(self):
+        return self.count()
+
+    def __iter__(self):
+        for key in self.keys():
+            yield key
+
+    #
+    # Used for implementation
+    #
+
+    def store_load(self):
+        pass
+
+    def store_sync(self):
+        pass
+
+    def store_get(self, key):
+        raise NotImplementedError
+
+    def store_put(self, key, value):
+        raise NotImplementedError
+
+    def store_exists(self, key):
+        raise NotImplementedError
+
+    def store_delete(self, key):
+        raise NotImplementedError
+
+    def store_find(self, filters):
+        return []
+
+    def store_keys(self):
+        return []
+
+    def store_count(self):
+        return len(self.store_keys())
+
+    def store_clear(self):
+        for key in self.store_keys():
+            self.store_delete(key)
+        self.store_sync()
+
+    def store_get_async(self, key, callback):
+        try:
+            value = self.store_get(key)
+            callback(self, key, value)
+        except KeyError:
+            callback(self, key, None)
+
+    def store_put_async(self, key, value, callback):
+        try:
+            value = self.put(key, **value)
+            callback(self, key, value)
+        except:
+            callback(self, key, None)
+
+    def store_exists_async(self, key, callback):
+        try:
+            value = self.store_exists(key)
+            callback(self, key, value)
+        except:
+            callback(self, key, None)
+
+    def store_delete_async(self, key, callback):
+        try:
+            value = self.delete(key)
+            callback(self, key, value)
+        except:
+            callback(self, key, None)
+
+    def store_find_async(self, filters, callback):
+        for key, entry in self.store_find(filters):
+            callback(self, filters, key, entry)
+        callback(self, filters, None, None)
+
+    def store_count_async(self, callback):
+        try:
+            value = self.store_count()
+            callback(self, value)
+        except:
+            callback(self, 0)
+
+    def store_keys_async(self, callback):
+        try:
+            keys = self.store_keys()
+            callback(self, keys)
+        except:
+            callback(self, [])
+
+    def store_clear_async(self, callback):
+        self.store_clear()
+        callback(self)
+
+    #
+    # Privates
+    #
+
+    def _schedule(self, cb, **kwargs):
+        # XXX not entirely sure about the best value (0 or -1).
+        Clock.schedule_once(lambda dt: cb(**kwargs), 0)