From 513f70b445da5238d95b0be2fd008ae115f287ba Mon Sep 17 00:00:00 2001
From: Ian Stapleton Cordasco <graffatcolmingov@gmail.com>
Date: Mon, 17 Jul 2017 16:56:50 -0500
Subject: [PATCH] Add check_validity_of to vaildator docs

Document the ability to replace `URIReference.is_valid` without
mentioning that method at all.
---
 docs/source/api-ref/validators.rst |  2 ++
 docs/source/user/validating.rst    | 49 ++++++++++++++++++++++++++++--
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/docs/source/api-ref/validators.rst b/docs/source/api-ref/validators.rst
index eaf078f..6dac5bd 100644
--- a/docs/source/api-ref/validators.rst
+++ b/docs/source/api-ref/validators.rst
@@ -12,6 +12,8 @@
 
 .. automethod:: rfc3986.validators.Validator.allow_use_of_password
 
+.. automethod:: rfc3986.validators.Validator.check_validity_of
+
 .. automethod:: rfc3986.validators.Validator.forbid_use_of_password
 
 .. automethod:: rfc3986.validators.Validator.require_presence_of
diff --git a/docs/source/user/validating.rst b/docs/source/user/validating.rst
index 26a0444..2b0ff96 100644
--- a/docs/source/user/validating.rst
+++ b/docs/source/user/validating.rst
@@ -7,6 +7,7 @@ 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
 =============
 
@@ -14,7 +15,10 @@ 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.
 
-Let's assume that we're building something that takes user input for a URl and
+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:
 
@@ -52,6 +56,9 @@ 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:
@@ -87,6 +94,9 @@ portion of the authority. In that case, our new validator would look like this:
     ...
     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
@@ -134,7 +144,42 @@ item to our validator:
     ...     'https://github.com/sigmavirus24/rfc3986'
     ... ))
 
-.. links
 
+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/