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
-
__dict__
= mappingproxy({'__module__': 'ldclient.interfaces', '__doc__': None, '__weakref__': <attribute '__weakref__' of 'BackgroundOperation' objects>, '__dict__': <attribute '__dict__' of 'BackgroundOperation' objects>, 'start': <function BackgroundOperation.start>, 'is_alive': <function BackgroundOperation.is_alive>, 'stop': <function BackgroundOperation.stop>})¶
-
__module__
= 'ldclient.interfaces'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
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.
-
__dict__
= mappingproxy({'__module__': 'ldclient.interfaces', '__doc__': '\n Interface for the component that buffers analytics events and sends them to LaunchDarkly.\n The default implementation can be replaced for testing purposes.\n ', '__weakref__': <attribute '__weakref__' of 'EventProcessor' objects>, '__dict__': <attribute '__dict__' of 'EventProcessor' objects>, 'send_event': <function EventProcessor.send_event>, '__metaclass__': <class 'abc.ABCMeta'>, 'stop': <function EventProcessor.stop>, 'flush': <function EventProcessor.flush>})¶
-
__metaclass__
¶ alias of
abc.ABCMeta
-
__module__
= 'ldclient.interfaces'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
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.
-
-
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.
-
__dict__
= mappingproxy({'__module__': 'ldclient.interfaces', 'get_all': <function FeatureRequester.get_all>, '__doc__': '\n Interface for the component that acquires feature flag data in polling mode. The default\n implementation can be replaced for testing purposes.\n ', 'get_one': <function FeatureRequester.get_one>, '__dict__': <attribute '__dict__' of 'FeatureRequester' objects>, '__metaclass__': <class 'abc.ABCMeta'>, '__weakref__': <attribute '__weakref__' of 'FeatureRequester' objects>})¶
-
__metaclass__
¶ alias of
abc.ABCMeta
-
__module__
= 'ldclient.interfaces'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
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.
-
__dict__
= mappingproxy({'init': <function FeatureStore.init>, 'delete': <function FeatureStore.delete>, '__weakref__': <attribute '__weakref__' of 'FeatureStore' objects>, 'all': <function FeatureStore.all>, '__metaclass__': <class 'abc.ABCMeta'>, 'initialized': <abc.abstractproperty object>, 'upsert': <function FeatureStore.upsert>, '__module__': 'ldclient.interfaces', '__doc__': '\n Interface for a versioned store for feature flags and related objects received from LaunchDarkly.\n Implementations should permit concurrent access and updates.\n\n An "object", for ``FeatureStore``, is simply a dict of arbitrary data which must have at least\n three properties: ``key`` (its unique key), ``version`` (the version number provided by\n LaunchDarkly), and ``deleted`` (True if this is a placeholder for a deleted object).\n \n Delete and upsert requests are versioned: if the version number in the request is less than\n the currently stored version of the object, the request should be ignored.\n \n These semantics support the primary use case for the store, which synchronizes a collection\n of objects based on update messages that may be received out-of-order.\n ', '__dict__': <attribute '__dict__' of 'FeatureStore' objects>, 'get': <function FeatureStore.get>})¶
-
__metaclass__
¶ alias of
abc.ABCMeta
-
__module__
= 'ldclient.interfaces'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
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 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
.-
__dict__
= mappingproxy({'init_internal': <function FeatureStoreCore.init_internal>, '__weakref__': <attribute '__weakref__' of 'FeatureStoreCore' objects>, 'initialized_internal': <function FeatureStoreCore.initialized_internal>, '__metaclass__': <class 'abc.ABCMeta'>, 'get_all_internal': <function FeatureStoreCore.get_all_internal>, '__module__': 'ldclient.interfaces', '__doc__': '\n Interface for a simplified subset of the functionality of :class:`FeatureStore`, to be used\n in conjunction with :class:`ldclient.feature_store_helpers.CachingStoreWrapper`. This allows\n developers of custom ``FeatureStore`` implementations to avoid repeating logic that would\n commonly be needed in any such implementation, such as caching. Instead, they can implement\n only ``FeatureStoreCore`` and then create a ``CachingStoreWrapper``.\n ', '__dict__': <attribute '__dict__' of 'FeatureStoreCore' objects>, 'get_internal': <function FeatureStoreCore.get_internal>, 'upsert_internal': <function FeatureStoreCore.upsert_internal>})¶
-
__metaclass__
¶ alias of
abc.ABCMeta
-
__module__
= 'ldclient.interfaces'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
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 alsoldclient.integrations.Files.new_data_source()
.-
__metaclass__
¶ alias of
abc.ABCMeta
-
__module__
= 'ldclient.interfaces'¶
-
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.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.-
__INITED_CACHE_KEY__
= '$inited'¶
-
__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
-
__module__
= 'ldclient.feature_store_helpers'¶
-
initialized
¶
-
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
-
__getnewargs__
()¶ Return self as a plain tuple. Used by copy and pickle.
-
__module__
= 'ldclient.versioned_data_kind'¶
-
static
__new__
(_cls, namespace, request_api_path, stream_api_path)¶ Create new instance of VersionedDataKind(namespace, request_api_path, stream_api_path)
-
__repr__
()¶ Return a nicely formatted representation string
-
__slots__
= ()¶
-
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
-
__getnewargs__
()¶ Return self as a plain tuple. Used by copy and pickle.
-
__module__
= 'ldclient.versioned_data_kind'¶
-
static
__new__
(_cls, namespace, request_api_path, stream_api_path, priority, get_dependency_keys)¶ Create new instance of VersionedDataKindWithOrdering(namespace, request_api_path, stream_api_path, priority, get_dependency_keys)
-
__repr__
()¶ Return a nicely formatted representation string
-
__slots__
= ()¶
-
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
-