Merge branch 'master' into 8.x

.gitignore

@@ -42,7 +42,6 @@ cover/
 .coverage
 .coverage.*
 .cache
-nosetests.xml
 coverage.xml
 *.cover
 .hypothesis/

.readthedocs.yaml

@@ -3,23 +3,19 @@
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
-version: 2
+version: 3
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-22.04
   tools:
-    python: "3.9"
+    python: "3.11"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/conf.py
 
-# If using Sphinx, optionally build your docs in additional formats such as PDF
-# formats:
-#    - pdf
-
-# Optionally declare the Python requirements required to build your docs
 python:
-   install:
-   - requirements: docs/requirements.txt
+  install:
+    - method: pip
+      path: .

docs/Changelog.rst

@@ -3,6 +3,20 @@
 Changelog
 =========
 
+8.6.2 (19 February 2023)
+------------------------
+
+**Announcement**
+
+Version sync with released Elasticsearch Python module.
+
+**Changes**
+
+  * Fix ``cloud_id`` and ``hosts`` collision detection and add test to cover this case.
+  * Code readability improvements (primarily for documentation).
+  * Documentation readability improvements, and improved cross-linking.
+  * Add example cli script to docs.
+
 8.6.1.post1 (30 January 2023)
 -----------------------------
 

docs/api.rst

@@ -0,0 +1,70 @@
+.. _api:
+
+ES Client API reference
+#######################
+
+ClientArgs Class
+================
+
+.. autoclass:: es_client.builder.ClientArgs
+   :members:
+   :undoc-members:
+   :private-members:
+
+OtherArgs Class
+===============
+
+.. autoclass:: es_client.builder.OtherArgs
+   :members:
+   :undoc-members:
+   :private-members:
+
+Builder Class
+=============
+
+.. autoclass:: es_client.builder.Builder
+   :members:
+   :undoc-members:
+   :private-members:
+
+Builder Attribute Errata
+------------------------
+
+:client: The :py:class:`~.elasticsearch.Elasticsearch` object is only created after passing all
+   other tests, and if ``autoconnect`` is ``True``, or
+   :py:meth:`~.es_client.builder.Builder.connect` has been called.
+
+:is_master: Initially set to ``None``, this value is set automatically if ``autoconnect`` is
+   ``True``.  It can otherwise be set by calling
+   :py:meth:`~.es_client.builder.Builder._find_master` after
+   :py:meth:`~.es_client.builder.Builder._get_client` has been called first.
+
+
+Class Instantiation Flow
+------------------------
+#. Check to see if ``elasticsearch`` key is in the supplied ``raw_config``
+   dictionary.  Log a warning about using defaults if it is not.
+#. Run :py:meth:`~.es_client.builder.Builder._check_config` on ``raw_config``
+#. Set instance attributes ``version_max`` and ``version_min`` with the
+   provided values.
+#. Set instance attribute ``master_only`` to the value from ``raw_config``
+#. Initialize instance attribute ``is_master`` with a ``None``
+#. Set instance attribute ``skip_version_test`` to the value from
+   ``raw_config``
+#. Set instance attribute ``client_args`` to the value of
+   ``raw_config['elasticsearch']['client']``
+#. Execute :py:meth:`~.es_client.builder.Builder._check_basic_auth` to build the ``basic_auth``
+   tuple, if ``username`` and ``password`` are not ``None``.
+#. Execute :py:meth:`~.es_client.builder.Builder._check_api_key` to build the
+   ``api_key`` tuple, if the ``id`` and ``api_key`` sub-keys are not ``None``.
+#. Execute :py:meth:`~.es_client.builder.Builder._check_cloud_id` to ensure the client
+   connects to the defined ``cloud_id`` rather than anything in ``hosts``.
+#. Execute :py:meth:`~.es_client.builder.Builder._check_ssl` to ensure we have at least the
+   `certifi <https://github.com/certifi/python-certifi>`_ signing certificates.
+#. If ``autoconnect`` is `True`:
+
+    #. Execute :py:meth:`~.es_client.builder.Builder._get_client` to finally build the
+       :py:class:`~.elasticsearch.Elasticsearch` client object.
+    #. Execute :py:meth:`~.es_client.builder.Builder._check_version` and
+       :py:meth:`~.es_client.builder.Builder._check_master` as post-checks.  Nothing will
+       happen if these checks are not enabled in ``raw_config``