fixup: remove lazy imports, shims, add check

Signed-off-by: Todd Baert <todd.baert@dynatrace.com>

Author: toddbaert

MIGRATION.md

@@ -0,0 +1,39 @@
+# Migration Guide
+
+## Unreleased
+
+### Import changes
+
+Several module-level convenience functions moved to `openfeature.api`. Function signatures are unchanged; update imports only.
+
+- Instead of `from openfeature.evaluation_context import get_evaluation_context`, use `from openfeature.api import get_evaluation_context`.
+- Instead of `from openfeature.hook import add_hooks`, use `from openfeature.api import add_hooks`.
+- Instead of `from openfeature.transaction_context import set_transaction_context_propagator`, use `from openfeature.api import set_transaction_context_propagator`.
+- Instead of `from openfeature.transaction_context import NoOpTransactionContextPropagator`, use `from openfeature.transaction_context.no_op_transaction_context_propagator import NoOpTransactionContextPropagator`.
+
+Type imports (`EvaluationContext`, `Hook`, `HookContext`, `HookData`, `HookHints`, `HookType`, `ContextVarsTransactionContextPropagator`, `TransactionContextPropagator`) are unchanged.
+
+### Constructor change: `OpenFeatureClient`
+
+`OpenFeatureClient.__init__` now requires the owning `OpenFeatureAPI` (3rd positional or `api=` keyword).
+
+Prefer the factory:
+
+```python
+from openfeature import api
+
+client = api.get_client()
+client = api.get_client(domain="my-domain")
+```
+
+For direct construction, pass `api`:
+
+```python
+# Before
+client = OpenFeatureClient("my-domain", None)
+client = OpenFeatureClient("my-domain", None, context=ctx)
+
+# After
+client = OpenFeatureClient("my-domain", None, api=my_api)
+client = OpenFeatureClient("my-domain", None, my_api, context=ctx)
+```

openfeature/_api.py

@@ -1,29 +1,25 @@
 from __future__ import annotations
 
-import typing
-
 from openfeature._event_support import EventSupport
+from openfeature.client import OpenFeatureClient
 from openfeature.evaluation_context import EvaluationContext
 from openfeature.event import EventHandler, ProviderEvent
 from openfeature.exception import GeneralError
 from openfeature.hook import Hook
 from openfeature.provider import FeatureProvider, ProviderStatus
 from openfeature.provider._registry import ProviderRegistry
 from openfeature.provider.metadata import Metadata
-from openfeature.transaction_context import (
+from openfeature.transaction_context import TransactionContextPropagator
+from openfeature.transaction_context.no_op_transaction_context_propagator import (
     NoOpTransactionContextPropagator,
-    TransactionContextPropagator,
 )
 
-if typing.TYPE_CHECKING:
-    from openfeature.client import OpenFeatureClient
-
 
 class OpenFeatureAPI:
     """An independent OpenFeature API instance with its own isolated state.
 
     Each instance maintains its own providers, evaluation context, hooks,
-    event handlers, and transaction context propagator — fully separate from
+    event handlers, and transaction context propagator; fully separate from
     the global singleton and from other instances.
     """
 
@@ -44,8 +40,6 @@ def __init__(self) -> None:
     def get_client(
         self, domain: str | None = None, version: str | None = None
     ) -> OpenFeatureClient:
-        from openfeature.client import OpenFeatureClient  # noqa: PLC0415
-
         return OpenFeatureClient(domain=domain, version=version, api=self)
 
     # --- Provider management ---
@@ -132,28 +126,4 @@ def remove_handler(self, event: ProviderEvent, handler: EventHandler) -> None:
         self._event_support.remove_global_handler(event, handler)
 
 
-def _create_default_api() -> OpenFeatureAPI:
-    """Create the default global API instance, wired to legacy module-level singletons.
-
-    The default API reuses the module-level ``_default_event_support`` and
-    ``provider_registry`` so that backward-compatible module-level functions
-    continue to work against the same state.
-    """
-    from openfeature._event_support import _default_event_support  # noqa: PLC0415
-    from openfeature.provider._registry import provider_registry  # noqa: PLC0415
-
-    api = OpenFeatureAPI.__new__(OpenFeatureAPI)
-    api._hooks = []
-    api._evaluation_context = EvaluationContext()
-    api._transaction_context_propagator = NoOpTransactionContextPropagator()
-    api._event_support = _default_event_support
-    api._provider_registry = provider_registry
-
-    # Wire the registry to this API's event support and context getter
-    provider_registry._event_support = _default_event_support
-    provider_registry._evaluation_context_getter = api.get_evaluation_context
-
-    return api
-
-
-_default_api = _create_default_api()
+_default_api = OpenFeatureAPI()

openfeature/_event_support.py

@@ -145,52 +145,3 @@ def clear(self) -> None:
             self._global_handlers.clear()
         with self._client_lock:
             self._client_handlers.clear()
-
-
-# Default instance used by the global singleton API
-_default_event_support = EventSupport()
-
-
-# Backward-compatible module-level functions delegating to the default instance
-def run_client_handlers(
-    client: OpenFeatureClient, event: ProviderEvent, details: EventDetails
-) -> None:
-    _default_event_support.run_client_handlers(client, event, details)
-
-
-def run_global_handlers(event: ProviderEvent, details: EventDetails) -> None:
-    _default_event_support.run_global_handlers(event, details)
-
-
-def add_client_handler(
-    client: OpenFeatureClient, event: ProviderEvent, handler: EventHandler
-) -> None:
-    _default_event_support.add_client_handler(client, event, handler)
-
-
-def remove_client_handler(
-    client: OpenFeatureClient, event: ProviderEvent, handler: EventHandler
-) -> None:
-    _default_event_support.remove_client_handler(client, event, handler)
-
-
-def add_global_handler(event: ProviderEvent, handler: EventHandler) -> None:
-    from openfeature.api import get_client  # noqa: PLC0415
-
-    _default_event_support.add_global_handler(event, handler, get_client)
-
-
-def remove_global_handler(event: ProviderEvent, handler: EventHandler) -> None:
-    _default_event_support.remove_global_handler(event, handler)
-
-
-def run_handlers_for_provider(
-    provider: FeatureProvider,
-    event: ProviderEvent,
-    provider_details: ProviderEventDetails,
-) -> None:
-    _default_event_support.run_handlers_for_provider(provider, event, provider_details)
-
-
-def clear() -> None:
-    _default_event_support.clear()

openfeature/api.py

@@ -1,27 +1,25 @@
 from openfeature._api import _default_api
 from openfeature.client import OpenFeatureClient
-from openfeature.evaluation_context import (
-    get_evaluation_context,
-    set_evaluation_context,
-)
+from openfeature.evaluation_context import EvaluationContext
 from openfeature.event import (
     EventHandler,
     ProviderEvent,
 )
-from openfeature.hook import add_hooks, clear_hooks, get_hooks
+from openfeature.hook import Hook
 from openfeature.provider import FeatureProvider
 from openfeature.provider.metadata import Metadata
-from openfeature.transaction_context import (
-    get_transaction_context,
-    set_transaction_context,
-    set_transaction_context_propagator,
+from openfeature.transaction_context import TransactionContextPropagator
+from openfeature.transaction_context.no_op_transaction_context_propagator import (
+    NoOpTransactionContextPropagator,
 )
 
 __all__ = [
     "add_handler",
     "add_hooks",
+    "clear_evaluation_context",
     "clear_hooks",
     "clear_providers",
+    "clear_transaction_context_propagator",
     "get_client",
     "get_evaluation_context",
     "get_hooks",
@@ -69,3 +67,45 @@ def add_handler(event: ProviderEvent, handler: EventHandler) -> None:
 
 def remove_handler(event: ProviderEvent, handler: EventHandler) -> None:
     _default_api.remove_handler(event, handler)
+
+
+def add_hooks(hooks: list[Hook]) -> None:
+    _default_api.add_hooks(hooks)
+
+
+def clear_hooks() -> None:
+    _default_api.clear_hooks()
+
+
+def get_hooks() -> list[Hook]:
+    return _default_api.get_hooks()
+
+
+def get_evaluation_context() -> EvaluationContext:
+    return _default_api.get_evaluation_context()
+
+
+def set_evaluation_context(evaluation_context: EvaluationContext) -> None:
+    _default_api.set_evaluation_context(evaluation_context)
+
+
+def clear_evaluation_context() -> None:
+    set_evaluation_context(EvaluationContext())
+
+
+def set_transaction_context_propagator(
+    transaction_context_propagator: TransactionContextPropagator,
+) -> None:
+    _default_api.set_transaction_context_propagator(transaction_context_propagator)
+
+
+def clear_transaction_context_propagator() -> None:
+    set_transaction_context_propagator(NoOpTransactionContextPropagator())
+
+
+def get_transaction_context() -> EvaluationContext:
+    return _default_api.get_transaction_context()
+
+
+def set_transaction_context(evaluation_context: EvaluationContext) -> None:
+    _default_api.set_transaction_context(evaluation_context)

openfeature/client.py

@@ -77,24 +77,27 @@ class ClientMetadata:
 
 
 class OpenFeatureClient:
+    """Client for evaluating feature flags against a specific OpenFeatureAPI.
+
+    Clients should be obtained via ``OpenFeatureAPI.get_client()`` (or the
+    module-level ``openfeature.api.get_client()`` for the default API);
+    direct construction is supported only for advanced use cases and requires
+    passing the owning ``OpenFeatureAPI`` instance.
+    """
+
     def __init__(
         self,
         domain: str | None,
         version: str | None,
+        api: OpenFeatureAPI,
         context: EvaluationContext | None = None,
         hooks: list[Hook] | None = None,
-        api: OpenFeatureAPI | None = None,
     ) -> None:
         self.domain = domain
         self.version = version
         self.context = context or EvaluationContext()
         self.hooks = hooks or []
-        if api is not None:
-            self._api = api
-        else:
-            from openfeature._api import _default_api  # noqa: PLC0415
-
-            self._api = _default_api
+        self._api = api
 
     @property
     def provider(self) -> FeatureProvider:

openfeature/evaluation_context/__init__.py

@@ -5,7 +5,7 @@
 from dataclasses import dataclass, field
 from datetime import datetime
 
-__all__ = ["EvaluationContext", "get_evaluation_context", "set_evaluation_context"]
+__all__ = ["EvaluationContext"]
 
 # https://openfeature.dev/specification/sections/evaluation-context#requirement-312
 EvaluationContextAttribute: typing.TypeAlias = (
@@ -32,19 +32,3 @@ def merge(self, ctx2: EvaluationContext) -> EvaluationContext:
         targeting_key = ctx2.targeting_key or self.targeting_key
 
         return EvaluationContext(targeting_key=targeting_key, attributes=attributes)
-
-
-def get_evaluation_context() -> EvaluationContext:
-    from openfeature._api import _default_api  # noqa: PLC0415
-
-    return _default_api.get_evaluation_context()
-
-
-def set_evaluation_context(evaluation_context: EvaluationContext) -> None:
-    from openfeature._api import _default_api  # noqa: PLC0415
-
-    _default_api.set_evaluation_context(evaluation_context)
-
-
-# Kept for backward compatibility but no longer used; state lives in _default_api.
-_evaluation_context = EvaluationContext()

openfeature/hook/__init__.py

@@ -18,9 +18,6 @@
     "HookData",
     "HookHints",
     "HookType",
-    "add_hooks",
-    "clear_hooks",
-    "get_hooks",
 ]
 
 
@@ -147,21 +144,3 @@ def supports_flag_value_type(self, flag_type: FlagType) -> bool:
         or not (False)
         """
         return True
-
-
-def add_hooks(hooks: list[Hook]) -> None:
-    from openfeature._api import _default_api  # noqa: PLC0415
-
-    _default_api.add_hooks(hooks)
-
-
-def clear_hooks() -> None:
-    from openfeature._api import _default_api  # noqa: PLC0415
-
-    _default_api.clear_hooks()
-
-
-def get_hooks() -> list[Hook]:
-    from openfeature._api import _default_api  # noqa: PLC0415
-
-    return _default_api.get_hooks()