ES Client API reference¶

Builder Class¶

Builder and associated Classes

This module provides the Builder class to construct Elasticsearch client connections using configuration from dictionaries or YAML files.

Classes:: Builder: Constructs an Elasticsearch client with validated configuration. SecretStore: Securely stores sensitive fields using Fernet encryption.

class es_client.builder.SecretStore[source]¶

Bases: object

Securely stores secrets using Fernet encryption.

Parameters:: key (bytes, optional) – Fernet key for encryption. If None, generates a key.

Example

>>> store = SecretStore()
>>> store.store_secret("api_key", ("id", "key"))
>>> store.get_secret("api_key")
('id', 'key')

__init__(key=None)[source]¶

Parameters:: key (bytes | None)

store_secret(name, value)[source]¶

Encrypt and store a secret.

Parameters:

name (str)
value (Any)

Return type:

None

get_secret(name)[source]¶

Decrypt and return a secret, or None if not found.

Parameters:: name (str)
Return type:: Any

class es_client.builder.Builder[source]¶

Bases: object

Constructs an Elasticsearch client connection from configuration.

The Builder class processes configuration from a dictionary or YAML file, validates it, and creates an Elasticsearch client. It supports automatic connection and version checking, with options for master-only connections. Sensitive fields are stored securely in a SecretStore.

Parameters:

configdict (dict, optional) – Configuration dictionary with an ‘elasticsearch’ key containing ‘client’ and ‘other_settings’ subkeys. Defaults to None.
configfile (str, optional) – Path to a YAML file with the same structure as configdict. Defaults to None.
autoconnect (bool, optional) – Connect to client automatically. Defaults to False.
version_min (tuple, optional) – Minimum Elasticsearch version as (major, minor, patch). Defaults to VERSION_MIN.
version_max (tuple, optional) – Maximum Elasticsearch version as (major, minor, patch). Defaults to VERSION_MAX.

attributes¶

Storage for configuration and settings.

Type:: DotMap

client¶

The Elasticsearch client connection.

Type:: Elasticsearch

_secrets¶

Secure storage for sensitive fields.

Type:: SecretStore

Raises:

ConfigurationError – If configuration is invalid, such as an invalid host schema (checked during initialization).
ESClientException – If connection to Elasticsearch fails.
NotMaster – If master_only is True and connected node is not the master.

Examples

>>> config = {'elasticsearch': {'client': {'hosts': ['http://localhost:9200']}}}
>>> builder = Builder(configdict=config)
>>> builder.client_args.hosts
['http://localhost:9200']
>>> builder.master_only = True
>>> builder.master_only
True
>>> cfg = {'elasticsearch': {'client': {'hosts': ['ftp://invalid']}}})
>>> Builder(configdict=cfg)
Traceback (most recent call last):
    ...
es_client.exceptions.ConfigurationError: Invalid host schema: ftp://invalid

__init__(configdict=None, configfile=None, autoconnect=False, version_min=(8, 0, 0), version_max=(8, 99, 99))[source]¶

Parameters:

configdict (Dict | None)
configfile (str | None)
autoconnect (bool)
version_min (Tuple)
version_max (Tuple)

property master_only: bool¶

Get or set whether to connect only to the elected master node.

Returns:: True if only the master node is allowed, False otherwise.
Return type:: bool

Example

>>> builder = Builder()
>>> builder.master_only = True
>>> builder.master_only
True

property is_master: bool¶

Get or set whether the connected node is the elected master.

Returns:: True if the connected node is the master, False otherwise.
Return type:: bool

Example

>>> builder = Builder()
>>> builder.is_master = False
>>> builder.is_master
False

property config: DotMap¶

Get or set the configuration settings from configfile or configdict.

Returns:: Configuration settings.
Return type:: DotMap

Example

>>> config = {
...     'elasticsearch': {
...         'client': {'hosts': ['http://localhost:9200']}
...     }
... }
>>> builder = Builder(configdict=config)
>>> builder.config.client.hosts
['http://localhost:9200']

property client_args: DotMap¶

Get or set the client settings.

Returns:: Client configuration settings.
Return type:: DotMap

Example

>>> builder = Builder()
>>> builder.client_args.hosts = ['http://localhost:9200']
>>> builder.client_args.hosts
['http://localhost:9200']

property other_args: DotMap¶

Get or set the other settings.

Returns:: Other configuration settings.
Return type:: DotMap

Example

>>> builder = Builder()
>>> builder.other_args.master_only = True
>>> builder.other_args.master_only
True

property skip_version_test: bool¶

Get or set whether to skip version compatibility tests.

Returns:: True if version tests are skipped, False otherwise.
Return type:: bool

Example

>>> builder = Builder()
>>> builder.skip_version_test = True
>>> builder.skip_version_test
True

property version_min: Tuple¶

Get or set the minimum acceptable Elasticsearch version.

Returns:: Minimum version as (major, minor, patch).
Return type:: tuple

Example

>>> builder = Builder()
>>> builder.version_min
(8, 0, 0)

property version_max: Tuple¶

Get or set the maximum acceptable Elasticsearch version.

Returns:: Maximum version as (major, minor, patch).
Return type:: tuple

Example

>>> builder = Builder()
>>> builder.version_max
(8, 99, 99)

set_client_defaults()[source]¶

Set default values for client_args.

Initializes client_args with None for all keys in CLIENT_SETTINGS.

Return type:: None

set_other_defaults()[source]¶

Set default values for other_args.

Initializes other_args with None for all keys in OTHER_SETTINGS.

Return type:: None

process_config_opts(configdict, configfile)[source]¶

Process configuration from configdict or configfile.

Parameters:

configdict (dict, optional) – Configuration dictionary with an ‘elasticsearch’ key containing ‘client’ and ‘other_settings’ subkeys.
configfile (str, optional) – Path to a YAML file with the same structure as configdict.

Return type:

None

Prioritizes configdict over configfile. If neither is provided, uses ES_DEFAULT, which sets hosts to ‘http://127.0.0.1:9200’.

Example

>>> builder = Builder()
>>> builder.config.client.hosts
['http://127.0.0.1:9200']

update_config()[source]¶

Update object with configuration values.

Applies settings from config to client_args and other_args, moves sensitive fields to a secure store, and sets master_only and skip_version_test.

Return type:: None

validate()[source]¶

Validate configuration settings.

Checks basic auth, API key, cloud ID, and SSL settings. Host schemas are validated in __init__() using verify_url_schema(). Issues warnings for experimental options like ssl_version.

Raises:: ConfigurationError – If validation fails, such as missing authentication credentials or invalid cloud ID.
Return type:: None

Example

>>> config = {'elasticsearch': {'client': {'ssl_version': 'TLSv1'}}}
>>> builder = Builder(configdict=config)
... # Warning: ssl_version is experimental; use ssl_context instead

connect()[source]¶

Establish connection to Elasticsearch.

Performs post-connection checks for version and master status using _check_version() and _find_master().

Raises:

NotMaster – If master_only is True and node is not master.
ESClientException – If version is incompatible.

Return type:

None

test_connection()[source]¶

Test the Elasticsearch connection.

Executes info() to verify connectivity.

Returns:

Response from Elasticsearch: info API.

Return type:

ObjectApiResponse