More documentation improvements.

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

diff --git a/wizard/app/__init__.py b/wizard/app/__init__.py
index 83954396562bf08747a8f0e4813fb43ffb0abbd8..0e6bd1aac76c440f0e0e0f3b2c9bd9ac069f5984 100644 (file)
--- a/wizard/app/__init__.py
+++ b/wizard/app/__init__.py
@@ -6,6 +6,11 @@ You'll need to know how to overload the :class:`Application` class
 and use some of the functions in this module in order to specify
 new applications.
 
+There are some submodules for programming languages that define common
+functions and data that may be used by applications in that language.  See:
+
+* :mod:`wizard.app.php`
+
 .. testsetup:: *
 
     import re
@@ -76,6 +81,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 +193,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 +201,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 +214,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 +222,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,7 +251,7 @@ 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
@@ -247,7 +261,7 @@ class Application(object):
         # 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 NotImplemented
+        raise NotImplementedError
     @staticmethod
     def make(name):
         """Makes an application, but uses the correct subtype if available."""
@@ -355,7 +369,7 @@ def expand_re(val):
 
 def make_extractors(seed):
     """
-    Take a dictionary of ``key``s to ``(file, regex)`` tuples and convert them into
+    Take a dictionary of ``key`` to ``(file, regex)`` tuples and convert them into
     extractor functions (which take a :class:`wizard.deploy.Deployment`
     and return the value of the second subpattern of ``regex`` when matched
     with the contents of ``file``).
@@ -364,7 +378,7 @@ def make_extractors(seed):
 
 def make_substitutions(seed):
     """
-    Take a dictionary of ``key``s to ``(file, regex)`` tuples and convert them into substitution
+    Take a dictionary of ``key`` to ``(file, regex)`` tuples and convert them into substitution
     functions (which take a :class:`wizard.deploy.Deployment`, replace the second subpattern
     of ``regex`` with ``key`` in ``file``, and returns the number of substitutions made.)
     """
@@ -516,6 +530,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