The top-level enaml package contains modules used throughout the Enaml library.
Bases: object
An object representing a task in the scheduler.
A sentinel object indicating that the result of the task is undefined or that the task has not yet been executed.
Set a callback to be run when the task is executed.
Parameters: | callback (callable) – A callable which accepts a single argument which is the results of the task. It will be invoked immediate after the task is executed, on the main event loop thread. |
---|
Unschedule the task so that it will not be executed. If the task has already been executed, this call has no effect.
Returns the result of the task, or ScheduledTask.undefined if the task has not yet been executed, was unscheduled before execution, or raised an exception on execution.
list of weak references to the object (if defined)
Bases: object
The application object which manages the top-level communication protocol for serving Enaml views.
alias of ABCMeta
Get the global Application instance.
Returns: | result (Application or None) – The global application instance, or None if one has not yet been created. |
---|
Create a new Enaml Application.
There may be only one application instance in existence at any point in time. Attempting to create a new Application when one exists will raise an exception.
Initialize an Enaml Application.
Parameters: | factories (iterable) – An iterable of SessionFactory instances that will be used to create the sessions for the application. |
---|
Start a new session of the given name.
This method will create a new session object for the requested session type and return the new session_id. If the session name is invalid, an exception will be raised.
Parameters: | name (str) – The name of the session to start. |
---|---|
Returns: | result (str) – The unique identifier for the created session. |
End the session with the given session id.
This method will close down the existing session. If the session id is not valid, an exception will be raised.
Parameters: | session_id (str) – The unique identifier for the session to close. |
---|
Get the session for the given session id.
Parameters: | session_id (str) – The unique identifier for the session to retrieve. |
---|---|
Returns: | result (Session or None) – The session object with the given id, or None if the id does not correspond to an active session. |
Get the currently active sessions for the application.
Returns: | result (list) – The list of currently active sessions for the application. |
---|
Invoke a callable on the next cycle of the main event loop thread.
Parameters: | callback (callable) – The callable object to execute at some point in the future. |
---|
Invoke a callable on the main event loop thread at a specified time in the future.
Parameters: |
---|
Indicates whether the caller is on the main gui thread.
Returns: | result (bool) – True if called from the main gui thread. False otherwise. |
---|
Schedule a callable to be executed on the event loop thread.
This call is thread-safe.
Parameters: |
|
---|---|
Returns: | result (ScheduledTask) – A task object which can be used to unschedule the task or retrieve the results of the callback after the task has been executed. |
Get whether or not the application has pending tasks.
Returns: | result (bool) – True if there are pending tasks. False otherwise. |
---|
Add session factories to the application.
Parameters: | factories (iterable) – An iterable of SessionFactory instances to add to the application. |
---|
Get a dictionary of session information for the application.
Returns: | result (list) – A list of dicts of information about the available sessions. |
---|
Destroy this application instance.
Once an application is created, it must be destroyed before a new application can be instantiated.
list of weak references to the object (if defined)
Invoke a callable on the next cycle of the main event loop thread.
This is a convenience function for invoking the same method on the current application instance. If an application instance does not exist, a RuntimeError will be raised.
Parameters: | callback (callable) – The callable object to execute at some point in the future. |
---|
Invoke a callable on the main event loop thread at a specified time in the future.
This is a convenience function for invoking the same method on the current application instance. If an application instance does not exist, a RuntimeError will be raised.
Parameters: |
---|
Indicates whether the caller is on the main gui thread.
This is a convenience function for invoking the same method on the current application instance. If an application instance does not exist, a RuntimeError will be raised.
Returns: | result (bool) – True if called from the main gui thread. False otherwise. |
---|
Schedule a callable to be executed on the event loop thread.
This call is thread-safe.
This is a convenience function for invoking the same method on the current application instance. If an application instance does not exist, a RuntimeError will be raised.
Parameters: |
|
---|---|
Returns: | result (ScheduledTask) – A task object which can be used to unschedule the task or retrieve the results of the callback after the task has been executed. |
Bases: object
An object which will weakly wrap a callable object.
This class is useful when weakrefs to callable objects need to be used alongside regular callables. It exposes a callable interface which will dererence the underlying callable before calling it.
Initialize a CallableRef.
Parameters: |
|
---|
Note
Instances of this class will compare equally to equivalent CallableRef instances as well as weakref instances which compare equally to the internal weakref.
A utility module for dealing with colors.
Parse a color string into a tuple of RGBA values.
Parameters: | color (string) – A CSS3 string representation of the color. |
---|---|
Returns: | result (tuple or None) – A tuple of RGBA values. All values are floats in the range 0.0 - 1.0. If the string is invalid, None will be returned. |
Bases: traits.has_traits.HasTraits
An object representing an image in an icon.
Instances of this class are used to populate the images list of an Icon instance. Instances of this class should be treated as read-only once they are created.
The widget mode for which this icon should apply.
The widget state for which this icon should apply.
The image to use for this icon.
alias of __NoInterface__
Bases: enaml.resource.Resource
A resource object representing an icon.
Instances of this class are created by an IconProvider when it handles a request for an icon. Instances of this class should be treated as read-only once they are created.
The list of icon images which compose this icon.
alias of __NoInterface__
Bases: object
An abstract API definition for an icon provider object.
alias of ABCMeta
Request an icon from this provider.
Parameters: |
|
---|
list of weak references to the object (if defined)
Bases: enaml.resource.Resource
A resource object representing an image.
Instances of this class are created by an ImageProvider when it handles a request for an image. Instances of this class should be treated as read-only once they are created.
The format of the image. By default, the consumer of the image will probe the header to automatically infer a type.
The (width, height) size of the image. An invalid size indicates that the size of the image should be automatically inferred.
The bytestring holding the data for the image.
alias of __NoInterface__
Bases: object
An abstract API definition for an image provider object.
alias of ABCMeta
Request an image from this provider.
Parameters: |
|
---|
list of weak references to the object (if defined)
Bases: traits.has_traits.HasTraits
A base class to use for creating resource objects.
Get a snapshot dictionary for this resource.
Subclass should reimplement this method to add more metadata to the snapshot dictionary.
alias of __NoInterface__
Bases: traits.has_traits.HasTraits
A class which manages resource loading for a Session.
A ResourceManager is used by a Session object to load resources when a url resource request is made by a client session. Users work with the manager by assigning provider objects associated with a host name. For example, a user can provide an image for the url image://filesystem/c:/foo/bar.png by assigning an ImageProvider instace to the image_providers dict with the key filesystem.
A dict mapping provider location to image provider object. When a resource image://foo/bar/baz is requested, the image provider provider foo is use to request path /bar/baz.
A dict of icon providers for the icon://... scheme.
Load a resource from the manager.
Parameters: |
|
---|
alias of __NoInterface__
Command-line tool to run .enaml files.
The set of actions which should be batched and sent to the client as a single message. This allows a client to perform intelligent message handling when dealing with messages that may affect the widget tree.
The dispatch function for action dispatching on the session.
Bases: object
A class which aggregates batch messages.
Each time a message is added to this object, its tick count is incremented and a tick down event is posted to the event queue. When the object receives the tick down event, it decrements its tick count, and if it’s zero, fires the triggered signal.
This allows a consumer of the batch to continually add messages and have the triggered signal fired only when the event queue is fully drained of relevant messages.
A signal emitted when the tick count of the batch reaches zero and the owner of the batch should consume the messages.
Release the messages that were added to the batch.
Returns: | result (list) – The list of messages added to the batch. |
---|
Add a message to the batch.
This will cause the batch to tick up and then start the tick down process if necessary.
Parameters: | message (object) – The message object to add to the batch. |
---|
list of weak references to the object (if defined)
Bases: object
A reply object for sending a loaded resource to a client session.
Initialize a URLReply.
Parameters: |
|
---|
Bases: traits.has_traits.HasTraits
An object representing the session between a client and its Enaml objects.
The session object is what ensures that each client has their own individual instances of objects, so that the only state that is shared between simultaneously existing clients is that which is explicitly provided by the developer.
The string identifier for this session. This is provided by the application when the session is opened. The value should not be manipulated by user code.
The top level windows which are managed by this session. This should be populated by user code during the on_open method.
The widget implementation groups which should be used by the widgets in this session. Widget groups are an advanced feature which allow the developer to selectively expose toolkit specific implementations of Enaml widgets. All standard Enaml widgets are available in the ‘default’ group. This value will rarely need to be changed by the user.
A resource manager used for loading resources for the session.
The socket used by this session for communication. This is provided by the Application when the session is activated. The value should not normally be manipulated by user code.
The current state of the session. This value is changed by the by the application as it drives the session through its lifetime. This should not be manipulated directly by user code.
A read-only property which is True if the session is inactive.
A read-only property which is True if the session is opening.
A read-only property which is True if the session is opened.
A read-only property which is True if the session is activating.
A read-only property which is True if the session is active.
A read-only property which is True if the session is closing.
A read-only property which is True if the session is closed.
Get a SessionFactory instance for this Session class.
Parameters: |
|
---|
Called by the application when the session is opened.
This method must be implemented in a subclass and is called to create the Enaml objects for the session. This method will only be called once during the session lifetime. User code should create their windows and assign them to the list of windows before the method returns.
Called by the application when the session is closed.
This method may be optionally implemented by subclasses so that they can perform custom cleaup. After this method returns, the session should be considered invalid. This method is only called once during the session lifetime.
Called by the application to open the session.
This method will call the on_open abstract method which must be implemented by subclasses. The method should never be called by user code.
Parameters: | session_id (str) – The unique identifier to use for this session. |
---|
Called by the application to activate the session and its windows.
This method will be called by the Application once during the session lifetime. Once this method returns, the session and its objects will be ready to send and receive messages. This should never be called by user code.
Parameters: | socket (ActionSocketInterface) – A concrete implementation of ActionSocketInterface to use for messaging by this session. |
---|
Called by the application when the session is closed.
This method will call the on_close method which can optionally be implemented by subclasses. The method should never be called by user code.
Get a snapshot of the windows of this session.
Returns: | result (list) – A list of snapshots representing the current windows for this session. |
---|
Register an object with the session.
This method is called by an Object when it is activated by a Session. It should never be called by user code.
Parameters: | obj (Object) – The object to register with the session. |
---|
Unregister an object from the session.
This method is called by an Object when it is being destroyed. It should never be called by user code.
Parameters: | obj (Object) – The object to unregister from the session. |
---|
Send a message to a client object.
This method is called by the Object instances owned by this session to send messages to their client implementations.
Parameters: |
---|
Receive a message sent to an object owned by this session.
This is a handler method registered as the callback for the action socket. The message will be routed to the appropriate Object instance.
Parameters: |
---|
alias of __NoInterface__
Bases: object
A class whose instances are used by an Enaml Application to create Session instances.
Initialize a SessionFactory.
Parameters: |
---|
Called by the Enaml Application to create an instance of the Session.
Returns: | result (Session) – A new instance of the Session type provided to the factory. |
---|
list of weak references to the object (if defined)
A descriptor which provides notification functionality similar to Qt signals and slots.
A Signal is used by creating an instance in the body of a class definition. Slots (callables) are connected to the signal through the connect and disconnect methods. A signal can be emitted by calling the emit method passing arbitrary positional and keyword arguments.
If a bound method is connected to a signal, then that slot will be automatically disconnected when the underlying object instance is garbage collected.
Bases: object
A bound Signal object.
Instances of this class are created on the fly by a Signal. This class performs the actual work for connecting, disconnecting, and emitting signals.
Initialize a BoundSignal.
Parameters: |
|
---|
Custom equality checking for a BoundSignal.
A BoundSignal will compare equal to another BoundSignal if the unerlying Signal and object reference are equal. This equality is part of the mechanism which allows a signal to be connected to another signal.
Custom call support for a BoundSignal.
Calling a signal is indentical invoking the emit method. By making a signal callable, it is possible to directly connect a signal to another signal.
Emit the signal with the given arguments and keywords.
If a connected slot raises an exceptions, no further slots will be invoked and the exception will be bubbled up.
Connect the given slot to the signal.
The slot will be called when the signal is emitted. It will be passed any positional and keyword arguments that were emitted with the signal. Multiple slots connected to a signal will be invoked in the order in which they were connected. Slots which are instance methods will be automatically disconnected when their underlying instance is garbage collected.
Parameters: | slot (callable) – The callable slot to invoke when the signal is emitted. |
---|
Bases: object
An abstract base class defining an action socket interface.
Concrete implementations of this interface can be used by Session instances to send and recieve messages to and from their client objects.
alias of ABCMeta
Register a callback for receiving messages sent by a client object.
Parameters: | callback (callable) – A callable with an argument signature that is equivalent to the send method. If the callback is a bound method, then the lifetime of the callback will be bound to lifetime of the method owner object. |
---|
list of weak references to the object (if defined)
An amalgamation of utilities used throughout the Enaml framework.
A unique identifier generator.
For a given stem, the returned generator is guaranteed to yield consecutively increasing identifiers using a randomly ordered base 62 charset. The identifiers are only guaranteed unique for a given instance of the generator. The randomness is employed to improve the hashing characteristics of the returned identifiers.
Parameters: | stem (str) – A string stem to prepend to a incrementing integer value. |
---|
Bases: object
A context manager generated by LoopbackGuard.
Instances of this class manage acquiring and releasing the lock items for instances of LoopbackGuard.
Bases: object
A guard object to protect against feedback loops.
Instances of this class are used by objects to protect against loopback conditions while updating attributes. Instances of this class are callable and return a guarding context manager for the provided lock items. The guard can be tested for a locked item using the in keyword.
Return a context manager which will guard the given items.
Returns: | result (LoopbackContext) – A context manager which will acquire the guard for the provided items. |
---|
Returns whether or not the given item is currently guarded.
Parameters: | item (object) – The item to check for guarded state. |
---|---|
Returns: | result (bool) – True if the item is currently guarded, False otherwise. |
Acquire the guard for the given items.
This method is normally called by the LoopbackContext returned by calling this instance. User code should not typically call this method directly. It is safe to call this method multiple times for and item, provided it is paired with the same number of calls to release(...). The guard will be released when the acquired count on the item reaches zeros.
Parameters: | items (iterable) – An iterable of objects for which to acquire the guard. The items must be hashable. |
---|
Release the guard for the given lock items.
This method is normally called by the LoopbackContext returned by calling this instance. User code should not normally call this method directly. It is safe to call this method multiple times for and item, provided it is paired with the same number of calls to acquire(...). The guard will be released when the acquired count on the item reaches zeros.
Parameters: | items (iterable) – An iterable of objects for which to release the guard. The items must be hashable. |
---|
Bases: dict
A dict subclass which exposes its keys as attributes.
list of weak references to the object (if defined)
A decorator which will catch errors raised by a function and convert them into log error messages.
When a decorated function raises an Exception, the return value will be None.
Create a function which will dispatch arguments to specially named handler methods on an object.
Parameters: |
|
---|---|
Returns: | result (types.FunctionType) – A function with the signature func(obj, name, *args). Calling it is equivalent to getattr(obj, prefix + name)(*args) |
The version information for this release of Enaml.
Bases: object
An object which weakly binds a method with a lifetime bound to the lifetime of the underlying object.
Instances of WeakMethod are also weakref-able with a lifetime which is also bound to lifetime of the method owner.
If multiple WeakMethods are requested for the same equivalent method object, the same WeakMethod will be returned. This behavior is the same as the standard weakref semantics.
Create a new WeakMethod instance or return an equivalent which already exists.
Parameters: | method (A bound method object) – The bound method which should be wrapped weakly. |
---|
Invoke the wrapped method by reconstructing the bound method from its components.
If the underlying instance object has been destroyed, this method will return None.
list of weak references to the object (if defined)