diff --git a/README.rst b/README.rst index a57777f..1295280 100644 --- a/README.rst +++ b/README.rst @@ -4,4 +4,70 @@ rfc3986 A Python implementation of `RFC 3986`_ including validation and authority parsing. Coming soon: `Reference Resolution `_. +Example Usage +------------- + +To parse a URI into a convenient named tuple, you can simply:: + + from rfc3986 import uri_reference + + example = uri_reference('http://example.com') + email = uri_reference('mailto:user@domain.com') + ssh = uri_reference('ssh://user@git.openstack.org:29418/openstack/keystone.git') + +With a parsed URI you can access data about the components:: + + print(example.scheme) # => http + print(email.path) # => user@domain.com + print(ssh.userinfo) # => user + print(ssh.host) # => git.openstack.org + print(ssh.port) # => 29418 + +It can also parse URIs with unicode present:: + + uni = uri_reference(b'http://httpbin.org/get?utf8=\xe2\x98\x83') # ☃ + print(uni.query) # utf8=%E2%98%83 + +With a parsed URI you can also validate it:: + + if ssh.is_valid(): + subprocess.call(['git', 'clone', ssh.unsplit()]) + +You can also take a parsed URI and normalize it:: + + mangled = uri_reference('hTTp://exAMPLe.COM') + print(mangled.scheme) # => hTTp + print(mangled.authority) # => exAMPLe.COM + + normal = mangled.normalize() + print(normal.scheme) # => http + print(mangled.authority) # => example.com + +But these two URIs are (functionally) equivalent:: + + if normal == mangled: + webbrowser.open(normal.unsplit()) + +Your paths, queries, and fragments are safe with us though:: + + mangled = uri_reference('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth') + normal = mangled.normalize() + assert normal == 'hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth' + assert normal == 'http://example.com/Some/reallY/biZZare/pAth' + assert normal != 'http://example.com/some/really/bizzare/path' + +If you do not actually need a real reference object and just want to normalize +your URI:: + + from rfc3986 import normalize_uri + + assert (normalize_uri('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth') == + 'http://example.com/Some/reallY/biZZare/pAth') + +You can also very simply validate a URI:: + + from rfc3986 import is_valid_uri + + assert is_valid_uri('hTTp://exAMPLe.COM/Some/reallY/biZZare/pAth') + .. _RFC 3986: http://tools.ietf.org/html/rfc3986