Expand documentation.

[wizard.git] / wizard / app / __init__.py

diff --git a/wizard/app/__init__.py b/wizard/app/__init__.py
index 74d99bd6ccb3fc5b45c9c3292127875161f1316c..929cacfb35c66715e3ba2999da46cafaf875e243 100644 (file)
--- a/wizard/app/__init__.py
+++ b/wizard/app/__init__.py
@@ -76,6 +76,9 @@ class Application(object):
     #: a conflict marker string and a result list.  See :mod:`wizard.resolve`
     #: for more information.
     resolutions = {}
+    #: Instance of :class:`wizard.install.ArgSchema` that defines the arguments
+    #: this application requires.
+    install_schema = None
     def __init__(self, name):
         self.name = name
         self.versions = {}
@@ -185,7 +188,7 @@ class Application(object):
         take a :class:`wizard.deploy.Deployment` as a parameter.)  Subclasses should
         provide an implementation.
         """
-        raise NotImplemented
+        raise NotImplementedError
     def upgrade(self, deployment, version, options):
         """
         Run for 'wizard upgrade' to upgrade database schemas and other
@@ -193,7 +196,7 @@ class Application(object):
         upgraded.  This assumes that the current working directory is the
         deployment.  Subclasses should provide an implementation.
         """
-        raise NotImplemented
+        raise NotImplementedError
     def backup(self, deployment, outdir, options):
         """
         Run for 'wizard backup' and upgrades to backup database schemas
@@ -206,7 +209,7 @@ class Application(object):
             Static user files may not need to be backed up, since in
             many applications upgrades do not modify static files.
         """
-        raise NotImplemented
+        raise NotImplementedError
     def restore(self, deployment, backup_dir, options):
         """
         Run for 'wizard restore' and failed upgrades to restore database
@@ -214,14 +217,20 @@ class Application(object):
         that the current working directory is the deployment.  Subclasses
         should provide an implementation.
         """
-        raise NotImplemented
+        raise NotImplementedError
     def detectVersion(self, deployment):
         """
         Checks source files to determine the version manually.  This assumes
         that the current working directory is the deployment.  Subclasses
         should provide an implementation.
         """
-        raise NotImplemented
+        raise NotImplementedError
+    def download(self, version):
+        """
+        Returns a URL that can be used to download a tarball of ``version`` of
+        this application.
+        """
+        raise NotImplementedError
     def checkWeb(self, deployment, output=None):
         """
         Checks if the autoinstall is viewable from the web.  To get
@@ -237,14 +246,17 @@ class Application(object):
             page does not contain the features you search for.  Try
             not to depend on pages that are not the main page.
         """
-        raise NotImplemented
+        raise NotImplementedError
     def checkConfig(self, deployment):
         """
         Checks whether or not an autoinstall has been configured/installed
         for use.  Assumes that the current working directory is the deployment.
         Subclasses should provide an implementation.
         """
-        raise NotImplemented
+        # XXX: Unfortunately, this doesn't quite work because we package
+        # bogus config files in the -scripts versions of installs.  Maybe
+        # we should check a hash or something?
+        raise NotImplementedError
     @staticmethod
     def make(name):
         """Makes an application, but uses the correct subtype if available."""
@@ -461,9 +473,10 @@ def filename_regex_substitution(key, files, regex):
         return subs
     return h
 
+# XXX: rename to show that it's mysql specific
 def backup_database(outdir, deployment):
     """
-    Generic database backup function.  Assumes that ``WIZARD_DBNAME``
+    Generic database backup function for MySQL.  Assumes that ``WIZARD_DBNAME``
     is extractable, and that :func:`wizard.scripts.get_sql_credentials`
     works.
     """
@@ -477,6 +490,10 @@ def backup_database(outdir, deployment):
         raise BackupFailure(e.stderr)
 
 def restore_database(backup_dir, deployment):
+    """
+    Generic database restoration function for MySQL.  See :func:`backup_database`
+    for the assumptions that we make.
+    """
     sh = shell.Shell()
     if not os.path.exists(backup_dir):
         raise RestoreFailure("Backup %s doesn't exist", backup_dir.rpartition("/")[2])
@@ -487,6 +504,10 @@ def restore_database(backup_dir, deployment):
     sql.close()
 
 def get_mysql_args(d):
+    """
+    Extracts arguments that would be passed to the command line mysql utility
+    from a deployment.
+    """
     # XXX: add support for getting these out of options
     vars = d.extract()
     if 'WIZARD_DBNAME' not in vars:
@@ -504,6 +525,19 @@ class Error(wizard.Error):
     """Generic error class for this module."""
     pass
 
+class RecoverableFailure(Error):
+    """
+    The installer failed, but we were able to determine what the
+    error was, and should give the user a second chance if we were
+    running interactively.
+    """
+    #: List of the errors that were found.
+    errors = None
+    def __init__(self, errors):
+        self.errors = errors
+    def __str__(self):
+        return """Installation failed due to the following errors: %s""" % ", ".join(self.errors)
+
 class NoRepositoryError(Error):
     """
     :class:`Application` does not appear to have a Git repository