188 lines
6.4 KiB
ReStructuredText
188 lines
6.4 KiB
ReStructuredText
.. _validating:
|
|
|
|
=================
|
|
Validating URIs
|
|
=================
|
|
|
|
While not as difficult as `validating an email address`_, validating URIs is
|
|
tricky. Different parts of the URI allow different characters. Those sets
|
|
sometimes overlap and othertimes they don't and it's not very convenient.
|
|
Luckily, |rfc3986| makes validating URIs far simpler.
|
|
|
|
|
|
Example Usage
|
|
=============
|
|
|
|
First we need to create an instance of a
|
|
:class:`~rfc3986.validators.Validator` which takes no parameters. After that
|
|
we can call methods on the instance to indicate what we want to validate.
|
|
|
|
Allowing Only Trusted Domains and Schemes
|
|
-----------------------------------------
|
|
|
|
Let's assume that we're building something that takes user input for a URL and
|
|
we want to ensure that URL is only ever using a specific domain with https. In
|
|
that case, our code would look like this:
|
|
|
|
.. doctest::
|
|
|
|
>>> from rfc3986 import validators, uri_reference
|
|
>>> user_url = 'https://github.com/sigmavirus24/rfc3986'
|
|
>>> validator = validators.Validator().allow_schemes(
|
|
... 'https',
|
|
... ).allow_hosts(
|
|
... 'github.com',
|
|
... )
|
|
>>> validator.validate(uri_reference(
|
|
... 'https://github.com/sigmavirus24/rfc3986'
|
|
... ))
|
|
>>> validator.validate(uri_reference(
|
|
... 'https://github.com/'
|
|
... ))
|
|
>>> validator.validate(uri_reference(
|
|
... 'http://example.com'
|
|
... ))
|
|
Traceback (most recent call last):
|
|
...
|
|
rfc3986.exceptions.UnpermittedComponentError
|
|
|
|
First notice that we can easily reuse our validator object for each URL.
|
|
This allows users to not have to constantly reconstruct Validators for each
|
|
bit of user input. Next, we have three different URLs that we validate:
|
|
|
|
#. ``https://github.com/sigmavirus24/rfc3986``
|
|
#. ``https://github.com/``
|
|
#. ``http://example.com``
|
|
|
|
As it stands, our validator will allow the first two URLs to pass but will
|
|
fail the third. This is specifically because we only allow URLs using
|
|
``https`` as a scheme and ``github.com`` as the domain name.
|
|
|
|
Preventing Leaks of User Credentials
|
|
------------------------------------
|
|
|
|
Next, let's imagine that we want to prevent leaking user credentials. In that
|
|
case, we want to ensure that there is no password in the user information
|
|
portion of the authority. In that case, our new validator would look like this:
|
|
|
|
.. doctest::
|
|
|
|
>>> from rfc3986 import validators, uri_reference
|
|
>>> user_url = 'https://github.com/sigmavirus24/rfc3986'
|
|
>>> validator = validators.Validator().allow_schemes(
|
|
... 'https',
|
|
... ).allow_hosts(
|
|
... 'github.com',
|
|
... ).forbid_use_of_password()
|
|
>>> validator.validate(uri_reference(
|
|
... 'https://github.com/sigmavirus24/rfc3986'
|
|
... ))
|
|
>>> validator.validate(uri_reference(
|
|
... 'https://github.com/'
|
|
... ))
|
|
>>> validator.validate(uri_reference(
|
|
... 'http://example.com'
|
|
... ))
|
|
Traceback (most recent call last):
|
|
...
|
|
rfc3986.exceptions.UnpermittedComponentError
|
|
>>> validator.validate(uri_reference(
|
|
... 'https://sigmavirus24@github.com'
|
|
... ))
|
|
>>> validator.validate(uri_reference(
|
|
... 'https://sigmavirus24:not-my-real-password@github.com'
|
|
... ))
|
|
Traceback (most recent call last):
|
|
...
|
|
rfc3986.exceptions.PasswordForbidden
|
|
|
|
Requiring the Presence of Components
|
|
------------------------------------
|
|
|
|
Up until now, we have assumed that we will get a URL that has the appropriate
|
|
components for validation. For example, we assume that we will have a URL that
|
|
has a scheme and hostname. However, our current validation doesn't require
|
|
those items exist.
|
|
|
|
.. doctest::
|
|
|
|
>>> from rfc3986 import validators, uri_reference
|
|
>>> user_url = 'https://github.com/sigmavirus24/rfc3986'
|
|
>>> validator = validators.Validator().allow_schemes(
|
|
... 'https',
|
|
... ).allow_hosts(
|
|
... 'github.com',
|
|
... ).forbid_use_of_password()
|
|
>>> validator.validate(uri_reference('//github.com'))
|
|
>>> validator.validate(uri_reference('https:/'))
|
|
|
|
In the first case, we have a host name but no scheme and in the second we have
|
|
a scheme and a path but no host. If we want to ensure that those components
|
|
are there and that they are *always* what we allow, then we must add one last
|
|
item to our validator:
|
|
|
|
.. doctest::
|
|
|
|
>>> from rfc3986 import validators, uri_reference
|
|
>>> user_url = 'https://github.com/sigmavirus24/rfc3986'
|
|
>>> validator = validators.Validator().allow_schemes(
|
|
... 'https',
|
|
... ).allow_hosts(
|
|
... 'github.com',
|
|
... ).forbid_use_of_password(
|
|
... ).require_presence_of(
|
|
... 'scheme', 'host',
|
|
... )
|
|
>>> validator.validate(uri_reference('//github.com'))
|
|
Traceback (most recent call last):
|
|
...
|
|
rfc3986.exceptions.MissingComponentError
|
|
>>> validator.validate(uri_reference('https:/'))
|
|
Traceback (most recent call last):
|
|
...
|
|
rfc3986.exceptions.MissingComponentError
|
|
>>> validator.validate(uri_reference('https://github.com'))
|
|
>>> validator.validate(uri_reference(
|
|
... 'https://github.com/sigmavirus24/rfc3986'
|
|
... ))
|
|
|
|
|
|
Checking the Validity of Components
|
|
-----------------------------------
|
|
|
|
As of version 1.1.0, |rfc3986| allows users to check the validity of a URI
|
|
Reference using a :class:`~rfc3986.validators.Validator`. Along with the above
|
|
examples we can also check that a URI is valid per :rfc:`3986`. The validation
|
|
of the components is pre-determined so all we need to do is specify which
|
|
components we want to validate:
|
|
|
|
.. doctest::
|
|
|
|
>>> from rfc3986 import validators, uri_reference
|
|
>>> valid_uri = uri_reference('https://github.com/')
|
|
>>> validator = validators.Validator().allow_schemes(
|
|
... 'https',
|
|
... ).allow_hosts(
|
|
... 'github.com',
|
|
... ).forbid_use_of_password(
|
|
... ).require_presence_of(
|
|
... 'scheme', 'host',
|
|
... ).check_validity_of(
|
|
... 'scheme', 'host', 'path',
|
|
... )
|
|
>>> validator.validate(valid_uri)
|
|
>>> invalid_uri = valid_uri.copy_with(path='/#invalid/path')
|
|
>>> validator.validate(invalid_uri)
|
|
Traceback (most recent call last):
|
|
...
|
|
rfc3986.exceptions.InvalidComponentsError
|
|
|
|
Paths are not allowed to contain a ``#`` character unless it's
|
|
percent-encoded. This is why our ``invalid_uri`` raises an exception when we
|
|
attempt to validate it.
|
|
|
|
|
|
.. links
|
|
.. _validating an email address:
|
|
http://haacked.com/archive/2007/08/21/i-knew-how-to-validate-an-email-address-until-i.aspx/
|