From f8f1496da8acd528b0189848c70dc857936e283f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Chalifour?= Date: Fri, 6 Nov 2026 16:19:25 +0100 Subject: [PATCH 1/2] feat: deprecate analytics environment routing --- CHANGELOG.md | 4 ++++ README.md | 11 ++++++++-- src/altertable/client.py | 21 ++++++++++++------- tests/test_altertable.py | 45 ++++++++++++++++++++++++++++++++++++---- tests/test_audience.py | 3 ++- 5 files changed, 69 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index be00c7a..d0b795d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,10 @@ * **api:** add native server batch overloads and align with client specs v0.13.0 +### Changed + +* deprecate the `environment` argument; the API key selects the environment and `environment` is no longer sent + ## [0.2.0](https://github.com/altertable-ai/altertable-python/compare/altertable-v0.1.0...altertable-v0.2.0) (2026-03-09) diff --git a/README.md b/README.md index a73fc30..c8dc931 100644 --- a/README.md +++ b/README.md @@ -48,13 +48,20 @@ not impose a client-side batch-size limit. ```python client.track([ - {"event": "button_clicked", "distinct_id": "user_123", "environment": "production"}, - {"event": "checkout_started", "distinct_id": "user_123", "environment": "production"}, + {"event": "button_clicked", "distinct_id": "user_123"}, + {"event": "checkout_started", "distinct_id": "user_123"}, ]) ``` Pass arrays to `identify` and `alias` for the same pass-through behavior. +### Environment + +The API key selects the Product Analytics environment. The `environment` +argument is deprecated and ignored, and `environment` fields in options and +batches are never sent. Replace unbound legacy API keys with environment-bound +keys before upgrading. + ### Audience measurement With an environment-bound API key, pass `mode="audience"` to send events without diff --git a/src/altertable/client.py b/src/altertable/client.py index a80bbe6..16a1048 100644 --- a/src/altertable/client.py +++ b/src/altertable/client.py @@ -4,6 +4,9 @@ TrackingMode = Literal["product", "audience"] +def _without_environment(payload: Dict[str, Any]) -> Dict[str, Any]: + return {key: value for key, value in payload.items() if key != "environment"} + class AltertableError(Exception): pass @@ -19,15 +22,15 @@ def __init__(self, message: str, cause: Exception): self.cause = cause class Altertable: - def __init__(self, api_key: str, server_url: str = "https://api.altertable.ai", environment: str = "production", timeout: int = 10000, *, mode: TrackingMode = "product"): + def __init__(self, api_key: str, server_url: str = "https://api.altertable.ai", environment: Optional[str] = None, timeout: int = 10000, *, mode: TrackingMode = "product"): """ Initialize the Altertable client. :param api_key: API key used to authenticate with the Altertable API. :param server_url: Base URL of the Altertable API server. - :param environment: Environment name (for example, "production" or "staging"). + :param environment: Deprecated and ignored. The API key determines the environment. :param mode: Collection mode, fixed for this client. Audience mode sends events - without identity or environment fields and ignores identify and alias. + without identity fields and ignores identify and alias. :param timeout: Request timeout in milliseconds. This value is converted to seconds before being passed to the underlying `requests` session. """ @@ -36,7 +39,10 @@ def __init__(self, api_key: str, server_url: str = "https://api.altertable.ai", self._mode: TrackingMode = mode self.api_key = api_key self.server_url = server_url.rstrip("/") - self.environment = environment + if environment is not None: + warnings.warn("The environment is determined by your API key. Remove the `environment` argument.", DeprecationWarning, stacklevel=2) + # Kept for existing callers; it no longer controls routing or appears in requests. + self.environment = "production" if environment is None else environment self.timeout = timeout / 1000.0 self.session = requests.Session() self.session.headers.update({"X-API-Key": self.api_key, "Content-Type": "application/json"}) @@ -51,7 +57,7 @@ def _ignore_identity(self) -> bool: def _apply_mode(self, payload: Dict[str, Any]) -> Dict[str, Any]: # The client owns the mode: raw batches and options cannot select another - # mode or restore identity and environment fields. + # mode or restore identity fields. if self._mode == "product": return {key: value for key, value in payload.items() if key != "mode"} return { @@ -69,6 +75,8 @@ def _get_timestamp(self, timestamp: Optional[Union[str, int]] = None) -> str: return timestamp def _post(self, endpoint: str, payload: Union[Dict[str, Any], List[Dict[str, Any]]]): + # The API key selects the environment, so the deprecated field is never sent. + payload = [_without_environment(record) for record in payload] if isinstance(payload, list) else _without_environment(payload) try: response = self.session.post(f"{self.server_url}{endpoint}", json=payload, timeout=self.timeout) if not response.ok: @@ -91,7 +99,6 @@ def track(self, event: Union[str, List[Dict[str, Any]]], distinct_id: Optional[s payload = { "timestamp": self._get_timestamp(options.get("timestamp")), "event": event, - "environment": options.get("environment", self.environment), "distinct_id": distinct_id, "properties": options.get("properties", {}) } @@ -111,7 +118,6 @@ def identify(self, distinct_id: Union[str, List[Dict[str, Any]]], options: Optio options = options or {} payload = { "timestamp": self._get_timestamp(options.get("timestamp")), - "environment": options.get("environment", self.environment), "distinct_id": distinct_id, } if "traits" in options: @@ -134,7 +140,6 @@ def alias(self, distinct_id: Union[str, List[Dict[str, Any]]], new_user_id: Opti options = options or {} payload = { "timestamp": self._get_timestamp(options.get("timestamp")), - "environment": options.get("environment", self.environment), "distinct_id": distinct_id, "new_user_id": new_user_id, } diff --git a/tests/test_altertable.py b/tests/test_altertable.py index a681598..a4b2e16 100644 --- a/tests/test_altertable.py +++ b/tests/test_altertable.py @@ -1,3 +1,4 @@ +import copy import os import pytest from unittest.mock import Mock @@ -32,7 +33,37 @@ def test_alias(client): ) assert response.get("ok") is True -def test_track_overload_passes_all_payloads_through_without_chunking(): +def test_environment_is_deprecated_and_never_sent_from_product_requests(): + with pytest.deprecated_call(match="environment is determined by your API key"): + client = Altertable("test_pk_abc123", MOCK_BASE_URL, "staging") + response = Mock(ok=True) + response.json.return_value = {"ok": True} + client.session.post = Mock(return_value=response) + + track_options = { + "environment": "event-env", + "properties": {"environment": "business-value"}, + } + identify_options = { + "environment": "identify-env", + "traits": {"environment": "trait-business-value"}, + } + original_track_options = copy.deepcopy(track_options) + original_identify_options = copy.deepcopy(identify_options) + client.track("tracked", "user-1", track_options) + client.identify("user-1", identify_options) + client.alias("user-1", "user-2", {"environment": "alias-env"}) + + payloads = [call.kwargs["json"] for call in client.session.post.call_args_list] + assert all("environment" not in payload for payload in payloads) + assert payloads[0]["properties"]["environment"] == "business-value" + assert payloads[1]["traits"]["environment"] == "trait-business-value" + assert track_options == original_track_options + assert identify_options == original_identify_options + assert client.environment == "staging" + + +def test_raw_batches_strip_environment_without_mutating_caller_payloads(): client = Altertable("test_pk_abc123", server_url=MOCK_BASE_URL) response = Mock(ok=True) response.json.return_value = {"ok": True} @@ -42,12 +73,17 @@ def test_track_overload_passes_all_payloads_through_without_chunking(): for index in range(101) ] + original = [payload.copy() for payload in payloads] assert client.track(payloads) == {"ok": True} client.session.post.assert_called_once() - assert client.session.post.call_args.kwargs["json"] == payloads + assert client.session.post.call_args.kwargs["json"] == [ + {"event": f"event-{index}", "distinct_id": f"user-{index}"} + for index in range(101) + ] + assert payloads == original @pytest.mark.parametrize("method_name, endpoint", [("identify", "/identify"), ("alias", "/alias")]) -def test_other_batch_overloads_pass_payloads_through(method_name, endpoint): +def test_identity_batches_strip_environment_without_mutating_caller(method_name, endpoint): client = Altertable("test_pk_abc123", server_url=MOCK_BASE_URL) response = Mock(ok=True) response.json.return_value = {"ok": True} @@ -56,7 +92,8 @@ def test_other_batch_overloads_pass_payloads_through(method_name, endpoint): assert getattr(client, method_name)(payloads) == {"ok": True} assert client.session.post.call_args.args[0] == f"{MOCK_BASE_URL}{endpoint}" - assert client.session.post.call_args.kwargs["json"] == payloads + assert client.session.post.call_args.kwargs["json"] == [{"distinct_id": "user-1"}] + assert payloads == [{"distinct_id": "user-1", "environment": "test"}] def test_authentication_error(): client = Altertable("wrong_api_key", server_url=MOCK_BASE_URL) diff --git a/tests/test_audience.py b/tests/test_audience.py index ece98e2..9bc4034 100644 --- a/tests/test_audience.py +++ b/tests/test_audience.py @@ -22,7 +22,8 @@ def sent_payloads(client): def test_track_sends_only_audience_fields_and_leaves_properties_unchanged(): - client = make_client(environment="ignored", mode="audience") + with pytest.deprecated_call(): + client = make_client(environment="ignored", mode="audience") properties = { "section": "docs", "environment": "business-value", From d7589fe53394b60c73bff51fedd6f57af6b33399 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fran=C3=A7ois=20Chalifour?= Date: Mon, 9 Nov 2026 15:41:36 +0100 Subject: [PATCH 2/2] refactor: drop the ignored environment value and warning --- src/altertable/client.py | 6 +----- tests/test_altertable.py | 6 ++---- tests/test_audience.py | 3 +-- 3 files changed, 4 insertions(+), 11 deletions(-) diff --git a/src/altertable/client.py b/src/altertable/client.py index 16a1048..1df1a73 100644 --- a/src/altertable/client.py +++ b/src/altertable/client.py @@ -28,7 +28,7 @@ def __init__(self, api_key: str, server_url: str = "https://api.altertable.ai", :param api_key: API key used to authenticate with the Altertable API. :param server_url: Base URL of the Altertable API server. - :param environment: Deprecated and ignored. The API key determines the environment. + :param environment: Ignored; kept so existing calls keep working. The API key determines the environment. :param mode: Collection mode, fixed for this client. Audience mode sends events without identity fields and ignores identify and alias. :param timeout: Request timeout in milliseconds. This value is converted to seconds @@ -39,10 +39,6 @@ def __init__(self, api_key: str, server_url: str = "https://api.altertable.ai", self._mode: TrackingMode = mode self.api_key = api_key self.server_url = server_url.rstrip("/") - if environment is not None: - warnings.warn("The environment is determined by your API key. Remove the `environment` argument.", DeprecationWarning, stacklevel=2) - # Kept for existing callers; it no longer controls routing or appears in requests. - self.environment = "production" if environment is None else environment self.timeout = timeout / 1000.0 self.session = requests.Session() self.session.headers.update({"X-API-Key": self.api_key, "Content-Type": "application/json"}) diff --git a/tests/test_altertable.py b/tests/test_altertable.py index a4b2e16..6cbcff7 100644 --- a/tests/test_altertable.py +++ b/tests/test_altertable.py @@ -33,9 +33,8 @@ def test_alias(client): ) assert response.get("ok") is True -def test_environment_is_deprecated_and_never_sent_from_product_requests(): - with pytest.deprecated_call(match="environment is determined by your API key"): - client = Altertable("test_pk_abc123", MOCK_BASE_URL, "staging") +def test_environment_is_ignored_and_never_sent_from_product_requests(): + client = Altertable("test_pk_abc123", MOCK_BASE_URL, "staging") response = Mock(ok=True) response.json.return_value = {"ok": True} client.session.post = Mock(return_value=response) @@ -60,7 +59,6 @@ def test_environment_is_deprecated_and_never_sent_from_product_requests(): assert payloads[1]["traits"]["environment"] == "trait-business-value" assert track_options == original_track_options assert identify_options == original_identify_options - assert client.environment == "staging" def test_raw_batches_strip_environment_without_mutating_caller_payloads(): diff --git a/tests/test_audience.py b/tests/test_audience.py index 9bc4034..ece98e2 100644 --- a/tests/test_audience.py +++ b/tests/test_audience.py @@ -22,8 +22,7 @@ def sent_payloads(client): def test_track_sends_only_audience_fields_and_leaves_properties_unchanged(): - with pytest.deprecated_call(): - client = make_client(environment="ignored", mode="audience") + client = make_client(environment="ignored", mode="audience") properties = { "section": "docs", "environment": "business-value",