Rethink the exception hierarchy

Now looks like this:

builtins.Exception
 +-- builtins.ArithmeticError
 |    +-- builtins.OverflowError (Integer was too large during parsing)
 +-- builtins.TypeError (Invalid parameter type)
 +-- builtins.LookupError
 |    +-- LookupError
           +-- ProtocolLookupError (MultiAddr did not contain the requested protocol)
 +-- builtins.ValueError
 |    +-- ParseError
 |         +-- BinaryParseError (Failed to parse the binary representation)
 |         +-- StringParseError (Failed to parse the text/string representation)
 +-- ProtocolManagerError
      +-- ProtocolExistsError (Tried to add protocol already defined)
      +-- ProtocolNotFoundError (Tried to find non-existing protocol)

Additionally all exceptions defined by *py-multiaddr* also derive from
`multiaddr.exceptions.Error`.

Author: ntninja

multiaddr/codecs/ip4.py

@@ -11,10 +11,7 @@
 
 
 def to_bytes(proto, string):
-	try:
-		return netaddr.IPAddress(string, version=4).packed
-	except Exception:
-		raise ValueError("failed to parse ip4 addr: %s" % string)
+	return netaddr.IPAddress(string, version=4).packed
 
 
 def to_string(proto, buf):

multiaddr/codecs/ip6.py

@@ -11,10 +11,7 @@
 
 
 def to_bytes(proto, string):
-	try:
-		return netaddr.IPAddress(string, version=6).packed
-	except Exception:
-		raise ValueError("failed to parse ip4 addr: %s" % string)
+	return netaddr.IPAddress(string, version=6).packed
 
 
 def to_string(proto, buf):

multiaddr/codecs/onion.py

@@ -12,34 +12,23 @@
 def to_bytes(proto, string):
 	addr = string.split(":")
 	if len(addr) != 2:
-		raise ValueError(
-		    "failed to parse %s addr: %s does not contain a port number."
-		    % (proto.name, string))
+		raise ValueError("Does not contain a port number")
 
 	# onion address without the ".onion" substring
 	if len(addr[0]) != 16:
-		raise ValueError(
-		    "failed to parse %s addr: %s not a Tor onion address."
-		    % (proto.name, string))
+		raise ValueError("Invalid onion host address length (must be 16 characters)")
 	try:
 		onion_host_bytes = base64.b32decode(addr[0].upper())
-	except Exception as ex:
-		raise ValueError(
-		    "failed to decode base32 %s addr: %s %s"
-		    % (proto.name, string, str(ex)))
+	except Exception as exc:
+		six.raise_from(ValueError("Cannot decode {0!r} as base32: {1}".format(addr[0], exc)), exc)
 
 	# onion port number
 	try:
-		port = int(addr[1])
-	except Exception as ex:
-		raise ValueError("failed to parse %s addr: %s"
-		                 % (proto.name, str(ex)))
-	if port >= 65536:
-		raise ValueError("failed to parse %s addr: %s"
-		                 % (proto.name, "port greater than 65536"))
-	if port < 1:
-		raise ValueError("failed to parse %s addr: %s"
-		                 % (proto.name, "port less than 1"))
+		port = int(addr[1], 10)
+	except ValueError as exc:
+		six.raise_from(ValueError("Port number is not an integer"), exc)
+	if port not in range(1, 65536):
+		raise ValueError("Port number is not in range(1, 65536)")
 
 	return b''.join((onion_host_bytes, struct.pack('>H', port)))
 

multiaddr/codecs/p2p.py

@@ -12,14 +12,11 @@
 
 def to_bytes(proto, string):
 	# the address is a base58-encoded string
-	try:
-		if six.PY2 and isinstance(string, unicode):
-			string = string.encode("ascii")
-		mm = base58.b58decode(string)
-	except Exception as ex:
-		raise ValueError("failed to parse p2p addr: %s %s" % (string, str(ex)))
+	if six.PY2 and isinstance(string, unicode):
+		string = string.encode("ascii")
+	mm = base58.b58decode(string)
 	if len(mm) < 5:
-		raise ValueError("invalid P2P multihash: %s" % mm)
+		raise ValueError("P2P MultiHash too short: len() < 5")
 	return mm
 
 

multiaddr/codecs/uint16be.py

@@ -11,15 +11,13 @@
 def to_bytes(proto, string):
 	try:
 		return struct.pack('>H', int(string, 10))
-	except ValueError as ex:
-		raise ValueError("failed to parse %s addr: %s"
-		                 % (proto.name, str(ex)))
-	except struct.error:
-		raise ValueError("failed to parse %s addr: %s" %
-		                 (proto.name, "greater than 65536"))
+	except ValueError as exc:
+		six.raise_from(ValueError("Not a base 10 integer"), exc)
+	except struct.error as exc:
+		six.raise_from(ValueError("Integer not in range(65536)"), exc)
 
 
 def to_string(proto, buf):
 	if len(buf) != 2:
-		raise ValueError("Not a uint16")
+		raise ValueError("Invalid integer length (must be 2 bytes / 16 bits)")
 	return six.text_type(struct.unpack('>H', buf)[0])

multiaddr/exceptions.py

@@ -0,0 +1,88 @@
+class Error(Exception):
+	pass
+
+
+class LookupError(LookupError, Error):
+	pass
+
+
+class ProtocolLookupError(LookupError):
+	"""
+	MultiAddr did not contain a protocol with the requested code
+	"""
+	
+	def __init__(self, proto, string):
+		self.proto  = proto
+		self.string = string
+		
+		super(ProtocolLookupError, self).__init__(
+			"MultiAddr {0!r} does not contain protocol {1}".format(string, proto)
+		)
+
+
+class ParseError(ValueError, Error):
+	pass
+
+
+class StringParseError(ParseError):
+	"""
+	MultiAddr string representation could not be parsed
+	"""
+
+	def __init__(self, message, string, protocol=None, original=None):
+		self.message  = message
+		self.string   = string
+		self.protocol = protocol
+		self.original = original
+
+		if protocol:
+			message = "Invalid MultiAddr {0!r} protocol {1}: {2}".format(string, protocol, message)
+		else:
+			message = "Invalid MultiAddr {0!r}: {1}".format(string, message)
+
+		super(StringParseError, self).__init__(message)
+
+
+class BinaryParseError(ParseError):
+	"""
+	MultiAddr binary representation could not be parsed
+	"""
+
+	def __init__(self, message, binary, protocol, original=None):
+		self.message  = message
+		self.binary   = binary
+		self.protocol = protocol
+		self.original = original
+
+		message = "Invalid binary MultiAddr protocol {0}: {1}".format(protocol, message)
+
+		super(BinaryParseError, self).__init__(message)
+
+
+class ProtocolManagerError(Error):
+	pass
+
+
+class ProtocolExistsError(ProtocolManagerError):
+	"""
+	Protocol with the given name or code already exists
+	"""
+	def __init__(self, proto, kind="name"):
+		self.proto = proto
+		self.kind  = kind
+
+		super(ProtocolExistsError, self).__init__(
+			"Protocol with {0} {1!r} already exists".format(kind, getattr(proto, kind))
+		)
+
+class ProtocolNotFoundError(ProtocolManagerError):
+	"""
+	No protocol with the given name or code found
+	"""
+	def __init__(self, value, kind="name"):
+		self.value = value
+		self.kind  = kind
+
+		super(ProtocolNotFoundError, self).__init__(
+			"No protocol with {0} {1!r} found".format(kind, value)
+		)

multiaddr/multiaddr.py

@@ -3,22 +3,20 @@
 
 import six
 
+from . import exceptions, protocols
+
 from .transforms import bytes_iter
 from .transforms import string_to_bytes
 from .transforms import bytes_to_string
 
 
-class ProtocolNotFoundException(Exception):
-    pass
-
-
 class Multiaddr(object):
     """Multiaddr is a representation of multiple nested internet addresses.
 
     Multiaddr is a cross-protocol, cross-platform format for representing
     internet addresses. It emphasizes explicitness and self-description.
 
-    Learn more here: https://github.com/jbenet/multiaddr
+    Learn more here: http://multiformats.io/multiaddr/
 
     Multiaddrs have both a binary and string representation.
 
@@ -49,7 +47,7 @@ def __init__(self, addr):
         elif isinstance(addr, six.binary_type):
             self._bytes = addr
         else:
-            raise ValueError("Invalid address type, must be bytes or str")
+            raise TypeError("MultiAddr must be bytes or str")
 
     def __eq__(self, other):
         """Checks if two Multiaddr objects are exactly equal."""
@@ -61,13 +59,9 @@ def __ne__(self, other):
     def __str__(self):
         """Return the string representation of this Multiaddr.
 
-        May raise an exception if the internal state of the Multiaddr is
-        corrupted."""
-        try:
-            return bytes_to_string(self._bytes)
-        except Exception:
-            raise ValueError(
-                "multiaddr failed to convert back to string. corrupted?")
+        May raise a :class:`~multiaddr.exceptions.BinaryParseError` if the
+        stored MultiAddr binary representation is invalid."""
+        return bytes_to_string(self._bytes)
 
     # On Python 2 __str__ needs to return binary text, so expose the original
     # function as __unicode__ and transparently encode its returned text based
@@ -113,25 +107,28 @@ def decapsulate(self, other):
         except ValueError:
             # if multiaddr not contained, returns a copy
             return copy(self)
-        try:
-            return Multiaddr(s1[:idx])
-        except Exception as ex:
-            raise ValueError(
-                "Multiaddr.decapsulate incorrect byte boundaries: %s"
-                % str(ex))
+        return Multiaddr(s1[:idx])
 
-    def value_for_protocol(self, code):
+    def value_for_protocol(self, proto):
         """Return the value (if any) following the specified protocol."""
-        if not isinstance(code, int):
-            raise ValueError("code type should be `int`, code={}".format(code))
-
-        for proto, codec, part in bytes_iter(self.to_bytes()):
-            if proto.code == code:
+        if not isinstance(proto, protocols.Protocol):
+            if isinstance(proto, int):
+                proto = protocols.protocol_with_code(proto)
+            elif isinstance(proto, six.string_types):
+                proto = protocols.protocol_with_name(proto)
+            else:
+                raise TypeError("Protocol object, name or code expected, got {0!r}".format(proto))
+
+        for proto2, codec, part in bytes_iter(self.to_bytes()):
+            if proto2 == proto:
                 if codec.SIZE != 0:
-                    # If we have an address, return it
-                    return codec.to_string(proto, part)
+                    try:
+                        # If we have an address, return it
+                        return codec.to_string(proto2, part)
+                    except Exception as exc:
+                        six.raise_from(exceptions.BinaryParseError(str(exc), self.to_bytes(), proto2.name, exc), exc)
                 else:
                     # We were given something like '/utp', which doesn't have
                     # an address, so return ''
                     return ''
-        raise ProtocolNotFoundException()
+        raise exceptions.ProtocolLookupError(proto, str(self))