Add info to the README about requiring components

Add kwargs to is_valid_uri

README.rst

@@ -82,6 +82,39 @@ You can also very simply validate a URI::
 
     assert is_valid_uri('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth')
 
+Requiring Components
+~~~~~~~~~~~~~~~~~~~~
+
+You can validate that a particular string is a valid URI and require
+independent components::
+
+    from rfc3986 import is_valid_uri
+
+    assert is_valid_uri('http://localhost:8774/v2/resource',
+                        require_scheme=True,
+                        require_authority=True,
+                        require_path=True)
+
+    # Assert that a mailto URI is invalid if you require an authority
+    # component
+    assert is_valid_uri('mailto:user@example.com', require_authority=True) is False
+
+If you have an instance of a ``URIReference``, you can pass the same arguments
+to ``URIReference#is_valid``, e.g.,
+
+.. code::
+
+    from rfc3986 import uri_reference
+
+    http = uri_reference('http://localhost:8774/v2/resource')
+    assert uri.is_valid(require_scheme=True,
+                        require_authority=True,
+                        require_path=True)
+
+    # Assert that a mailto URI is invalid if you require an authority
+    # component
+    mailto = uri_reference('mailto:user@example.com')
+    assert uri.is_valid(require_authority=True) is False
 
 Alternatives
 ------------

rfc3986/api.py

@@ -37,7 +37,7 @@ def uri_reference(uri, encoding='utf-8'):
     return URIReference.from_string(uri, encoding)
 
 
-def is_valid_uri(uri, encoding='utf-8'):
+def is_valid_uri(uri, encoding='utf-8', **kwargs):
     """Determine if the URI given is valid.
 
     This is a convenience function. You could use either
@@ -46,10 +46,20 @@ def is_valid_uri(uri, encoding='utf-8'):
 
     :param str uri: The URI to be validated.
     :param str encoding: The encoding of the string provided
+    :param bool require_scheme: Set to ``True`` if you wish to require the
+        presence of the scheme component.
+    :param bool require_authority: Set to ``True`` if you wish to require the
+        presence of the authority component.
+    :param bool require_path: Set to ``True`` if you wish to require the
+        presence of the path component.
+    :param bool require_query: Set to ``True`` if you wish to require the
+        presence of the query component.
+    :param bool require_fragment: Set to ``True`` if you wish to require the
+        presence of the fragment component.
     :returns: ``True`` if the URI is valid, ``False`` otherwise.
     :rtype: bool
     """
-    return URIReference.from_string(uri, encoding).is_valid()
+    return URIReference.from_string(uri, encoding).is_valid(**kwargs)
 
 
 def normalize_uri(uri, encoding='utf-8'):