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

kivy/tools/gallery.py

@@ -0,0 +1,323 @@
+''' Create rst documentation of the examples directory.
+
+This uses screenshots in the screenshots_dir
+(currently doc/sources/images/examples) along with source code and files
+in the examples/ directory to create rst files in the generation_dir
+(doc/sources/examples) gallery.rst, index.rst, and gen__*.rst
+
+'''
+
+
+import os
+import re
+from os.path import sep
+from os.path import join as slash  # just like that name better
+from os.path import dirname, abspath
+import kivy
+from kivy.logger import Logger
+import textwrap
+
+# from here to the kivy top
+base_dir = dirname(dirname(abspath(kivy.__file__)))
+examples_dir = slash(base_dir, 'examples')
+screenshots_dir = slash(base_dir, 'doc/sources/images/examples')
+generation_dir = slash(base_dir, 'doc/sources/examples')
+
+image_dir = "../images/examples/"  # relative to generation_dir
+gallery_filename = slash(generation_dir, 'gallery.rst')
+
+
+# Info is a dict built up from
+# straight filename information, more from reading the docstring,
+# and more from parsing the description text. Errors are often
+# shown by setting the key 'error' with the value being the error message.
+#
+# It doesn't quite meet the requirements for a class, but is a vocabulary
+# word in this module.
+
+def iter_filename_info(dir_name):
+    """
+    Yield info (dict) of each matching screenshot found walking the
+    directory dir_name. A matching screenshot uses double underscores to
+    separate fields, i.e. path__to__filename__py.png as the screenshot for
+    examples/path/to/filename.py.
+
+    Files not ending with .png are ignored, others are either parsed or
+    yield an error.
+
+    Info fields 'dunder', 'dir', 'file', 'ext', 'source' if not 'error'
+    """
+    pattern = re.compile(r'^((.+)__(.+)__([^-]+))\.png')
+    for t in os.walk(dir_name):
+        for filename in t[2]:
+            if filename.endswith('.png'):
+                m = pattern.match(filename)
+                if m is None:
+                    yield {'error': 'png filename not following screenshot'
+                                    ' pattern: {}'.format(filename)}
+                else:
+                    d = m.group(2).replace('__', sep)
+                    yield {'dunder': m.group(1),
+                           'dir': d,
+                           'file': m.group(3),
+                           'ext': m.group(4),
+                           'source': slash(d, m.group(3) + '.' + m.group(4))
+                           }
+
+
+def parse_docstring_info(text):
+    ''' parse docstring from text (normal string with '\n's) and return an info
+    dict. A docstring should the first triple quoted string, have a title
+    followed by a line of equal signs, and then a description at
+    least one sentence long.
+
+    fields are 'docstring', 'title', and 'first_sentence' if not 'error'
+    'first_sentence' is a single line without newlines.
+    '''
+    q = '\"\"\"|\'\'\''
+    p = r'({})\s+([^\n]+)\s+\=+\s+(.*?)(\1)'.format(q)
+    m = re.search(p, text, re.S)
+    if m:
+        comment = m.group(3).replace('\n', ' ')
+        first_sentence = comment[:comment.find('.') + 1]
+        return {'docstring': m.group(0), 'title': m.group(2),
+                'description': m.group(3), 'first_sentence': first_sentence}
+    else:
+        return {'error': 'Did not find docstring with title at top of file.'}
+
+
+def iter_docstring_info(dir_name):
+    ''' Iterate over screenshots in directory, yield info from the file
+     name and initial parse of the docstring. Errors are logged, but
+     files with errors are skipped.
+    '''
+    for file_info in iter_filename_info(dir_name):
+        if 'error' in file_info:
+            Logger.error(file_info['error'])
+            continue
+        source = slash(examples_dir, file_info['dir'],
+                       file_info['file'] + '.' + file_info['ext'])
+        if not os.path.exists(source):
+            Logger.error('Screen shot references source code that does '
+                         'not exist:  %s', source)
+            continue
+        with open(source) as f:
+            text = f.read()
+            docstring_info = parse_docstring_info(text)
+            if 'error' in docstring_info:
+                Logger.error(docstring_info['error'] + '  File: ' + source)
+                continue  # don't want to show ugly entries
+            else:
+                file_info.update(docstring_info)
+        yield file_info
+
+
+def enhance_info_description(info, line_length=79):
+    ''' Using the info['description'], add fields to info.
+
+    info['files'] is the source filename and any filenames referenced by the
+    magic words in the description, e.g. 'the file xxx.py' or
+    'The image this.png'. These are as written in the description, do
+    not allow ../dir notation, and are relative to the source directory.
+
+    info['enhanced_description'] is the description, as an array of
+    paragraphs where each paragraph is an array of lines wrapped to width
+    line_length. This enhanced description include the rst links to
+    the files of info['files'].
+    '''
+
+    # make text a set of long lines, one per paragraph.
+    paragraphs = info['description'].split('\n\n')
+    lines = [
+        paragraph.replace('\n', '$newline$')
+        for paragraph in paragraphs
+    ]
+    text = '\n'.join(lines)
+
+    info['files'] = [info['file'] + '.' + info['ext']]
+    regex = r'[tT]he (?:file|image) ([\w\/]+\.\w+)'
+    for name in re.findall(regex, text):
+        if name not in info['files']:
+            info['files'].append(name)
+
+    # add links where the files are referenced
+    folder = '_'.join(info['source'].split(sep)[:-1]) + '_'
+    text = re.sub(r'([tT]he (?:file|image) )([\w\/]+\.\w+)',
+                  r'\1:ref:`\2 <$folder$\2>`', text)
+    text = text.replace('$folder$', folder)
+
+    # now break up text into array of paragraphs, each an array of lines.
+    lines = [line.replace('$newline$', '\n') for line in text.split('\n')]
+    paragraphs = [
+        textwrap.wrap(line, line_length)
+        # ignore wrapping if .. note:: or similar block
+        if not line.startswith(' ') else [line]
+        for line in lines
+    ]
+    info['enhanced_description'] = paragraphs
+
+
+def get_infos(dir_name):
+    ''' return infos, an array info dicts for each matching screenshot in the
+    dir, sorted by source file name, and adding the field 'num' as he unique
+    order in this array of dicts'.
+
+    '''
+    infos = [i for i in iter_docstring_info(dir_name)]
+    infos.sort(key=lambda x: x['source'])
+    for num, info in enumerate(infos):
+        info['num'] = num
+        enhance_info_description(info)
+    return infos
+
+
+def make_gallery_page(infos):
+    ''' return string of the rst (Restructured Text) of the gallery page,
+    showing information on all screenshots found.
+    '''
+
+    gallery_top = '''
+Gallery
+-------
+
+.. _Tutorials:  ../tutorials-index.html
+
+.. container:: title
+
+    This gallery lets you explore the many examples included with Kivy.
+    Click on any screenshot to see the code.
+
+This gallery contains:
+
+    * Examples from the examples/ directory that show specific capabilities of
+      different libraries and features of Kivy.
+    * Demonstrations from the examples/demos/ directory that explore many of
+      Kivy's abilities.
+
+There are more Kivy programs elsewhere:
+
+    * Tutorials_ walks through the development of complete Kivy applications.
+    * Unit tests found in the source code under the subdirectory kivy/tests/
+      can also be useful.
+
+We hope your journey into learning Kivy is exciting and fun!
+
+'''
+    output = [gallery_top]
+
+    for info in infos:
+        output.append(
+                "\n**{title}** (:doc:`{source}<gen__{dunder}>`)\n"
+                "\n{description}"
+                "\n.. image:: ../images/examples/{dunder}.png"
+                "\n  :width:  216pt"
+                "\n  :align:  left"
+                "\n  :target: gen__{dunder}.html".format(**info))
+    return "\n".join(output) + "\n"
+
+
+def make_detail_page(info):
+    ''' return str of the rst text for the detail page of the file in info. '''
+
+    def a(s=''):
+        ''' append formatted s to output, which will be joined into lines '''
+        output.append(s.format(**info))
+
+    output = []
+    a('{title}')
+    a('=' * len(info['title']))
+    a('\n.. |pic{num}| image:: /images/examples/{dunder}.png'
+      '\n   :width: 50%'
+      '\n   :align: middle')
+    a('\n|pic{num}|')
+    a()
+    for paragraph in info['enhanced_description']:
+        for line in paragraph:
+            a(line)
+        a()
+
+    # include images
+    last_lang = '.py'
+    for fname in info['files']:
+        full_name = slash(info['dir'], fname)
+        ext = re.search(r'\.\w+$', fname).group(0)
+        a('\n.. _`' + full_name.replace(sep, '_') + '`:')
+        # double separator if building on windows (sphinx skips backslash)
+        if '\\' in full_name:
+            full_name = full_name.replace(sep, sep * 2)
+
+        if ext in ['.png', '.jpg', '.jpeg']:
+            title = 'Image **' + full_name + '**'
+            a('\n' + title)
+            a('~' * len(title))
+            a('\n.. image:: ../../../examples/' + full_name)
+            a('    :align: ' ' center')
+        else:  # code
+            title = 'File **' + full_name + '**'
+            a('\n' + title)
+            a('~' * len(title))
+            if ext != last_lang and ext != '.txt':
+                a('\n.. highlight:: ' + ext[1:])
+                a('    :linenothreshold: 3')
+                last_lang = ext
+            # prevent highlight errors with 'none'
+            elif ext == '.txt':
+                a('\n.. highlight:: none')
+                a('    :linenothreshold: 3')
+                last_lang = ext
+            a('\n.. include:: ../../../examples/' + full_name)
+            a('    :code:')
+    return '\n'.join(output) + '\n'
+
+
+def write_file(name, s):
+    ''' write the string to the filename '''
+
+    # Make sure all the directories has been created before
+    # trying to write to the file
+    directory = os.path.dirname(name)
+    if not os.path.exists(directory):
+        os.makedirs(directory)
+
+    with open(name, 'w') as f:
+        f.write(s)
+
+
+def make_index(infos):
+    ''' return string of the rst for the gallery's index.rst file. '''
+    start_string = '''
+Gallery of Examples
+===================
+
+.. toctree::
+    :maxdepth: 1
+
+    gallery'''
+    output = [start_string]
+    for info in infos:
+        output.append('    gen__{}'.format(info['dunder']))
+    return '\n'.join(output) + '\n'
+
+
+def write_all_rst_pages():
+    ''' Do the main task of writing the gallery,
+    detail, and index rst pages.
+    '''
+    infos = get_infos(screenshots_dir)
+    s = make_gallery_page(infos)
+    write_file(gallery_filename, s)
+
+    for info in infos:
+        s = make_detail_page(info)
+        detail_name = slash(generation_dir,
+                            'gen__{}.rst'.format(info['dunder']))
+        write_file(detail_name, s)
+
+    s = make_index(infos)
+    index_name = slash(generation_dir, 'index.rst')
+    write_file(index_name, s)
+    Logger.info('gallery.py: Created gallery rst documentation pages.')
+
+
+if __name__ == '__main__':
+    write_all_rst_pages()

kivy/tools/generate-icons.py

@@ -0,0 +1,117 @@
+'''
+Icon generator
+==============
+
+This tool will help you to generate all the icons wanted for Google Play Store,
+App Store, Amazon store.
+'''
+
+import sys
+from PIL import Image
+from os.path import exists, join, realpath, basename, dirname
+from os import makedirs
+from argparse import ArgumentParser
+
+
+class Converter(object):
+
+    converters = {
+        'appstore': {
+            'directory_name': 'ios',
+            'sizes': [
+                ('App store high resolution', '{}-appstore-1024.png', 1024),
+                ('App store normal resolution', '{}-appstore-512.png', 512),
+                # iOS 7
+                ('iPhone (iOS 7)', '{}-60.png', 120),
+                ('iPhone @2 (iOS 7)', '{}-60@2x.png', 120),
+                ('iPad (iOS 7)', '{}-76.png', 76),
+                ('iPad @2 (iOS 7)', '{}-60@2x.png', 152),
+                # iOS 6.1 and earlier
+                ('iPhone (iOS >= 6.1)', '{}-57.png', 57),
+                ('iPhone @2 (iOS >= 6.1)', '{}-57@2x.png', 114),
+                ('iPad (iOS >= 6.1)', '{}-72.png', 72),
+                ('iPad @2 (iOS >= 6.1)', '{}-72@2x.png', 114),
+                # iTunes artwork (ad-hoc)
+                ('iTunes Artwork (ad-hoc)', 'iTunesArtwork', 512),
+                ('iTunes Artwork @2 (ad-hoc)', 'iTunesArtwork@2x', 1024),
+            ]},
+        'playstore': {
+            'directory_name': 'android',
+            'sizes': [
+                ('Google Play icon', '{}-googleplay-512.png', 512),
+                ('Launcher icon MDPI', '{}-48.png', 48),
+                ('Launcher icon HDPI', '{}-72.png', 72),
+                ('Launcher icon XHDPI', '{}-96.png', 96),
+                ('Launcher icon XXHDPI', '{}-144.png', 48),
+                ('Launcher icon XXXHDPI', '{}-192.png', 192),
+            ]},
+        'amazonstore': {
+            'directory_name': 'amazon',
+            'sizes': [
+                ('Small icon', '{}-114.png', 114),
+                ('Large icon', '{}-512.png', 512),
+            ]}}
+
+    def run(self):
+        parser = ArgumentParser(
+                description='Generate icons for various stores')
+        parser.add_argument('--dir', type=str, default=None,
+                help=('Output directory to generate all the icons,'
+                      'defaults to the directory of the source icon'))
+        parser.add_argument('--force', type=bool, default=False,
+                help=('Generate all icons even if the source is not perfect.'))
+        parser.add_argument('icon', type=str,
+                help='Base icon (must be 1024x1024 or 512x512)')
+
+        args = parser.parse_args()
+        if not exists(args.icon):
+            print('Error: No such icon file')
+            sys.exit(1)
+
+        # ensure the destination directory will be set
+        if args.dir is None:
+            args.dir = dirname(args.icon)
+
+        # read the source image, and do some quality checks
+        base_fn = basename(args.icon).rsplit('.', 1)[0]
+        source = Image.open(args.icon)
+        self.ensure_quality(source, args.force)
+
+        for directory_name, sizeinfo in self.iterate():
+            description, pattern_fn, size = sizeinfo
+            print('Generate {}: {}x{}'.format(description, size, size))
+            dest_dir = realpath(join(args.dir, directory_name))
+            if not exists(dest_dir):
+                makedirs(dest_dir)
+            icon_fn = join(dest_dir, pattern_fn.format('Icon'))
+            self.convert_to(source, icon_fn, size)
+
+    def convert_to(self, source, icon_fn, size):
+        dest = source.resize((size, size))
+        dest.save(icon_fn, 'png')
+
+    def ensure_quality(self, image, force=False):
+        messages = []
+        w, h = image.size
+        if w != h:
+            messages.append('Width and height should be the same')
+        if w not in (512, 1024):
+            messages.append(
+                'Source image is recommended to be 1024 (512 minimum)')
+        if not messages:
+            return
+
+        print('Quality check failed')
+        for message in messages:
+            print('- {}'.format(message))
+        if not force:
+            sys.exit(1)
+
+    def iterate(self):
+        for store, infos in Converter.converters.items():
+            for size in infos['sizes']:
+                yield infos['directory_name'], size
+
+
+if __name__ == '__main__':
+    Converter().run()

kivy/tools/gles_compat/subset_gles.py

@@ -0,0 +1,125 @@
+'''
+    Common GLES Subset Extraction Script
+    ====================================
+
+    In Kivy, our goal is to use OpenGL ES 2.0 (GLES2) for all drawing on all
+    platforms. The problem is that GLES2 is not a proper subset of any OpenGL
+    Desktop (GL) version prior to version 4.1.
+    However, to keep all our drawing cross-platform compatible, we're
+    restricting the Kivy drawing core to a real subset of GLES2 that is
+    available on all platforms.
+
+    This script therefore parses the GL and GL Extension (GLEXT) headers and
+    compares them with the GLES2 header. It then generates a header that only
+    contains symbols that are common to GLES2 and at least either GL or GLEXT.
+    However, since GLES2 doesn't support double values, we also need to do some
+    renaming, because functions in GL that took doubles as arguments now take
+    floats in GLES2, with their function name being suffixed with 'f'.
+
+    Furthermore, sometimes the pure symbol name doesn't match because there
+    might be an _EXT or _ARB or something akin to that at the end of a symbol
+    name. In that case, we take the symbol from the original header and add
+    a #define directive to redirect to that symbol from the symbol name without
+    extension.
+'''
+
+from __future__ import print_function
+
+gl = open("/Developer/SDKs/MacOSX10.6.sdk/System/Library/Frameworks/" +
+          "OpenGL.framework/Versions/A/Headers/gl.h", 'r')
+glext = open("/Developer/SDKs/MacOSX10.6.sdk/System/Library/Frameworks/" +
+             "OpenGL.framework/Versions/A/Headers/glext.h", 'r')
+gles = open("gl2.h", 'r')
+
+
+def add_defines_to_set(header):
+    symbols = []
+    lineno = 0
+    for line in header:
+        symbol = None
+        hexcode = None
+        lineno += 1
+        line = line.strip()
+        try:
+            elements = line.split()
+            if line.startswith("#define"):
+                symbol = elements[1]
+                for element in elements:
+                    if element.startswith("0x"):
+                        hexcode = element
+            elif line.startswith("typedef"):
+                symbol = elements[-1]
+            else:
+                for element in elements:
+                    if element.startswith("gl"):
+                        symbol = element
+            if symbol:
+                symbols.append((symbol, lineno, line, hexcode))
+        except Exception as e:
+            print('error:', lineno, ':', line)
+            print(e)
+
+    return symbols
+
+
+def extract_common_symbols(symbols1, symbols2, already_extracted):
+    for symbol1, lineno1, line1, hexcode1 in symbols1:
+        for symbol2, lineno2, line2, hexcode2 in symbols2:
+            if symbol1 in already_extracted or symbol2 in already_extracted:
+                continue
+            if symbol1 == symbol2 + 'f':
+                # There is no `double` type in GLES; Functions that were using
+                # a double were renamed with the suffix 'f'.
+                print("// Different Name; Redefine")
+                print(line2)
+                print("#define %s %s" % (symbol1, symbol2))
+            elif symbol1 == symbol2:
+                already_extracted.append(symbol1)
+                print(line1)
+                if symbol1 == 'GLclampf;':
+                    # See explanation about doubles on GLES above.
+                    print('typedef GLclampf GLclampd;')
+            elif hexcode1 and hexcode2 and hexcode1 == hexcode2:
+                already_extracted.append(symbol1)
+                already_extracted.append(symbol2)
+                print("// Different Name; Redefine")
+                print(line2)
+                print("#define %s %s" % (symbol1, symbol2))
+
+
+# Generate ------------------------------------------------
+# pipe to kivy/kivy/graphics/common_subset.h
+
+gl_symbols = add_defines_to_set(gl)
+glext_symbols = add_defines_to_set(glext)
+gles_symbols = add_defines_to_set(gles)
+
+print('// GLES 2.0 Header file, generated for Kivy')
+print('// Check kivy/kivy/tools/gles_compat/subset_gles.py')
+print('#pragma once')
+print('#include "gl2platform.h"')
+print('#ifdef __cplusplus')
+print('extern "C" {')
+print('#endif')
+
+# Don't add the same symbol more than once
+already_extracted = []
+
+print('\n// Subset common to GLES and GL: ===================================')
+extract_common_symbols(gles_symbols, gl_symbols, already_extracted)
+
+print('\n// Subset common to GLES and GLEXT: ================================')
+extract_common_symbols(gles_symbols, glext_symbols, already_extracted)
+
+print()
+print('// What follows was manually extracted from the GLES2 headers because')
+print('// it was not present in any other header.', end=' ')
+print('''
+#define GL_SHADER_BINARY_FORMATS          0x8DF8
+#define GL_RGB565                         0x8D62
+''')
+
+print('#ifdef __cplusplus')
+print('}')
+print('#endif')
+print('\n')

kivy/tools/highlight/__init__.py

@@ -0,0 +1,9 @@
+'''
+Syntax Highlighting
+===================
+
+This module contains various files for providing Kivy syntax highlighting in
+some popular text editors. Please see the contents of this folder for the
+provided resources.
+
+'''

kivy/tools/kviewer.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python
+'''
+KViewer
+=======
+
+KViewer, for KV-Viewer, is a simple tool allowing you to dynamically display
+a KV file, taking its changes into account (thanks to watchdog). The
+idea is to facilitate design using the KV language. It's somewhat related to
+the KivyCatalog demo, except it uses an on-disc file, allowing the user to use
+any editor.
+
+You can use the script as follows::
+
+    python kviewer.py ./test.kv
+
+This will display the test.kv and automatically update the display when the
+file changes.
+
+.. note: This scripts uses watchdog to listen for file changes. To install
+   watchdog::
+
+   pip install watchdog
+
+'''
+
+from sys import argv
+from kivy.lang import Builder
+from kivy.app import App
+from kivy.core.window import Window
+from kivy.clock import Clock, mainthread
+from kivy.uix.label import Label
+
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+from os.path import dirname, basename, join
+
+
+if len(argv) != 2:
+    print('usage: %s filename.kv' % argv[0])
+    exit(1)
+
+
+PATH = dirname(argv[1])
+TARGET = basename(argv[1])
+
+
+class KvHandler(FileSystemEventHandler):
+    def __init__(self, callback, target, **kwargs):
+        super(KvHandler, self).__init__(**kwargs)
+        self.callback = callback
+        self.target = target
+
+    def on_any_event(self, event):
+        if basename(event.src_path) == self.target:
+            self.callback()
+
+
+class KvViewerApp(App):
+    def build(self):
+        o = Observer()
+        o.schedule(KvHandler(self.update, TARGET), PATH)
+        o.start()
+        Clock.schedule_once(self.update, 1)
+        return super(KvViewerApp, self).build()
+
+    @mainthread
+    def update(self, *args):
+        Builder.unload_file(join(PATH, TARGET))
+        for w in Window.children[:]:
+            Window.remove_widget(w)
+        try:
+            Window.add_widget(Builder.load_file(join(PATH, TARGET)))
+        except Exception as e:
+            Window.add_widget(Label(text=(
+                e.message if getattr(e, r'message', None) else str(e)
+            )))
+
+
+if __name__ == '__main__':
+    KvViewerApp().run()

kivy/tools/packaging/__init__.py

@@ -0,0 +1,12 @@
+'''
+Packaging
+=========
+
+This module contains `PyInstaller <http://www.pyinstaller.org/>`_ hooks in
+order to assist in the process of building binary packages. PyInstaller allows
+you to produce stand-alone, self-contained executables of your Kivy app for
+Windows, Linux and Mac.
+
+For more information, please see the `PyInstaller website
+<http://www.pyinstaller.org/>`_
+'''