prepare 9.0.0 release (#227)

## [9.0.0] - 2023-10-17
The latest version of this SDK supports the ability to manage migrations
or modernizations, using migration flags. You might use this
functionality if you are optimizing queries, upgrading to new tech
stacks, migrating from one database to another, or other similar
technology changes. Migration flags are part of LaunchDarkly's Early
Access Program. This feature is available to all LaunchDarkly customers
but may undergo additional changes before it is finalized.

For detailed information about this version, refer to the list below.
For information on how to upgrade from the previous version, read the
[migration
guide](https://docs.launchdarkly.com/sdk/server-side/python/migration-8-to-9).

### Added:
- A new `Migrator` type which provides an out-of-the-box configurable
migration framework.
- For more advanced use cases, added new `migration_variation` and
`track_migration_op` methods on `LDClient`.

### Changed:
- Raised `pyyaml` dependency to `>=5.3`.

### Removed:
- Python 3.7 support was removed.
- The legacy user format for contexts is no longer supported. To learn
more, read the [Contexts
documentation](https://docs.launchdarkly.com/guides/flags/intro-contexts).
- Methods which originally took a `Context` or a `dict` now only accept
a `Context`.
- Previously deprecated config options `user_cache_size`,
`user_cache_time`, `user_keys_capacity`, `user_keys_flush_interval`, and
`private_attribute_names` have been removed.
- Previously deprecated test data flag builder method
`variation_for_all_users` has been removed.

---------

Co-authored-by: Eli Bishop <eli@launchdarkly.com>
Co-authored-by: charukiewicz <charukiewicz@protonmail.com>
Co-authored-by: LaunchDarklyReleaseBot <launchdarklyreleasebot@launchdarkly.com>
Co-authored-by: Christian Charukiewicz <christian@foxhound.systems>
Co-authored-by: Matthew M. Keeler <keelerm84@gmail.com>
Co-authored-by: Matthew M. Keeler <mkeeler@launchdarkly.com>
Co-authored-by: Ember Stevens <ember.stevens@launchdarkly.com>
Co-authored-by: Ember Stevens <79482775+ember-stevens@users.noreply.github.com>
Co-authored-by: LaunchDarklyCI <dev@launchdarkly.com>
Co-authored-by: Ben Woskow <bwoskow@launchdarkly.com>
Co-authored-by: Gavin Whelan <gwhelan@launchdarkly.com>
Co-authored-by: Elliot <35050275+Apache-HB@users.noreply.github.com>
Co-authored-by: Gabor Angeli <gabor@squareup.com>
Co-authored-by: Elliot <apachehaisley@gmail.com>
Co-authored-by: Ben Woskow <48036130+bwoskow-ld@users.noreply.github.com>
Co-authored-by: LaunchDarklyCI <LaunchDarklyCI@users.noreply.github.com>
Co-authored-by: hroederld <hroeder@launchdarkly.com>
Co-authored-by: Robert J. Neal <rneal@launchdarkly.com>
Co-authored-by: Robert J. Neal <robertjneal@users.noreply.github.com>
Co-authored-by: Louis Chan <lchan@launchdarkly.com>
Co-authored-by: prpnmac <95777763+prpnmac@users.noreply.github.com>
Co-authored-by: Louis Chan <91093020+louis-launchdarkly@users.noreply.github.com>
Co-authored-by: Daniel Fritz <dfritz@indigoag.com>

Author: 16 people

.circleci/config.yml

@@ -7,14 +7,11 @@ workflows:
   test:
     jobs:
       - test-linux:
-          name: Python 3.7
-          docker-image: cimg/python:3.7
+          name: Python 3.8
+          docker-image: cimg/python:3.8
           test-build-docs: true
           skip-sse-contract-tests: true
           skip-contract-tests: true
-      - test-linux:
-          name: Python 3.8
-          docker-image: cimg/python:3.8
       - test-linux:
           name: Python 3.9
           docker-image: cimg/python:3.9
@@ -24,6 +21,9 @@ workflows:
       - test-linux:
           name: Python 3.11
           docker-image: cimg/python:3.11
+      - test-linux:
+          name: Python 3.12
+          docker-image: cimg/python:3.12
       - test-windows:
           name: Windows Python 3
           py3: true
@@ -60,6 +60,7 @@ jobs:
           name: install requirements
           command: |
             pip install --upgrade pip
+            pip install setuptools
             pip install -r test-requirements.txt;
             pip install -r test-filesource-optional-requirements.txt;
             pip install -r consul-requirements.txt;
@@ -136,15 +137,7 @@ jobs:
       - checkout
       - run:
           name: install Python 3
-          command: |
-            choco install pyenv-win --force
-            refreshenv
-            pyenv install 3.11.0b3
-            pyenv global 3.11.0b3
-            [System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
-            [System.Environment]::SetEnvironmentVariable('PYENV_ROOT',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
-            [System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
-            [System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")
+          command: choco install python --no-progress
       - run: python --version
       - run:
           name: set up DynamoDB
@@ -182,6 +175,7 @@ jobs:
           name: install requirements
           command: |
             python --version
+            pip install setuptools
             pip install -r test-requirements.txt
             pip install -r consul-requirements.txt
             python setup.py install

.readthedocs.yml

@@ -1,7 +1,7 @@
 version: 2
 
 python:
-  version: 3.7
+  version: 3.8
   install:
     - requirements: docs/requirements.txt
     - requirements: requirements.txt

README.md

@@ -13,7 +13,7 @@
 
 ## Supported Python versions
 
-This version of the LaunchDarkly SDK is compatible with Python 3.7 through 3.11. It is tested with the most recent patch releases of those versions. Python versions 2.7 to 3.6 are no longer supported.
+This version of the LaunchDarkly SDK is compatible with Python 3.8 through 3.12. It is tested with the most recent patch releases of those versions. Python versions 2.7 to 3.6 are no longer supported.
 
 ## Getting started
 

contract-tests/client_entity.py

@@ -2,6 +2,7 @@
 import logging
 import os
 import sys
+import requests
 from typing import Optional
 
 from big_segment_store_fixture import BigSegmentStoreFixture
@@ -10,6 +11,7 @@
 
 # Import ldclient from parent directory
 sys.path.insert(1, os.path.join(sys.path[0], '..'))
+from ldclient import Context, MigratorBuilder, ExecutionOrder, MigratorFn, Operation, Stage
 from ldclient import *
 
 
@@ -39,7 +41,7 @@ def __init__(self, tag, config):
                 opts["events_max_pending"] = events["capacity"]
             opts["diagnostic_opt_out"] = not events.get("enableDiagnostics", False)
             opts["all_attributes_private"] = events.get("allAttributesPrivate", False)
-            opts["private_attribute_names"] = events.get("globalPrivateAttributes", {})
+            opts["private_attributes"] = events.get("globalPrivateAttributes", {})
             _set_optional_time_prop(events, "flushIntervalMs", opts, "flush_interval")
         else:
             opts["send_events"] = False
@@ -55,7 +57,7 @@ def __init__(self, tag, config):
             _set_optional_time_prop(big_params, "statusPollIntervalMs", big_config, "status_poll_interval")
             _set_optional_time_prop(big_params, "staleAfterMs", big_config, "stale_after")
             opts["big_segments"] = BigSegmentsConfig(**big_config)
-        
+
         start_wait = config.get("startWaitTimeMs") or 5000
         config = Config(**opts)
 
@@ -68,12 +70,12 @@ def evaluate(self, params: dict) -> dict:
         response = {}
 
         if params.get("detail", False):
-            detail = self.client.variation_detail(params["flagKey"], params["context"], params["defaultValue"])
+            detail = self.client.variation_detail(params["flagKey"], Context.from_dict(params["context"]), params["defaultValue"])
             response["value"] = detail.value
             response["variationIndex"] = detail.variation_index
             response["reason"] = detail.reason
         else:
-            response["value"] = self.client.variation(params["flagKey"], params["context"], params["defaultValue"])
+            response["value"] = self.client.variation(params["flagKey"], Context.from_dict(params["context"]), params["defaultValue"])
 
         return response
 
@@ -83,30 +85,30 @@ def evaluate_all(self, params: dict):
         opts["with_reasons"] = params.get("withReasons", False)
         opts["details_only_for_tracked_flags"] = params.get("detailsOnlyForTrackedFlags", False)
 
-        state = self.client.all_flags_state(params["context"], **opts)
+        state = self.client.all_flags_state(Context.from_dict(params["context"]), **opts)
 
         return {"state": state.to_json_dict()}
 
     def track(self, params: dict):
-        self.client.track(params["eventKey"], params["context"], params["data"], params.get("metricValue", None))
+        self.client.track(params["eventKey"], Context.from_dict(params["context"]), params["data"], params.get("metricValue", None))
 
     def identify(self, params: dict):
-        self.client.identify(params["context"])
+        self.client.identify(Context.from_dict(params["context"]))
 
     def flush(self):
         self.client.flush()
 
     def secure_mode_hash(self, params: dict) -> dict:
-        return {"result": self.client.secure_mode_hash(params["context"])}
-    
+        return {"result": self.client.secure_mode_hash(Context.from_dict(params["context"]))}
+
     def context_build(self, params: dict) -> dict:
         if params.get("multi"):
             b = Context.multi_builder()
             for c in params.get("multi"):
                 b.add(self._context_build_single(c))
             return self._context_response(b.build())
         return self._context_response(self._context_build_single(params["single"]))
-    
+
     def _context_build_single(self, params: dict) -> Context:
         b = Context.builder(params["key"])
         if "kind" in params:
@@ -122,31 +124,76 @@ def _context_build_single(self, params: dict) -> Context:
             for attr in params.get("private"):
                 b.private(attr)
         return b.build()
-    
+
     def context_convert(self, params: dict) -> dict:
         input = params["input"]
         try:
             props = json.loads(input)
             return self._context_response(Context.from_dict(props))
         except Exception as e:
             return {"error": str(e)}
-    
+
     def _context_response(self, c: Context) -> dict:
         if c.valid:
             return {"output": c.to_json_string()}
         return {"error": c.error}
-    
+
     def get_big_segment_store_status(self) -> dict:
         status = self.client.big_segment_store_status_provider.status
         return {
             "available": status.available,
             "stale": status.stale
         }
 
+    def migration_variation(self, params: dict) -> dict:
+        stage, _ = self.client.migration_variation(params["key"], Context.from_dict(params["context"]), Stage.from_str(params["defaultStage"]))
+
+        return {'result': stage.value}
+
+    def migration_operation(self, params: dict) -> dict:
+        builder = MigratorBuilder(self.client)
+
+        if params["readExecutionOrder"] == "concurrent":
+            params["readExecutionOrder"] = "parallel"
+
+        builder.read_execution_order(ExecutionOrder.from_str(params["readExecutionOrder"]))
+        builder.track_latency(params["trackLatency"])
+        builder.track_errors(params["trackErrors"])
+
+        def callback(endpoint) -> MigratorFn:
+            def fn(payload) -> Result:
+                response = requests.post(endpoint, data=payload)
+
+                if response.status_code == 200:
+                    return Result.success(response.text)
+
+                return Result.error(f"Request failed with status code {response.status_code}")
+
+            return fn
+
+        if params["trackConsistency"]:
+            builder.read(callback(params["oldEndpoint"]), callback(params["newEndpoint"]), lambda lhs, rhs: lhs == rhs)
+        else:
+            builder.read(callback(params["oldEndpoint"]), callback(params["newEndpoint"]))
+
+        builder.write(callback(params["oldEndpoint"]), callback(params["newEndpoint"]))
+        migrator = builder.build()
+
+        if isinstance(migrator, str):
+            return {"result": migrator}
+
+        if params["operation"] == Operation.READ.value:
+            result = migrator.read(params["key"], Context.from_dict(params["context"]), Stage.from_str(params["defaultStage"]), params["payload"])
+            return {"result": result.value if result.is_success() else result.error}
+
+        result = migrator.write(params["key"], Context.from_dict(params["context"]), Stage.from_str(params["defaultStage"]), params["payload"])
+        return {"result": result.authoritative.value if result.authoritative.is_success() else result.authoritative.error}
+
     def close(self):
         self.client.close()
         self.log.info('Test ended')
 
+
 def _set_optional_time_prop(params_in: dict, name_in: str, params_out: dict, name_out: str):
     if params_in.get(name_in) is not None:
         params_out[name_out] = params_in[name_in] / 1000.0

contract-tests/requirements.txt

@@ -1,2 +1,3 @@
 Flask==2.3.2
+requests>=2.31.0
 urllib3>=1.22.0,<3

contract-tests/service.py

@@ -68,6 +68,8 @@ def status():
             'context-type',
             'secure-mode-hash',
             'tags',
+            'migrations',
+            'event-sampling'
         ]
     }
     return (json.dumps(body), 200, {'Content-type': 'application/json'})
@@ -130,6 +132,10 @@ def post_client_command(id):
         response = client.context_convert(sub_params)
     elif command == "getBigSegmentStoreStatus":
         response = client.get_big_segment_store_status()
+    elif command == "migrationVariation":
+        response = client.migration_variation(sub_params)
+    elif command == "migrationOperation":
+        response = client.migration_operation(sub_params)
     else:
         return ('', 400)
 

contract-tests/setup.cfg

@@ -0,0 +1,2 @@
+[pycodestyle]
+ignore = E501

docs/api-main.rst

@@ -26,3 +26,10 @@ ldclient.evaluation module
 .. automodule:: ldclient.evaluation
     :members:
     :special-members: __init__
+
+ldclient.migrations module
+--------------------------
+
+.. automodule:: ldclient.migrations
+    :members:
+    :special-members: __init__

ldclient/__init__.py

@@ -3,10 +3,11 @@
 """
 
 from ldclient.impl.rwlock import ReadWriteLock as _ReadWriteLock
-from ldclient.impl.util import log
+from ldclient.impl.util import log, Result
 from ldclient.version import VERSION
 from .client import *
 from .context import *
+from .migrations import *
 
 __version__ = VERSION
 
@@ -104,9 +105,11 @@ def _reset_client():
     'ContextBuilder',
     'ContextMultiBuilder',
     'LDClient',
+    'Result',
     'client',
     'context',
     'evaluation',
     'integrations',
-    'interfaces'
+    'interfaces',
+    'migrations'
 ]