~bzr-pqm/bzr/bzr.dev

# Copyright (C) 2005, 2006, 2007, 2008 Canonical Ltd

#

# This program is free software; you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation; either version 2 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program; if not, write to the Free Software

# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

"""Exceptions for bzr, and reporting of them.

"""

from bzrlib import (

    osutils,

    symbol_versioning,

    )

from bzrlib.patches import (

    MalformedHunkHeader,

    MalformedLine,

    MalformedPatchHeader,

    PatchConflict,

    PatchSyntax,

    )

# TODO: is there any value in providing the .args field used by standard

# python exceptions?   A list of values with no names seems less useful 

# to me.

# TODO: Perhaps convert the exception to a string at the moment it's 

# constructed to make sure it will succeed.  But that says nothing about

# exceptions that are never raised.

# TODO: selftest assertRaises should probably also check that every error

# raised can be formatted as a string successfully, and without giving

# 'unprintable'.

# return codes from the bzr program

EXIT_OK = 0

EXIT_ERROR = 3

EXIT_INTERNAL_ERROR = 4

class BzrError(StandardError):

    """

    Base class for errors raised by bzrlib.

    :cvar internal_error: if True this was probably caused by a bzr bug and

    should be displayed with a traceback; if False (or absent) this was

    probably a user or environment error and they don't need the gory details.

    (That can be overridden by -Derror on the command line.)

    :cvar _fmt: Format string to display the error; this is expanded

    by the instance's dict.

    """

    internal_error = False

    def __init__(self, msg=None, **kwds):

        """Construct a new BzrError.

        There are two alternative forms for constructing these objects.

        Either a preformatted string may be passed, or a set of named

        arguments can be given.  The first is for generic "user" errors which

        are not intended to be caught and so do not need a specific subclass.

        The second case is for use with subclasses that provide a _fmt format

        string to print the arguments.  

        Keyword arguments are taken as parameters to the error, which can 

        be inserted into the format string template.  It's recommended 

        that subclasses override the __init__ method to require specific 

        parameters.

        :param msg: If given, this is the literal complete text for the error,

        not subject to expansion.

        """

        StandardError.__init__(self)

        if msg is not None:

            # I was going to deprecate this, but it actually turns out to be

            # quite handy - mbp 20061103.

            self._preformatted_string = msg

        else:

            self._preformatted_string = None

            for key, value in kwds.items():

                setattr(self, key, value)

    def __str__(self):

        s = getattr(self, '_preformatted_string', None)

        if s is not None:

            # contains a preformatted message; must be cast to plain str

            return str(s)

        try:

            fmt = self._get_format_string()

            if fmt:

                d = dict(self.__dict__)

                # special case: python2.5 puts the 'message' attribute in a

                # slot, so it isn't seen in __dict__

                d['message'] = getattr(self, 'message', 'no message')

                s = fmt % d

                # __str__() should always return a 'str' object

                # never a 'unicode' object.

                if isinstance(s, unicode):

                    return s.encode('utf8')

                return s

        except (AttributeError, TypeError, NameError, ValueError, KeyError), e:

            return 'Unprintable exception %s: dict=%r, fmt=%r, error=%r' \

                % (self.__class__.__name__,

                   self.__dict__,

                   getattr(self, '_fmt', None),

                   e)

    def _get_format_string(self):

        """Return format string for this exception or None"""

        fmt = getattr(self, '_fmt', None)

        if fmt is not None:

            return fmt

        fmt = getattr(self, '__doc__', None)

        if fmt is not None:

            symbol_versioning.warn("%s uses its docstring as a format, "

                    "it should use _fmt instead" % self.__class__.__name__,

                    DeprecationWarning)

            return fmt

        return 'Unprintable exception %s: dict=%r, fmt=%r' \

            % (self.__class__.__name__,

               self.__dict__,

               getattr(self, '_fmt', None),

               )

class InternalBzrError(BzrError):

    """Base class for errors that are internal in nature.

    This is a convenience class for errors that are internal. The

    internal_error attribute can still be altered in subclasses, if needed.

    Using this class is simply an easy way to get internal errors.

    """

    internal_error = True

class BzrNewError(BzrError):

    """Deprecated error base class."""

    # base classes should override the docstring with their human-

    # readable explanation

    def __init__(self, *args, **kwds):

        # XXX: Use the underlying BzrError to always generate the args

        # attribute if it doesn't exist.  We can't use super here, because

        # exceptions are old-style classes in python2.4 (but new in 2.5).

        # --bmc, 20060426

        symbol_versioning.warn('BzrNewError was deprecated in bzr 0.13; '

             'please convert %s to use BzrError instead'

             % self.__class__.__name__,

             DeprecationWarning,

             stacklevel=2)

        BzrError.__init__(self, *args)

        for key, value in kwds.items():

            setattr(self, key, value)

    def __str__(self):

        try:

            # __str__() should always return a 'str' object

            # never a 'unicode' object.

            s = self.__doc__ % self.__dict__

            if isinstance(s, unicode):

                return s.encode('utf8')

            return s

        except (TypeError, NameError, ValueError, KeyError), e:

            return 'Unprintable exception %s(%r): %r' \

                % (self.__class__.__name__,

                   self.__dict__, e)

class AlreadyBuilding(BzrError):

    _fmt = "The tree builder is already building a tree."

class BranchError(BzrError):

    """Base class for concrete 'errors about a branch'."""

    def __init__(self, branch):

        BzrError.__init__(self, branch=branch)

class BzrCheckError(InternalBzrError):

    _fmt = "Internal check failed: %(message)s"

    def __init__(self, message):

        BzrError.__init__(self)

        self.message = message

class DisabledMethod(InternalBzrError):

    _fmt = "The smart server method '%(class_name)s' is disabled."

    def __init__(self, class_name):

        BzrError.__init__(self)

        self.class_name = class_name

class IncompatibleAPI(BzrError):

    _fmt = 'The API for "%(api)s" is not compatible with "%(wanted)s". '\

        'It supports versions "%(minimum)s" to "%(current)s".'

    def __init__(self, api, wanted, minimum, current):

        self.api = api

        self.wanted = wanted

        self.minimum = minimum

        self.current = current

class InProcessTransport(BzrError):

    _fmt = "The transport '%(transport)s' is only accessible within this " \

        "process."

    def __init__(self, transport):

        self.transport = transport

class InvalidEntryName(InternalBzrError):

    _fmt = "Invalid entry name: %(name)s"

    def __init__(self, name):

        BzrError.__init__(self)

        self.name = name

class InvalidRevisionNumber(BzrError):

    _fmt = "Invalid revision number %(revno)s"

    def __init__(self, revno):

        BzrError.__init__(self)

        self.revno = revno

class InvalidRevisionId(BzrError):

    _fmt = "Invalid revision-id {%(revision_id)s} in %(branch)s"

    def __init__(self, revision_id, branch):

        # branch can be any string or object with __str__ defined

        BzrError.__init__(self)

        self.revision_id = revision_id

        self.branch = branch

class ReservedId(BzrError):

    _fmt = "Reserved revision-id {%(revision_id)s}"

    def __init__(self, revision_id):

        self.revision_id = revision_id

class RootMissing(InternalBzrError):

    _fmt = ("The root entry of a tree must be the first entry supplied to "

        "record_entry_contents.")

class NoPublicBranch(BzrError):

    _fmt = 'There is no public branch set for "%(branch_url)s".'

    def __init__(self, branch):

        import bzrlib.urlutils as urlutils

        public_location = urlutils.unescape_for_display(branch.base, 'ascii')

        BzrError.__init__(self, branch_url=public_location)

class NoHelpTopic(BzrError):

    _fmt = ("No help could be found for '%(topic)s'. "

        "Please use 'bzr help topics' to obtain a list of topics.")

    def __init__(self, topic):

        self.topic = topic

class NoSuchId(BzrError):

    _fmt = 'The file id "%(file_id)s" is not present in the tree %(tree)s.'

    def __init__(self, tree, file_id):

        BzrError.__init__(self)

        self.file_id = file_id

        self.tree = tree

class NoSuchIdInRepository(NoSuchId):

    _fmt = ('The file id "%(file_id)s" is not present in the repository'

            ' %(repository)r')

    def __init__(self, repository, file_id):

        BzrError.__init__(self, repository=repository, file_id=file_id)

class NotStacked(BranchError):

    _fmt = "The branch '%(branch)s' is not stacked."

class InventoryModified(InternalBzrError):

    _fmt = ("The current inventory for the tree %(tree)r has been modified,"

            " so a clean inventory cannot be read without data loss.")

    def __init__(self, tree):

        self.tree = tree

class NoWorkingTree(BzrError):

    _fmt = 'No WorkingTree exists for "%(base)s".'

    def __init__(self, base):

        BzrError.__init__(self)

        self.base = base

class NotBuilding(BzrError):

    _fmt = "Not currently building a tree."

class NotLocalUrl(BzrError):

    _fmt = "%(url)s is not a local path."

    def __init__(self, url):

        self.url = url

class WorkingTreeAlreadyPopulated(InternalBzrError):

    _fmt = 'Working tree already populated in "%(base)s"'

    def __init__(self, base):

        self.base = base

class BzrCommandError(BzrError):

    """Error from user command"""

    # Error from malformed user command; please avoid raising this as a

    # generic exception not caused by user input.

    #

    # I think it's a waste of effort to differentiate between errors that

    # are not intended to be caught anyway.  UI code need not subclass

    # BzrCommandError, and non-UI code should not throw a subclass of

    # BzrCommandError.  ADHB 20051211

    def __init__(self, msg):

        # Object.__str__() must return a real string

        # returning a Unicode string is a python error.

        if isinstance(msg, unicode):

            self.msg = msg.encode('utf8')

        else:

            self.msg = msg

    def __str__(self):

        return self.msg

class NotWriteLocked(BzrError):

    _fmt = """%(not_locked)r is not write locked but needs to be."""

    def __init__(self, not_locked):

        self.not_locked = not_locked

class BzrOptionError(BzrCommandError):

    _fmt = "Error in command line options"

class BadIndexFormatSignature(BzrError):

    _fmt = "%(value)s is not an index of type %(_type)s."

    def __init__(self, value, _type):

        BzrError.__init__(self)

        self.value = value

        self._type = _type

class BadIndexData(BzrError):

    _fmt = "Error in data for index %(value)s."

    def __init__(self, value):

        BzrError.__init__(self)

        self.value = value

class BadIndexDuplicateKey(BzrError):

    _fmt = "The key '%(key)s' is already in index '%(index)s'."

    def __init__(self, key, index):

        BzrError.__init__(self)

        self.key = key

        self.index = index

class BadIndexKey(BzrError):

    _fmt = "The key '%(key)s' is not a valid key."

    def __init__(self, key):

        BzrError.__init__(self)

        self.key = key

class BadIndexOptions(BzrError):

    _fmt = "Could not parse options for index %(value)s."

    def __init__(self, value):

        BzrError.__init__(self)

        self.value = value

class BadIndexValue(BzrError):

    _fmt = "The value '%(value)s' is not a valid value."

    def __init__(self, value):

        BzrError.__init__(self)

        self.value = value

class BadOptionValue(BzrError):

    _fmt = """Bad value "%(value)s" for option "%(name)s"."""

    def __init__(self, name, value):

        BzrError.__init__(self, name=name, value=value)

class StrictCommitFailed(BzrError):

    _fmt = "Commit refused because there are unknown files in the tree"

# XXX: Should be unified with TransportError; they seem to represent the

# same thing

# RBC 20060929: I think that unifiying with TransportError would be a mistake

# - this is finer than a TransportError - and more useful as such. It 

# differentiates between 'transport has failed' and 'operation on a transport

# has failed.'

class PathError(BzrError):

    _fmt = "Generic path error: %(path)r%(extra)s)"

    def __init__(self, path, extra=None):

        BzrError.__init__(self)

        self.path = path

        if extra:

            self.extra = ': ' + str(extra)

        else:

            self.extra = ''

class NoSuchFile(PathError):

    _fmt = "No such file: %(path)r%(extra)s"

class FileExists(PathError):

    _fmt = "File exists: %(path)r%(extra)s"

class RenameFailedFilesExist(BzrError):

    """Used when renaming and both source and dest exist."""

    _fmt = ("Could not rename %(source)s => %(dest)s because both files exist."

            " (Use --after to tell bzr about a rename that has already"

            " happened)%(extra)s")

    def __init__(self, source, dest, extra=None):

        BzrError.__init__(self)

        self.source = str(source)

        self.dest = str(dest)

        if extra:

            self.extra = ' ' + str(extra)

        else:

            self.extra = ''

class NotADirectory(PathError):

    _fmt = '"%(path)s" is not a directory %(extra)s'

class NotInWorkingDirectory(PathError):

    _fmt = '"%(path)s" is not in the working directory %(extra)s'

class DirectoryNotEmpty(PathError):

    _fmt = 'Directory not empty: "%(path)s"%(extra)s'

class HardLinkNotSupported(PathError):

    _fmt = 'Hard-linking "%(path)s" is not supported'

class ReadingCompleted(InternalBzrError):

    _fmt = ("The MediumRequest '%(request)s' has already had finish_reading "

            "called upon it - the request has been completed and no more "

            "data may be read.")

    def __init__(self, request):

        self.request = request

class ResourceBusy(PathError):

    _fmt = 'Device or resource busy: "%(path)s"%(extra)s'

class PermissionDenied(PathError):

    _fmt = 'Permission denied: "%(path)s"%(extra)s'

class InvalidURL(PathError):

    _fmt = 'Invalid url supplied to transport: "%(path)s"%(extra)s'

class InvalidURLJoin(PathError):

    _fmt = "Invalid URL join request: %(reason)s: %(base)r + %(join_args)r"

    def __init__(self, reason, base, join_args):

        self.reason = reason

        self.base = base

        self.join_args = join_args

        PathError.__init__(self, base, reason)

class UnavailableRepresentation(InternalBzrError):

    _fmt = ("The encoding '%(wanted)s' is not available for key %(key)s which "

        "is encoded as '%(native)s'.")

    def __init__(self, key, wanted, native):

        InternalBzrError.__init__(self)

        self.wanted = wanted

        self.native = native

        self.key = key

class UnknownHook(BzrError):

    _fmt = "The %(type)s hook '%(hook)s' is unknown in this version of bzrlib."

    def __init__(self, hook_type, hook_name):

        BzrError.__init__(self)

        self.type = hook_type

        self.hook = hook_name

class UnsupportedProtocol(PathError):

    _fmt = 'Unsupported protocol for url "%(path)s"%(extra)s'

    def __init__(self, url, extra):

        PathError.__init__(self, url, extra=extra)

class UnstackableBranchFormat(BzrError):

    _fmt = ("The branch '%(url)s'(%(format)s) is not a stackable format. "

        "You will need to upgrade the branch to permit branch stacking.")

    def __init__(self, format, url):

        BzrError.__init__(self)

        self.format = format

        self.url = url

class UnstackableRepositoryFormat(BzrError):

    _fmt = ("The repository '%(url)s'(%(format)s) is not a stackable format. "

        "You will need to upgrade the repository to permit branch stacking.")

    def __init__(self, format, url):

        BzrError.__init__(self)

        self.format = format

        self.url = url

class ReadError(PathError):

    _fmt = """Error reading from %(path)r."""

class ShortReadvError(PathError):

    _fmt = ('readv() read %(actual)s bytes rather than %(length)s bytes'

            ' at %(offset)s for "%(path)s"%(extra)s')

    internal_error = True

    def __init__(self, path, offset, length, actual, extra=None):

        PathError.__init__(self, path, extra=extra)

        self.offset = offset

        self.length = length

        self.actual = actual

class PathNotChild(PathError):

    _fmt = 'Path "%(path)s" is not a child of path "%(base)s"%(extra)s'

    internal_error = True

    def __init__(self, path, base, extra=None):

        BzrError.__init__(self)

        self.path = path

        self.base = base

        if extra:

            self.extra = ': ' + str(extra)

        else:

            self.extra = ''

class InvalidNormalization(PathError):

    _fmt = 'Path "%(path)s" is not unicode normalized'

# TODO: This is given a URL; we try to unescape it but doing that from inside

# the exception object is a bit undesirable.

# TODO: Probably this behavior of should be a common superclass 

class NotBranchError(PathError):

    _fmt = 'Not a branch: "%(path)s".'

    def __init__(self, path):

       import bzrlib.urlutils as urlutils

       self.path = urlutils.unescape_for_display(path, 'ascii')

class NoSubmitBranch(PathError):

    _fmt = 'No submit branch available for branch "%(path)s"'

    def __init__(self, branch):

       import bzrlib.urlutils as urlutils

       self.path = urlutils.unescape_for_display(branch.base, 'ascii')

class AlreadyBranchError(PathError):

    _fmt = 'Already a branch: "%(path)s".'

class BranchExistsWithoutWorkingTree(PathError):

    _fmt = 'Directory contains a branch, but no working tree \

(use bzr checkout if you wish to build a working tree): "%(path)s"'

class AtomicFileAlreadyClosed(PathError):

    _fmt = ('"%(function)s" called on an AtomicFile after it was closed:'

            ' "%(path)s"')

    def __init__(self, path, function):

        PathError.__init__(self, path=path, extra=None)

        self.function = function

class InaccessibleParent(PathError):

    _fmt = ('Parent not accessible given base "%(base)s" and'

            ' relative path "%(path)s"')

    def __init__(self, path, base):

        PathError.__init__(self, path)