Extending the SDK

ldclient.interfaces module

This submodule contains interfaces for various components of the SDK.

They may be useful in writing new implementations of these components, or for testing.

class ldclient.interfaces.BackgroundOperation[source]

Bases: object

is_alive()[source]

Returns whether the operation is alive or not :rtype: bool

start()[source]

Starts an operation in the background. Should return immediately and not block.

stop()[source]

Stops an operation running in the background. May return before the operation is actually stopped.

class ldclient.interfaces.DiagnosticDescription[source]

Bases: object

Optional interface for components to describe their own configuration.

describe_configuration(config)[source]

Used internally by the SDK to inspect the configuration. :param ldclient.config.Config config: the full configuration, in case this component depends on properties outside itself :return: a string describing the type of the component, or None :rtype: string

class ldclient.interfaces.EventProcessor[source]

Bases: object

Interface for the component that buffers analytics events and sends them to LaunchDarkly. The default implementation can be replaced for testing purposes.

flush()[source]

Specifies that any buffered events should be sent as soon as possible, rather than waiting for the next flush interval. This method is asynchronous, so events still may not be sent until a later time. However, calling stop() will synchronously deliver any events that were not yet delivered prior to shutting down.

send_event(event)[source]

Processes an event to be sent at some point.

stop()[source]

Shuts down the event processor after first delivering all pending events.

class ldclient.interfaces.FeatureRequester[source]

Bases: object

Interface for the component that acquires feature flag data in polling mode. The default implementation can be replaced for testing purposes.

get_all()[source]

Gets all feature flags.

class ldclient.interfaces.FeatureStore[source]

Bases: object

Interface for a versioned store for feature flags and related objects received from LaunchDarkly. Implementations should permit concurrent access and updates.

An “object”, for FeatureStore, is simply a dict of arbitrary data which must have at least three properties: key (its unique key), version (the version number provided by LaunchDarkly), and deleted (True if this is a placeholder for a deleted object).

Delete and upsert requests are versioned: if the version number in the request is less than the currently stored version of the object, the request should be ignored.

These semantics support the primary use case for the store, which synchronizes a collection of objects based on update messages that may be received out-of-order.

all(kind, callback=<function FeatureStore.<lambda>>)[source]

Retrieves a dictionary of all associated objects of a given kind. The retrieved dict of keys to objects can be transformed by the specified callback.

Parameters:
  • kind (VersionedDataKind) – The kind of objects to get
  • callback (function) – A function that accepts the retrieved data and returns a transformed value
Return type:

The result of executing callback

delete(kind, key, version)[source]

Deletes the object associated with the specified key, if it exists and its version is less than the specified version. The object should be replaced in the data store by a placeholder with the specified version and a “deleted” property of TErue.

Parameters:
  • kind (VersionedDataKind) – The kind of object to delete
  • key (str) – The key of the object to be deleted
  • version (int) – The version for the delete operation
get(kind, key, callback=<function FeatureStore.<lambda>>)[source]

Retrieves the object to which the specified key is mapped, or None if the key is not found or the associated object has a deleted property of True. The retrieved object, if any (a dict) can be transformed by the specified callback.

Parameters:
  • kind (VersionedDataKind) – The kind of object to get
  • key (str) – The key whose associated object is to be returned
  • callback (function) – A function that accepts the retrieved data and returns a transformed value
Returns:

The result of executing callback

init(all_data)[source]

Initializes (or re-initializes) the store with the specified set of objects. Any existing entries will be removed. Implementations can assume that this set of objects is up to date– there is no need to perform individual version comparisons between the existing objects and the supplied data.

Parameters:all_data (dict[VersionedDataKind, dict[str, dict]]) – All objects to be stored
initialized

Returns whether the store has been initialized yet or not

Return type:bool
upsert(kind, item)[source]

Updates or inserts the object associated with the specified key. If an item with the same key already exists, it should update it only if the new item’s version property is greater than the old one.

Parameters:
  • kind (VersionedDataKind) – The kind of object to update
  • item – The object to update or insert
class ldclient.interfaces.FeatureStoreCore[source]

Bases: object

Interface for a simplified subset of the functionality of FeatureStore, to be used in conjunction with ldclient.feature_store_helpers.CachingStoreWrapper. This allows developers of custom FeatureStore implementations to avoid repeating logic that would commonly be needed in any such implementation, such as caching. Instead, they can implement only FeatureStoreCore and then create a CachingStoreWrapper.

get_all_internal(callback)[source]

Returns a dictionary of all associated objects of a given kind. The method should not attempt to filter out any items based on their deleted property, nor to cache any items.

Parameters:kind (VersionedDataKind) – The kind of objects to get
Returns:A dictionary of keys to items
Return type:dict[str, dict]
get_internal(kind, key)[source]

Returns the object to which the specified key is mapped, or None if no such item exists. The method should not attempt to filter out any items based on their deleted property, nor to cache any items.

Parameters:
  • kind (VersionedDataKind) – The kind of object to get
  • key (str) – The key of the object
Returns:

The object to which the specified key is mapped, or None

Return type:

dict

init_internal(all_data)[source]

Initializes (or re-initializes) the store with the specified set of objects. Any existing entries will be removed. Implementations can assume that this set of objects is up to date– there is no need to perform individual version comparisons between the existing objects and the supplied data.

Parameters:all_data (dict[VersionedDataKind, dict[str, dict]]) – A dictionary of data kinds to item collections
initialized_internal()[source]

Returns true if this store has been initialized. In a shared data store, it should be able to detect this even if initInternal was called in a different process, i.e. the test should be based on looking at what is in the data store. The method does not need to worry about caching this value; CachingStoreWrapper will only call it when necessary.

Return type:bool
upsert_internal(kind, item)[source]

Updates or inserts the object associated with the specified key. If an item with the same key already exists, it should update it only if the new item’s version property is greater than the old one. It should return the final state of the item, i.e. if the update succeeded then it returns the item that was passed in, and if the update failed due to the version check then it returns the item that is currently in the data store (this ensures that CachingStoreWrapper will update the cache correctly).

Parameters:
  • kind (VersionedDataKind) – The kind of object to update
  • item (dict) – The object to update or insert
Returns:

The state of the object after the update

Return type:

dict

class ldclient.interfaces.UpdateProcessor[source]

Bases: ldclient.interfaces.BackgroundOperation

Interface for the component that obtains feature flag data in some way and passes it to a FeatureStore. The built-in implementations of this are the client’s standard streaming or polling behavior. For testing purposes, there is also ldclient.integrations.Files.new_data_source().

initialized()[source]

Returns whether the update processor has received feature flags and has initialized its feature store.

Return type:bool

ldclient.feature_store_helpers module

This submodule contains support code for writing feature store implementations.

class ldclient.feature_store_helpers.CachingStoreWrapper(core, cache_config)[source]

Bases: ldclient.interfaces.DiagnosticDescription, ldclient.interfaces.FeatureStore

A partial implementation of ldclient.interfaces.FeatureStore.

This class delegates the basic functionality to an implementation of ldclient.interfaces.FeatureStoreCore - while adding optional caching behavior and other logic that would otherwise be repeated in every feature store implementation. This makes it easier to create new database integrations by implementing only the database-specific logic.

__init__(core, cache_config)[source]

Constructs an instance by wrapping a core implementation object.

Parameters:
  • core (FeatureStoreCore) – the implementation object
  • cache_config (ldclient.feature_store.CacheConfig) – the caching parameters
all(kind, callback=<function CachingStoreWrapper.<lambda>>)[source]
delete(kind, key, version)[source]
describe_configuration(config)[source]

Used internally by the SDK to inspect the configuration. :param ldclient.config.Config config: the full configuration, in case this component depends on properties outside itself :return: a string describing the type of the component, or None :rtype: string

get(kind, key, callback=<function CachingStoreWrapper.<lambda>>)[source]
init(all_data)[source]
initialized
upsert(kind, item)[source]

ldclient.versioned_data_kind module

This submodule is used only by the internals of the feature flag storage mechanism.

If you are writing your own implementation of ldclient.integrations.FeatureStore, the VersionedDataKind tuple type will be passed to the kind parameter of the feature store methods; its namespace property tells the feature store which collection of objects is being referenced (“features”, “segments”, etc.). The intention is for the feature store to treat storable objects as completely generic JSON dictionaries, rather than having any special logic for features or segments.

class ldclient.versioned_data_kind.VersionedDataKind(namespace, request_api_path, stream_api_path)

Bases: tuple

namespace

Alias for field number 0

request_api_path

Alias for field number 1

stream_api_path

Alias for field number 2

class ldclient.versioned_data_kind.VersionedDataKindWithOrdering(namespace, request_api_path, stream_api_path, priority, get_dependency_keys)

Bases: tuple

get_dependency_keys

Alias for field number 4

namespace

Alias for field number 0

priority

Alias for field number 3

request_api_path

Alias for field number 1

stream_api_path

Alias for field number 2