Source code for pyface.application
# (C) Copyright 2005-2023 Enthought, Inc., Austin, TX
# All rights reserved.
#
# This software is provided without warranty under the terms of the BSD
# license included in LICENSE.txt and may be redistributed only under
# the conditions described in the aforementioned license. The license
# is also available online at http://www.enthought.com/licenses/BSD.txt
#
# Thanks for using Enthought open source!
"""
This module defines the :py:class:`Application` class for Pyface, Tasks
and similar applications. Although the primary use cases are for GUI
applications, the :py:class:`Application` class does not have any explicit
dependency on GUI code, and can be used for CLI or server applications.
Usual usage is to subclass :py:class:`Application`, overriding at least the
:py:meth:`Application._run` method, but usually the
:py:meth:`Application.start` and :py:meth:`Application.stop`
methods as well.
However the class can be used as-is by listening to the
:py:attr:`Application.application_initialized` event and performing
appropriate work there::
def do_work(event):
print("Hello world")
app = Application()
app.observe(do_work, 'application_initialized')
"""
import logging
import os
from traits.api import (
Directory,
Event,
HasStrictTraits,
Instance,
ReadOnly,
Str,
Vetoable,
VetoableEvent,
)
logger = logging.getLogger(__name__)
[docs]class ApplicationException(Exception):
""" Exception subclass for Application-centric exceptions """
pass
[docs]class ApplicationExit(ApplicationException):
""" Exception which indicates application should try to exit.
If no arguments, then assumed to be a normal exit, otherwise the arguments
give information about the problem.
"""
pass
[docs]class ApplicationEvent(HasStrictTraits):
""" An event associated with an application """
#: The application that the event happened to.
application = ReadOnly
#: The type of application event.
event_type = ReadOnly
[docs]class Application(HasStrictTraits):
""" A base class for applications.
This class handles the basic lifecycle of an application and a few
fundamental facilities. It is suitable as a base for any application,
not just GUI applications.
"""
# 'Application' traits ----------------------------------------------------
# Branding ----------------------------------------------------------------
#: Human-readable application name
name = Str("Pyface Application")
#: Human-readable company name
company = Str()
#: Human-readable description of the application
description = Str()
# Infrastructure ---------------------------------------------------------
#: The application's globally unique identifier.
id = Str()
#: Application home directory (for preferences, logging, etc.)
home = Directory()
#: User data directory (for user files, projects, etc)
user_data = Directory()
# Application lifecycle --------------------------------------------------
#: Fired when the application is starting. Called immediately before the
#: start method is run.
starting = Event(Instance(ApplicationEvent))
#: Upon successful completion of the start method.
started = Event(Instance(ApplicationEvent))
#: Fired after the GUI event loop has been started during the run method.
application_initialized = Event(Instance(ApplicationEvent))
#: Fired when the application is starting. Called immediately before the
#: stop method is run.
exiting = VetoableEvent()
#: Fired when the application is starting. Called immediately before the
#: stop method is run.
stopping = Event(Instance(ApplicationEvent))
#: Upon successful completion of the stop method.
stopped = Event(Instance(ApplicationEvent))
# -------------------------------------------------------------------------
# Application interface
# -------------------------------------------------------------------------
# Application lifecycle methods ------------------------------------------
[docs] def start(self):
""" Start the application, setting up things that are required
Subclasses should call the superclass start() method before doing any
work themselves.
"""
return True
[docs] def stop(self):
""" Stop the application, cleanly releasing resources if possible.
Subclasses should call the superclass stop() method after doing any
work themselves.
"""
return True
[docs] def run(self):
""" Run the application.
Return
------
status : bool
Whether or not the application ran normally
"""
run = stopped = False
# Start up the application.
logger.info("---- Application starting ----")
self._fire_application_event("starting")
started = self.start()
if started:
logger.info("---- Application started ----")
self._fire_application_event("started")
try:
run = self._run()
except ApplicationExit as exc:
if exc.args == ():
logger.info("---- ApplicationExit raised ----")
else:
logger.exception("---- ApplicationExit raised ----")
run = exc.args == ()
finally:
# Try to shut the application down.
logger.info("---- Application stopping ----")
self._fire_application_event("stopping")
stopped = self.stop()
if stopped:
self._fire_application_event("stopped")
logger.info("---- Application stopped ----")
return started and run and stopped
[docs] def exit(self, force=False):
""" Exits the application.
This method handles a request to shut down the application by the user,
eg. from a menu. If force is False, the application can potentially
veto the close event, leaving the application in the state that it was
before the exit method was called.
Parameters
----------
force : bool, optional (default False)
If set, windows will receive no closing events and will be
destroyed unconditionally. This can be useful for reliably tearing
down regression tests, but should be used with caution.
Raises
------
ApplicationExit
Some subclasses may trigger the exit by raising ApplicationExit.
"""
logger.info("---- Application exit started ----")
if force or self._can_exit():
try:
self._prepare_exit()
except Exception:
logger.exception("Error preparing for application exit")
finally:
logger.info("---- Application exit ----")
self._exit()
else:
logger.info("---- Application exit vetoed ----")
# Initialization utilities -----------------------------------------------
[docs] def initialize_application_home(self):
""" Set up the home directory for the application
This is where logs, preference files and other config files will be
stored.
"""
if not os.path.exists(self.home):
logger.info("Application home directory does not exist, creating")
os.makedirs(self.home)
# -------------------------------------------------------------------------
# Private interface
# -------------------------------------------------------------------------
# Main method -------------------------------------------------------------
def _run(self):
""" Actual implementation of running the application
This should be completely overriden by applications which want to
actually do something. Usually this method starts an event loop and
blocks, but for command-line applications this could be where the
main application logic is called from.
"""
# Fire a notification that the app is running. If the app has an
# event loop (eg. a GUI, Tornado web app, etc.) then this should be
# fired _after_ the event loop starts using an appropriate callback
# (eg. gui.set_trait_later).
self._fire_application_event("application_initialized")
return True
# Utilities ---------------------------------------------------------------
def _fire_application_event(self, event_type):
event = ApplicationEvent(application=self, event_type=event_type)
setattr(self, event_type, event)
# Destruction methods -----------------------------------------------------
def _can_exit(self):
""" Is exit vetoed by anything?
The default behaviour is to fire the :py:attr:`exiting` event and check
to see if any listeners veto. Subclasses may wish to override to
perform additional checks.
Returns
-------
can_exit : bool
Return True if exit is OK, False if something vetoes the exit.
"""
self.exiting = event = Vetoable()
return not event.veto
def _prepare_exit(self):
""" Do any application-level state saving and clean-up
Subclasses should override this method.
"""
pass
def _exit(self):
""" Shut down the application
This is where application event loops and similar should be shut down.
"""
# invoke a normal exit from the application
raise ApplicationExit()
# Traits defaults ---------------------------------------------------------
def _id_default(self):
""" Use the application's directory as the id """
from traits.etsconfig.api import ETSConfig
return ETSConfig._get_application_dirname()
def _home_default(self):
""" Default home comes from ETSConfig. """
from traits.etsconfig.api import ETSConfig
return os.path.join(ETSConfig.application_data, self.id)
def _user_data_default(self):
""" Default user_data comes from ETSConfig. """
from traits.etsconfig.api import ETSConfig
return ETSConfig.user_data
def _company_default(self):
""" Default company comes from ETSConfig. """
from traits.etsconfig.api import ETSConfig
return ETSConfig.company
def _description_default(self):
""" Default description is the docstring of the application class. """
from inspect import getdoc
text = getdoc(self)
return text