From 697c9d15969cd081fcc2fc41d62825c24d08f0b7 Mon Sep 17 00:00:00 2001
From: Julian Berman <Julian@GrayVines.com>
Date: Sat, 16 Feb 2013 21:36:26 -0500
Subject: Move all format docs to the docs.

---
 docs/validate.rst | 103 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 95 insertions(+), 8 deletions(-)

(limited to 'docs')

diff --git a/docs/validate.rst b/docs/validate.rst
index b6df7d8..f4044e2 100644
--- a/docs/validate.rst
+++ b/docs/validate.rst
@@ -235,21 +235,108 @@ any use for them. They are listed below, along with any limitations they come
 with.
 
 
-.. autofunction:: is_date
+.. function:: is_date
 
-.. autofunction:: is_time
+    Check if the instance is a date in ``YYYY-MM-DD`` format.
 
-.. autofunction:: is_regex
+        >>> is_date("1970-12-31")
+        True
+        >>> is_date("12/31/1970")
+        False
+        >>> is_date("0000-13-32")
+        False
+
+.. function:: is_time
+
+    Check if the instance is a time in ``hh:mm:ss`` format.
+
+        >>> is_time("23:59:59")
+        True
+        >>> is_time("11:59:59 PM")
+        False
+        >>> is_time("59:60:61")
+        False
+
+.. function:: is_regex
+
+    Check if the instance is a well-formed regular expression.
+
+        >>> is_regex("^(bob)?cat$")
+        True
+        >>> is_ipv6("^(bob?cat$")
+        False
+
+.. function:: is_uri
+
+    Check if the instance is a valid URI.
+
+    Also supports relative URIs.
+
+        >>> is_uri("ftp://joe.bloggs@www2.example.com:8080/pub/os/")
+        True
+        >>> is_uri("http://www2.example.com:8000/pub/#os?user=joe.bloggs")
+        True
+        >>> is_uri(r"\\\\WINDOWS\My Files")
+        False
+        >>> is_uri("#/properties/foo")
+        True
+
+.. function:: is_email
 
-.. autofunction:: is_uri
+    Check if the instance is a valid e-mail address.
 
-.. autofunction:: is_email
+    Checking is based on `RFC 2822`_
 
-.. autofunction:: is_ip_address
+        >>> is_email("joe.bloggs@example.com")
+        True
+        >>> is_email("joe.bloggs")
+        False
+
+    .. _RFC 2822: http://tools.ietf.org/html/rfc2822
+
+.. function:: is_host_name
+
+    Check if the instance is a valid host name.
+
+        >>> is_host_name("www.example.com")
+        True
+        >>> is_host_name("my laptop")
+        False
+        >>> is_host_name(
+        ...     "a.vvvvvvvvvvvvvvvvveeeeeeeeeeeeeeeeerrrrrrrrrrrrrrrrryyyyyyyy"
+        ...     "yyyyyyyyy.long.host.name"
+        ... )
+        False
+
+    .. note:: Does not perform a DNS lookup.
+
+        >>> is_host_name("www.example.doesnotexist")
+        True
 
-.. autofunction:: is_ipv6
+.. function:: is_ip_address
 
-.. autofunction:: is_host_name
+    Check if the instance is a valid IP address.
+
+        >>> is_ip_address("192.168.0.1")
+        True
+        >>> is_ip_address("::1")
+        False
+        >>> is_ip_address("256.256.256.256")
+        False
+
+On OSes with the ``socket.inet_pton`` function, an additional checker for
+``ipv6`` will be enabled:
+
+.. function:: is_ipv6
+
+    Check if the instance is a valid IPv6 address.
+
+        >>> is_ipv6("::1")
+        True
+        >>> is_ipv6("192.168.0.1")
+        False
+        >>> is_ipv6("1:1:1:1:1:1:1:1:1")
+        False
 
 
 If the iso8601_ library is present, a date-time checker will also be present.
-- 
cgit v1.2.1