Merge pull request elastic#690 from fxdgear/nick/update_docs

Updating Docs to reference SSL Context

Author: fxdgear

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

@@ -59,8 +59,8 @@ Example Usage
  es = Elasticsearch()
 
  doc = {
- 'author': 'kimchy', 
- 'text': 'Elasticsearch: cool. bonsai cool.', 
+ 'author': 'kimchy',
+ 'text': 'Elasticsearch: cool. bonsai cool.',
  'timestamp': datetime.now(),
  }
  res = es.index(index="test-index", doc_type='tweet', id=1, body=doc)
@@ -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,
- ca_certs='/path/to/cacert.pem',
- client_cert='/path/to/client_cert.pem',
- client_key='/path/to/client_key.pem',
+ ssl_context=context,
  )
 
 .. 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
- automatically.
+ as ``cafile`` or ``capath`` or ``cadata`` or install `certifi`_ which will
+ 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
+