omlish 0.0.0.dev484__py3-none-any.whl → 0.0.0.dev493__py3-none-any.whl

omlish/inject/binder.py

@@ -88,7 +88,7 @@ def bind(
         in_: Scope | None = None,
         singleton: bool = False,
 
-        eager: bool = False,
+        eager: bool | int = False,
         expose: bool = False,
 ) -> Element | Elements:
     if obj is None or obj is inspect.Parameter.empty:
@@ -117,7 +117,10 @@ def bind(
     elif _is_fn(obj) and not has_to:
         sig = _inspect.signature(obj)
         ty = rfl.type_(sig.return_annotation)
-        to_fn = obj
+        if inspect.iscoroutinefunction(obj):
+            to_async_fn = obj
+        else:
+            to_fn = obj
         key = Key(ty)
     else:
         if to_const is not None:
@@ -180,8 +183,8 @@ def bind(
 
     elements: list[Element] = [binding]
 
-    if eager:
-        elements.append(Eager(key))
+    if eager is not False:
+        elements.append(Eager(key, priority=eager if isinstance(eager, int) else 0))
     if expose:
         elements.append(Expose(key))
 

omlish/inject/eagers.py

@@ -16,3 +16,5 @@ from .keys import Key
 @dc.extra_class_params(cache_hash=True)
 class Eager(Element, lang.Final):
     key: Key = dc.xfield(coerce=check.of_isinstance(Key))
+
+    priority: int = dc.xfield(0, kw_only=True)

omlish/inject/helpers/late.py

@@ -0,0 +1,76 @@
+"""
+A minor tidiness for hiding refs to [Async]Injector in circ-dep workarounds. Unfortunately unsuitable outside of
+injection modules due to it itself being in here (as user code shouldn't reference injector guts), but at least it's
+something.
+"""
+import abc
+import functools
+import typing as ta
+
+from ... import lang
+from ... import reflect as rfl
+from ..binder import bind
+from ..elements import Elements
+from ..elements import as_elements
+from ..injector import AsyncInjector
+from ..inspect import KwargsTarget
+from ..keys import Key
+from ..keys import as_key
+from ..sync import Injector
+
+
+T = ta.TypeVar('T')
+
+
+##
+
+
+class Late(lang.Abstract, ta.Generic[T]):
+    @abc.abstractmethod
+    def __call__(self) -> T:
+        raise NotImplementedError
+
+
+class AsyncLate(lang.Abstract, ta.Generic[T]):
+    @abc.abstractmethod
+    def __call__(self) -> ta.Awaitable[T]:
+        raise NotImplementedError
+
+
+#
+
+
+def _bind_late(
+        injector_cls: type,
+        late_cls: ta.Any,
+        inner: ta.Any,
+        outer: ta.Any | None = None,
+) -> Elements:
+    inner_key = as_key(inner)
+
+    outer_key: Key
+    outer_fac: ta.Callable[[ta.Any], ta.Any]
+    if outer is None:
+        inner_ann = rfl.to_annotation(inner_key.ty)
+        outer_ann = late_cls[inner_ann]
+        outer_key = Key(rfl.type_(outer_ann))
+        outer_fac = lang.identity
+    else:
+        outer_key = as_key(outer)
+        outer_cls = rfl.get_concrete_type(outer_key.ty)
+        outer_fac = outer_cls  # type: ignore[assignment]
+
+    return as_elements(
+        bind(outer_key, to_fn=KwargsTarget.of(  # noqa
+            lambda i: outer_fac(functools.partial(i.provide, inner_key)),
+            i=injector_cls,
+        )),
+    )
+
+
+def bind_late(inner: ta.Any, outer: ta.Any | None = None) -> Elements:
+    return _bind_late(Injector, Late, inner, outer)
+
+
+def bind_async_late(inner: ta.Any, outer: ta.Any | None = None) -> Elements:
+    return _bind_late(AsyncInjector, AsyncLate, inner, outer)

omlish/inject/{managed.py → helpers/managed.py}

@@ -5,20 +5,20 @@ TODO:
 import contextlib
 import typing as ta
 
-from .. import lang
-from .binder import bind
-from .elements import Elemental
-from .impl.inspect import build_kwargs_target
+from ... import lang
+from ..binder import bind
+from ..elements import Elemental
+from ..impl.inspect import build_kwargs_target
 
 
 if ta.TYPE_CHECKING:
-    from . import injector as _injector
-    from . import maysync as _maysync
-    from . import sync as _sync
+    from .. import injector as _injector
+    from .. import maysync as _maysync
+    from .. import sync as _sync
 else:
-    _injector = lang.proxy_import('.injector', __package__)
-    _maysync = lang.proxy_import('.maysync', __package__)
-    _sync = lang.proxy_import('.sync', __package__)
+    _injector = lang.proxy_import('..injector', __package__)
+    _maysync = lang.proxy_import('..maysync', __package__)
+    _sync = lang.proxy_import('..sync', __package__)
 
 
 T = ta.TypeVar('T')

omlish/inject/impl/elements.py

@@ -214,13 +214,16 @@ class ElementCollection(CollectedElements, lang.Final):
         return [sb.scope for sb in self.elements_of_type(ScopeBinding)]
 
     @lang.cached_function
-    def eager_keys_by_scope(self) -> ta.Mapping[Scope, ta.Sequence[Key]]:
+    def sorted_eager_keys_by_scope(self) -> ta.Mapping[Scope, ta.Sequence[Key]]:
         bim = self.binding_impl_map()
-        ret: dict[Scope, list[Key]] = {}
+        dct: dict[Scope, list[Eager]] = {}
         for e in self.elements_of_type(Eager):
             bi = bim[e.key]
-            ret.setdefault(bi.scope, []).append(e.key)
-        return ret
+            dct.setdefault(bi.scope, []).append(e)
+        return {
+            sc: tuple(eg.key for eg in sorted(egs, key=lambda eg: eg.priority))
+            for sc, egs in dct.items()
+        }
 
 
 ##

omlish/inject/impl/injector.py

@@ -12,6 +12,9 @@ TODO:
  - multiple live request scopes on single injector - use private injectors?
  - more listeners - UnboundKeyListener
   - lazy parent listener chain cache thing
+ - https://github.com/7mind/izumi-chibi-ts
+  - Axis tagging for conditional bindings (e.g., dev vs prod implementations)
+  - Fail-fast validation with circular and missing dependency detection
 """
 import contextlib
 import functools
@@ -73,14 +76,14 @@ class AsyncInjectorImpl(AsyncInjector, lang.Final):
 
         self._bim = ec.binding_impl_map()
 
-        self._ekbs = ec.eager_keys_by_scope()
+        self._ekbs = ec.sorted_eager_keys_by_scope()
 
-        self._pls: tuple[ProvisionListener, ...] = tuple(
-            b.listener  # type: ignore[attr-defined]
-            for b in itertools.chain(
-                ec.elements_of_type(ProvisionListenerBinding),
-                p._pls if p is not None else (),  # noqa
-            )
+        self._pls: tuple[ProvisionListener, ...] = (
+            *(
+                b.listener
+                for b in ec.elements_of_type(ProvisionListenerBinding)
+            ),
+            *(p._pls if p is not None else []),  # noqa
         )
 
         self._root: AsyncInjectorImpl = p._root if p is not None else self  # noqa

omlish/inject/inspect.py

@@ -58,7 +58,7 @@ class KwargsTarget(ta.NamedTuple):
 
         return cls(
             obj,
-            [*kws, *kw_kwargs],
+            (*kws, *kw_kwargs),
         )
 
 

omlish/lang/__init__.py

@@ -621,6 +621,8 @@ with _auto_proxy_init(globals(), update_exports=True):
         Func2,
         Func3,
 
+        CachedFunc0,
+
         typing_annotations_attr,
     )
 

omlish/lifecycles/README.md

@@ -0,0 +1,30 @@
+Lifecycle management, inspired by [governator](https://github.com/Netflix/governator/tree/master/governator-core/).
+
+A central idea is to 'hide the guts' of a given class's lifecycle management from code interacting with it.
+
+The main classes are as follows:
+
+- Lifecycle / AsyncLifecycle - the code 'managed by' the rest of the lifecycle machinery. In general, user code will
+  hide its implementations of these from the code that otherwise interacts with it. Being the lowest level / unit of
+  management callbacks, it intentionally provides no additional machinery, existing solely as a skeleton of methods
+  which will be called by lifecycle internals - this is to reduce friction with more functional / less OO code. However,
+  it still chooses to be a class with multiple nullary methods, rather than a more functional-style single unary free
+  function: the operations present in each method are generally intended to have no overlap in practice, and their
+  explicit division is a conscious choice.
+
+- LifecycleManaged / AsyncLifecycleManaged - a mixin which can be used to add lifecycle management behavior to a class.
+  This removes the need for manual subclassing of Lifecycle / AsyncLifecycle, providing private '\_lifecycle_<state>'
+  callback methods (with default no-op implementations) which subclasses may override.
+
+- LifecycleListener / AsyncLifecycleListener - callback interfaces whose methods will be called when a lifecycle object
+  goes through a lifecycle state transition.
+
+- LifecycleController / AsyncLifecycleController - these classes run the state machine for any single Lifecycle /
+  AsyncLifecycle instance. They are also responsible for maintaining a registry of lifecycle listeners and calling their
+  methods as necessary. Unlike user code, these classes are openly subclasses of Lifecycle / AsyncLifecycle, allowing
+  them to be called as application state dictates - they will internally ensure correct state transitions.
+
+- LifecycleManager / AsyncLifecycleManager - these classes are responsible for construction and operation of (acyclic)
+  graphs of lifecycle objects. They will ensure that, as necessary according to registered dependencies, lifecycle
+  objects are started in the correct order, and that they are stopped in the correct order. This class is itself a
+  LifecycleManaged / AsyncLifecycleManaged. Notably, AsyncLifecycleManager can also manage sync Lifecycles.

omlish/lifecycles/__init__.py

@@ -1,43 +1,71 @@
-from .abstract import (  # noqa
-    AbstractLifecycle,
+from .. import dataclasses as _dc
 
-    AbstractAsyncLifecycle,
+
+_dc.init_package(
+    globals(),
+    codegen=True,
 )
 
+
+##
+
+
 from .base import (  # noqa
-    AnyLifecycleCallback,
+    Lifecycle,
+    AsyncLifecycle,
     AnyLifecycle,
-    AnyCallbackLifecycle,
+    ANY_LIFECYCLE_TYPES,
 
-    LifecycleCallback,
-    CallbackLifecycle,
-    Lifecycle,
+    sync_to_async_lifecycle,
+    as_async_lifecycle,
+    async_to_sync_lifecycle,
+    as_sync_lifecycle,
 
-    AsyncLifecycleCallback,
+    CallbackLifecycle,
     CallbackAsyncLifecycle,
-    AsyncLifecycle,
 )
 
 from .contextmanagers import (  # noqa
     ContextManagerLifecycle,
+    AsyncContextManagerLifecycle,
+
     LifecycleContextManager,
+    AsyncLifecycleContextManager,
+
+    lifecycle_context_manage,
+    async_lifecycle_context_manage,
 )
 
 from .controller import (  # noqa
-    AnyLifecycleListener,
+    LifecycleController,
+    AsyncLifecycleController,
     AnyLifecycleController,
+    ANY_LIFECYCLE_CONTROLLER_TYPES,
+)
 
-    LifecycleController,
+from .listeners import (  # noqa
     LifecycleListener,
+    AsyncLifecycleListener,
+    AnyLifecycleListener,
+    ANY_LIFECYCLE_LISTENER_TYPES,
+)
+
+from .managed import (  # noqa
+    LifecycleManaged,
+    AsyncLifecycleManaged,
+    AnyLifecycleManaged,
+    ANY_LIFECYCLE_MANAGED_TYPES,
 )
 
 from .manager import (  # noqa
+    LifecycleManagerEntry,
     LifecycleManager,
+    AsyncLifecycleManager,
 )
 
 from .states import (  # noqa
-    LifecycleState,
     LifecycleStateError,
+    LifecycleState,
     LifecycleStates,
 )
 
@@ -45,3 +73,49 @@ from .transitions import (  # noqa
     LifecycleTransition,
     LifecycleTransitions,
 )
+
+from .unwrap import (  # noqa
+    unwrap_lifecycle,
+    unwrap_async_lifecycle,
+    unwrap_any_lifecycle,
+)
+
+
+##
+
+
+from .. import lang as _lang  # noqa
+
+
+with _lang.auto_proxy_init(globals()):
+    ##
+
+    from .injection import (  # noqa
+        bind_lifecycle_registrar,
+        bind_async_lifecycle_registrar,
+
+        bind_managed_lifecycle_manager,
+        bind_async_managed_lifecycle_manager,
+    )
+
+
+##
+
+
+NEW = LifecycleStates.NEW
+
+CONSTRUCTING = LifecycleStates.CONSTRUCTING
+FAILED_CONSTRUCTING = LifecycleStates.FAILED_CONSTRUCTING
+CONSTRUCTED = LifecycleStates.CONSTRUCTED
+
+STARTING = LifecycleStates.STARTING
+FAILED_STARTING = LifecycleStates.FAILED_STARTING
+STARTED = LifecycleStates.STARTED
+
+STOPPING = LifecycleStates.STOPPING
+FAILED_STOPPING = LifecycleStates.FAILED_STOPPING
+STOPPED = LifecycleStates.STOPPED
+
+DESTROYING = LifecycleStates.DESTROYING
+FAILED_DESTROYING = LifecycleStates.FAILED_DESTROYING
+DESTROYED = LifecycleStates.DESTROYED