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.
BigSegmentStore
[source]¶ Bases:
object
Interface for a read-only data store that allows querying of user membership in Big Segments.
Big Segments are a specific type of user segments. For more information, read the LaunchDarkly documentation: https://docs.launchdarkly.com/home/users/big-segments
-
abstract
get_membership
(user_hash)[source]¶ Queries the store for a snapshot of the current segment state for a specific user.
The user_hash is a base64-encoded string produced by hashing the user key as defined by the Big Segments specification; the store implementation does not need to know the details of how this is done, because it deals only with already-hashed keys, but the string can be assumed to only contain characters that are valid in base64.
The return value should be either a dict, or None if the user is not referenced in any big segments. Each key in the dictionary is a “segment reference”, which is how segments are identified in Big Segment data. This string is not identical to the segment key– the SDK will add other information. The store implementation should not be concerned with the format of the string. Each value in the dictionary is True if the user is explicitly included in the segment, False if the user is explicitly excluded from the segment– and is not also explicitly included (that is, if both an include and an exclude existed in the data, the include would take precedence). If the user’s status in a particular segment is undefined, there should be no key or value for that segment.
This dictionary may be cached by the SDK, so it should not be modified after it is created. It is a snapshot of the segment membership state at one point in time.
- Parameters
user_hash (
str
) – the hashed user key- Return type
Optional
[dict
]- Returns
True/False values for Big Segments that reference this user
-
abstract
-
class
ldclient.interfaces.
BigSegmentStoreMetadata
(last_up_to_date)[source]¶ Bases:
object
Values returned by
BigSegmentStore.get_metadata()
.-
property
last_up_to_date
¶ The Unix epoch millisecond timestamp of the last update to the BigSegmentStore. It is None if the store has never been updated.
- Return type
Optional
[int
]
-
property
-
class
ldclient.interfaces.
BigSegmentStoreStatus
(available, stale)[source]¶ Bases:
object
Information about the state of a Big Segment store, provided by
BigSegmentStoreStatusProvider
.Big Segments are a specific type of user segments. For more information, read the LaunchDarkly documentation: https://docs.launchdarkly.com/home/users/big-segments
-
property
available
¶ True if the Big Segment store is able to respond to queries, so that the SDK can evaluate whether a user is in a segment or not.
If this property is False, the store is not able to make queries (for instance, it may not have a valid database connection). In this case, the SDK will treat any reference to a Big Segment as if no users are included in that segment. Also, the
ldclient.flag.EvaluationDetail.reason()
associated with with any flag evaluation that references a Big Segment when the store is not available will have a bigSegmentsStatus of “STORE_ERROR”.- Return type
bool
-
property
stale
¶ True if the Big Segment store is available, but has not been updated within the amount of time specified by {BigSegmentsConfig#stale_after}.
This may indicate that the LaunchDarkly Relay Proxy, which populates the store, has stopped running or has become unable to receive fresh data from LaunchDarkly. Any feature flag evaluations that reference a Big Segment will be using the last known data, which may be out of date. Also, the
ldclient.flag.EvaluationDetail.reason()
associated with those evaluations will have a bigSegmentsStatus of “STALE”.- Return type
bool
-
property
-
class
ldclient.interfaces.
BigSegmentStoreStatusProvider
[source]¶ Bases:
object
An interface for querying the status of a Big Segment store.
The Big Segment store is the component that receives information about Big Segments, normally from a database populated by the LaunchDarkly Relay Proxy. Big Segments are a specific type of user segments. For more information, read the LaunchDarkly documentation: https://docs.launchdarkly.com/home/users/big-segments
An implementation of this abstract class is returned by
ldclient.client.LDClient.big_segment_store_status_provider()
. Application code never needs to implement this interface.There are two ways to interact with the status. One is to simply get the current status; if its available property is true, then the SDK is able to evaluate user membership in Big Segments, and the stale` property indicates whether the data might be out of date.
The other way is to subscribe to status change notifications. Applications may wish to know if there is an outage in the Big Segment store, or if it has become stale (the Relay Proxy has stopped updating it with new data), since then flag evaluations that reference a Big Segment might return incorrect values. Use add_listener to register a callback for notifications.
-
abstract
add_listener
(listener)[source]¶ Subscribes for notifications of status changes.
The listener is a function or method that will be called with a single parameter: the new BigSegmentStoreStatus.
- Parameters
listener (
Callable
[[BigSegmentStoreStatus
],None
]) – the listener to add- Return type
None
-
abstract
remove_listener
(listener)[source]¶ Unsubscribes from notifications of status changes.
- Parameters
listener (
Callable
[[BigSegmentStoreStatus
],None
]) – a listener that was previously added with add_listener; if it was not, this method does nothing- Return type
None
-
abstract property
status
¶ Gets the current status of the store.
- Return type
- Returns
the status
-
abstract
-
class
ldclient.interfaces.
DiagnosticDescription
[source]¶ Bases:
object
Optional interface for components to describe their own configuration.
-
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.
-
abstract
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.
-
abstract
-
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.
-
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), anddeleted
(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.
-
abstract
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 getcallback (
Callable
[[Any
],Any
]) – A function that accepts the retrieved data and returns a transformed value
- Return type
Any
-
abstract
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 deletekey (
str
) – The key of the object to be deletedversion (
int
) – The version for the delete operation
-
abstract
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 getkey (
str
) – The key whose associated object is to be returnedcallback (
Callable
[[Any
],Any
]) – A function that accepts the retrieved data and returns a transformed value
- Return type
Any
- Returns
The result of executing callback
-
abstract
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 (
Mapping
[VersionedDataKind
,Mapping
[str
,dict
]]) – All objects to be stored
-
abstract property
initialized
¶ Returns whether the store has been initialized yet or not
- Return type
bool
-
abstract
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 updateitem (
dict
) – The object to update or insert
-
abstract
-
class
ldclient.interfaces.
FeatureStoreCore
[source]¶ Bases:
object
Interface for a simplified subset of the functionality of
FeatureStore
, to be used in conjunction withldclient.feature_store_helpers.CachingStoreWrapper
. This allows developers of customFeatureStore
implementations to avoid repeating logic that would commonly be needed in any such implementation, such as caching. Instead, they can implement onlyFeatureStoreCore
and then create aCachingStoreWrapper
.-
abstract
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 – The kind of objects to get
- Return type
Mapping
[str
,dict
]- Returns
A dictionary of keys to items
-
abstract
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 getkey (
str
) – The key of the object
- Return type
dict
- Returns
The object to which the specified key is mapped, or None
-
abstract
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 (
Mapping
[VersionedDataKind
,Mapping
[str
,dict
]]) – A dictionary of data kinds to item collections
-
abstract
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
-
abstract
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 updateitem (
dict
) – The object to update or insert
- Return type
dict
- Returns
The state of the object after the update
-
abstract
-
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 alsoldclient.integrations.Files.new_data_source()
.
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 objectcache_config (
CacheConfig
) – the caching parameters
-
describe_configuration
(config)[source]¶ Used internally by the SDK to inspect the configuration. :param config: the full configuration, in case this component depends on properties outside itself :return: a string describing the type of the component, or None
-
property
initialized
¶ - Return type
bool
-
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)[source]¶ Bases:
object
-
property
namespace
¶ - Return type
str
-
property
request_api_path
¶ - Return type
str
-
property
stream_api_path
¶ - Return type
str
-
property
-
class
ldclient.versioned_data_kind.
VersionedDataKindWithOrdering
(namespace, request_api_path, stream_api_path, priority, get_dependency_keys)[source]¶ Bases:
ldclient.versioned_data_kind.VersionedDataKind
-
property
get_dependency_keys
¶ - Return type
Optional
[Callable
[[dict
],Iterable
[str
]]]
-
property
priority
¶ - Return type
int
-
property