URI Builder Module

class rfc3986.builder.URIBuilder(scheme=None, userinfo=None, host=None, port=None, path=None, query=None, fragment=None)

Object to aid in building up a URI Reference from parts.

Note

This object should be instantiated by the user, but it’s recommended that it is not provided with arguments. Instead, use the available method to populate the fields.

classmethod URIBuilder.from_uri(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.

URIBuilder.add_scheme(scheme)

Add a scheme to our builder object.

After normalizing, this will generate a new URIBuilder instance with the specified scheme and all other attributes the same.

>>> URIBuilder().add_scheme('HTTPS')
URIBuilder(scheme='https', userinfo=None, host=None, port=None,
        path=None, query=None, fragment=None)
URIBuilder.add_credentials(username, password)

Add credentials as the userinfo portion of the URI.

>>> URIBuilder().add_credentials('root', 's3crete')
URIBuilder(scheme=None, userinfo='root:s3crete', host=None,
        port=None, path=None, query=None, fragment=None)

>>> URIBuilder().add_credentials('root', None)
URIBuilder(scheme=None, userinfo='root', host=None,
        port=None, path=None, query=None, fragment=None)
URIBuilder.add_host(host)

Add hostname to the URI.

>>> URIBuilder().add_host('google.com')
URIBuilder(scheme=None, userinfo=None, host='google.com',
        port=None, path=None, query=None, fragment=None)
URIBuilder.add_port(port)

Add port to the URI.

>>> URIBuilder().add_port(80)
URIBuilder(scheme=None, userinfo=None, host=None, port='80',
        path=None, query=None, fragment=None)

>>> URIBuilder().add_port(443)
URIBuilder(scheme=None, userinfo=None, host=None, port='443',
        path=None, query=None, fragment=None)
URIBuilder.add_path(path)

Add a path to the URI.

>>> URIBuilder().add_path('sigmavirus24/rfc3985')
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/sigmavirus24/rfc3986', query=None, fragment=None)

>>> URIBuilder().add_path('/checkout.php')
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/checkout.php', query=None, fragment=None)
URIBuilder.extend_path(path)

Extend the existing path value with the provided value.

New in version 1.5.0.

>>> URIBuilder(path="/users").extend_path("/sigmavirus24")
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/users/sigmavirus24', query=None, fragment=None)

>>> URIBuilder(path="/users/").extend_path("/sigmavirus24")
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/users/sigmavirus24', query=None, fragment=None)

>>> URIBuilder(path="/users/").extend_path("sigmavirus24")
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/users/sigmavirus24', query=None, fragment=None)

>>> URIBuilder(path="/users").extend_path("sigmavirus24")
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path='/users/sigmavirus24', query=None, fragment=None)
URIBuilder.add_query_from(query_items)

Generate and add a query a dictionary or list of tuples.

>>> URIBuilder().add_query_from({'a': 'b c'})
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b+c', fragment=None)

>>> URIBuilder().add_query_from([('a', 'b c')])
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b+c', fragment=None)
URIBuilder.extend_query_with(query_items)

Extend the existing query string with the new query items.

New in version 1.5.0.

>>> URIBuilder(query='a=b+c').extend_query_with({'a': 'b c'})
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b+c&a=b+c', fragment=None)

>>> URIBuilder(query='a=b+c').extend_query_with([('a', 'b c')])
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b+c&a=b+c', fragment=None)
URIBuilder.add_query(query)

Add a pre-formated query string to the URI.

>>> URIBuilder().add_query('a=b&c=d')
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query='a=b&c=d', fragment=None)
URIBuilder.add_fragment(fragment)

Add a fragment to the URI.

>>> URIBuilder().add_fragment('section-2.6.1')
URIBuilder(scheme=None, userinfo=None, host=None, port=None,
        path=None, query=None, fragment='section-2.6.1')
URIBuilder.finalize()

Create a URIReference from our builder.

>>> 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'
URIBuilder.geturl()

Generate the URL from this builder.

New in version 1.5.0.

This is an alternative to calling finalize() and keeping the rfc3986.uri.URIReference around.