Class IS_URL

object --+    
         |    
 Validator --+
             |
            IS_URL

Rejects a URL string if any of the following is true:
   * The string is empty or None
   * The string uses characters that are not allowed in a URL
   * The string breaks any of the HTTP syntactic rules
   * The URL scheme specified (if one is specified) is not 'http' or 'https'
   * The top-level domain (if a host name is specified) does not exist

(These rules are based on RFC 2616: http://www.faqs.org/rfcs/rfc2616.html)

This function only checks the URL's syntax. It does not check that the URL
points to a real document, for example, or that it otherwise makes sense
semantically. This function does automatically prepend 'http://' in front
of a URL in the case of an abbreviated URL (e.g. 'google.ca').

If the parameter mode='generic' is used, then this function's behavior
changes. It then rejects a URL string if any of the following is true:
   * The string is empty or None
   * The string uses characters that are not allowed in a URL
   * The URL scheme specified (if one is specified) is not valid

(These rules are based on RFC 2396: http://www.faqs.org/rfcs/rfc2396.html)

The list of allowed schemes is customizable with the allowed_schemes
parameter. If you exclude None from the list, then abbreviated URLs
(lacking a scheme such as 'http') will be rejected.

The default prepended scheme is customizable with the prepend_scheme
parameter. If you set prepend_scheme to None then prepending will be
disabled. URLs that require prepending to parse will still be accepted,
but the return value will not be modified.

IS_URL is compatible with the Internationalized Domain Name (IDN) standard
specified in RFC 3490 (http://tools.ietf.org/html/rfc3490). As a result,
URLs can be regular strings or unicode strings.
If the URL's domain component (e.g. google.ca) contains non-US-ASCII
letters, then the domain will be converted into Punycode (defined in
RFC 3492, http://tools.ietf.org/html/rfc3492). IS_URL goes a bit beyond
the standards, and allows non-US-ASCII characters to be present in the path
and query components of the URL as well. These non-US-ASCII characters will
be escaped using the standard '%20' type syntax. e.g. the unicode
character with hex code 0x4e86 will become '%4e%86'

Code Examples::

    INPUT(_type='text', _name='name', requires=IS_URL())
    >>> IS_URL()('abc.com')
    ('http://abc.com', None)

    INPUT(_type='text', _name='name', requires=IS_URL(mode='generic'))
    >>> IS_URL(mode='generic')('abc.com')
    ('abc.com', None)

    INPUT(_type='text', _name='name',
        requires=IS_URL(allowed_schemes=['https'], prepend_scheme='https'))
    >>> IS_URL(allowed_schemes=['https'], prepend_scheme='https')('https://abc.com')
    ('https://abc.com', None)

    INPUT(_type='text', _name='name',
        requires=IS_URL(prepend_scheme='https'))
    >>> IS_URL(prepend_scheme='https')('abc.com')
    ('https://abc.com', None)

    INPUT(_type='text', _name='name',
        requires=IS_URL(mode='generic', allowed_schemes=['ftps', 'https'],
            prepend_scheme='https'))
    >>> IS_URL(mode='generic', allowed_schemes=['ftps', 'https'], prepend_scheme='https')('https://abc.com')
    ('https://abc.com', None)
    >>> IS_URL(mode='generic', allowed_schemes=['ftps', 'https', None], prepend_scheme='https')('abc.com')
    ('abc.com', None)

@author: Jonathan Benn

:param error_message: a string, the error message to give the end user
    if the URL does not validate
:param allowed_schemes: a list containing strings or None. Each element
    is a scheme the inputed URL is allowed to use
:param prepend_scheme: a string, this scheme is prepended if it's
    necessary to make the URL valid

:param value: a unicode or regular string, the URL to validate
:returns: a (string, string) tuple, where tuple[0] is the modified
    input value and tuple[1] is either None (success!) or the
    string error_message. The input value will never be modified in the
    case of an error. However, if there is success then the input URL
    may be modified to (1) prepend a scheme, and/or (2) convert a
    non-compliant unicode URL into a compliant US-ASCII version.