Merge pull request #690 from fxdgear/nick/update_docs

Updating Docs to reference SSL Context

README

@@ -88,6 +88,22 @@ Simple use-case::
 
 .. _Full documentation: https://elasticsearch-py.readthedocs.io/
 
+Elastic Cloud (and SSL) use-case::
+
+    >>> from elasticsearch import Elasticsearch
+    >>> es = Elasticsearch("https://elasticsearch.url:port", http_auth=('elastic','yourpassword'))
+    >>> es.info()
+
+Using SSL Context with a self-signed cert use-case::
+
+    >>> from elasticsearch import Elasticsearch
+    >>> from elasticsearch.connection import create_ssl_context
+
+    >>> context = create_ssl_context(cafile="path/to/cafile.pem")
+    >>> es = Elasticsearch("https://elasticsearch.url:port", ssl_context=context, http_auth=('elastic','yourpassword'))
+    >>> es.info()
+
+
 
 Features
 --------

docs/connection.rst

@@ -54,6 +54,14 @@ If you want to create your own `SSLContext` object you can create one natively u
 python SSL library with the `create_default_context` (https://docs.python.org/3/library/ssl.html#ssl.create_default_context) method
 or you can use the wrapper function :function:`~elasticsearch.connection.http_urllib3.create_ssl_context`.
 
+To create an `SSLContext` object you only need to use one of cafile, capath or cadata::
+
+    >>> from elasticsearch.connection import create_ssl_context
+    >>> context = create_ssl_context(cafile=None, capath=None, cadata=None)
+
+* `cafile` is the path to your CA File
+* `capath` is the directory of a collection of CA's
+* `cadata` is either an ASCII string of one or more PEM-encoded certificates or a bytes-like object of DER-encoded certificates.
 
 .. autoclass:: Urllib3HttpConnection
    :members:

docs/index.rst

@@ -191,34 +191,32 @@ elasticsearch cluster, including certificate verification and http auth::
 
     # ... or specify common parameters as kwargs
 
-    # use certifi for CA certificates
-    import certifi
-
     es = Elasticsearch(
         ['localhost', 'otherhost'],
         http_auth=('user', 'secret'),
+        scheme="https",
         port=443,
-        use_ssl=True
     )
 
     # SSL client authentication using client_cert and client_key
 
+    from elasticsearch.connection import create_ssl_context
+
+    context = create_ssl_context(cafile="path/to/cert.pem")
     es = Elasticsearch(
         ['localhost', 'otherhost'],
         http_auth=('user', 'secret'),
+        scheme="https",
         port=443,
-        use_ssl=True,
+        ssl_context=context,
-        ca_certs='/path/to/cacert.pem',
-        client_cert='/path/to/client_cert.pem',
-        client_key='/path/to/client_key.pem',
     )
 
 ..  warning::
 
     ``elasticsearch-py`` doesn't ship with default set of root certificates. To
     have working SSL certificate validation you need to either specify your own
-    as ``ca_certs`` or install `certifi`_ which will be picked up
+    as ``cafile`` or ``capath`` or ``cadata``  or install `certifi`_ which will
-    automatically.
+    be picked up automatically.
 
 
 See class :class:`~elasticsearch.Urllib3HttpConnection` for detailed

elasticsearch/connection/__init__.py

@@ -1,3 +1,4 @@
 from .base import Connection
 from .http_requests import RequestsHttpConnection
-from .http_urllib3 import Urllib3HttpConnection
+from .http_urllib3 import Urllib3HttpConnection, create_ssl_context
+