Merge pull request #63 from berislavlopac/28-builder-from-uri

implement from_uri to create builder

Author: sigmavirus24

docs/source/api-ref/builder.rst

@@ -4,6 +4,8 @@
 
 .. autoclass:: rfc3986.builder.URIBuilder
 
+.. automethod:: rfc3986.builder.URIBuilder.from_uri
+
 .. automethod:: rfc3986.builder.URIBuilder.add_scheme
 
 .. automethod:: rfc3986.builder.URIBuilder.add_credentials

docs/source/user/building.rst

@@ -42,6 +42,17 @@ a :class:`~rfc3986.uri.URIReference` and call
     ... ).finalize().unsplit())
     https://github.com
 
+It is possible to update an existing URI by constructing a builder from an
+instance of :class:`~rfc3986.uri.URIReference` or a textual representation:
+
+.. doctest::
+
+    >>> from rfc3986 import builder
+    >>> print(builder.URIBuilder.from_uri("http://github.com").add_scheme(
+    ...     'https'
+    ... ).finalize().unsplit())
+    https://github.com
+
 Each time you invoke a method, you get a new instance of a
 :class:`~rfc3986.builder.URIBuilder` class so you can build several different
 URLs from one base instance.

src/rfc3986/builder.py

@@ -16,6 +16,7 @@
 from . import compat
 from . import normalizers
 from . import uri
+from . import uri_reference
 
 
 class URIBuilder(object):
@@ -63,6 +64,26 @@ def __repr__(self):
                      'query={b.query}, fragment={b.fragment})')
         return formatstr.format(b=self)
 
+    @classmethod
+    def from_uri(cls, reference):
+        """Initialize the URI builder from another URI.
+
+        Takes the given URI reference and creates a new URI builder instance
+        populated with the values from the reference. If given a string it will
+        try to convert it to a reference before constructing the builder.
+        """
+        if not isinstance(reference, uri.URIReference):
+            reference = uri_reference(reference)
+        return cls(
+            scheme=reference.scheme,
+            userinfo=reference.userinfo,
+            host=reference.host,
+            port=reference.port,
+            path=reference.path,
+            query=reference.query,
+            fragment=reference.fragment
+        )
+
     def add_scheme(self, scheme):
         """Add a scheme to our builder object.
 

tests/test_builder.py

@@ -15,7 +15,7 @@
 """Module containing the tests for the URIBuilder object."""
 import pytest
 
-from rfc3986 import builder
+from rfc3986 import builder, uri_reference
 
 
 def test_builder_default():
@@ -30,6 +30,29 @@ def test_builder_default():
     assert uribuilder.fragment is None
 
 
+def test_from_uri_reference():
+    uri = uri_reference("http://foo.bar:1234/baz")
+    uribuilder = builder.URIBuilder().from_uri(uri)
+    assert uribuilder.scheme == 'http'
+    assert uribuilder.userinfo is None
+    assert uribuilder.host == 'foo.bar'
+    assert uribuilder.port == '1234'
+    assert uribuilder.path == '/baz'
+    assert uribuilder.query is None
+    assert uribuilder.fragment is None
+
+
+def test_from_uri_string():
+    uribuilder = builder.URIBuilder().from_uri("https://bar.foo:4321/boom")
+    assert uribuilder.scheme == 'https'
+    assert uribuilder.userinfo is None
+    assert uribuilder.host == 'bar.foo'
+    assert uribuilder.port == '4321'
+    assert uribuilder.path == '/boom'
+    assert uribuilder.query is None
+    assert uribuilder.fragment is None
+
+
 def test_repr():
     """Verify our repr looks like our class."""
     uribuilder = builder.URIBuilder()