How to Make a Python Project Support Both Elasticsearch and Easysearch – A Practical Walkthrough

Background and Goal

Need a single Python codebase that can connect to both Elasticsearch 8.x/9.x and Easysearch, allowing the front‑end to select the engine while the back‑end executes the appropriate DSL and handles HTTPS self‑signed certificates.

Product Compatibility Check

From elasticsearch‑py 7.14 the client validates that the server is an official Elasticsearch distribution and raises UnsupportedProductError for Easysearch/OpenSearch. Version 7.13.1 lacks this validation and can connect to any ES‑compatible service. Versions 8.x enforce stricter validation and reject Easysearch.

NumPy 2.0 Compatibility

NumPy 2.0 removes np.float_ and np.int_, which are used by elasticsearch 7.13. A shim must be applied before importing the client:

import numpy as _np
if not hasattr(_np, "float_"):
    _np.float_ = _np.float64
if not hasattr(_np, "int_"):
    _np.int_ = _np.int64
from elasticsearch import Elasticsearch

HTTPS Self‑Signed Certificate

When using HTTPS with a self‑signed certificate the client raises SSLError: certificate verify failed. Disabling verification (acceptable for internal networks) and suppressing warnings resolves the issue:

kwargs = {
    "hosts": [{"host": host, "port": port, "scheme": scheme}],
    "timeout": 30,
    "max_retries": 3,
    "retry_on_timeout": True,
}
if scheme == "https" and not verify_certs:
    kwargs["verify_certs"] = False
    import urllib3
    urllib3.disable_warnings()
    from elasticsearch import RequestsHttpConnection
    kwargs["connection_class"] = RequestsHttpConnection
client = Elasticsearch(**kwargs)

Dependency Constraints

elasticsearch==7.13.1
numpy<2   # apply the compatibility shim if using NumPy 2.0
requests>=2.26.0

Solution Exploration

Solution A – Dual Clients (ES 8.x + opensearch‑py)

Elasticsearch client: elasticsearch>=8 Easysearch client: opensearch‑py Problem: introduces two packages, two APIs and higher maintenance; the author does not want to add opensearch‑py.

Solution B – Single Client 8.x with Disabled Product Validation

Attempted to monkey‑patch or customize the transport in 8.x to turn off product validation.

Problem: relies on non‑official implementation, carries upgrade risk and is considered unstable.

Solution C – Single Client 7.13.1 (Chosen)

Fix the client to elasticsearch==7.13.1 Connect to both Elasticsearch 8.x/9.x and Easysearch

No product validation, stable API, simple dependencies

Conclusion: Solution C best meets the current requirements.

Unified Client Creation Example

# NumPy compatibility (if using NumPy 2.0)
import numpy as _np
if not hasattr(_np, "float_"):
    _np.float_ = _np.float64
if not hasattr(_np, "int_"):
    _np.int_ = _np.int64

from elasticsearch import Elasticsearch, RequestsHttpConnection
import urllib3

def create_es_client(host, port, scheme="http", http_auth=None, verify_certs=True):
    hosts = [{"host": host, "port": port, "scheme": scheme}]
    kwargs = {
        "hosts": hosts,
        "timeout": 30,
        "max_retries": 3,
        "retry_on_timeout": True,
    }
    if http_auth:
        kwargs["http_auth"] = http_auth
    if scheme == "https" and not verify_certs:
        kwargs["verify_certs"] = False
        urllib3.disable_warnings()
        kwargs["connection_class"] = RequestsHttpConnection
    try:
        client = Elasticsearch(**kwargs)
    except TypeError:
        # Some 7.x versions have different parameters
        kwargs.pop("verify_certs", None)
        client = Elasticsearch(**kwargs)
    if not client.ping():
        client.info()  # fallback
    return client

Configuration sets product: "elasticsearch" or "easysearch"; the back‑end always uses the same elasticsearch 7.13.1 client.

Final Summary

Use a single client ( elasticsearch==7.13.1) to support both Elasticsearch 8.x/9.x and Easysearch.

Version 7.13.1 lacks product validation; versions 7.14+ enforce it, which is why 7.13.1 is selected.

Apply the NumPy shim before importing the client when running under NumPy 2.0.

For self‑signed HTTPS certificates set verify_certs=False and optionally use RequestsHttpConnection with urllib3.disable_warnings().

Avoid adding opensearch‑py to keep dependencies minimal.

If future requirements need Elasticsearch 8.x features together with Easysearch, consider adding opensearch‑py or switching clients per product type.

Full code repository: https://t.zsxq.com/n2LB9