Package web2py :: Package gluon :: Module validators :: Class IS_URL |
[hide private]
[frames] | no frames]

# Class IS_URL

source code

    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

Instance Methods | [hide private]
__init__(self, error_message=`'``enter a valid URL``'`, mode=`'``http``'`, allowed_schemes=1, prepend_scheme=`'``http``'`) :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. | source code
__call__(self, value) :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. | source code
Inherited from `Validator`: `formatter` Inherited from `object`: `__delattr__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__repr__`, `__setattr__`, `__str__`

Properties | [hide private]
Inherited from `object`: `__class__`

Method Details | [hide private]

### __init__(self, error_message=`'``enter a valid URL``'`, mode=`'``http``'`, allowed_schemes=1, prepend_scheme=`'``http``'`) (Constructor) | source code
    :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
Overrides: object.__init__

### __call__(self, value) (Call operator) | source code
    :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.