Add the ability to finalize a URI

This will return a URIReference to the user and allow them to unsplit
the object.

src/rfc3986/builder.py

@@ -15,6 +15,7 @@
 """Module containing the logic for the URIBuilder object."""
 from . import compat
 from . import normalizers
+from . import uri
 
 
 class URIBuilder(object):
@@ -267,3 +268,28 @@ class URIBuilder(object):
             query=self.query,
             fragment=normalizers.normalize_fragment(fragment),
         )
+
+    def finalize(self):
+        """Create a URIReference from our builder.
+
+        .. code-block:: python
+
+            >>> URIBuilder().add_scheme('https').add_host('github.com'
+            ...     ).add_path('sigmavirus24/rfc3986').finalize().unsplit()
+            'https://github.com/sigmavirus24/rfc3986'
+
+            >>> URIBuilder().add_scheme('https').add_host('github.com'
+            ...     ).add_path('sigmavirus24/rfc3986').add_credentials(
+            ...     'sigmavirus24', 'not-re@l').finalize().unsplit()
+            'https://sigmavirus24:not-re%40l@github.com/sigmavirus24/rfc3986'
+
+        """
+        return uri.URIReference(
+            self.scheme,
+            normalizers.normalize_authority(
+                (self.userinfo, self.host, self.port)
+            ),
+            self.path,
+            self.query,
+            self.fragment,
+        )

tests/test_builder.py

@@ -152,3 +152,14 @@ def test_add_fragment():
     """Verify our handling of fragments."""
     uribuilder = builder.URIBuilder().add_fragment('section-2.5.1')
     assert uribuilder.fragment == 'section-2.5.1'
+
+
+def test_finalize():
+    """Verify the whole thing."""
+    uri = builder.URIBuilder().add_scheme('https').add_credentials(
+        'sigmavirus24', 'not-my-re@l-password'
+    ).add_host('github.com').add_path('sigmavirus24/rfc3986').finalize(
+    ).unsplit()
+    expected = ('https://sigmavirus24:not-my-re%40l-password@github.com/'
+                'sigmavirus24/rfc3986')
+    assert expected == uri