improve top-level docstring

diff --git a/requests/__init__.py b/requests/__init__.py
index e61dda7..a5a7807 100644 (file)
--- a/requests/__init__.py
+++ b/requests/__init__.py
@@ -6,8 +6,35 @@
 #          /
 
 """
-requests
-~~~~~~~~
+requests HTTP library
+~~~~~~~~~~~~~~~~~~~~~
+
+Requests is an HTTP library, written in Python, for human beings. Basic GET
+usage:
+
+   >>> import requests
+   >>> r = requests.get('http://python.org')
+   >>> r.status_code
+   200
+   >>> 'Python is a programming language' in r.content
+   True
+
+... or POST:
+
+   >>> payload = dict(key1='value1', key2='value2')
+   >>> r = requests.post("http://httpbin.org/post", data=payload)
+   >>> print r.text
+   {
+     // ...snip... //
+     "form": {
+       "key2": "value2",
+       "key1": "value1"
+     },
+     // ...snip... //
+   }
+
+The other HTTP methods are supported - see `requests.api`. Full documentation
+is at <http://requests.rtfd.org/>.
 
 :copyright: (c) 2012 by Kenneth Reitz.
 :license: ISC, see LICENSE for more details.