growthbook 1.2.1__py2.py3-none-any.whl → 1.3.1__py2.py3-none-any.whl

growthbook/__init__.py

@@ -1 +1,22 @@
-from .growthbook import *
+from .growthbook import *
+
+from .growthbook_client import (
+    GrowthBookClient,
+    EnhancedFeatureRepository,
+    FeatureCache,
+    BackoffStrategy
+)
+
+# Plugin support
+from .plugins import (
+    GrowthBookTrackingPlugin,
+    growthbook_tracking_plugin,
+    RequestContextPlugin,
+    ClientSideAttributes,
+    request_context_plugin,
+    client_side_attributes
+)
+
+# x-release-please-start-version
+__version__ = "1.3.1"
+# x-release-please-end

growthbook/common_types.py

@@ -220,9 +220,8 @@ class FeatureResult(object):
             "source": self.source,
             "on": self.on,
             "off": self.off,
+            "ruleId": self.ruleId or "",
         }
-        if self.ruleId:
-            data["ruleId"] = self.ruleId
         if self.experiment:
             data["experiment"] = self.experiment.to_dict()
         if self.experimentResult:

growthbook/core.py

@@ -413,7 +413,8 @@ def getBucketRanges(
 def eval_feature(
     key: str,
     evalContext: EvaluationContext = None,
-    callback_subscription: Callable[[Experiment, Result], None] = None
+    callback_subscription: Callable[[Experiment, Result], None] = None,
+    tracking_cb: Callable[[Experiment, Result], None] = None
 ) -> FeatureResult:
     """Core feature evaluation logic as a standalone function"""
 
@@ -506,7 +507,7 @@ def eval_feature(
             minBucketVersion=rule.minBucketVersion,
         )
 
-        result = run_experiment(experiment=exp, featureId=key, evalContext=evalContext)
+        result = run_experiment(experiment=exp, featureId=key, evalContext=evalContext, tracking_cb=tracking_cb)
 
         if callback_subscription:
             callback_subscription(exp, result)
@@ -536,12 +537,20 @@ def eval_prereqs(parentConditions: List[dict], evalContext: EvaluationContext) -
         # Reset the stack in each iteration
         evalContext.stack.evaluated_features = evaluated_features.copy()
 
-        parentRes = eval_feature(key=parentCondition.get("id", None), evalContext=evalContext)
+        parent_id = parentCondition.get("id")
+        if parent_id is None:
+            continue  # Skip if no valid ID
+            
+        parentRes = eval_feature(key=parent_id, evalContext=evalContext)
 
         if parentRes.source == "cyclicPrerequisite":
             return "cyclic"
 
-        if not evalCondition({'value': parentRes.value}, parentCondition.get("condition", None), evalContext.global_ctx.saved_groups):
+        parent_condition = parentCondition.get("condition")
+        if parent_condition is None:
+            continue  # Skip if no valid condition
+            
+        if not evalCondition({'value': parentRes.value}, parent_condition, evalContext.global_ctx.saved_groups):
             if parentCondition.get("gate", False):
                 return "gate"
             return "fail"

growthbook/growthbook.py

@@ -11,7 +11,7 @@ import threading
 import logging
 
 from abc import ABC, abstractmethod
-from typing import Optional, Any, Set, Tuple, List, Dict
+from typing import Optional, Any, Set, Tuple, List, Dict, Callable
 
 from .common_types import ( EvaluationContext, 
     Experiment, 
@@ -251,6 +251,7 @@ class FeatureRepository(object):
         self.cache: AbstractFeatureCache = InMemoryFeatureCache()
         self.http: Optional[PoolManager] = None
         self.sse_client: Optional[SSEClient] = None
+        self._feature_update_callbacks: List[Callable[[Dict], None]] = []
 
     def set_cache(self, cache: AbstractFeatureCache) -> None:
         self.cache = cache
@@ -258,12 +259,30 @@ class FeatureRepository(object):
     def clear_cache(self):
         self.cache.clear()
 
-    def save_in_cache(self, key: str, res, ttl: int = 60):
+    def save_in_cache(self, key: str, res, ttl: int = 600):
         self.cache.set(key, res, ttl)
 
-    # Loads features with an in-memory cache in front
+    def add_feature_update_callback(self, callback: Callable[[Dict], None]) -> None:
+        """Add a callback to be notified when features are updated due to cache expiry"""
+        if callback not in self._feature_update_callbacks:
+            self._feature_update_callbacks.append(callback)
+
+    def remove_feature_update_callback(self, callback: Callable[[Dict], None]) -> None:
+        """Remove a feature update callback"""
+        if callback in self._feature_update_callbacks:
+            self._feature_update_callbacks.remove(callback)
+
+    def _notify_feature_update_callbacks(self, features_data: Dict) -> None:
+        """Notify all registered callbacks about feature updates"""
+        for callback in self._feature_update_callbacks:
+            try:
+                callback(features_data)
+            except Exception as e:
+                logger.warning(f"Error in feature update callback: {e}")
+
+    # Loads features with an in-memory cache in front using stale-while-revalidate approach
     def load_features(
-        self, api_host: str, client_key: str, decryption_key: str = "", ttl: int = 60
+        self, api_host: str, client_key: str, decryption_key: str = "", ttl: int = 600
     ) -> Optional[Dict]:
         if not client_key:
             raise ValueError("Must specify `client_key` to refresh features")
@@ -276,11 +295,13 @@ class FeatureRepository(object):
             if res is not None:
                 self.cache.set(key, res, ttl)
                 logger.debug("Fetched features from API, stored in cache")
+                # Notify callbacks about fresh features
+                self._notify_feature_update_callbacks(res)
                 return res
         return cached
     
     async def load_features_async(
-        self, api_host: str, client_key: str, decryption_key: str = "", ttl: int = 60
+        self, api_host: str, client_key: str, decryption_key: str = "", ttl: int = 600
     ) -> Optional[Dict]:
         key = api_host + "::" + client_key
 
@@ -290,6 +311,8 @@ class FeatureRepository(object):
             if res is not None:
                 self.cache.set(key, res, ttl)
                 logger.debug("Fetched features from API, stored in cache")
+                # Notify callbacks about fresh features
+                self._notify_feature_update_callbacks(res)
                 return res
         return cached
 
@@ -414,12 +437,13 @@ class GrowthBook(object):
         api_host: str = "",
         client_key: str = "",
         decryption_key: str = "",
-        cache_ttl: int = 60,
+        cache_ttl: int = 600,
         forced_variations: dict = {},
         sticky_bucket_service: AbstractStickyBucketService = None,
         sticky_bucket_identifier_attributes: List[str] = None,
         savedGroups: dict = {},
         streaming: bool = False,
+        plugins: List = None,
         # Deprecated args
         trackingCallback=None,
         qaMode: bool = False,
@@ -458,6 +482,10 @@ class GrowthBook(object):
         self._assigned: Dict[str, Any] = {}
         self._subscriptions: Set[Any] = set()
 
+        # support plugins
+        self._plugins: List = plugins or []
+        self._initialized_plugins: List = []
+
         self._global_ctx = GlobalContext(
             options=Options(
                 url=self._url,
@@ -486,10 +514,22 @@ class GrowthBook(object):
         if features:
             self.setFeatures(features)
 
+        # Register for automatic feature updates when cache expires
+        if self._client_key:
+            feature_repo.add_feature_update_callback(self._on_feature_update)
+
+        self._initialize_plugins()
+
         if self._streaming:
             self.load_features()
             self.startAutoRefresh()
 
+    def _on_feature_update(self, features_data: Dict) -> None:
+        """Callback to handle automatic feature updates from FeatureRepository"""
+        if features_data and "features" in features_data:
+            self.set_features(features_data["features"])
+        if features_data and "savedGroups" in features_data:
+            self._saved_groups = features_data["savedGroups"]
 
     def load_features(self) -> None:
 
@@ -595,6 +635,13 @@ class GrowthBook(object):
         return self._attributes
 
     def destroy(self) -> None:
+        # Clean up plugins first
+        self._cleanup_plugins()
+        
+        # Clean up feature update callback
+        if self._client_key:
+            feature_repo.remove_feature_update_callback(self._on_feature_update)
+            
         self._subscriptions.clear()
         self._tracked.clear()
         self._assigned.clear()
@@ -631,7 +678,21 @@ class GrowthBook(object):
     def evalFeature(self, key: str) -> FeatureResult:
         return self.eval_feature(key)
     
+    def _ensure_fresh_features(self) -> None:
+        """Lazy refresh: Check cache expiry and refresh if needed, but only if client_key is provided"""
+        
+        if self._streaming or not self._client_key:
+            return  # Skip cache checks - SSE handles freshness for streaming users
+
+        try:
+            self.load_features()
+        except Exception as e:
+            logger.warning(f"Failed to refresh features: {e}")
+
     def _get_eval_context(self) -> EvaluationContext:
+        # Lazy refresh: ensure features are fresh before evaluation
+        self._ensure_fresh_features()
+        
         # use the latest attributes for every evaluation.
         self._user_ctx.attributes = self._attributes
         self._user_ctx.url = self._url
@@ -647,7 +708,8 @@ class GrowthBook(object):
     def eval_feature(self, key: str) -> FeatureResult:
         return core_eval_feature(key=key, 
                                  evalContext=self._get_eval_context(), 
-                                 callback_subscription=self._fireSubscriptions
+                                 callback_subscription=self._fireSubscriptions,
+                                 tracking_cb=self._track
                                  )
 
     # @deprecated, use get_all_results
@@ -744,3 +806,33 @@ class GrowthBook(object):
         self._sticky_bucket_assignment_docs = self.sticky_bucket_service.get_all_assignments(attributes)
         # Update the user context with the new sticky bucket assignment docs
         self._user_ctx.sticky_bucket_assignment_docs = self._sticky_bucket_assignment_docs
+
+    def _initialize_plugins(self) -> None:
+        """Initialize all plugins with this GrowthBook instance."""
+        for plugin in self._plugins:
+            try:
+                if hasattr(plugin, 'initialize'):
+                    # Plugin is a class instance with initialize method
+                    plugin.initialize(self)
+                    self._initialized_plugins.append(plugin)
+                    logger.debug(f"Initialized plugin: {plugin.__class__.__name__}")
+                elif callable(plugin):
+                    # Plugin is a callable function
+                    plugin(self)
+                    self._initialized_plugins.append(plugin)
+                    logger.debug(f"Initialized callable plugin: {plugin.__name__}")
+                else:
+                    logger.warning(f"Plugin {plugin} is neither callable nor has initialize method")
+            except Exception as e:
+                logger.error(f"Failed to initialize plugin {plugin}: {e}")
+
+    def _cleanup_plugins(self) -> None:
+        """Cleanup all initialized plugins."""
+        for plugin in self._initialized_plugins:
+            try:
+                if hasattr(plugin, 'cleanup'):
+                    plugin.cleanup()
+                    logger.debug(f"Cleaned up plugin: {plugin.__class__.__name__}")
+            except Exception as e:
+                logger.error(f"Error cleaning up plugin {plugin}: {e}")
+        self._initialized_plugins.clear()

growthbook/growthbook_client.py

@@ -10,11 +10,7 @@ import threading
 import traceback
 from datetime import datetime
 from growthbook import FeatureRepository
-try:
-    from contextlib import asynccontextmanager
-except ImportError:
-    # to support python 3.6
-    from async_generator import asynccontextmanager
+from contextlib import asynccontextmanager
 
 from .core import eval_feature as core_eval_feature, run_experiment
 from .common_types import (
@@ -34,7 +30,7 @@ logger = logging.getLogger("growthbook.growthbook_client")
 
 class SingletonMeta(type):
     """Thread-safe implementation of Singleton pattern"""
-    _instances = {}
+    _instances: Dict[type, Any] = {}
     _lock = threading.Lock()
 
     def __call__(cls, *args, **kwargs):
@@ -113,11 +109,11 @@ class EnhancedFeatureRepository(FeatureRepository, metaclass=SingletonMeta):
         self._decryption_key = decryption_key
         self._cache_ttl = cache_ttl
         self._refresh_lock = threading.Lock()
-        self._refresh_task = None
+        self._refresh_task: Optional[asyncio.Task] = None
         self._stop_event = asyncio.Event()
         self._backoff = BackoffStrategy()
         self._feature_cache = FeatureCache()
-        self._callbacks = []
+        self._callbacks: List[Callable[[Dict[str, Any]], Awaitable[None]]] = []
         self._last_successful_refresh = None
         self._refresh_in_progress = asyncio.Lock()
 
@@ -161,13 +157,13 @@ class EnhancedFeatureRepository(FeatureRepository, metaclass=SingletonMeta):
             except Exception:
                 traceback.print_exc()
 
-    def add_callback(self, callback: Callable) -> None:
+    def add_callback(self, callback: Callable[[Dict[str, Any]], Awaitable[None]]) -> None:
         """Add callback to the list"""
         with self._refresh_lock:
             if callback not in self._callbacks:
                 self._callbacks.append(callback)
 
-    def remove_callback(self, callback: Callable) -> None:
+    def remove_callback(self, callback: Callable[[Dict[str, Any]], Awaitable[None]]) -> None:
         """Remove callback from the list"""
         with self._refresh_lock:
             if callback in self._callbacks:
@@ -185,7 +181,8 @@ class EnhancedFeatureRepository(FeatureRepository, metaclass=SingletonMeta):
                         response = await self.load_features_async(
                             self._api_host, self._client_key, self._decryption_key, self._cache_ttl
                         )
-                        await self._handle_feature_update(response)
+                        if response is not None:
+                            await self._handle_feature_update(response)
                     elif event_data['type'] == 'features':
                         await self._handle_feature_update(event_data['data'])
                 except Exception:
@@ -224,7 +221,8 @@ class EnhancedFeatureRepository(FeatureRepository, metaclass=SingletonMeta):
                                     decryption_key=self._decryption_key,
                                     ttl=self._cache_ttl
                                 )
-                                await self._handle_feature_update(response)
+                                if response is not None:
+                                    await self._handle_feature_update(response)
                                 # On success, reset backoff and use normal interval
                                 self._backoff.reset()
                                 try:
@@ -313,21 +311,27 @@ class GrowthBookClient:
         self._subscriptions_lock = threading.Lock()
 
         # Add sticky bucket cache
-        self._sticky_bucket_cache = {
+        self._sticky_bucket_cache: Dict[str, Dict[str, Any]] = {
             'attributes': {},
             'assignments': {}
         }
         self._sticky_bucket_cache_lock = False
         
         self._features_repository = (
-            EnhancedFeatureRepository(self.options.api_host, self.options.client_key, self.options.decryption_key)
+            EnhancedFeatureRepository(
+                self.options.api_host or "https://cdn.growthbook.io", 
+                self.options.client_key or "", 
+                self.options.decryption_key or "", 
+                self.options.cache_ttl
+            )
             if self.options.client_key
             else None
         )
         
-        self._global_context = None
+        self._global_context: Optional[GlobalContext] = None
         self._context_lock = asyncio.Lock()
 
+
     def _track(self, experiment: Experiment, result: Result) -> None:
         """Thread-safe tracking implementation"""
         if not self.options.on_experiment_viewed:
@@ -369,6 +373,11 @@ class GrowthBookClient:
             except Exception:
                 logger.exception("Error in subscription callback")
 
+
+    async def set_features(self, features: dict) -> None:
+        await self._feature_update_callback({"features": features})
+        
+    
     async def _refresh_sticky_buckets(self, attributes: Dict[str, Any]) -> Dict[str, Any]:
         """Refresh sticky bucket assignments only if attributes have changed"""
         if not self.options.sticky_bucket_service:
@@ -387,6 +396,9 @@ class GrowthBookClient:
                 return assignments
             finally:
                 self._sticky_bucket_cache_lock = False
+        
+        # Fallback return for edge case where loop condition is never satisfied
+        return {}
 
     async def initialize(self) -> bool:
         """Initialize client with features and start refresh"""
@@ -397,7 +409,10 @@ class GrowthBookClient:
         try:
             # Initial feature load
             initial_features = await self._features_repository.load_features_async(
-                self.options.api_host, self.options.client_key, self.options.decryption_key, self.options.cache_ttl
+                self.options.api_host or "https://cdn.growthbook.io", 
+                self.options.client_key or "", 
+                self.options.decryption_key or "", 
+                self.options.cache_ttl
             )
             if not initial_features:
                 logger.error("Failed to load initial features")
@@ -410,7 +425,8 @@ class GrowthBookClient:
             self._features_repository.add_callback(self._feature_update_callback)
             
             # Start feature refresh
-            await self._features_repository.start_feature_refresh(self.options.refresh_strategy)
+            refresh_strategy = self.options.refresh_strategy or FeatureRefreshStrategy.STALE_WHILE_REVALIDATE
+            await self._features_repository.start_feature_refresh(refresh_strategy)
             return True
             
         except Exception as e:

growthbook/plugins/__init__.py

@@ -0,0 +1,16 @@
+from .base import GrowthBookPlugin
+# from .auto_attributes import auto_attributes_plugin, AutoAttributesPlugin
+from .growthbook_tracking import growthbook_tracking_plugin, GrowthBookTrackingPlugin
+from .request_context import request_context_plugin, client_side_attributes, RequestContextPlugin, ClientSideAttributes
+
+__all__ = [
+    'GrowthBookPlugin',
+    # 'auto_attributes_plugin', 
+    # 'AutoAttributesPlugin',
+    'growthbook_tracking_plugin',
+    'GrowthBookTrackingPlugin',
+    'request_context_plugin',
+    'client_side_attributes',
+    'RequestContextPlugin', 
+    'ClientSideAttributes',
+] 

growthbook/plugins/base.py

@@ -0,0 +1,103 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class GrowthBookPlugin(ABC):
+    """
+    Base class for all GrowthBook plugins.
+    
+    Plugins extend GrowthBook functionality by adding auto-attributes,
+    tracking capabilities, or other enhancements.
+    
+    Lifecycle:
+    1. Plugin is instantiated with configuration options
+    2. initialize(gb_instance) is called when GrowthBook is created
+    3. Plugin enhances GrowthBook functionality
+    4. cleanup() is called when GrowthBook.destroy() is called
+    """
+    
+    def __init__(self, **options):
+        """Initialize plugin with configuration options."""
+        self.options = options
+        self._initialized = False
+        self._gb_instance = None
+        self.logger = logging.getLogger(f"{self.__class__.__module__}.{self.__class__.__name__}")
+    
+    @abstractmethod
+    def initialize(self, gb_instance) -> None:
+        """
+        Initialize the plugin with a GrowthBook instance.
+        
+        This method is called automatically when the GrowthBook instance
+        is created. Use this to set up the plugin functionality.
+        
+        Args:
+            gb_instance: The GrowthBook instance to enhance
+        """
+        pass
+    
+    def cleanup(self) -> None:
+        """
+        Cleanup plugin resources when GrowthBook instance is destroyed.
+        
+        Override this method if your plugin needs to:
+        - Close network connections
+        - Cancel timers/threads
+        - Flush pending data
+        - Release resources
+        
+        Default implementation does nothing.
+        """
+        self.logger.debug(f"Cleaning up plugin {self.__class__.__name__}")
+        self._gb_instance = None
+    
+    def is_initialized(self) -> bool:
+        """Check if plugin has been initialized."""
+        return self._initialized
+    
+    def _set_initialized(self, gb_instance) -> None:
+        """Mark plugin as initialized and store GrowthBook reference."""
+        self._initialized = True
+        self._gb_instance = gb_instance
+        self.logger.debug(f"Plugin {self.__class__.__name__} initialized successfully")
+    
+    def _get_option(self, key: str, default: Any = None) -> Any:
+        """Get a configuration option with optional default."""
+        return self.options.get(key, default)
+    
+    def _merge_attributes(self, new_attributes: Dict[str, Any]) -> None:
+        """
+        Helper method to merge new attributes with existing ones.
+        
+        Args:
+            new_attributes: Dictionary of attributes to add/update
+        """
+        if not self._gb_instance:
+            self.logger.warning("Cannot merge attributes - plugin not initialized")
+            return
+        
+        current_attributes = self._gb_instance.get_attributes()
+        merged_attributes = {**new_attributes, **current_attributes}  # Existing attrs take precedence
+        self._gb_instance.set_attributes(merged_attributes)
+        
+        self.logger.debug(f"Merged {len(new_attributes)} attributes: {list(new_attributes.keys())}")
+    
+    def _safe_execute(self, func, *args, **kwargs):
+        """
+        Safely execute a function, logging any exceptions.
+        
+        Args:
+            func: Function to execute
+            *args, **kwargs: Arguments to pass to function
+            
+        Returns:
+            Function result or None if exception occurred
+        """
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            self.logger.error(f"Error in {func.__name__}: {e}")
+            return None 

growthbook/plugins/growthbook_tracking.py

@@ -0,0 +1,262 @@
+import json
+import logging
+import threading
+import time
+from typing import Dict, Any, Optional, List, Callable
+from .base import GrowthBookPlugin
+
+requests: Any = None
+try:
+    import requests
+except ImportError:
+    pass
+
+logger = logging.getLogger("growthbook.plugins.growthbook_tracking")
+
+
+class GrowthBookTrackingPlugin(GrowthBookPlugin):
+    """
+    GrowthBook tracking plugin for Built-in Warehouse.
+    
+    This plugin automatically tracks "Experiment Viewed" and "Feature Evaluated" 
+    events to GrowthBook's built-in data warehouse.
+    """
+    
+    def __init__(
+        self,
+        ingestor_host: str,
+        track_experiment_viewed: bool = True,
+        track_feature_evaluated: bool = True,
+        batch_size: int = 10,
+        batch_timeout: float = 10.0,
+        additional_callback: Optional[Callable] = None,
+        **options
+    ):
+        """
+        Initialize GrowthBook tracking plugin.
+        
+        Args:
+            ingestor_host: The GrowthBook ingestor endpoint
+            track_experiment_viewed: Whether to track experiment viewed events
+            track_feature_evaluated: Whether to track feature evaluated events
+            batch_size: Number of events to batch before sending
+            batch_timeout: Maximum time (seconds) to wait before sending a batch
+            additional_callback: Optional additional tracking callback
+        """
+        super().__init__(**options)
+        
+        if not requests:
+            raise ImportError("requests library is required for GrowthBookTrackingPlugin. Install with: pip install requests")
+        
+        self.ingestor_host = ingestor_host.rstrip('/')
+        self.track_experiment_viewed = track_experiment_viewed
+        self.track_feature_evaluated = track_feature_evaluated
+        self.batch_size = batch_size
+        self.batch_timeout = batch_timeout
+        self.additional_callback = additional_callback
+        
+        # batching
+        self._event_batch: List[Dict[str, Any]] = []
+        self._batch_lock = threading.Lock()
+        self._flush_timer: Optional[threading.Timer] = None
+        self._client_key: Optional[str] = None
+        
+    def initialize(self, gb_instance) -> None:
+        """Initialize plugin with GrowthBook instance."""
+        try:
+            self._client_key = getattr(gb_instance, '_client_key', '')
+            
+            # Hook into experiment tracking
+            if self.track_experiment_viewed:
+                self._setup_experiment_tracking(gb_instance)
+            
+            # Hook into feature evaluation
+            if self.track_feature_evaluated:
+                self._setup_feature_tracking(gb_instance)
+            
+            self._set_initialized(gb_instance)
+            self.logger.info(f"Tracking enabled for {self.ingestor_host}")
+            
+        except Exception as e:
+            self.logger.error(f"Failed to initialize tracking plugin: {e}")
+    
+    def cleanup(self) -> None:
+        """Cleanup plugin resources."""
+        self._flush_events()
+        if self._flush_timer:
+            self._flush_timer.cancel()
+        super().cleanup()
+    
+    def _setup_experiment_tracking(self, gb_instance) -> None:
+        """Setup experiment tracking."""
+        original_callback = getattr(gb_instance, '_trackingCallback', None)
+        
+        def tracking_wrapper(experiment, result):
+            # Track to ingestor
+            self._track_experiment_viewed(experiment, result)
+            
+            # Call additional callback
+            if self.additional_callback:
+                self._safe_execute(self.additional_callback, experiment, result)
+            
+            # Call original callback
+            if original_callback:
+                self._safe_execute(original_callback, experiment, result)
+        
+        gb_instance._trackingCallback = tracking_wrapper
+    
+    def _setup_feature_tracking(self, gb_instance):
+        """Setup feature evaluation tracking."""
+        original_eval_feature = gb_instance.eval_feature
+        
+        def eval_feature_wrapper(key: str):
+            result = original_eval_feature(key)
+            self._track_feature_evaluated(key, result, gb_instance)
+            return result
+        
+        gb_instance.eval_feature = eval_feature_wrapper
+    
+    def _track_experiment_viewed(self, experiment, result) -> None:
+        """Track experiment viewed event."""
+        try:
+            # Build event data with all metadata
+            event_data = {
+                'event_type': 'experiment_viewed',
+                'timestamp': int(time.time() * 1000),
+                'client_key': self._client_key,
+                'sdk_language': 'python',
+                'sdk_version': self._get_sdk_version(),
+                # Core experiment data
+                'experiment_id': experiment.key,
+                'variation_id': result.variationId,
+                'variation_key': getattr(result, 'key', str(result.variationId)),
+                'variation_value': result.value,
+                'in_experiment': result.inExperiment,
+                'hash_used': result.hashUsed,
+                'hash_attribute': result.hashAttribute,
+                'hash_value': result.hashValue,
+            }
+            
+            # Add optional metadata if available
+            if hasattr(experiment, 'name') and experiment.name:
+                event_data['experiment_name'] = experiment.name
+            if hasattr(result, 'featureId') and result.featureId:
+                event_data['feature_id'] = result.featureId
+            
+            self._add_event_to_batch(event_data)
+            
+        except Exception as e:
+            self.logger.error(f"Error tracking experiment: {e}")
+    
+    def _track_feature_evaluated(self, feature_key: str, result, gb_instance) -> None:
+        """Track feature evaluated event."""
+        try:
+            # Build event data with all metadata
+            event_data = {
+                'event_type': 'feature_evaluated',
+                'timestamp': int(time.time() * 1000),
+                'client_key': self._client_key,
+                'sdk_language': 'python',
+                'sdk_version': self._get_sdk_version(),
+                # Core feature data
+                'feature_key': feature_key,
+                'feature_value': result.value,
+                'source': result.source,
+                'on': getattr(result, 'on', bool(result.value)),
+                'off': getattr(result, 'off', not bool(result.value)),
+            }
+            
+            # Add optional metadata if available
+            if hasattr(result, 'ruleId') and result.ruleId:
+                event_data['rule_id'] = result.ruleId
+            
+            # Add experiment info if feature came from experiment
+            if hasattr(result, 'experiment') and result.experiment:
+                event_data['experiment_id'] = result.experiment.key
+                if hasattr(result, 'experimentResult') and result.experimentResult:
+                    event_data['variation_id'] = result.experimentResult.variationId
+                    event_data['in_experiment'] = result.experimentResult.inExperiment
+            
+            self._add_event_to_batch(event_data)
+            
+        except Exception as e:
+            self.logger.error(f"Error tracking feature: {e}")
+    
+    def _add_event_to_batch(self, event_data: Dict[str, Any]) -> None:
+        with self._batch_lock:
+            self._event_batch.append(event_data)
+            
+            # Flush if batch is full
+            if len(self._event_batch) >= self.batch_size:
+                self._flush_batch_locked()
+            elif len(self._event_batch) == 1:
+                # Start timer for first event
+                self._start_flush_timer()
+    
+    def _start_flush_timer(self) -> None:
+        """Start flush timer."""
+        if self._flush_timer:
+            self._flush_timer.cancel()
+        
+        self._flush_timer = threading.Timer(self.batch_timeout, self._flush_events)
+        self._flush_timer.start()
+    
+    def _flush_events(self) -> None:
+        """Flush events with lock."""
+        with self._batch_lock:
+            self._flush_batch_locked()
+    
+    def _flush_batch_locked(self) -> None:
+        """Flush current batch (called while holding lock)."""
+        if not self._event_batch:
+            return
+        
+        events_to_send = self._event_batch.copy()
+        self._event_batch.clear()
+        
+        if self._flush_timer:
+            self._flush_timer.cancel()
+            self._flush_timer = None
+        
+        # Send in background thread
+        threading.Thread(target=self._send_events, args=(events_to_send,), daemon=True).start()
+    
+    def _send_events(self, events: List[Dict[str, Any]]) -> None:
+        """Send events using requests library."""
+        if not events:
+            return
+        
+        try:
+            payload = {
+                'events': events,
+                'client_key': self._client_key
+            }
+            
+            url = f"{self.ingestor_host}/events"
+            response = requests.post(
+                url,
+                json=payload,
+                headers={'User-Agent': f'growthbook-python-sdk/{self._get_sdk_version()}'},
+                timeout=30
+            )
+            
+            if response.status_code == 200:
+                self.logger.debug(f"Successfully sent {len(events)} events")
+            else:
+                self.logger.warning(f"Ingestor returned status {response.status_code}")
+                
+        except Exception as e:
+            self.logger.error(f"Failed to send events: {e}")
+    
+    def _get_sdk_version(self) -> str:
+        """Get SDK version."""
+        try:
+            import growthbook
+            return getattr(growthbook, '__version__', 'unknown')
+        except:
+            return 'unknown'
+
+
+def growthbook_tracking_plugin(**options) -> GrowthBookTrackingPlugin:
+    """Create a GrowthBook tracking plugin."""
+    return GrowthBookTrackingPlugin(**options) 

growthbook/plugins/request_context.py

@@ -0,0 +1,341 @@
+"""
+Request Context Plugin for GrowthBook Python SDK
+
+This plugin extracts attributes from HTTP request context using a framework-agnostic approach.
+"""
+
+import logging
+import uuid
+import time
+from typing import Dict, Any, Optional, Callable, Union
+from urllib.parse import urlparse
+from .base import GrowthBookPlugin
+
+logger = logging.getLogger("growthbook.plugins.request_context")
+
+# Global context variable for storing current request
+_current_request_context: Dict[str, Any] = {}
+
+
+class ClientSideAttributes:
+    """
+    Client-side attributes that can't be detected server-side.
+    """
+    
+    def __init__(self, **attributes: Any):
+        """
+        Initialize with any client-side attributes.
+        
+        Common attributes:
+            pageTitle: Current page title
+            deviceType: "mobile" | "desktop" | "tablet"  
+            browser: "chrome" | "firefox" | "safari" | "edge"
+            timezone: User's timezone (e.g., "America/New_York")
+            language: User's language (e.g., "en-US")
+        
+        Args:
+            **attributes: Any client-side attributes as key-value pairs
+        """
+        for key, value in attributes.items():
+            if value is not None:
+                setattr(self, key, value)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {k: v for k, v in self.__dict__.items() if v is not None}
+
+
+class RequestContextPlugin(GrowthBookPlugin):
+    """
+    Framework-agnostic request context plugin.
+    
+    This plugin uses:
+    1. Manual request object passing via set_request_context()
+    2. Context variables set by middleware
+    3. Direct attribute extraction from provided data
+    """
+    
+    def __init__(
+        self,
+        request_extractor: Optional[Callable] = None,
+        client_side_attributes: Optional[ClientSideAttributes] = None,
+        extract_utm: bool = True,
+        extract_user_agent: bool = True,
+        **options
+    ):
+        """
+        Initialize request context plugin.
+        
+        Args:
+            request_extractor: Optional function to extract request object from context
+            client_side_attributes: Manual client-side attributes
+            extract_utm: Whether to extract UTM parameters
+            extract_user_agent: Whether to parse User-Agent header
+        """
+        super().__init__(**options)
+        self.request_extractor = request_extractor
+        self.client_side_attributes = client_side_attributes
+        self.extract_utm = extract_utm
+        self.extract_user_agent = extract_user_agent
+        
+    def initialize(self, gb_instance) -> None:
+        """Initialize plugin - extract attributes from request context."""
+        try:
+            self._set_initialized(gb_instance)
+            
+            # Get request data from various sources
+            request_attributes = self._extract_all_attributes()
+            
+            if request_attributes:
+                # Merge with existing attributes (existing take precedence)
+                current_attributes = gb_instance.get_attributes()
+                merged_attributes = {**request_attributes, **current_attributes}
+                gb_instance.set_attributes(merged_attributes)
+                
+                self.logger.info(f"Extracted {len(request_attributes)} request attributes")
+            else:
+                self.logger.debug("No request context available")
+                
+        except Exception as e:
+            self.logger.error(f"Failed to extract request attributes: {e}")
+    
+    def _extract_all_attributes(self) -> Dict[str, Any]:
+        """Extract all available attributes from request context."""
+        attributes = {}
+        
+        # Get request object/data
+        request_data = self._get_request_data()
+        
+        if request_data:
+            # Extract core request info
+            attributes.update(self._extract_basic_info(request_data))
+            
+            # Extract UTM parameters
+            if self.extract_utm:
+                attributes.update(self._extract_utm_params(request_data))
+            
+            # Extract User-Agent info
+            if self.extract_user_agent:
+                attributes.update(self._extract_user_agent(request_data))
+        
+        # Add client-side attributes (these override auto-detected)
+        if self.client_side_attributes:
+            attributes.update(self.client_side_attributes.to_dict())
+        
+        # Add server context
+        attributes.update({
+            'server_timestamp': int(time.time()),
+            'request_id': str(uuid.uuid4())[:8],
+            'sdk_context': 'server'
+        })
+        
+        return attributes
+    
+    def _get_request_data(self) -> Optional[Dict[str, Any]]:
+        """Get request data from various sources."""
+        # 1. Try custom extractor
+        if self.request_extractor:
+            try:
+                request_obj = self.request_extractor()
+                if request_obj:
+                    return self._normalize_request_object(request_obj)
+            except Exception as e:
+                self.logger.debug(f"Custom extractor failed: {e}")
+        
+        # 2. Try global context
+        if _current_request_context:
+            return _current_request_context.copy()
+        
+        # 3. Try thread-local storage
+        import threading
+        thread_local = getattr(threading.current_thread(), 'gb_request_context', None)
+        if thread_local:
+            return thread_local
+        
+        return None
+    
+    def _normalize_request_object(self, request_obj) -> Dict[str, Any]:
+        """Convert various request objects to normalized dict."""
+        normalized = {}
+        
+        try:
+            # Extract URL
+            url = None
+            if hasattr(request_obj, 'build_absolute_uri'):  # Django
+                url = request_obj.build_absolute_uri()
+            elif hasattr(request_obj, 'url'):  # Flask/FastAPI
+                url = str(request_obj.url)
+            
+            if url:
+                normalized['url'] = url
+                parsed = urlparse(url)
+                normalized['path'] = parsed.path
+                normalized['host'] = parsed.netloc
+                normalized['query_string'] = parsed.query
+            
+            # Extract query parameters
+            query_params = {}
+            if hasattr(request_obj, 'GET'):  # Django
+                query_params = dict(request_obj.GET)
+            elif hasattr(request_obj, 'args'):  # Flask
+                query_params = dict(request_obj.args)
+            elif hasattr(request_obj, 'query_params'):  # FastAPI
+                query_params = dict(request_obj.query_params)
+            
+            normalized['query_params'] = query_params
+            
+            # Extract User-Agent
+            user_agent = None
+            if hasattr(request_obj, 'META'):  # Django
+                user_agent = request_obj.META.get('HTTP_USER_AGENT')
+            elif hasattr(request_obj, 'headers'):  # Flask/FastAPI
+                user_agent = request_obj.headers.get('user-agent') or request_obj.headers.get('User-Agent')
+            
+            if user_agent:
+                normalized['user_agent'] = user_agent
+            
+            # Extract user info (if available)
+            if hasattr(request_obj, 'user') and hasattr(request_obj.user, 'id'):
+                if getattr(request_obj.user, 'is_authenticated', True):
+                    normalized['user_id'] = str(request_obj.user.id)
+            
+        except Exception as e:
+            self.logger.debug(f"Error normalizing request object: {e}")
+        
+        return normalized
+    
+    def _extract_basic_info(self, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract basic request information."""
+        info = {}
+        
+        if 'url' in request_data:
+            info['url'] = request_data['url']
+        if 'path' in request_data:
+            info['path'] = request_data['path'] 
+        if 'host' in request_data:
+            info['host'] = request_data['host']
+        if 'user_id' in request_data:
+            info['id'] = request_data['user_id']
+            
+        return info
+    
+    def _extract_utm_params(self, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract UTM parameters from query string."""
+        utm_params = {}
+        query_params = request_data.get('query_params', {})
+        
+        utm_mappings = {
+            'utm_source': 'utmSource',
+            'utm_medium': 'utmMedium', 
+            'utm_campaign': 'utmCampaign',
+            'utm_term': 'utmTerm',
+            'utm_content': 'utmContent'
+        }
+        
+        for param, attr_name in utm_mappings.items():
+            value = query_params.get(param)
+            if value:
+                utm_params[attr_name] = value
+                
+        return utm_params
+    
+    def _extract_user_agent(self, request_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract browser and device info from User-Agent."""
+        user_agent = request_data.get('user_agent')
+        if not user_agent:
+            return {}
+        
+        ua_lower = user_agent.lower()
+        info = {'userAgent': user_agent}
+        
+        # Simple browser detection
+        if 'edge' in ua_lower or 'edg' in ua_lower:
+            info['browser'] = 'edge'
+        elif 'chrome' in ua_lower:
+            info['browser'] = 'chrome'
+        elif 'firefox' in ua_lower:
+            info['browser'] = 'firefox'
+        elif 'safari' in ua_lower:
+            info['browser'] = 'safari'
+        else:
+            info['browser'] = 'unknown'
+        
+        # Simple device detection
+        mobile_indicators = ['mobile', 'android', 'iphone', 'ipad']
+        if any(indicator in ua_lower for indicator in mobile_indicators):
+            info['deviceType'] = 'mobile'
+        else:
+            info['deviceType'] = 'desktop'
+        
+        return info
+
+
+# Framework-agnostic helper functions
+def set_request_context(request_data: Union[Dict[str, Any], Any]) -> None:
+    """
+    Set request context globally for the current thread.
+    
+    Args:
+        request_data: Either a dict of request data or a request object to normalize
+    """
+    global _current_request_context
+    
+    if isinstance(request_data, dict):
+        _current_request_context = request_data
+    else:
+        # Try to normalize request object
+        plugin = RequestContextPlugin()
+        _current_request_context = plugin._normalize_request_object(request_data)
+
+
+def clear_request_context() -> None:
+    """Clear the global request context."""
+    global _current_request_context
+    _current_request_context = {}
+
+
+# Convenience functions
+def request_context_plugin(**options) -> RequestContextPlugin:
+    """
+    Create a request context plugin.
+    
+    Usage examples:
+    
+    # 1. With middleware setting global context:
+    set_request_context(request)
+    gb = GrowthBook(plugins=[request_context_plugin()])
+    
+    # 2. With custom extractor:
+    def get_current_request():
+        return my_framework.get_current_request()
+    
+    gb = GrowthBook(plugins=[
+        request_context_plugin(request_extractor=get_current_request)
+    ])
+    
+    # 3. With client-side attributes:
+    gb = GrowthBook(plugins=[
+        request_context_plugin(
+            client_side_attributes=client_side_attributes(
+                pageTitle="Dashboard",
+                deviceType="mobile"
+            )
+        )
+    ])
+    """
+    return RequestContextPlugin(**options)
+
+
+def client_side_attributes(**kwargs) -> ClientSideAttributes:
+    """
+    Create client-side attributes.
+    
+    Usage:
+        attrs = client_side_attributes(
+            pageTitle="My Page",
+            deviceType="mobile", 
+            browser="chrome",
+            customField="value"
+        )
+    """
+    return ClientSideAttributes(**kwargs)

{growthbook-1.2.1.dist-info → growthbook-1.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: growthbook
-Version: 1.2.1
+Version: 1.3.1
 Summary: Powerful Feature flagging and A/B testing for Python apps
 Home-page: https://github.com/growthbook/growthbook-python
 Author: GrowthBook
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.6
+Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: cryptography
@@ -30,22 +30,27 @@ Requires-Dist: aiohttp>=3.6.0
 Requires-Dist: importlib-metadata; python_version < "3.8"
 Dynamic: author
 Dynamic: home-page
+Dynamic: license-file
 Dynamic: requires-python
 
 # GrowthBook Python SDK
 
-Powerful Feature flagging and A/B testing for Python apps.
-
 ![Build Status](https://github.com/growthbook/growthbook-python/workflows/Build/badge.svg)
+[![PyPI](https://img.shields.io/pypi/v/growthbook.svg?maxAge=2592000)](https://pypi.org/project/growthbook/)
+[![PyPI](https://img.shields.io/pypi/pyversions/growthbook.svg)](https://pypi.org/project/growthbook/)
+
+## Overview
+
+Powerful Feature flagging and A/B testing for Python apps.
 
 - **Lightweight and fast**
 - **Local evaluation**, no network requests required
-- Python 3.6+
-- 100% test coverage
 - Flexible **targeting**
 - **Use your existing event tracking** (GA, Segment, Mixpanel, custom)
 - **Remote configuration** to change feature flags without deploying new code
 - **Async support** with real-time feature updates
+- Python 3.6+
+- 100% test coverage
 
 ## Installation
 
@@ -410,6 +415,33 @@ gb = GrowthBook(
 )
 ```
 
+#### Built-in Tracking Plugin
+
+For easier setup, you can use the built-in tracking plugin that automatically sends experiment and feature events to GrowthBook's data warehouse:
+
+```python
+from growthbook import GrowthBook
+from growthbook.plugins import growthbook_tracking_plugin, request_context_plugin
+
+gb = GrowthBook(
+  attributes={"id": "user-123"},
+  plugins=[
+    request_context_plugin(),  # Extracts request data
+    growthbook_tracking_plugin(
+      ingestor_host="https://gb-ingest.growthbook.io",
+      # Optional: Add custom tracking callback
+      additional_callback=my_custom_tracker
+    )
+  ]
+)
+
+# Events are now automatically tracked for experiments and features
+result = gb.run(experiment)  # -> Tracked automatically
+is_enabled = gb.is_on("my-feature")  # -> Tracked automatically
+```
+
+The tracking plugin provides batching, error handling, and works alongside your existing tracking callbacks. See the [plugin documentation](https://docs.growthbook.io/lib/python#tracking-plugins) for more details.
+
 ## Using Features
 
 There are 3 main methods for interacting with features.

growthbook-1.3.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+growthbook/__init__.py,sha256=2pw6uyYKI4IQ59LZbCUsNroy4LLFZ_5XyPmscPUyAwI,444
+growthbook/common_types.py,sha256=1jDWwS_9L0z_AZb5AJq1arEqi6QU66N3S4vYzkcDFDY,14728
+growthbook/core.py,sha256=LCz5f5rchUL056kgJxgH566NoZWr2nr4hhL7MRlyNiM,35184
+growthbook/growthbook.py,sha256=IJmFKTx87zAwQ6nO_Gepm5-S_Mtwf-lnt2RFBviB6Lk,30672
+growthbook/growthbook_client.py,sha256=zLgoBSBCSfCb8OE0b-XQiDAEB4djTiMSrbNpqBui-M0,21454
+growthbook/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+growthbook/plugins/__init__.py,sha256=y2eAV1sA041XWcftBVTDH0t-ggy9r2C5oKRYRF6XR6s,602
+growthbook/plugins/base.py,sha256=PWBXUBj62hi25Y5Eif9WmEWagWdkwGXHi2dMtn44bo8,3637
+growthbook/plugins/growthbook_tracking.py,sha256=aL_dgsPt51IZNxRVZVA5U3QEiGW-e-l5tC7Owl6CZO0,10032
+growthbook/plugins/request_context.py,sha256=7_9LOfS5nXbxXE7KJ-zNT4Ug4-_698A4c3t0hjr6l4c,11895
+growthbook-1.3.1.dist-info/licenses/LICENSE,sha256=D-TcBckB0dTPUlNJ8jBiTIJIj1ekHLB1CY7HJtJKhMY,1069
+growthbook-1.3.1.dist-info/METADATA,sha256=FwTzARVgHtfSH2ZnCWVq0G9k5ISiPyQDIeYjabR3vCQ,22073
+growthbook-1.3.1.dist-info/WHEEL,sha256=JNWh1Fm1UdwIQV075glCn4MVuCRs0sotJIq-J6rbxCU,109
+growthbook-1.3.1.dist-info/top_level.txt,sha256=dzfRQFGYejCIUstRSrrRVTMlxf7pBqASTI5S8gGRlXw,11
+growthbook-1.3.1.dist-info/RECORD,,

{growthbook-1.2.1.dist-info → growthbook-1.3.1.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.2)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py2-none-any
 Tag: py3-none-any

growthbook-1.2.1.dist-info/RECORD

@@ -1,11 +0,0 @@
-growthbook/__init__.py,sha256=j7q2Y9SF-g2sZKxpqKeyFeRDIxWv_JlBeWmb3NUaOs0,25
-growthbook/common_types.py,sha256=PmZ6fmje0Tvr2rTxUU1pYkyGr-M4CKRnZhJbf9fKSr0,14752
-growthbook/core.py,sha256=kcr5wZ6yWdiHjss408qteqio3NHFMh1sk2JNR4S0OrE,34847
-growthbook/growthbook.py,sha256=mFdURTSTMjcQrl1FkrXGr6SFdXdErQNyIttpcuHlL9E,26360
-growthbook/growthbook_client.py,sha256=KNBL_TQUySl1ZCbYcB2xL_0p2ZTGhUKtjFXW2odSOhU,20647
-growthbook/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-growthbook-1.2.1.dist-info/LICENSE,sha256=D-TcBckB0dTPUlNJ8jBiTIJIj1ekHLB1CY7HJtJKhMY,1069
-growthbook-1.2.1.dist-info/METADATA,sha256=QIaobsseMytueEdiMZXDvDCBnBMGeIbVo_i6D1VYS6A,20805
-growthbook-1.2.1.dist-info/WHEEL,sha256=rF4EZyR2XVS6irmOHQIJx2SUqXLZKRMUrjsg8UwN-XQ,109
-growthbook-1.2.1.dist-info/top_level.txt,sha256=dzfRQFGYejCIUstRSrrRVTMlxf7pBqASTI5S8gGRlXw,11
-growthbook-1.2.1.dist-info/RECORD,,