Merge pull request #27 from sigmavirus24/moar-validation

Expand our Validation efforts and documentation

Author: sigmavirus24

.coveragerc

@@ -1,4 +1,5 @@
 [report]
 exclude_lines =
     .* # Python \d.*
+    .* # nocov: Python \d.*
 fail_under = 100

src/rfc3986/exceptions.py

@@ -90,3 +90,22 @@ def __init__(self, uri):
             )
         )
         self.uri = uri
+
+
+class InvalidComponentsError(ValidationError):
+    """Exception raised when one or more components are invalid."""
+
+    def __init__(self, uri, *component_names):
+        """Initialize the error with the invalid component name(s)."""
+        verb = 'was'
+        if len(component_names) > 1:
+            verb = 'were'
+
+        self.uri = uri
+        self.components = sorted(component_names)
+        components = ', '.join(self.components)
+        super(InvalidComponentsError, self).__init__(
+            "{} {} found to be invalid".format(components, verb),
+            uri,
+            self.components,
+        )

src/rfc3986/validators.py

@@ -21,6 +21,8 @@
 class Validator(object):
     """Object used to configure validation of all objects in rfc3986.
 
+    .. versionadded:: 1.0
+
     Example usage::
 
          >>> from rfc3986 import api, validators
@@ -68,10 +70,13 @@ def __init__(self):
             'query': False,
             'fragment': False,
         }
+        self.validated_components = self.required_components.copy()
 
     def allow_schemes(self, *schemes):
         """Require the scheme to be one of the provided schemes.
 
+        .. versionadded:: 1.0
+
         :param schemes:
             Schemes, without ``://`` that are allowed.
         :returns:
@@ -86,6 +91,8 @@ def allow_schemes(self, *schemes):
     def allow_hosts(self, *hosts):
         """Require the host to be one of the provided hosts.
 
+        .. versionadded:: 1.0
+
         :param hosts:
             Hosts that are allowed.
         :returns:
@@ -100,6 +107,8 @@ def allow_hosts(self, *hosts):
     def allow_ports(self, *ports):
         """Require the port to be one of the provided ports.
 
+        .. versionadded:: 1.0
+
         :param ports:
             Ports that are allowed.
         :returns:
@@ -114,18 +123,63 @@ def allow_ports(self, *ports):
         return self
 
     def allow_use_of_password(self):
-        """Allow passwords to be present in the URI."""
+        """Allow passwords to be present in the URI.
+
+        .. versionadded:: 1.0
+
+        :returns:
+            The validator instance.
+        :rtype:
+            Validator
+        """
         self.allow_password = True
         return self
 
     def forbid_use_of_password(self):
-        """Prevent passwords from being included in the URI."""
+        """Prevent passwords from being included in the URI.
+
+        .. versionadded:: 1.0
+
+        :returns:
+            The validator instance.
+        :rtype:
+            Validator
+        """
         self.allow_password = False
         return self
 
+    def check_validity_of(self, *components):
+        """Check the validity of the components provided.
+
+        This can be specified repeatedly.
+
+        .. versionadded:: 1.1
+
+        :param components:
+            Names of components from :attr:`Validator.COMPONENT_NAMES`.
+        :returns:
+            The validator instance.
+        :rtype:
+            Validator
+        """
+        components = [c.lower() for c in components]
+        for component in components:
+            if component not in self.COMPONENT_NAMES:
+                raise ValueError(
+                    '"{}" is not a valid component'.format(component)
+                )
+        self.validated_components.update({
+            component: True for component in components
+        })
+        return self
+
     def require_presence_of(self, *components):
         """Require the components provided.
 
+        This can be specified repeatedly.
+
+        .. versionadded:: 1.0
+
         :param components:
             Names of components from :attr:`Validator.COMPONENT_NAMES`.
         :returns:
@@ -147,6 +201,8 @@ def require_presence_of(self, *components):
     def validate(self, uri):
         """Check a URI for conditions specified on this validator.
 
+        .. versionadded:: 1.0
+
         :param uri:
             Parsed URI to validate.
         :type uri:
@@ -158,6 +214,8 @@ def validate(self, uri):
         :raises PasswordForbidden:
             When a password is present in the userinfo component but is
             not permitted by configuration.
+        :raises InvalidComponentsError:
+            When a component was found to be invalid.
         """
         if not self.allow_password:
             check_password(uri)
@@ -167,8 +225,15 @@ def validate(self, uri):
             for component, required in self.required_components.items()
             if required
         ]
+        validated_components = [
+            component
+            for component, required in self.validated_components.items()
+            if required
+        ]
         if required_components:
             ensure_required_components_exist(uri, required_components)
+        if validated_components:
+            ensure_components_are_valid(uri, validated_components)
 
         ensure_one_of(self.allowed_schemes, uri, 'scheme')
         ensure_one_of(self.allowed_hosts, uri, 'host')
@@ -309,3 +374,55 @@ def valid_ipv4_host_address(host):
     # If the host exists, and it might be IPv4, check each byte in the
     # address.
     return all([0 <= int(byte, base=10) <= 255 for byte in host.split('.')])
+
+
+_COMPONENT_VALIDATORS = {
+    'scheme': scheme_is_valid,
+    'path': path_is_valid,
+    'query': query_is_valid,
+    'fragment': fragment_is_valid,
+}
+
+_SUBAUTHORITY_VALIDATORS = set(['userinfo', 'host', 'port'])
+
+
+def subauthority_component_is_valid(uri, component):
+    """Determine if the userinfo, host, and port are valid."""
+    try:
+        subauthority_dict = uri.authority_info()
+    except exceptions.InvalidAuthority:
+        return False
+
+    # If we can parse the authority into sub-components and we're not
+    # validating the port, we can assume it's valid.
+    if component != 'port':
+        return True
+
+    try:
+        port = int(subauthority_dict['port'])
+    except TypeError:
+        # If the port wasn't provided it'll be None and int(None) raises a
+        # TypeError
+        return True
+
+    return (0 <= port <= 65535)
+
+
+def ensure_components_are_valid(uri, validated_components):
+    """Assert that all components are valid in the URI."""
+    invalid_components = set([])
+    for component in validated_components:
+        if component in _SUBAUTHORITY_VALIDATORS:
+            if not subauthority_component_is_valid(uri, component):
+                invalid_components.add(component)
+            # Python's peephole optimizer means that while this continue *is*
+            # actually executed, coverage.py cannot detect that. See also,
+            # https://bitbucket.org/ned/coveragepy/issues/198/continue-marked-as-not-covered
+            continue  # nocov: Python 2.7, 3.3, 3.4
+
+        validator = _COMPONENT_VALIDATORS[component]
+        if not validator(getattr(uri, component)):
+            invalid_components.add(component)
+
+    if invalid_components:
+        raise exceptions.InvalidComponentsError(uri, *invalid_components)

tests/test_validators.py

@@ -52,6 +52,12 @@ def test_requiring_invalid_component():
         validators.Validator().require_presence_of('frob')
 
 
+def test_checking_validity_of_component():
+    """Verify that we validate components we're validating."""
+    with pytest.raises(ValueError):
+        validators.Validator().check_validity_of('frob')
+
+
 def test_use_of_password():
     """Verify the behaviour of {forbid,allow}_use_of_password."""
     validator = validators.Validator()
@@ -182,6 +188,22 @@ def test_allowed_hosts_and_schemes(uri, failed_component):
     rfc3986.uri_reference('ssh://git.openstack.org/sigmavirus24'),
     rfc3986.uri_reference('ssh://[email protected]:22/sigmavirus24'),
     rfc3986.uri_reference('https://git.openstack.org:443/sigmavirus24'),
+    rfc3986.uri_reference(
+        'ssh://[email protected]:22/sigmavirus24?foo=bar#fragment'
+    ),
+    rfc3986.uri_reference(
+        'ssh://git.openstack.org:22/sigmavirus24?foo=bar#fragment'
+    ),
+    rfc3986.uri_reference('ssh://git.openstack.org:22/?foo=bar#fragment'),
+    rfc3986.uri_reference('ssh://git.openstack.org:22/sigmavirus24#fragment'),
+    rfc3986.uri_reference('ssh://git.openstack.org:22/#fragment'),
+    rfc3986.uri_reference('ssh://git.openstack.org:22/'),
+    rfc3986.uri_reference('ssh://[email protected]:22/?foo=bar#fragment'),
+    rfc3986.uri_reference(
+        'ssh://[email protected]:22/sigmavirus24#fragment'
+    ),
+    rfc3986.uri_reference('ssh://[email protected]:22/#fragment'),
+    rfc3986.uri_reference('ssh://[email protected]:22/'),
 ])
 def test_successful_complex_validation(uri):
     """Verify we do not raise ValidationErrors for good URIs."""
@@ -193,4 +215,23 @@ def test_successful_complex_validation(uri):
         '22', '443',
     ).require_presence_of(
         'scheme', 'host', 'path',
+    ).check_validity_of(
+        'scheme', 'userinfo', 'host', 'port', 'path', 'query', 'fragment',
     ).validate(uri)
+
+
+def test_invalid_uri_generates_error(invalid_uri):
+    """Verify we catch invalid URIs."""
+    uri = rfc3986.uri_reference(invalid_uri)
+    with pytest.raises(exceptions.InvalidComponentsError):
+        validators.Validator().check_validity_of('host').validate(uri)
+
+
+def test_invalid_uri_with_invalid_path(invalid_uri):
+    """Verify we catch multiple invalid components."""
+    uri = rfc3986.uri_reference(invalid_uri)
+    uri = uri.copy_with(path='#foobar')
+    with pytest.raises(exceptions.InvalidComponentsError):
+        validators.Validator().check_validity_of(
+            'host', 'path',
+        ).validate(uri)