Configuration API Documentation¶

Bases: object

Hazelcast client configuration.

property cluster_members: List[str]¶

Candidate address list that the client will use to establish initial connection.

By default, set to ["127.0.0.1"].

property cluster_name: str¶

Name of the cluster to connect to.

The name is sent as part of the client authentication message and may be verified on the member. By default, set to dev.

property client_name: Optional[str]¶

Name of the client instance.

By default, set to hz.client_${CLIENT_ID}, where CLIENT_ID starts from 0 and it is incremented by 1 for each new client.

property connection_timeout: Union[int, float]¶

Socket timeout value in seconds for the client to connect member nodes.

Setting this to 0 makes the connection blocking. By default, set to 5.0.

property socket_options: List[Tuple[int, int, Union[int, bytes]]]¶

List of socket option tuples.

The tuples must contain the parameters passed into the socket.setsockopt() in the same order.

property redo_operation: bool¶

When set to True, the client will redo the operations that were executing on the server in case if the client lost connection.

This can happen because of network problems, or simply because the member died. However, it is not clear whether the operation was performed or not. For idempotent operations this is harmless, but for non-idempotent ones retrying can cause to undesirable effects. Note that the redo can be processed on any member. By default, set to False.

property smart_routing: bool¶

Enables smart mode for the client instead of unisocket client.

Smart clients send key based operations to owner of the keys. Unisocket clients send all operations to a single node. By default, set to True.

property ssl_enabled: bool¶

If it is True, SSL is enabled.

By default, set to False.

property ssl_cafile: Optional[str]¶

Absolute path of concatenated CA certificates used to validate server’s certificates in PEM format.

When SSL is enabled and cafile is not set, a set of default CA certificates from default locations will be used.

property ssl_certfile: Optional[str]¶: Absolute path of the client certificate in PEM format.

property ssl_keyfile: Optional[str]¶

Absolute path of the private key file for the client certificate in the PEM format.

If this parameter is None, private key will be taken from the certfile.

property ssl_password: Optional[Union[Callable[[], Union[str, bytes]], str, bytes]]¶

Password for decrypting the keyfile if it is encrypted.

The password may be a function to call to get the password. It will be called with no arguments, and it should return a string, bytes, or bytearray. If the return value is a string it will be encoded as UTF-8 before using it to decrypt the key. Alternatively a string, bytes, or bytearray value may be supplied directly as the password.

property ssl_protocol: int¶

Protocol version used in SSL communication.

By default, set to TLSv1_2. See the hazelcast.config.SSLProtocol for possible values.

property ssl_ciphers: Optional[str]¶

String in the OpenSSL cipher list format to set the available ciphers for sockets.

More than one cipher can be set by separating them with a colon.

property ssl_check_hostname: bool¶

When set to True, verifies that the hostname in the member’s certificate and the address of the member matches during the handshake.

By default, set to False.

property cloud_discovery_token: Optional[str]¶

Discovery token of the Hazelcast Viridian cluster.

When this value is set, Hazelcast Viridian discovery is enabled.

property async_start: bool¶

Enables non-blocking start mode of the client.

When set to True, the client creation will not wait to connect to cluster. The client instance will throw exceptions until it connects to cluster and becomes ready. If set to False, the client will block until a cluster connection established, and it is ready to use the client instance. By default, set to False.

property reconnect_mode: int¶

Defines how the client reconnects to cluster after a disconnect.

By default, set to ON. See the hazelcast.config.ReconnectMode for possible values.

property retry_initial_backoff: Union[int, float]¶

Wait period in seconds after the first failure before retrying.

Must be non-negative. By default, set to 1.0.

property retry_max_backoff: Union[int, float]¶

Upper bound for the backoff interval in seconds.

Must be non-negative. By default, set to 30.0.

property retry_jitter: Union[int, float]¶

Defines how much to randomize backoffs.

At each iteration the calculated back-off is randomized via following method in pseudocode:

Random(-jitter * current_backoff, jitter * current_backoff).

Must be in range [0.0, 1.0]. By default, set to 0.0 (no randomization).

property retry_multiplier: Union[int, float]¶

The factor with which to multiply backoff after a failed retry.

Must be greater than or equal to 1. By default, set to 1.05.

property cluster_connect_timeout: Union[int, float]¶

Timeout value in seconds for the client to give up connecting to the cluster.

Must be non-negative or equal to -1. By default, set to -1. -1 means that the client will not stop trying to the target cluster. (infinite timeout)

property portable_version: int¶

Default value for the portable version if the class does not have the get_portable_version() method.

Portable versions are used to differentiate two versions of the hazelcast.serialization.api.Portable classes that have added or removed fields, or fields with different types.

property data_serializable_factories: Dict[int, Dict[int, Type[IdentifiedDataSerializable]]]¶

Dictionary of factory id and corresponding hazelcast.serialization.api.IdentifiedDataSerializable factories.

A factory is simply a dictionary with class id and callable class constructors.

FACTORY_ID = 1
CLASS_ID = 1

class SomeSerializable(IdentifiedDataSerializable):
    # omitting the implementation
    pass


client = HazelcastClient(data_serializable_factories={
    FACTORY_ID: {
        CLASS_ID: SomeSerializable
    }
})

property portable_factories: Dict[int, Dict[int, Type[Portable]]]¶

Dictionary of factory id and corresponding hazelcast.serialization.api.Portable factories.

A factory is simply a dictionary with class id and callable class constructors.

FACTORY_ID = 2
CLASS_ID = 2

class SomeSerializable(Portable):
    # omitting the implementation
    pass


client = HazelcastClient(portable_factories={
    FACTORY_ID: {
        CLASS_ID: SomeSerializable
    }
})

property compact_serializers: List[CompactSerializer]¶

List of Compact serializers.

class Foo:
    pass

class FooSerializer(CompactSerializer[Foo]):
    pass

client = HazelcastClient(
    compact_serializers=[
        FooSerializer(),
    ],
)

property class_definitions: List[ClassDefinition]¶: List of all portable class definitions.

property check_class_definition_errors: bool¶

When enabled, serialization system will check for class definition errors at start and throw an hazelcast.errors.HazelcastSerializationError with error definition.

By default, set to True.

property is_big_endian: bool¶

Defines if big-endian is used as the byte order for the serialization.

By default, set to True.

property default_int_type: int¶

Defines how the int type is represented on the member side.

By default, it is serialized as INT (32 bits). See the hazelcast.config.IntType for possible values.

property global_serializer: Optional[Type[StreamSerializer]]¶

Defines the global serializer.

This serializer is registered as a fallback serializer to handle all other objects if a serializer cannot be located for them.

property custom_serializers: Dict[Type[Any], Type[StreamSerializer]]¶

Dictionary of class and the corresponding custom serializers.

class SomeClass:
    # omitting the implementation
    pass


class SomeClassSerializer(StreamSerializer):
    # omitting the implementation
    pass

client = HazelcastClient(custom_serializers={
    SomeClass: SomeClassSerializer
})

property near_caches: Dict[str, NearCacheConfig]¶

Dictionary of near cache names to the corresponding near cache configurations.

See the hazelcast.config.NearCacheConfig for the possible configuration options.

The near cache configuration can also be passed as a dictionary of configuration option name to value. When an option is missing from the dictionary configuration, it will be set to its default value.

property load_balancer: Optional[LoadBalancer]¶: Load balancer implementation for the client.

property membership_listeners: List[Tuple[Optional[Callable[[MemberInfo], None]], Optional[Callable[[MemberInfo], None]]]]¶

List of membership listener tuples.

Tuples must be of size 2. The first element will be the function to be called when a member is added, and the second element will be the function to be called when the member is removed with the hazelcast.core.MemberInfo as the only parameter.

Any of the elements can be None, but not at the same time.

property lifecycle_listeners: List[Callable[[str], None]]¶

List of lifecycle listeners.

Listeners will be called with the new lifecycle state as the only parameter when the client changes lifecycle states.

property flake_id_generators: Dict[str, FlakeIdGeneratorConfig]¶

Dictionary of flake id generator names to the corresponding flake id generator configurations.

See the hazelcast.config.FlakeIdGeneratorConfig for the possible configuration options.

The flake id generator configuration can also be passed as a dictionary of configuration option name to value. When an option is missing from the dictionary configuration, it will be set to its default value.

property reliable_topics: Dict[str, ReliableTopicConfig]¶

Dictionary of reliable topic names to the corresponding reliable topic configurations.

See the hazelcast.config.ReliableTopicConfig for the possible configuration options.

The reliable topic configuration can also be passed as a dictionary of configuration option name to value. When an option is missing from the dictionary configuration, it will be set to its default value.

property labels: List[str]¶: Labels for the client to be sent to the cluster.

property heartbeat_interval: Union[int, float]¶

Time interval between the heartbeats sent by the client to the member nodes in seconds.

By default, set to 5.0.

property heartbeat_timeout: Union[int, float]¶

If there is no message passing between the client and a member within the given time via this property in seconds, the connection will be closed.

By default, set to 60.0.

property invocation_timeout: Union[int, float]¶

When an invocation gets an exception because

Member throws an exception.
Connection between the client and member is closed.
The client’s heartbeat requests are timed out.

Time passed since invocation started is compared with this property. If the time is already passed, then the exception is delegated to the user. If not, the invocation is retried. Note that, if invocation gets no exception, and it is a long-running one, then it will not get any exception, no matter how small this timeout is set. Time unit is in seconds.

By default, set to 120.0.

property invocation_retry_pause: Union[int, float]¶

Pause time between each retry cycle of an invocation in seconds.

By default, set to 1.0.

property statistics_enabled: bool¶

When set to True, the client statistics collection is enabled.

By default, set to False.

property statistics_period: Union[int, float]¶: The period in seconds the statistics run.

property shuffle_member_list: bool¶

The client shuffles the given member list to prevent all clients to connect to the same node when this property is set to True.

When it is set to False, the client tries to connect to the nodes in the given order.

By default, set to True.

property backup_ack_to_client_enabled: bool¶

Enables the client to get backup acknowledgements directly from the member that backups are applied, which reduces number of hops and increases performance for smart clients.

This option has no effect for unisocket clients.

By default, set to True (enabled).

property operation_backup_timeout: Union[int, float]¶

If an operation has backups, defines how long the invocation will wait for acks from the backup replicas in seconds.

If acks are not received from some backups, there won’t be any rollback on other successful replicas.

By default, set to 5.0.

property fail_on_indeterminate_operation_state: bool¶

When enabled, if an operation has sync backups and acks are not received from backup replicas in time, or the member which owns primary replica of the target partition leaves the cluster, then the invocation fails with hazelcast.errors.IndeterminateOperationStateError.

However, even if the invocation fails, there will not be any rollback on other successful replicas.

By default, set to False (do not fail).

property creds_username: Optional[str]¶: Username for credentials authentication (Enterprise feature).

property creds_password: Optional[str]¶: Password for credentials authentication (Enterprise feature).

property token_provider: Optional[TokenProvider]¶

Token provider for custom authentication (Enterprise feature).

Note that token_provider setting has priority over credentials settings.

property use_public_ip: bool¶

When set to True, the client uses the public IP addresses reported by members while connecting to them, if available.

By default, set to False.

classmethod from_dict(d: Dict[str, Any]) → Config[source]¶

Constructs a configuration object out of the given dictionary.

The dictionary items must be valid pairs of configuration option name to its value.

If a configuration is missing from the dictionary, the default value for it will be used.

Parameters:: d – Dictionary that describes the configuration.
Returns:: The constructed configuration object.

class NearCacheConfig[source]¶

Bases: object

property invalidate_on_change: bool¶

Enables cluster-assisted invalidate on change behavior.

When set to True, entries are invalidated when they are changed in cluster.

By default, set to True.

property in_memory_format: int¶

Specifies in which format data will be stored in the Near Cache.

See the hazelcast.config.InMemoryFormat for possible values.

By default, set to BINARY.

property time_to_live: Optional[Union[int, float]]¶

Maximum number of seconds that an entry can stay in cache.

When not set, entries won’t be evicted due to expiration.

property max_idle: Optional[Union[int, float]]¶

Maximum number of seconds that an entry can stay in the Near Cache until it is accessed.

When not set, entries won’t be evicted due to inactivity.

property eviction_policy: int¶

Defines eviction policy configuration.

See the:class:hazelcast.config.EvictionPolicy for possible values.

By default, set to LRU.

property eviction_max_size: int¶

Defines maximum number of entries kept in the memory before eviction kicks in.

By default, set to 10000.

property eviction_sampling_count: int¶

Number of random entries that are evaluated to see if some of them are already expired.

By default, set to 8.

property eviction_sampling_pool_size: int¶

Size of the pool for eviction candidates.

The pool is kept sorted according to the eviction policy. By default, set to 16.

classmethod from_dict(d: Dict[str, Any]) → NearCacheConfig[source]¶

Constructs a configuration object out of the given dictionary.

The dictionary items must be valid pairs of configuration option name to its value.

If a configuration is missing from the dictionary, the default value for it will be used.

Parameters:: d – Dictionary that describes the configuration.
Returns:: The constructed configuration object.

class FlakeIdGeneratorConfig[source]¶

Bases: object

property prefetch_count: int¶

Defines how many IDs are pre-fetched on the background when a new flake id is requested from the cluster.

Should be in the range 1..100000. By default, set to 100.

property prefetch_validity: Union[int, float]¶

Defines for how long the pre-fetched IDs can be used.

If this time elapsed, a new batch of IDs will be fetched. Time unit is in seconds. By default, set to 600 (10 minutes).

The IDs contain timestamp component, which ensures rough global ordering of IDs. If an ID is assigned to an object that was created much later, it will be much out of order. If you don’t care about ordering, set this value to 0 for unlimited ID validity.

classmethod from_dict(d: Dict[str, Any]) → FlakeIdGeneratorConfig[source]¶

Constructs a configuration object out of the given dictionary.

The dictionary items must be valid pairs of configuration option name to its value.

If a configuration is missing from the dictionary, the default value for it will be used.

Parameters:: d – Dictionary that describes the configuration.
Returns:: The constructed configuration object.

class ReliableTopicConfig[source]¶

Bases: object

property read_batch_size: int¶

Number of messages the reliable topic will try to read in batch.

It will get at least one, but if there are more available, then it will try to get more to increase throughput. By default, set to 10.

property overload_policy: int¶

Policy to handle an overloaded topic.

By default, set to BLOCK. See the hazelcast.config.TopicOverloadPolicy for possible values.

classmethod from_dict(d: Dict[str, Any]) → ReliableTopicConfig[source]¶

Constructs a configuration object out of the given dictionary.

The dictionary items must be valid pairs of configuration option name to its value.

If a configuration is missing from the dictionary, the default value for it will be used.

Parameters:: d – Dictionary that describes the configuration.
Returns:: The constructed configuration object.

class IntType[source]¶

Bases: object

Integer type options that can be used by serialization service.

VAR = 0¶: Integer types will be serialized as 8, 16, 32, 64 bit integers or as Java BigInteger according to their value. This option may cause problems when the Python client is used in conjunction with statically typed language clients such as Java or .NET.

BYTE = 1¶: Integer types will be serialized as a 8 bit integer(as Java byte)

SHORT = 2¶: Integer types will be serialized as a 16 bit integer(as Java short)

INT = 3¶: Integer types will be serialized as a 32 bit integer(as Java int)

LONG = 4¶: Integer types will be serialized as a 64 bit integer(as Java long)

BIG_INT = 5¶: Integer types will be serialized as Java BigInteger. This option can handle integer types which are less than -2^63 or greater than or equal to 2^63. However, when this option is set, serializing/de-serializing integer types is costly.

class EvictionPolicy[source]¶

Bases: object

Near Cache eviction policy options.

NONE = 0¶: No eviction.

LRU = 1¶: Least Recently Used items will be evicted.

LFU = 2¶: Least frequently Used items will be evicted.

RANDOM = 3¶: Items will be evicted randomly.

class InMemoryFormat[source]¶

Bases: object

Near Cache in memory format of the values.

BINARY = 0¶: As Hazelcast serialized bytearray data.

OBJECT = 1¶: As the actual object.

class SSLProtocol[source]¶

Bases: object

SSL protocol options.

TLSv1_3 requires at least Python 3.7 build with OpenSSL 1.1.1+

SSLv2 = 0¶: SSL 2.0 Protocol. RFC 6176 prohibits SSL 2.0. Please use TLSv1+.

SSLv3 = 1¶: SSL 3.0 Protocol. RFC 7568 prohibits SSL 3.0. Please use TLSv1+.

TLSv1 = 2¶: TLS 1.0 Protocol described in RFC 2246.

TLSv1_1 = 3¶: TLS 1.1 Protocol described in RFC 4346.

TLSv1_2 = 4¶: TLS 1.2 Protocol described in RFC 5246.

TLSv1_3 = 5¶: TLS 1.3 Protocol described in RFC 8446.

class QueryConstants[source]¶

Bases: object

Contains constants for Query.

KEY_ATTRIBUTE_NAME = '__key'¶: Attribute name of the key.

THIS_ATTRIBUTE_NAME = 'this'¶: Attribute name of the value.

class UniqueKeyTransformation[source]¶

Bases: object

Defines an assortment of transformations which can be applied to unique key values.

OBJECT = 0¶: Extracted unique key value is interpreted as an object value. Non-negative unique ID is assigned to every distinct object value.

LONG = 1¶: Extracted unique key value is interpreted as a whole integer value of byte, short, int or long type. The extracted value is up casted to long (if necessary) and unique non-negative ID is assigned to every distinct value.

RAW = 2¶: Extracted unique key value is interpreted as a whole integer value of byte, short, int or long type. The extracted value is up casted to long (if necessary) and the resulting value is used directly as an ID.

class IndexType[source]¶

Bases: object

Type of the index.

SORTED = 0¶: Sorted index. Can be used with equality and range predicates.

HASH = 1¶: Hash index. Can be used with equality predicates.

BITMAP = 2¶: Bitmap index. Can be used with equality predicates.

class ReconnectMode[source]¶

Bases: object

Reconnect options.

OFF = 0¶: Prevent reconnect to cluster after a disconnect.

ON = 1¶: Reconnect to cluster by blocking invocations.

ASYNC = 2¶: Reconnect to cluster without blocking invocations. Invocations will receive ClientOfflineError

class TopicOverloadPolicy[source]¶

Bases: object

A policy to deal with an overloaded topic; a topic where there is no place to store new messages.

The reliable topic uses a hazelcast.proxy.ringbuffer.Ringbuffer to store the messages. A ringbuffer doesn’t track where readers are, so it has no concept of a slow consumers. This provides many advantages like high performance reads, but it also gives the ability to the reader to re-read the same message multiple times in case of an error.

A ringbuffer has a limited, fixed capacity. A fast producer may overwrite old messages that are still being read by a slow consumer. To prevent this, we may configure a time-to-live on the ringbuffer.

Once the time-to-live is configured, the TopicOverloadPolicy controls how the publisher is going to deal with the situation that a ringbuffer is full and the oldest item in the ringbuffer is not old enough to get overwritten.

Keep in mind that this retention period (time-to-live) can keep messages from being overwritten, even though all readers might have already completed reading.

DISCARD_OLDEST = 0¶

Using this policy, a message that has not expired can be overwritten.

No matter the retention period set, the overwrite will just overwrite the item.

This can be a problem for slow consumers because they were promised a certain time window to process messages. But it will benefit producers and fast consumers since they are able to continue. This policy sacrifices the slow producer in favor of fast producers/consumers.

DISCARD_NEWEST = 1¶: The message that was to be published is discarded.

BLOCK = 2¶: The caller will wait till there space in the ringbuffer.

ERROR = 3¶: The publish call immediately fails.