numbunch 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,10 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ .mypy_cache/
7
+ dist/
8
+ build/
9
+ *.egg-info/
10
+ uv.lock
numbunch-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Numbunch contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,23 @@
1
+ Metadata-Version: 2.5
2
+ Name: numbunch
3
+ Version: 0.1.0
4
+ Summary: Numbunch Python SDK: batched capture, local flag evaluation (sha1_v1 and murmur3_v1), exceptions, OpenTelemetry
5
+ Project-URL: Homepage, https://numbunch.com
6
+ Project-URL: Source, https://github.com/MidgardAI/numbunch/tree/main/sdk/python
7
+ Author: Numbunch contributors
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: analytics,feature flags,numbunch,product analytics
11
+ Classifier: Operating System :: OS Independent
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Typing :: Typed
14
+ Requires-Python: >=3.9
15
+ Provides-Extra: celery
16
+ Requires-Dist: celery>=5; extra == 'celery'
17
+ Provides-Extra: fastapi
18
+ Requires-Dist: starlette>=0.27; extra == 'fastapi'
19
+ Provides-Extra: opentelemetry
20
+ Requires-Dist: opentelemetry-api>=1.20; extra == 'opentelemetry'
21
+ Description-Content-Type: text/plain
22
+
23
+ Numbunch Python SDK. See https://numbunch.com/docs/sdks/python.
@@ -0,0 +1,55 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.24"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "numbunch"
7
+ dynamic = ["version"]
8
+ description = "Numbunch Python SDK: batched capture, local flag evaluation (sha1_v1 and murmur3_v1), exceptions, OpenTelemetry"
9
+ readme = { text = "Numbunch Python SDK. See https://numbunch.com/docs/sdks/python.", content-type = "text/plain" }
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.9"
13
+ authors = [{ name = "Numbunch contributors" }]
14
+ keywords = ["analytics", "feature flags", "product analytics", "numbunch"]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "Operating System :: OS Independent",
18
+ "Typing :: Typed",
19
+ ]
20
+ dependencies = []
21
+
22
+ [project.optional-dependencies]
23
+ opentelemetry = ["opentelemetry-api>=1.20"]
24
+ fastapi = ["starlette>=0.27"]
25
+ celery = ["celery>=5"]
26
+
27
+ [project.urls]
28
+ Homepage = "https://numbunch.com"
29
+ Source = "https://github.com/MidgardAI/numbunch/tree/main/sdk/python"
30
+
31
+ [dependency-groups]
32
+ dev = ["pytest>=8", "ruff>=0.6", "opentelemetry-api>=1.20", "opentelemetry-sdk>=1.20", "starlette>=0.27", "httpx>=0.27"]
33
+
34
+ [tool.hatch.version]
35
+ path = "src/numbunch/version.py"
36
+ pattern = "VERSION = \"(?P<version>[^\"]+)\""
37
+
38
+ [tool.hatch.build.targets.wheel]
39
+ packages = ["src/numbunch"]
40
+
41
+ [tool.hatch.build.targets.sdist]
42
+ include = ["src/numbunch", "tests", "LICENSE", "pyproject.toml"]
43
+
44
+ [tool.pytest.ini_options]
45
+ testpaths = ["tests"]
46
+ addopts = "-q"
47
+
48
+ [tool.ruff]
49
+ line-length = 120
50
+ target-version = "py39"
51
+ src = ["src", "tests"]
52
+
53
+ [tool.ruff.lint]
54
+ select = ["E", "F", "W", "I", "B", "UP", "SIM"]
55
+ ignore = ["UP006", "UP007", "UP035", "UP045"]
@@ -0,0 +1,37 @@
1
+ """Numbunch Python SDK (MIT).
2
+
3
+ from numbunch import Numbunch
4
+
5
+ numbunch = Numbunch("nb_pub_…", host="https://in.example.com", secret_key="nb_sec_…")
6
+ numbunch.capture("user@example.com", "Signed up", {"plan": "pro"})
7
+ variant = numbunch.get_feature_flag("landing-home-new", "user@example.com")
8
+ numbunch.shutdown()
9
+ """
10
+
11
+ from .client import DEFAULT_HOST, Numbunch
12
+ from .context import parse_baggage, request_context, trace_properties, with_request_context
13
+ from .evaluate import Evaluation, evaluate
14
+ from .hashing import murmur3_v1, murmur3_x86_32, sha1_v1
15
+ from .matching import Inconclusive
16
+ from .uuid7 import uuid7
17
+ from .version import VERSION
18
+
19
+ __version__ = VERSION
20
+
21
+ __all__ = [
22
+ "DEFAULT_HOST",
23
+ "VERSION",
24
+ "Evaluation",
25
+ "Inconclusive",
26
+ "Numbunch",
27
+ "__version__",
28
+ "evaluate",
29
+ "murmur3_v1",
30
+ "murmur3_x86_32",
31
+ "parse_baggage",
32
+ "request_context",
33
+ "sha1_v1",
34
+ "trace_properties",
35
+ "uuid7",
36
+ "with_request_context",
37
+ ]
@@ -0,0 +1,520 @@
1
+ """The Numbunch client: batched capture, identity, local flag evaluation and exceptions.
2
+
3
+ The wire format is PostHog's (``/batch/``, ``/flags/?v=2``), so the server needs no new ingestion path. Local
4
+ evaluation reads ``GET /v1/flags/definitions`` with the environment's ``nb_sec_`` secret and evaluates both
5
+ bucketing algorithms; flags it cannot decide (experience continuity, properties the caller did not supply) are asked
6
+ of the server. Parts are shaped after posthog-python (MIT, Copyright (c) PostHog Inc.).
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import atexit
12
+ import json
13
+ import logging
14
+ import random
15
+ import sys
16
+ import threading
17
+ import time
18
+ import uuid as uuid_module
19
+ import weakref
20
+ from collections import OrderedDict
21
+ from datetime import datetime, timezone
22
+ from typing import Any, Callable, Dict, List, Mapping, Optional, Tuple, Union
23
+
24
+ from . import context
25
+ from .consumer import Consumer
26
+ from .evaluate import NO_GROUP_TYPE, Evaluation, evaluate, payload
27
+ from .exceptions import exception_properties
28
+ from .matching import Inconclusive
29
+ from .transport import Response, Transport, json_body
30
+ from .uuid7 import uuid7
31
+ from .version import VERSION
32
+
33
+ DEFAULT_HOST = "https://in.numbunch.com"
34
+ LIB = "numbunch-python"
35
+
36
+ log = logging.getLogger("numbunch")
37
+
38
+ FlagValue = Union[str, bool]
39
+
40
+
41
+ class _NeedsServer(Exception):
42
+ """A flag the client cannot decide locally."""
43
+
44
+
45
+ def _iso(timestamp: Union[datetime, str, None]) -> str:
46
+ if timestamp is None:
47
+ return datetime.now(timezone.utc).isoformat()
48
+ if isinstance(timestamp, str):
49
+ return timestamp
50
+ if timestamp.tzinfo is None:
51
+ timestamp = timestamp.replace(tzinfo=timezone.utc)
52
+ return timestamp.isoformat()
53
+
54
+
55
+ def _decode_payload(value: Any) -> Any:
56
+ if isinstance(value, str):
57
+ try:
58
+ return json.loads(value)
59
+ except ValueError:
60
+ return value
61
+ return value
62
+
63
+
64
+ class _Definitions:
65
+ """Flag definitions for local evaluation, refreshed with ``If-None-Match`` every ``poll_interval`` seconds."""
66
+
67
+ def __init__(self, client: Numbunch, poll_interval: float) -> None:
68
+ self._client = client
69
+ self._poll_interval = poll_interval
70
+ self._lock = threading.Lock()
71
+ self._etag: Optional[str] = None
72
+ self.flags: Dict[str, Dict[str, Any]] = {}
73
+ self.group_types: Dict[str, str] = {}
74
+ self.loaded = False
75
+ self._stop = threading.Event()
76
+ self._thread: Optional[threading.Thread] = None
77
+
78
+ def start(self) -> None:
79
+ self._thread = threading.Thread(target=self._run, name="numbunch-flags", daemon=True)
80
+ self._thread.start()
81
+
82
+ def stop(self) -> None:
83
+ self._stop.set()
84
+
85
+ def _run(self) -> None:
86
+ while not self._stop.is_set():
87
+ self.load()
88
+ self._stop.wait(self._poll_interval)
89
+
90
+ def ensure_loaded(self) -> bool:
91
+ if not self.loaded:
92
+ self.load()
93
+ return self.loaded
94
+
95
+ def load(self) -> None:
96
+ with self._lock:
97
+ headers = {"Authorization": f"Bearer {self._client.secret_key}"}
98
+ if self._etag:
99
+ headers["If-None-Match"] = self._etag
100
+ try:
101
+ reply = self._client._request("GET", "/v1/flags/definitions", headers=headers)
102
+ except OSError as error:
103
+ self._client._error(f"loading flag definitions failed: {error}")
104
+ return
105
+ if reply.status == 304:
106
+ self.loaded = True
107
+ return
108
+ if reply.status != 200:
109
+ self._client._error(f"loading flag definitions failed: HTTP {reply.status} {reply.body[:200]!r}")
110
+ return
111
+ try:
112
+ body = reply.json() or {}
113
+ except ValueError as error:
114
+ self._client._error(f"flag definitions are not JSON: {error}")
115
+ return
116
+ self.flags = {flag["key"]: flag for flag in body.get("flags") or []}
117
+ self.group_types = {str(k): v for k, v in (body.get("group_type_mapping") or {}).items()}
118
+ self._etag = reply.headers.get("etag")
119
+ self.loaded = True
120
+
121
+
122
+ def _shutdown_at_exit(ref: weakref.ReferenceType[Numbunch]) -> None:
123
+ client = ref()
124
+ if client is not None:
125
+ client.shutdown()
126
+
127
+
128
+ class Numbunch:
129
+ """A Numbunch client. Thread-safe; create one per process and call :meth:`shutdown` (also run at exit).
130
+
131
+ ``api_key`` is the environment's public ``nb_pub_`` token. ``secret_key`` (the environment's ``nb_sec_`` secret)
132
+ turns on local flag evaluation.
133
+ """
134
+
135
+ def __init__(
136
+ self,
137
+ api_key: str,
138
+ host: str = DEFAULT_HOST,
139
+ secret_key: Optional[str] = None,
140
+ flush_at: int = 100,
141
+ flush_interval: float = 10.0,
142
+ max_queue_size: int = 10000,
143
+ poll_interval: float = 30,
144
+ timeout: float = 10,
145
+ max_retries: int = 3,
146
+ disabled: bool = False,
147
+ on_error: Optional[Callable[[str], None]] = None,
148
+ gzip: bool = True,
149
+ transport: Optional[Transport] = None,
150
+ ) -> None:
151
+ self.api_key = api_key
152
+ self.host = host.rstrip("/")
153
+ self.secret_key = secret_key
154
+ self.timeout = timeout
155
+ self.max_retries = max(0, max_retries)
156
+ self.disabled = disabled
157
+ self.gzip = gzip
158
+ self._on_error = on_error
159
+ self._transport = transport or Transport()
160
+ self._flag_calls: OrderedDict[Tuple[str, str, str], None] = OrderedDict()
161
+ self._flag_calls_lock = threading.Lock()
162
+ self._shutdown = False
163
+ self._previous_hooks: Optional[Tuple[Any, Any]] = None
164
+ self._consumer = None if disabled else Consumer(self._send_batch, flush_at, flush_interval, max_queue_size)
165
+ self._definitions: Optional[_Definitions] = None
166
+ if secret_key and not disabled:
167
+ self._definitions = _Definitions(self, poll_interval)
168
+ self._definitions.start()
169
+ atexit.register(_shutdown_at_exit, weakref.ref(self))
170
+
171
+ # ----------------------------------------------------------------------------------------------------- transport
172
+
173
+ def _error(self, message: str) -> None:
174
+ log.warning("numbunch: %s", message)
175
+ if self._on_error is not None:
176
+ try:
177
+ self._on_error(message)
178
+ except Exception: # noqa: BLE001 - a failing callback must not break capture
179
+ log.exception("numbunch: on_error raised")
180
+
181
+ def _request(
182
+ self, method: str, path: str, payload: Any = None, headers: Optional[Dict[str, str]] = None
183
+ ) -> Response:
184
+ body = None
185
+ all_headers = dict(headers or {})
186
+ if payload is not None:
187
+ body, json_headers = json_body(payload, self.gzip)
188
+ all_headers.update(json_headers)
189
+ return self._transport.request(method, f"{self.host}{path}", all_headers, body, self.timeout)
190
+
191
+ def _send_batch(self, batch: List[Dict[str, Any]]) -> None:
192
+ payload = {"api_key": self.api_key, "batch": batch, "sent_at": datetime.now(timezone.utc).isoformat()}
193
+ for attempt in range(self.max_retries + 1):
194
+ try:
195
+ reply = self._request("POST", "/batch/", payload)
196
+ if 200 <= reply.status < 300:
197
+ return
198
+ retryable = reply.status >= 500 or reply.status == 429
199
+ problem = f"HTTP {reply.status} {reply.body[:200]!r}"
200
+ except (ValueError, TypeError, RecursionError) as error:
201
+ # Isolate a malformed property without losing valid events in the same batch.
202
+ if len(batch) == 1:
203
+ self._error(f"invalid event payload: {type(error).__name__}")
204
+ else:
205
+ middle = len(batch) // 2
206
+ self._send_batch(batch[:middle])
207
+ self._send_batch(batch[middle:])
208
+ return
209
+ except OSError as error:
210
+ retryable, problem = True, str(error)
211
+ if not retryable or attempt == self.max_retries:
212
+ self._error(f"sending {len(batch)} events failed: {problem}")
213
+ return
214
+ # Exponential backoff with jitter: 0.5 s, 1 s, 2 s, … (at most 30 s), times 0.5–1.5.
215
+ time.sleep(min(30.0, 0.5 * 2**attempt) * (0.5 + random.random()))
216
+
217
+ # ------------------------------------------------------------------------------------------------------ capture
218
+
219
+ def capture(
220
+ self,
221
+ distinct_id: Optional[str],
222
+ event: str,
223
+ properties: Optional[Mapping[str, Any]] = None,
224
+ groups: Optional[Mapping[str, str]] = None,
225
+ uuid: Union[str, uuid_module.UUID, None] = None,
226
+ timestamp: Union[datetime, str, None] = None,
227
+ ) -> Optional[str]:
228
+ """Queues an event and returns its UUID (``None`` if disabled or the queue is full).
229
+
230
+ Pass ``uuid`` and ``timestamp`` for idempotent server events: the server deduplicates on the UUID. Without a
231
+ ``distinct_id`` the request context's ``user.id`` is used, else the event is personless.
232
+ """
233
+ if self.disabled or self._consumer is None:
234
+ return None
235
+ props: Dict[str, Any] = dict(context.trace_properties())
236
+ session_id = context.current_session_id()
237
+ if session_id:
238
+ props["$session_id"] = session_id
239
+ props.update(properties or {})
240
+ if distinct_id is None:
241
+ distinct_id = context.current_distinct_id()
242
+ if distinct_id is None:
243
+ distinct_id = str(uuid7())
244
+ props.setdefault("$process_person_profile", False)
245
+ if groups:
246
+ props["$groups"] = dict(groups)
247
+ props["$lib"] = LIB
248
+ props["$lib_version"] = VERSION
249
+ event_uuid = str(uuid or uuid7())
250
+ message = {
251
+ "type": "capture",
252
+ "event": event,
253
+ "distinct_id": str(distinct_id),
254
+ "properties": props,
255
+ "timestamp": _iso(timestamp),
256
+ "uuid": event_uuid,
257
+ }
258
+ if not self._consumer.put(message):
259
+ self._error(f"queue full or shut down; dropped {event!r}")
260
+ return None
261
+ return event_uuid
262
+
263
+ def identify(
264
+ self, distinct_id: str, properties: Optional[Mapping[str, Any]] = None, **kwargs: Any
265
+ ) -> Optional[str]:
266
+ """Sets person properties (``$set``) on ``distinct_id``'s person."""
267
+ return self.capture(distinct_id, "$identify", {"$set": dict(properties or {})}, **kwargs)
268
+
269
+ def group_identify(
270
+ self,
271
+ group_type: str,
272
+ group_key: str,
273
+ properties: Optional[Mapping[str, Any]] = None,
274
+ distinct_id: Optional[str] = None,
275
+ **kwargs: Any,
276
+ ) -> Optional[str]:
277
+ """Sets properties of a group (``$groupidentify``)."""
278
+ props = {"$group_type": group_type, "$group_key": group_key, "$group_set": dict(properties or {})}
279
+ return self.capture(distinct_id or f"${group_type}_{group_key}", "$groupidentify", props, **kwargs)
280
+
281
+ def capture_exception(
282
+ self,
283
+ exc: Optional[BaseException] = None,
284
+ distinct_id: Optional[str] = None,
285
+ properties: Optional[Mapping[str, Any]] = None,
286
+ handled: bool = True,
287
+ ) -> Optional[str]:
288
+ """Captures ``exc`` (default: the exception being handled) as ``$exception``."""
289
+ props = exception_properties(exc, handled)
290
+ if props is None:
291
+ return None
292
+ props.update(properties or {})
293
+ return self.capture(distinct_id, "$exception", props)
294
+
295
+ def enable_exception_autocapture(self) -> None:
296
+ """Captures uncaught exceptions (``sys.excepthook`` and ``threading.excepthook``), then calls the previous
297
+ hooks."""
298
+ if self._previous_hooks is not None:
299
+ return
300
+ previous_sys, previous_thread = sys.excepthook, threading.excepthook
301
+ self._previous_hooks = (previous_sys, previous_thread)
302
+
303
+ def sys_hook(exc_type: Any, exc: BaseException, tb: Any) -> None:
304
+ if not isinstance(exc, KeyboardInterrupt):
305
+ self.capture_exception(exc, handled=False)
306
+ self.flush(timeout=self.timeout)
307
+ previous_sys(exc_type, exc, tb)
308
+
309
+ def thread_hook(args: Any) -> None:
310
+ if args.exc_value is not None and not isinstance(args.exc_value, SystemExit):
311
+ self.capture_exception(args.exc_value, handled=False)
312
+ previous_thread(args)
313
+
314
+ sys.excepthook = sys_hook
315
+ threading.excepthook = thread_hook
316
+
317
+ # -------------------------------------------------------------------------------------------------------- flags
318
+
319
+ def _local(
320
+ self,
321
+ flag: Mapping[str, Any],
322
+ distinct_id: str,
323
+ person_properties: Optional[Mapping[str, Any]],
324
+ groups: Optional[Mapping[str, str]],
325
+ group_properties: Optional[Mapping[str, Mapping[str, Any]]],
326
+ ) -> Evaluation:
327
+ if flag.get("ensure_continuity"):
328
+ raise _NeedsServer
329
+ filters = flag.get("filters") or {}
330
+ index = filters.get("aggregation_group_type_index")
331
+ try:
332
+ if index is not None:
333
+ group_types = self._definitions.group_types if self._definitions is not None else {}
334
+ name = group_types.get(str(index))
335
+ key = (groups or {}).get(name) if name else None
336
+ if key is None or name is None:
337
+ if not flag.get("active", True):
338
+ return evaluate(flag, "", {})
339
+ return Evaluation(False, None, NO_GROUP_TYPE)
340
+ props: Dict[str, Any] = {"$group_key": key, **dict((group_properties or {}).get(name) or {})}
341
+ result = evaluate(flag, str(key), props)
342
+ else:
343
+ props = dict(person_properties or {})
344
+ props.setdefault("distinct_id", distinct_id)
345
+ result = evaluate(flag, distinct_id, props)
346
+ except Inconclusive as error:
347
+ raise _NeedsServer from error
348
+ if result.skipped_inconclusive:
349
+ raise _NeedsServer
350
+ return result
351
+
352
+ def _remote(
353
+ self,
354
+ distinct_id: str,
355
+ person_properties: Optional[Mapping[str, Any]],
356
+ groups: Optional[Mapping[str, str]],
357
+ group_properties: Optional[Mapping[str, Mapping[str, Any]]],
358
+ keys: Optional[List[str]] = None,
359
+ ) -> Optional[Dict[str, Dict[str, Any]]]:
360
+ body: Dict[str, Any] = {
361
+ "token": self.api_key,
362
+ "distinct_id": distinct_id,
363
+ "person_properties": dict(person_properties or {}),
364
+ "groups": dict(groups or {}),
365
+ "group_properties": {k: dict(v) for k, v in (group_properties or {}).items()},
366
+ }
367
+ if keys is not None:
368
+ body["flag_keys_to_evaluate"] = keys
369
+ try:
370
+ reply = self._request("POST", "/flags/?v=2", body)
371
+ except OSError as error:
372
+ self._error(f"remote flag evaluation failed: {error}")
373
+ return None
374
+ if reply.status != 200:
375
+ self._error(f"remote flag evaluation failed: HTTP {reply.status}")
376
+ return None
377
+ try:
378
+ flags = (reply.json() or {}).get("flags") or {}
379
+ except ValueError:
380
+ return None
381
+ out = {}
382
+ for key, detail in flags.items():
383
+ variant = detail.get("variant")
384
+ value = variant if variant is not None else bool(detail.get("enabled"))
385
+ out[key] = {"value": value, "payload": (detail.get("metadata") or {}).get("payload")}
386
+ return out
387
+
388
+ def _detail(
389
+ self,
390
+ key: str,
391
+ distinct_id: str,
392
+ person_properties: Optional[Mapping[str, Any]],
393
+ groups: Optional[Mapping[str, str]],
394
+ group_properties: Optional[Mapping[str, Mapping[str, Any]]],
395
+ only_evaluate_locally: bool,
396
+ ) -> Optional[Tuple[FlagValue, Any, bool]]:
397
+ """``(value, payload, locally_evaluated)``, or ``None`` when the flag is unknown or undecidable."""
398
+ if self.disabled:
399
+ return None
400
+ if self._definitions is not None and self._definitions.ensure_loaded():
401
+ flag = self._definitions.flags.get(key)
402
+ if flag is not None:
403
+ try:
404
+ result = self._local(flag, distinct_id, person_properties, groups, group_properties)
405
+ return result.value, payload(flag, result), True
406
+ except _NeedsServer:
407
+ pass
408
+ if only_evaluate_locally:
409
+ return None
410
+ remote = self._remote(distinct_id, person_properties, groups, group_properties, [key])
411
+ if remote is None or key not in remote:
412
+ return None
413
+ return remote[key]["value"], remote[key]["payload"], False
414
+
415
+ def get_feature_flag(
416
+ self,
417
+ key: str,
418
+ distinct_id: str,
419
+ person_properties: Optional[Mapping[str, Any]] = None,
420
+ groups: Optional[Mapping[str, str]] = None,
421
+ group_properties: Optional[Mapping[str, Mapping[str, Any]]] = None,
422
+ only_evaluate_locally: bool = False,
423
+ send_feature_flag_events: bool = True,
424
+ ) -> Optional[FlagValue]:
425
+ """The flag's variant, ``True``/``False``, or ``None`` if it is unknown or could not be evaluated."""
426
+ detail = self._detail(key, distinct_id, person_properties, groups, group_properties, only_evaluate_locally)
427
+ if detail is None:
428
+ return None
429
+ if send_feature_flag_events:
430
+ self._flag_called(key, distinct_id, detail[0], detail[2], groups)
431
+ return detail[0]
432
+
433
+ def feature_enabled(self, key: str, distinct_id: str, **kwargs: Any) -> Optional[bool]:
434
+ value = self.get_feature_flag(key, distinct_id, **kwargs)
435
+ return None if value is None else bool(value)
436
+
437
+ def get_feature_flag_payload(
438
+ self,
439
+ key: str,
440
+ distinct_id: str,
441
+ person_properties: Optional[Mapping[str, Any]] = None,
442
+ groups: Optional[Mapping[str, str]] = None,
443
+ group_properties: Optional[Mapping[str, Mapping[str, Any]]] = None,
444
+ only_evaluate_locally: bool = False,
445
+ ) -> Any:
446
+ """The payload for the flag's current value (JSON-decoded), or ``None``."""
447
+ detail = self._detail(key, distinct_id, person_properties, groups, group_properties, only_evaluate_locally)
448
+ return None if detail is None else _decode_payload(detail[1])
449
+
450
+ def get_all_flags(
451
+ self,
452
+ distinct_id: str,
453
+ person_properties: Optional[Mapping[str, Any]] = None,
454
+ groups: Optional[Mapping[str, str]] = None,
455
+ group_properties: Optional[Mapping[str, Mapping[str, Any]]] = None,
456
+ only_evaluate_locally: bool = False,
457
+ ) -> Dict[str, FlagValue]:
458
+ """Every flag's value for ``distinct_id``: local where possible, one server request for the rest."""
459
+ if self.disabled:
460
+ return {}
461
+ out: Dict[str, FlagValue] = {}
462
+ needs_server = True
463
+ if self._definitions is not None and self._definitions.ensure_loaded():
464
+ needs_server = False
465
+ for key, flag in self._definitions.flags.items():
466
+ try:
467
+ out[key] = self._local(flag, distinct_id, person_properties, groups, group_properties).value
468
+ except _NeedsServer:
469
+ needs_server = True
470
+ if needs_server and not only_evaluate_locally:
471
+ remote = self._remote(distinct_id, person_properties, groups, group_properties)
472
+ for key, detail in (remote or {}).items():
473
+ out.setdefault(key, detail["value"])
474
+ return out
475
+
476
+ def get_bootstrap(self, distinct_id: str, **kwargs: Any) -> Dict[str, Any]:
477
+ """``{"distinctId", "flags"}`` to embed in HTML as ``@numbunch/browser``'s ``bootstrap`` option, so the page
478
+ reads flags before any request."""
479
+ return {"distinctId": distinct_id, "flags": self.get_all_flags(distinct_id, **kwargs)}
480
+
481
+ def _flag_called(
482
+ self, key: str, distinct_id: str, value: FlagValue, locally: bool, groups: Optional[Mapping[str, str]]
483
+ ) -> None:
484
+ cache_key = (distinct_id, key, json.dumps(value))
485
+ with self._flag_calls_lock:
486
+ if cache_key in self._flag_calls:
487
+ self._flag_calls.move_to_end(cache_key)
488
+ return
489
+ self._flag_calls[cache_key] = None
490
+ if len(self._flag_calls) > 50_000:
491
+ self._flag_calls.popitem(last=False)
492
+ properties = {
493
+ "$feature_flag": key,
494
+ "$feature_flag_response": value,
495
+ "locally_evaluated": locally,
496
+ f"$feature/{key}": value,
497
+ }
498
+ self.capture(distinct_id, "$feature_flag_called", properties, groups=groups)
499
+
500
+ # ----------------------------------------------------------------------------------------------------- lifecycle
501
+
502
+ def flush(self, timeout: Optional[float] = None) -> bool:
503
+ """Blocks until every queued event is sent (or ``timeout`` seconds pass)."""
504
+ return True if self._consumer is None else self._consumer.flush(timeout)
505
+
506
+ def shutdown(self, timeout: Optional[float] = None) -> None:
507
+ """Flushes, stops polling and stops the background threads. Idempotent."""
508
+ if self._shutdown:
509
+ return
510
+ self._shutdown = True
511
+ if self._definitions is not None:
512
+ self._definitions.stop()
513
+ if self._consumer is not None:
514
+ self._consumer.stop(timeout)
515
+
516
+ def __enter__(self) -> Numbunch:
517
+ return self
518
+
519
+ def __exit__(self, *exc: Any) -> None:
520
+ self.shutdown()