From 9fcfec18daf65028b06ab3c32620a21a8ce70f94 Mon Sep 17 00:00:00 2001 From: Kenneth Reitz Date: Wed, 28 Dec 2011 03:18:40 -0500 Subject: [PATCH] ssl docs --- README.rst | 3 ++- docs/community/faq.rst | 6 ++++++ docs/index.rst | 3 +-- docs/user/advanced.rst | 19 +++++++++++++++++-- requests/api.py | 1 + requests/sessions.py | 2 +- 6 files changed, 28 insertions(+), 6 deletions(-) diff --git a/README.rst b/README.rst index 5e8fa6db..4c2fd1df 100644 --- a/README.rst +++ b/README.rst @@ -34,9 +34,10 @@ all the hard work and crazy hacks for you. Features -------- +- Browser standard SSL verification. - Extremely simple HEAD, GET, POST, PUT, PATCH, DELETE Requests. - Gevent support for Asyncronous Requests. -- Sessions with cookie persistience. +- Sessions with cookie persistence. - Basic, Digest, and Custom Authentication support. - Automatic form-encoding of dictionaries - A simple dictionary interface for request/response cookies. diff --git a/docs/community/faq.rst b/docs/community/faq.rst index bad71b88..c900d973 100644 --- a/docs/community/faq.rst +++ b/docs/community/faq.rst @@ -81,3 +81,9 @@ Proxy Support? You bet! + +SSL Verification? +----------------- + +Absolutely. + diff --git a/docs/index.rst b/docs/index.rst index 677d615f..78658cef 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -65,14 +65,13 @@ Requests is ready for today's web. - International Domains and URLs - Keep-Alive & Connection Pooling - Sessions with Cookie Persistence +- Browser-style SSL Verification - Basic/Digest Authentication - Elegant Key/Value Cookies - Automatic Decompression - Unicode Response Bodies - Multipart File Uploads - Connection Timeouts -- Zero Dependencies - User Guide diff --git a/docs/user/advanced.rst b/docs/user/advanced.rst index 4b3430f2..4b94a7aa 100644 --- a/docs/user/advanced.rst +++ b/docs/user/advanced.rst @@ -45,9 +45,24 @@ Any dictionaries that you pass to a request method will be merged with the sessi All values that are contained within a session are directly available to you. See the :ref:`Session API Docs ` to learn more. +SSL Cert Verification +--------------------- + +Requests can verify SSL certificates for HTTPS requests, just like a web browser. To check a host's SSL certificate, you can use the ``verify`` argument:: + + >>> requests.get('https://kennethreitz.com', verify=True) + requests.exceptions.SSLError: hostname 'kennethreitz.com' doesn't match either of '*.herokuapp.com', 'herokuapp.com' + +I don't have SSL setup on this domain, so it fails. Excellent. I do hate it setup for httpbin.org though:: + + >>> requests.get('https://httpbin.org', verify=True) + + +You can also pass ``verify`` the path to a CA_BUNDLE file for private certs. You can also set the ``REQUESTS_CA_BUNDLE`` environment variable. + Body Content Workflow ----------------------- +--------------------- By default, when you make a request, the body of the response isn't downloaded immediately. The response headers are downloaded when you make a request, but the content isn't downloaded until you access the :class:`Response.content` attribute. @@ -246,7 +261,7 @@ Then, we can make a request using our Pizza Auth:: Streaming Requests ------------------ -With ``requests.Response.iter_lines()`` you can easily iterate over streaming +With ``requests.Response.iter_lines()`` you can easily iterate over streaming APIs such as the `Twitter Streaming API `_. To use the Twitter Streaming API to track the keyword "requests": diff --git a/requests/api.py b/requests/api.py index 7f2ed419..72ab3056 100644 --- a/requests/api.py +++ b/requests/api.py @@ -31,6 +31,7 @@ def request(method, url, **kwargs): :param return_response: (optional) If False, an un-sent Request object will returned. :param session: (optional) A :class:`Session` object to be used for the request. :param config: (optional) A configuration dictionary. + :param verify: (optional) if ``True``, the SSL cert will be verified. A CA_BUNDLE path can also be provided. """ s = kwargs.get('session') or sessions.session() diff --git a/requests/sessions.py b/requests/sessions.py index 280bd5cc..292e8af7 100644 --- a/requests/sessions.py +++ b/requests/sessions.py @@ -133,7 +133,7 @@ class Session(object): :param return_response: (optional) If False, an un-sent Request object will returned. :param config: (optional) A configuration dictionary. :param prefetch: (optional) if ``True``, the response content will be immediately downloaded. - :param prefetch: (optional) if ``True``, the SSL cert will be verified. A CA_BUNDLE path can also be provided. + :param verify: (optional) if ``True``, the SSL cert will be verified. A CA_BUNDLE path can also be provided. """ method = str(method).upper()