Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
315 lines (235 sloc) 9.39 KB
Interactive launcher
.. versionadded:: 1.3.0
The :class:`InteractiveLauncher` provides a user-friendly python shell interface
to an :class:`App` so that it can be prototyped and debugged interactively.
.. note::
The Kivy API intends for some functions to only be run once or before the
main EventLoop has started. Methods that can normally be called during the
course of an application will work as intended, but specifically overriding
methods such as :meth:`on_touch` dynamically leads to trouble.
Creating an InteractiveLauncher
Take you existing subclass of :class:`App` (this can be production code) and
pass an instance to the :class:`InteractiveLauncher` constructor.::
from kivy.interactive import InteractiveLauncher
from import App
from kivy.uix.button import Button
class MyApp(App):
def build(self):
return Button(test='Hello Shell')
interactiveLauncher = InteractiveLauncher(MyApp()).run()
The script will return, allowing an interpreter shell to continue running and
inspection or modification of the :class:`App` can be done safely through the
InteractiveLauncher instance or the provided SafeMembrane class instances.
Interactive Development
IPython provides a fast way to learn the kivy API. The :class:`App` instance
itself, all of it's attributes, including methods and the entire widget tree,
can be quickly listed by using the '.' operator and pressing 'tab.' Try this
code in an Ipython shell.::
from kivy.interactive import InteractiveLauncher
from imort App
from kivy.uix.widget import Widget
from import Color, Ellipse
class MyPaintWidget(Widget):
def on_touch_down(self, touch):
with self.canvas:
Color(1, 1, 0)
d = 30.
Ellipse(pos=(touch.x - d/2, touch.y - d/2), size=(d, d))
class TestApp(App):
def build(self):
return Widget()
i = InteractiveLauncher(TestApp())
i. # press 'tab' to list attributes of the app
i.root. # press 'tab' to list attributes of the root widget
# App is boring. Attach a new widget!
# The application is now blocked.
# Click on the screen several times.
# The clicks will show up now
# Erase artwork and start over
.. note::
All of the proxies used in the module store their referent in the
:attr:`_ref` attribute, which can be accessed directly if needed, such as
for getting doc strings. :func:`help` and :func:`type` will access the
proxy, not its referent.
Directly Pausing the Application
Both :class:`InteractiveLauncher` and :class:`SafeMembrane` hold internal
references to :class:`EventLoop`'s 'safe' and 'confirmed'
:class:`threading.Event` objects. You can use their safing methods to control
the application manually.
:meth:`Interactive.safeIn()` will cause the applicaiton to pause and
:meth:`InteractiveLauncher.safeOut()` will allow a paused application
to continue running. This is potentially useful for scripting actions into
functions that need the screen to update etc.
.. note::
The pausing is implemented via :meth:`kivy.clock.Clock.schedule_once` and
occurs before the start of each frame.
Adding Attributes Dynamically
.. note::
This module uses threading and object proxies to encapsulate the running
:class:`App`. Deadlocks and memory corruption can occur if making direct
references inside the thread without going through the provided proxy(s).
The :class:`InteractiveLauncher` can have attributes added to it exactly like a
normal object, and if these were created from outside the membrane, they will
not be threadsafe because the external references to them in the python
interpreter do not go through InteractiveLauncher's membrane behavior, inherited
from SafeMembrane.
To threadsafe these external referencess, simply assign them to SafeMembrane
instances of themselves like so::
from kivy.interactive import SafeMembrane
interactiveLauncher.attribute = myNewObject
# myNewObject is unsafe
myNewObject = SafeMembrane(myNewObject)
# myNewObject is now safe. Call at will.
Unit tests, an example, and more understanding of which methods are safe in a
running application would be nice. All three would be excellent.
Could be re-written with a context-manager style, ie::
with safe:
Any use cases besides compacting code?
__all__ = ('SafeMembrane', 'InteractiveLauncher')
from import App
from kivy.base import EventLoop
from kivy.clock import Clock
from threading import Thread, Event
def safeWait(dt):
def unwrap(ob):
while type(ob) == SafeMembrane:
ob = ob._ref
return ob
class SafeMembrane(object):
This help is for a proxy object. Did you want help on the proxy's referent
instead? Try using help(<instance>._ref)
Threadsafe proxy that also returns attributes as new thread-safe objects
and makes thread-safe method calls, preventing thread-unsafe objects
from leaking into the user's environment.
__slots__ = ('_ref', 'safe', 'confirmed')
def __init__(self, ob, *args, **kwargs):
self.confirmed = EventLoop.confirmed =
self._ref = ob
def safeIn(self):
Clock.schedule_once(safeWait, -1)
def safeOut(self):
def isMethod(self, fn):
return type(fn) is type(self.isMethod)
# Everything from this point on is just a series of thread-safing proxy
# methods that make calls against _ref and threadsafe whenever data will be
# written to or if a method will be called. SafeMembrane instances should
# be unwrapped whenever passing them into the thread
#use type() to determine if an object is a SafeMembrane while debugging
def __repr__(self):
return self._ref.__repr__()
def __call__(self, *args, **kw):
args = map(unwrap, args)
for k in kw.keys():
kw[k] = unwrap(kw[k])
r = self._ref(*args, **kw)
if r is not None:
return SafeMembrane(r)
def __getattribute__(self, attr, oga=object.__getattribute__):
if attr.startswith('__') or attr == '_ref':
subject = oga(self, '_ref')
if attr == '_ref':
return subject
return getattr(subject, attr)
return oga(self, attr)
def __getattr__(self, attr, oga=object.__getattribute__):
r = getattr(oga(self, '_ref'), attr)
return SafeMembrane(r)
def __setattr__(self, attr, val, osa=object.__setattr__):
if (attr == '_ref'
or hasattr(type(self), attr) and not attr.startswith('__')):
osa(self, attr, val)
val = unwrap(val)
setattr(self._ref, attr, val)
def __delattr__(self, attr, oda=object.__delattr__):
delattr(self._ref, attr)
def __nonzero__(self):
return bool(self._ref)
def __getitem__(self, arg):
return SafeMembrane(self._ref[arg])
def __setitem__(self, arg, val):
val = unwrap(val)
self._ref[arg] = val
def __delitem__(self, arg):
del self._ref[arg]
def __getslice__(self, i, j):
return SafeMembrane(self._ref[i:j])
def __setslice__(self, i, j, val):
val = unwrap(val)
self._ref[i:j] = val
def __delslice__(self, i, j):
del self._ref[i:j]
def __enter__(self, *args, **kwargs):
self._ref.__enter__(*args, **kwargs)
def __exit__(self, *args, **kwargs):
self._ref.__exit__(*args, **kwargs)
class InteractiveLauncher(SafeMembrane):
Proxy to an application instance that launches it in a thread and
then returns and acts as a proxy to the application in the thread
__slots__ = ('_ref', 'safe', 'confirmed', 'thread', 'app')
def __init__(self, app=None, *args, **kwargs):
if app is None:
app = App() = Event() =
EventLoop.confirmed = Event()
self.confirmed = EventLoop.confirmed = app
def startApp(app=app, *args, **kwargs):*args, **kwargs)
self.thread = Thread(target=startApp, *args, **kwargs)
def run(self):
#Proxy behavior starts after this is set. Before this point, attaching
#widgets etc can only be done through the Launcher's app attribute
self._ref =
def stop(self):
EventLoop.quit = True
#Act like the app instance even before _ref is set
def __repr__(self):
Jump to Line
Something went wrong with that request. Please try again.