Core API

ldclient module

The ldclient module contains the most common top-level entry points for the SDK.

ldclient.get()[source]

Returns the shared SDK client instance, using the current global configuration.

To use the SDK as a singleton, first make sure you have called ldclient.set_sdk_key() or ldclient.set_config() at startup time. Then get() will return the same shared ldclient.client.LDClient instance each time. The client will be initialized if it has not been already.

If you need to create multiple client instances with different configurations, instead of this singleton approach you can call the ldclient.client.LDClient constructor directly instead.

Return type:ldclient.client.LDClient
ldclient.set_config(config)[source]

Sets the configuration for the shared SDK client instance.

If this is called prior to ldclient.get(), it stores the configuration that will be used when the client is initialized. If it is called after the client has already been initialized, the client will be re-initialized with the new configuration (this will result in the next call to ldclient.get() returning a new client instance).

Parameters:config (ldclient.config.Config) – the client configuration
ldclient.set_sdk_key(sdk_key)[source]

Sets the SDK key for the shared SDK client instance.

If this is called prior to ldclient.get(), it stores the SDK key that will be used when the client is initialized. If it is called after the client has already been initialized, the client will be re-initialized with the new SDK key (this will result in the next call to ldclient.get() returning a new client instance).

If you need to set any configuration options other than the SDK key, use ldclient.set_config() instead.

Parameters:sdk_key (string) – the new SDK key

ldclient.client module

This submodule contains the client class that provides most of the SDK functionality.

class ldclient.client.LDClient(sdk_key=None, config=None, start_wait=5)[source]

The LaunchDarkly SDK client object.

Applications should configure the client at startup time and continue to use it throughout the lifetime of the application, rather than creating instances on the fly. The best way to do this is with the singleton methods ldclient.set_sdk_key(), ldclient.set_config(), and ldclient.get(). However, you may also call the constructor directly if you need to maintain multiple instances.

Client instances are thread-safe.

__init__(sdk_key=None, config=None, start_wait=5)[source]

Constructs a new LDClient instance.

Parameters:
  • sdk_key (string) – the SDK key for your LaunchDarkly environment
  • config (ldclient.config.Config) – optional custom configuration
  • start_wait (float) – the number of seconds to wait for a successful connection to LaunchDarkly
all_flags(user)[source]

Returns all feature flag values for the given user.

This method is deprecated - please use all_flags_state() instead. Current versions of the client-side SDK will not generate analytics events correctly if you pass the result of all_flags.

Parameters:user (dict) – the end user requesting the feature flags
Returns:a dictionary of feature flag keys to values; returns None if the client is offline, has not been initialized, or the user is None or has no key
Return type:dict
all_flags_state(user, **kwargs)[source]

Returns an object that encapsulates the state of all feature flags for a given user, including the flag values and also metadata that can be used on the front end. See the JavaScript SDK Reference Guide on Bootstrapping.

This method does not send analytics events back to LaunchDarkly.

Parameters:
  • user (dict) – the end user requesting the feature flags
  • kwargs – optional parameters affecting how the state is computed - see below
Keyword Arguments:
 
  • client_side_only (boolean) – set to True to limit it to only flags that are marked for use with the client-side SDK (by default, all flags are included)
  • with_reasons (boolean) – set to True to include evaluation reasons in the state (see variation_detail())
  • details_only_for_tracked_flags (boolean) – set to True to omit any metadata that is normally only used for event generation, such as flag versions and evaluation reasons, unless the flag has event tracking or debugging turned on
Returns:

a FeatureFlagsState object (will never be None; its valid property will be False if the client is offline, has not been initialized, or the user is None or has no key)

Return type:

FeatureFlagsState

close()[source]

Releases all threads and network connections used by the LaunchDarkly client.

Do not attempt to use the client after calling this method.

flush()[source]

Flushes all pending analytics events.

Normally, batches of events are delivered in the background at intervals determined by the flush_interval property of ldclient.config.Config. Calling flush() schedules the next event delivery to be as soon as possible; however, the delivery still happens asynchronously on a worker thread, so this method will return immediately.

get_sdk_key()[source]

Returns the configured SDK key.

Return type:string
identify(user)[source]

Registers the user.

This simply creates an analytics event that will transmit the given user properties to LaunchDarkly, so that the user will be visible on your dashboard even if you have not evaluated any flags for that user. It has no other effect.

Parameters:user (dict) – attributes of the user to register
is_initialized()[source]

Returns true if the client has successfully connected to LaunchDarkly.

If this returns false, it means that the client has not yet successfully connected to LaunchDarkly. It might still be in the process of starting up, or it might be attempting to reconnect after an unsuccessful attempt, or it might have received an unrecoverable error (such as an invalid SDK key) and given up.

Return type:bool
is_offline()[source]

Returns true if the client is in offline mode.

Return type:bool
secure_mode_hash(user)[source]

Computes an HMAC signature of a user signed with the client’s SDK key, for use with the JavaScript SDK.

For more information, see the JavaScript SDK Reference Guide on Secure mode.

Parameters:user (dict) – the attributes of the user
Returns:a hash string that can be passed to the front end
Return type:string
toggle(key, user, default)[source]

Deprecated synonym for variation().

Deprecated since version 2.0.0.

track(event_name, user, data=None, metric_value=None)[source]

Tracks that a user performed an event.

LaunchDarkly automatically tracks pageviews and clicks that are specified in the Goals section of the dashboard. This can be used to track custom goals or other events that do not currently have goals.

Parameters:
  • event_name (string) – the name of the event, which may correspond to a goal in A/B tests
  • user (dict) – the attributes of the user
  • data – optional additional data associated with the event
  • metric_value – a numeric value used by the LaunchDarkly experimentation feature in numeric custom metrics. Can be omitted if this event is used by only non-numeric metrics. This field will also be returned as part of the custom event for Data Export.
variation(key, user, default)[source]

Determines the variation of a feature flag for a user.

Parameters:
  • key (string) – the unique key for the feature flag
  • user (dict) – a dictionary containing parameters for the end user requesting the flag
  • default (object) – the default value of the flag, to be used if the value is not available from LaunchDarkly
Returns:

one of the flag’s variation values, or the default value

variation_detail(key, user, default)[source]

Determines the variation of a feature flag for a user, like variation(), but also provides additional information about how this value was calculated, in the form of an ldclient.flag.EvaluationDetail object.

Calling this method also causes the “reason” data to be included in analytics events, if you are capturing detailed event data for this flag.

Parameters:
  • key (string) – the unique key for the feature flag
  • user (dict) – a dictionary containing parameters for the end user requesting the flag
  • default (object) – the default value of the flag, to be used if the value is not available from LaunchDarkly
Returns:

an object describing the result

Return type:

EvaluationDetail

ldclient.config module

This submodule contains the Config class for custom configuration of the SDK client.

Note that the same class can also be imported from the ldclient.client submodule.

class ldclient.config.Config(sdk_key=None, base_uri='https://app.launchdarkly.com', events_uri='https://events.launchdarkly.com', connect_timeout=10, read_timeout=15, events_max_pending=10000, flush_interval=5, stream_uri='https://stream.launchdarkly.com', stream=True, verify_ssl=True, defaults=None, send_events=None, events_enabled=True, update_processor_class=None, poll_interval=30, use_ldd=False, feature_store=None, feature_requester_class=None, event_processor_class=None, private_attribute_names=(), all_attributes_private=False, offline=False, user_keys_capacity=1000, user_keys_flush_interval=300, inline_users_in_events=False)[source]

Advanced configuration options for the SDK client.

To use these options, create an instance of Config and pass it to either ldclient.set_config() if you are using the singleton client, or the ldclient.client.LDClient constructor otherwise.

__init__(sdk_key=None, base_uri='https://app.launchdarkly.com', events_uri='https://events.launchdarkly.com', connect_timeout=10, read_timeout=15, events_max_pending=10000, flush_interval=5, stream_uri='https://stream.launchdarkly.com', stream=True, verify_ssl=True, defaults=None, send_events=None, events_enabled=True, update_processor_class=None, poll_interval=30, use_ldd=False, feature_store=None, feature_requester_class=None, event_processor_class=None, private_attribute_names=(), all_attributes_private=False, offline=False, user_keys_capacity=1000, user_keys_flush_interval=300, inline_users_in_events=False)[source]
Parameters:
  • sdk_key (string) – The SDK key for your LaunchDarkly account.
  • base_uri (string) – The base URL for the LaunchDarkly server. Most users should use the default value.
  • events_uri (string) – The URL for the LaunchDarkly events server. Most users should use the default value.
  • connect_timeout (float) – The connect timeout for network connections in seconds.
  • read_timeout (float) – The read timeout for network connections in seconds.
  • events_upload_max_batch_size (int) – The maximum number of analytics events that the client will send at once.
  • events_max_pending (int) – The capacity of the events buffer. The client buffers up to this many events in memory before flushing. If the capacity is exceeded before the buffer is flushed, events will be discarded.
  • flush_interval (float) – The number of seconds in between flushes of the events buffer. Decreasing the flush interval means that the event buffer is less likely to reach capacity.
  • stream_uri (string) – The URL for the LaunchDarkly streaming events server. Most users should use the default value.
  • stream (bool) – Whether or not the streaming API should be used to receive flag updates. By default, it is enabled. Streaming should only be disabled on the advice of LaunchDarkly support.
  • send_events (bool) – Whether or not to send events back to LaunchDarkly. This differs from offline in that it affects only the sending of client-side events, not streaming or polling for events from the server. By default, events will be sent.
  • events_enabled (bool) – Obsolete name for send_events.
  • offline (bool) – Whether the client should be initialized in offline mode. In offline mode, default values are returned for all flags and no remote network requests are made. By default, this is false.
  • poll_interval (float) – The number of seconds between polls for flag updates if streaming is off.
  • use_ldd (bool) – Whether you are using the LaunchDarkly relay proxy in daemon mode. In this configuration, the client will not use a streaming connection to listen for updates, but instead will get feature state from a Redis instance. The stream and poll_interval options will be ignored if this option is set to true. By default, this is false.
  • private_attribute_names (array) – Marks a set of attribute names private. Any users sent to LaunchDarkly with this configuration active will have attributes with these names removed.
  • all_attributes_private (bool) – If true, all user attributes (other than the key) will be private, not just the attributes specified in private_attribute_names.
  • feature_store (FeatureStore) – A FeatureStore implementation
  • user_keys_capacity (int) – The number of user keys that the event processor can remember at any one time, so that duplicate user details will not be sent in analytics events.
  • user_keys_flush_interval (float) – The interval in seconds at which the event processor will reset its set of known user keys.
  • inline_users_in_events (bool) – Whether to include full user details in every analytics event. By default, events will only include the user key, except for one “index” event that provides the full details for the user.
  • feature_requester_class ((str, ldclient.config.Config, FeatureStore) -> FeatureRequester) – A factory for a FeatureRequester implementation taking the sdk key and config
  • event_processor_class ((ldclient.config.Config) -> EventProcessor) – A factory for an EventProcessor implementation taking the config
  • update_processor_class ((str, ldclient.config.Config, FeatureStore) -> UpdateProcessor) – A factory for an UpdateProcessor implementation taking the sdk key, config, and FeatureStore implementation
all_attributes_private
base_uri
connect_timeout
copy_with_new_sdk_key(new_sdk_key)[source]

Returns a new Config instance that is the same as this one, except for having a different SDK key.

Parameters:new_sdk_key (string) – the new SDK key
Return type:ldclient.config.Config
classmethod default()[source]

Returns a Config instance with default values for all properties.

Return type:ldclient.config.Config
event_processor_class
events_enabled
events_max_pending
events_uri
feature_requester_class
feature_store
flush_interval
get_default(key, default)[source]
get_latest_flags_uri
inline_users_in_events
offline
poll_interval
private_attribute_names
read_timeout
sdk_key
send_events
stream
stream_base_uri
stream_uri
update_processor_class
use_ldd
user_keys_capacity
user_keys_flush_interval
verify_ssl

ldclient.flag module

This submodule contains a helper class for feature flag evaluation, as well as some implementation details.

class ldclient.flag.EvaluationDetail(value, variation_index, reason)[source]

The return type of ldclient.client.LDClient.variation_detail(), combining the result of a flag evaluation with information about how it was calculated.

__init__(value, variation_index, reason)[source]

Constructs an instance.

is_default_value()[source]

Returns True if the flag evaluated to the default value rather than one of its variations.

Return type:bool
reason

A dictionary describing the main factor that influenced the flag evaluation value. It contains the following properties:

  • kind: The general category of reason, as follows:
    • "OFF": the flag was off
    • "FALLTHROUGH" – the flag was on but the user did not match any targets or rules
    • "TARGET_MATCH" – the user was specifically targeted for this flag
    • "RULE_MATCH" – the user matched one of the flag’s rules
    • "PREREQUISITE_FAILED" – the flag was considered off because it had at least one prerequisite flag that did not return the desired variation
    • "ERROR" - the flag could not be evaluated due to an unexpected error.
  • ruleIndex, ruleId: The positional index and unique identifier of the matched rule, if the kind was RULE_MATCH
  • prerequisiteKey: The flag key of the prerequisite that failed, if the kind was PREREQUISITE_FAILED
  • errorKind: further describes the nature of the error if the kind was ERROR, e.g. "FLAG_NOT_FOUND"
Return type:dict
value

The result of the flag evaluation. This will be either one of the flag’s variations or the default value that was passed to the ldclient.client.LDClient.variation_detail() method.

variation_index

The index of the returned value within the flag’s list of variations, e.g. 0 for the first variation – or None if the default value was returned.

Return type:int or None

ldclient.flags_state module

This submodule contains a helper class for feature flag evaluation.

class ldclient.flags_state.FeatureFlagsState(valid)[source]

A snapshot of the state of all feature flags with regard to a specific user, generated by calling the ldclient.client.LDClient.all_flags_state() method. Serializing this object to JSON, using the to_json_dict() method or jsonpickle, will produce the appropriate data structure for bootstrapping the LaunchDarkly JavaScript client. See the JavaScript SDK Reference Guide on Bootstrapping.

get_flag_reason(key)[source]

Returns the evaluation reason for an individual feature flag at the time the state was recorded.

Parameters:key (string) – the feature flag key
Returns:a dictionary describing the reason; None if reasons were not recorded, or if there was no such flag
Return type:dict or None
get_flag_value(key)[source]

Returns the value of an individual feature flag at the time the state was recorded.

Parameters:key (string) – the feature flag key
Returns:the flag’s value; None if the flag returned the default value, or if there was no such flag
to_json_dict()[source]

Returns a dictionary suitable for passing as JSON, in the format used by the LaunchDarkly JavaScript SDK. Use this method if you are passing data to the front end in order to “bootstrap” the JavaScript client.

Return type:dict
to_json_string()[source]

Same as to_json_dict, but serializes the JSON structure into a string.

Return type:string
to_values_map()[source]

Returns a dictionary of flag keys to flag values. If the flag would have evaluated to the default value, its value will be None.

Do not use this method if you are passing data to the front end to “bootstrap” the JavaScript client. Instead, use to_json_dict().

Return type:dict
valid

True if this object contains a valid snapshot of feature flag state, or False if the state could not be computed (for instance, because the client was offline or there was no user).

Return type:bool