<commit_before>"""
Elastic Client Adapters
-----------------------

This library encapsulates the CommCare HQ Elasticsearch client adapters. It
implements a high-level Elasticsearch client protocol necessary to accomplish
all interactions with the backend Elasticsearch cluster. Client adapters are
split into two usage patterns, the "Management Adapter" and "Document Adapters".

.. toctree::

    Management Adapter
    Document Adapters
    Code Documentation

Management Adapter
''''''''''''''''''

There is only one management adapter, ``ElasticManageAdapter``. This adapter is
used for performing all cluster management tasks such as creating and updating
indices and their mappings, changing index settings, changing cluster settings,
etc.  This functionality is split into a separate class for a few reasons:

1. The management adapter is responsible for low-level Elastic operations which
   document adapters should never be performing because the scope of a document
   adapter does not extend beyond a single index.
2. Future versions of Elasticsearch implement security features which limit the
   kinds of operations a connection can be used for. The separation in these
   client adapter classes is designed to fit into that model.

The management adapter does not need any special parameters to work with, and
can be instantiated and used directly:

.. code-block:: python

    adapter = ElasticManageAdapter()
    adapter.index_create("books")
    mapping = {"properties": {
        "author": {"type": "text"},
        "title": {"type": "text"},
        "published": {"type": "date"},
    }}<commit_msg>Code review: future-proof manage adapter explanation<commit_after>"""
Elastic Client Adapters
-----------------------

This library encapsulates the CommCare HQ Elasticsearch client adapters. It
implements a high-level Elasticsearch client protocol necessary to accomplish
all interactions with the backend Elasticsearch cluster. Client adapters are
split into two usage patterns, the "Management Adapter" and "Document Adapters".

.. toctree::

    Management Adapter
    Document Adapters
    Code Documentation

Management Adapter
''''''''''''''''''

There is only one management adapter, ``ElasticManageAdapter``. This adapter is
used for performing all cluster management tasks such as creating and updating
indices and their mappings, changing index settings, changing cluster settings,
etc.  This functionality is split into a separate class for a few reasons:

1. The management adapter is responsible for low-level Elastic operations which
   document adapters should never be performing because the scope of a document
   adapter does not extend beyond a single index.
2. Elasticsearch 5+ implements security features which limit the kinds of
   operations a connection can be used for. The separation in these client
   adapter classes is designed to fit into that model.

The management adapter does not need any special parameters to work with, and
can be instantiated and used directly:

.. code-block:: python

    adapter = ElasticManageAdapter()
    adapter.index_create("books")
    mapping = {"properties": {
        "author": {"type": "text"},
        "title": {"type": "text"},
        "published": {"type": "date"},
    }}
{'fraction_non_alphanumeric': 0.08241421568627451, 'fraction_numerical': 0.0015318627450980392, 'mean_word_length': 4.062015503875969, 'pattern_counts': {'":': 14, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2098078', 'n_tokens_mistral': 765, 'n_tokens_neox': 746, 'n_words': 399}