prepare 6.3.0 release (#94)

Author: eli-darkly

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to the LaunchDarkly Python SDK will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [6.3.0] - 2018-08-27
+### Added:
+- The new `LDClient` method `all_flags_state()` should be used instead of `all_flags()` if you are passing flag data to the front end for use with the JavaScript SDK. It preserves some flag metadata that the front end requires in order to send analytics events correctly. Versions 2.5.0 and above of the JavaScript SDK are able to use this metadata, but the output of `all_flags_state()` will still work with older versions.
+- The `all_flags_state()` method also allows you to select only client-side-enabled flags to pass to the front end, by using the option `client_side_only=True`.
+
+### Deprecated:
+- `LDClient.all_flags()`
+
 ## [6.2.0] - 2018-08-03
 ### Changed:
 - In streaming mode, each connection failure or unsuccessful reconnection attempt logs a message at `ERROR` level. Previously, this message included the amount of time before the next retry; since that interval is different for each attempt, that meant the `ERROR`-level messages were all unique, which could cause problems for monitors. This has been changed so the `ERROR`-level message is always the same, and is followed by an `INFO`-level message about the time delay. (Note that in order to suppress the default message, the LaunchDarkly client modifies the logger used by the `backoff` package; if you are using `backoff` for some other purpose and _do_ want to see the default message, set `logging.getLogger('backoff').propagate` to `True`.) ([#88](https://github.com/launchdarkly/python-client/issues/88))

ldclient/client.py

@@ -10,6 +10,7 @@
 from ldclient.event_processor import NullEventProcessor
 from ldclient.feature_requester import FeatureRequesterImpl
 from ldclient.flag import evaluate
+from ldclient.flags_state import FeatureFlagsState
 from ldclient.polling import PollingUpdateProcessor
 from ldclient.streaming import StreamingUpdateProcessor
 from ldclient.util import check_uwsgi, log
@@ -27,6 +28,16 @@
 
 class LDClient(object):
     def __init__(self, sdk_key=None, config=None, start_wait=5):
+        """Constructs a new LDClient instance.
+
+        Rather than calling this constructor directly, you can call the `ldclient.set_sdk_key`,
+        `ldclient.set_config`, and `ldclient.get` functions to configure and use a singleton
+        client instance.
+
+        :param string sdk_key: the SDK key for your LaunchDarkly environment
+        :param Config config: optional custom configuration
+        :param float start_wait: the number of seconds to wait for a successful connection to LaunchDarkly
+        """
         check_uwsgi()
 
         if config is not None and config.sdk_key is not None and sdk_key is not None:
@@ -93,9 +104,17 @@ def __init__(self, sdk_key=None, config=None, start_wait=5):
                      "Feature Flags may not yet be available.")
 
     def get_sdk_key(self):
+        """Returns the configured SDK key.
+
+        :rtype: string
+        """
         return self._config.sdk_key
 
     def close(self):
+        """Releases all threads and network connections used by the LaunchDarkly client.
+        
+        Do not attempt to use the client after calling this method.
+        """
         log.info("Closing LaunchDarkly client..")
         if self.is_offline():
             return
@@ -108,33 +127,63 @@ def _send_event(self, event):
         self._event_processor.send_event(event)
 
     def track(self, event_name, user, data=None):
+        """Tracks that a user performed an event.
+
+        :param string event_name: The name of the event.
+        :param dict user: The attributes of the user.
+        :param data: Optional additional data associated with the event.
+        """
         self._sanitize_user(user)
         if user is None or user.get('key') is None:
             log.warn("Missing user or user key when calling track().")
         self._send_event({'kind': 'custom', 'key': event_name, 'user': user, 'data': data})
 
     def identify(self, user):
+        """Registers the user.
+
+        :param dict user: attributes of the user to register
+        """
         self._sanitize_user(user)
         if user is None or user.get('key') is None:
             log.warn("Missing user or user key when calling identify().")
         self._send_event({'kind': 'identify', 'key': user.get('key'), 'user': user})
 
     def is_offline(self):
+        """Returns true if the client is in offline mode.
+
+        :rtype: bool
+        """
         return self._config.offline
 
     def is_initialized(self):
+        """Returns true if the client has successfully connected to LaunchDarkly.
+
+        :rype: bool
+        """
         return self.is_offline() or self._config.use_ldd or self._update_processor.initialized()
 
     def flush(self):
+        """Flushes all pending events.
+        """
         if self._config.offline:
             return
         return self._event_processor.flush()
 
     def toggle(self, key, user, default):
+        """Deprecated synonym for `variation`.
+        """
         log.warn("Deprecated method: toggle() called. Use variation() instead.")
         return self.variation(key, user, default)
 
     def variation(self, key, user, default):
+        """Determines the variation of a feature flag for a user.
+
+        :param string key: the unique key for the feature flag
+        :param dict user: a dictionary containing parameters for the end user requesting the flag
+        :param object default: the default value of the flag, to be used if the value is not
+          available from LaunchDarkly
+        :return: one of the flag's variation values, or the default value
+        """
         default = self._config.get_default(key, default)
         if user is not None:
             self._sanitize_user(user)
@@ -199,34 +248,79 @@ def _evaluate_and_send_events(self, flag, user, default):
         return value
 
     def all_flags(self, user):
-        if self._config.offline:
-            log.warn("all_flags() called, but client is in offline mode. Returning None")
+        """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`.
+
+        :param dict user: the end user requesting the feature flags
+        :return: 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
+        :rtype: dict
+        """
+        state = self.all_flags_state(user)
+        if not state.valid:
             return None
+        return state.to_values_map()
+    
+    def all_flags_state(self, user, **kwargs):
+        """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. 
+        
+        This method does not send analytics events back to LaunchDarkly.
+
+        :param dict user: the end user requesting the feature flags
+        :param kwargs: optional parameters affecting how the state is computed: set
+          `client_side_only=True` to limit it to only flags that are marked for use with the
+          client-side SDK (by default, all flags are included)
+        :return: 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)
+        :rtype: FeatureFlagsState
+        """
+        if self._config.offline:
+            log.warn("all_flags_state() called, but client is in offline mode. Returning empty state")
+            return FeatureFlagsState(False)
 
         if not self.is_initialized():
             if self._store.initialized:
-                log.warn("all_flags() called before client has finished initializing! Using last known values from feature store")
+                log.warn("all_flags_state() called before client has finished initializing! Using last known values from feature store")
             else:
-                log.warn("all_flags() called before client has finished initializing! Feature store unavailable - returning None")
-                return None
+                log.warn("all_flags_state() called before client has finished initializing! Feature store unavailable - returning empty state")
+                return FeatureFlagsState(False)
 
         if user is None or user.get('key') is None:
-            log.warn("User or user key is None when calling all_flags(). Returning None.")
-            return None
-
-        def cb(all_flags):
+            log.warn("User or user key is None when calling all_flags_state(). Returning empty state.")
+            return FeatureFlagsState(False)
+        
+        state = FeatureFlagsState(True)
+        client_only = kwargs.get('client_side_only', False)
+        try:
+            flags_map = self._store.all(FEATURES, lambda x: x)
+        except Exception as e:
+            log.error("Unable to read flags for all_flag_state: %s" % e)
+            return FeatureFlagsState(False)
+        
+        for key, flag in flags_map.items():
+            if client_only and not flag.get('clientSide', False):
+                continue
             try:
-                return self._evaluate_multi(user, all_flags)
+                result = self._evaluate(flag, user)
+                state.add_flag(flag, result.value, result.variation)
             except Exception as e:
-                log.error("Exception caught in all_flags: " + e.message + " for user: " + str(user))
-            return {}
-
-        return self._store.all(FEATURES, cb)
-
-    def _evaluate_multi(self, user, flags):
-        return dict([(k, self._evaluate(v, user).value) for k, v in flags.items() or {}])
-
+                log.error("Error evaluating flag \"%s\" in all_flags_state: %s" % (key, e))
+                state.add_flag(flag, None, None)
+        
+        return state
+    
     def secure_mode_hash(self, user):
+        """Generates a hash value for a user.
+
+        For more info: <a href="https://github.com/launchdarkly/js-client#secure-mode">https://github.com/launchdarkly/js-client#secure-mode</a>
+        
+        :param dict user: the attributes of the user
+        :return: a hash string that can be passed to the front end
+        :rtype: string
+        """
         if user.get('key') is None or self._config.sdk_key is None:
             return ""
         return hmac.new(self._config.sdk_key.encode(), user.get('key').encode(), hashlib.sha256).hexdigest()

ldclient/config.py

@@ -46,7 +46,7 @@ def __init__(self,
         :param int events_max_pending: 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.
-        : param float flush_interval: The number of seconds in between flushes of the events buffer. Decreasing
+        :param float flush_interval: 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.
         :param string stream_uri: The URL for the LaunchDarkly streaming events server. Most users should
           use the default value.

ldclient/flags_state.py

@@ -0,0 +1,67 @@
+import json
+
+class FeatureFlagsState(object):
+    """
+    A snapshot of the state of all feature flags with regard to a specific user, generated by
+    calling the client's 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.
+    """
+    def __init__(self, valid):
+        self.__flag_values = {}
+        self.__flag_metadata = {}
+        self.__valid = valid
+
+    def add_flag(self, flag, value, variation):
+        """Used internally to build the state map."""
+        key = flag['key']
+        self.__flag_values[key] = value
+        meta = { 'version': flag.get('version'), 'trackEvents': flag.get('trackEvents') }
+        if variation is not None:
+            meta['variation'] = variation
+        if flag.get('debugEventsUntilDate') is not None:
+            meta['debugEventsUntilDate'] = flag.get('debugEventsUntilDate')
+        self.__flag_metadata[key] = meta
+    
+    @property
+    def valid(self):
+        """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 self.__valid
+    
+    def get_flag_value(self, key):
+        """Returns the value of an individual feature flag at the time the state was recorded.
+        :param string key: the feature flag key
+        :return: the flag's value; None if the flag returned the default value, or if there was no such flag
+        """
+        return self.__flag_values.get(key)
+    
+    def to_values_map(self):
+        """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 self.__flag_values
+
+    def to_json_dict(self):
+        """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.
+        """
+        ret = self.__flag_values.copy()
+        ret['$flagsState'] = self.__flag_metadata
+        ret['$valid'] = self.__valid
+        return ret
+    
+    def to_json_string(self):
+        """Same as to_json_dict, but serializes the JSON structure into a string.
+        """
+        return json.dumps(self.to_json_dict())
+
+    def __getstate__(self):
+        """Equivalent to to_json_dict() - used if you are serializing the object with jsonpickle.
+        """
+        return self.to_json_dict()

setup.py

@@ -13,7 +13,7 @@ def parse_requirements(filename):
     return [line for line in lineiter if line and not line.startswith("#")]
 
 
-ldclient_version='6.2.0'
+ldclient_version='6.3.0'
 
 # parse_requirements() returns generator of pip.req.InstallRequirement objects
 install_reqs = parse_requirements('requirements.txt')

testing/test_flags_state.py

@@ -0,0 +1,71 @@
+import pytest
+import json
+import jsonpickle
+from ldclient.flags_state import FeatureFlagsState
+
+def test_can_get_flag_value():
+    state = FeatureFlagsState(True)
+    flag = { 'key': 'key' }
+    state.add_flag(flag, 'value', 1)
+    assert state.get_flag_value('key') == 'value'
+
+def test_returns_none_for_unknown_flag():
+    state = FeatureFlagsState(True)
+    assert state.get_flag_value('key') is None
+
+def test_can_convert_to_values_map():
+    state = FeatureFlagsState(True)
+    flag1 = { 'key': 'key1' }
+    flag2 = { 'key': 'key2' }
+    state.add_flag(flag1, 'value1', 0)
+    state.add_flag(flag2, 'value2', 1)
+    assert state.to_values_map() == { 'key1': 'value1', 'key2': 'value2' }
+
+def test_can_convert_to_json_dict():
+    state = FeatureFlagsState(True)
+    flag1 = { 'key': 'key1', 'version': 100, 'offVariation': 0, 'variations': [ 'value1' ], 'trackEvents': False }
+    flag2 = { 'key': 'key2', 'version': 200, 'offVariation': 1, 'variations': [ 'x', 'value2' ], 'trackEvents': True, 'debugEventsUntilDate': 1000 }
+    state.add_flag(flag1, 'value1', 0)
+    state.add_flag(flag2, 'value2', 1)
+
+    result = state.to_json_dict()
+    assert result == {
+        'key1': 'value1',
+        'key2': 'value2',
+        '$flagsState': {
+            'key1': {
+                'variation': 0,
+                'version': 100,
+                'trackEvents': False
+            },
+            'key2': {
+                'variation': 1,
+                'version': 200,
+                'trackEvents': True,
+                'debugEventsUntilDate': 1000
+            }
+        },
+        '$valid': True
+    }
+
+def test_can_convert_to_json_string():
+    state = FeatureFlagsState(True)
+    flag1 = { 'key': 'key1', 'version': 100, 'offVariation': 0, 'variations': [ 'value1' ], 'trackEvents': False }
+    flag2 = { 'key': 'key2', 'version': 200, 'offVariation': 1, 'variations': [ 'x', 'value2' ], 'trackEvents': True, 'debugEventsUntilDate': 1000 }
+    state.add_flag(flag1, 'value1', 0)
+    state.add_flag(flag2, 'value2', 1)
+
+    obj = state.to_json_dict()
+    str = state.to_json_string()
+    assert json.loads(str) == obj
+
+def test_can_serialize_with_jsonpickle():
+    state = FeatureFlagsState(True)
+    flag1 = { 'key': 'key1', 'version': 100, 'offVariation': 0, 'variations': [ 'value1' ], 'trackEvents': False }
+    flag2 = { 'key': 'key2', 'version': 200, 'offVariation': 1, 'variations': [ 'x', 'value2' ], 'trackEvents': True, 'debugEventsUntilDate': 1000 }
+    state.add_flag(flag1, 'value1', 0)
+    state.add_flag(flag2, 'value2', 1)
+
+    obj = state.to_json_dict()
+    str = jsonpickle.encode(state, unpicklable=False)
+    assert json.loads(str) == obj