omdev 0.0.0.dev416__py3-none-any.whl → 0.0.0.dev500__py3-none-any.whl

omdev/scripts/lib/inject.py

@@ -0,0 +1,2086 @@
+#!/usr/bin/env python3
+# noinspection DuplicatedCode
+# @omlish-lite
+# @omlish-script
+# @omlish-generated
+# @omlish-amalg-output ../../../omlish/lite/inject.py
+# @omlish-git-diff-omit
+# ruff: noqa: UP006 UP007 UP036 UP043 UP045
+import abc
+import collections
+import contextlib
+import contextvars
+import dataclasses as dc
+import functools
+import inspect
+import operator
+import sys
+import threading
+import types
+import typing as ta
+import weakref
+
+
+########################################
+
+
+if sys.version_info < (3, 8):
+    raise OSError(f'Requires python (3, 8), got {sys.version_info} from {sys.executable}')  # noqa
+
+
+def __omlish_amalg__():  # noqa
+    return dict(
+        src_files=[
+            dict(path='abstract.py', sha1='a2fc3f3697fa8de5247761e9d554e70176f37aac'),
+            dict(path='check.py', sha1='bb6b6b63333699b84462951a854d99ae83195b94'),
+            dict(path='reflect.py', sha1='c4fec44bf144e9d93293c996af06f6c65fc5e63d'),
+            dict(path='maybes.py', sha1='bdf5136654ccd14b6a072588cad228925bdfbabd'),
+            dict(path='inject.py', sha1='6f097e3170019a34ff6834d36fcc9cbeed3a7ab4'),
+        ],
+    )
+
+
+########################################
+
+
+# abstract.py
+T = ta.TypeVar('T')
+
+# check.py
+SizedT = ta.TypeVar('SizedT', bound=ta.Sized)
+CheckMessage = ta.Union[str, ta.Callable[..., ta.Optional[str]], None]  # ta.TypeAlias
+CheckLateConfigureFn = ta.Callable[['Checks'], None]  # ta.TypeAlias
+CheckOnRaiseFn = ta.Callable[[Exception], None]  # ta.TypeAlias
+CheckExceptionFactory = ta.Callable[..., Exception]  # ta.TypeAlias
+CheckArgsRenderer = ta.Callable[..., ta.Optional[str]]  # ta.TypeAlias
+
+# maybes.py
+U = ta.TypeVar('U')
+
+# inject.py
+InjectorKeyCls = ta.Union[type, ta.NewType]  # ta.TypeAlias
+InjectorProviderFn = ta.Callable[['Injector'], ta.Any]  # ta.TypeAlias
+InjectorProviderFnMap = ta.Mapping['InjectorKey', 'InjectorProviderFn']  # ta.TypeAlias
+InjectorBindingOrBindings = ta.Union['InjectorBinding', 'InjectorBindings']  # ta.TypeAlias
+
+
+########################################
+# ../abstract.py
+
+
+##
+
+
+_ABSTRACT_METHODS_ATTR = '__abstractmethods__'
+_IS_ABSTRACT_METHOD_ATTR = '__isabstractmethod__'
+
+
+def is_abstract_method(obj: ta.Any) -> bool:
+    return bool(getattr(obj, _IS_ABSTRACT_METHOD_ATTR, False))
+
+
+def compute_abstract_methods(cls: type) -> ta.FrozenSet[str]:
+    # ~> https://github.com/python/cpython/blob/f3476c6507381ca860eec0989f53647b13517423/Modules/_abc.c#L358
+
+    # Stage 1: direct abstract methods
+
+    abstracts = {
+        a
+        # Get items as a list to avoid mutation issues during iteration
+        for a, v in list(cls.__dict__.items())
+        if is_abstract_method(v)
+    }
+
+    # Stage 2: inherited abstract methods
+
+    for base in cls.__bases__:
+        # Get __abstractmethods__ from base if it exists
+        if (base_abstracts := getattr(base, _ABSTRACT_METHODS_ATTR, None)) is None:
+            continue
+
+        # Iterate over abstract methods in base
+        for key in base_abstracts:
+            # Check if this class has an attribute with this name
+            try:
+                value = getattr(cls, key)
+            except AttributeError:
+                # Attribute not found in this class, skip
+                continue
+
+            # Check if it's still abstract
+            if is_abstract_method(value):
+                abstracts.add(key)
+
+    return frozenset(abstracts)
+
+
+def update_abstracts(cls: ta.Type[T], *, force: bool = False) -> ta.Type[T]:
+    if not force and not hasattr(cls, _ABSTRACT_METHODS_ATTR):
+        # Per stdlib: We check for __abstractmethods__ here because cls might by a C implementation or a python
+        # implementation (especially during testing), and we want to handle both cases.
+        return cls
+
+    abstracts = compute_abstract_methods(cls)
+    setattr(cls, _ABSTRACT_METHODS_ATTR, abstracts)
+    return cls
+
+
+#
+
+
+class AbstractTypeError(TypeError):
+    pass
+
+
+_FORCE_ABSTRACT_ATTR = '__forceabstract__'
+
+
+class Abstract:
+    """
+    Different from, but interoperable with, abc.ABC / abc.ABCMeta:
+
+     - This raises AbstractTypeError during class creation, not instance instantiation - unless Abstract or abc.ABC are
+       explicitly present in the class's direct bases.
+     - This will forbid instantiation of classes with Abstract in their direct bases even if there are no
+       abstractmethods left on the class.
+     - This is a mixin, not a metaclass.
+     - As it is not an ABCMeta, this does not support virtual base classes. As a result, operations like `isinstance`
+       and `issubclass` are ~7x faster.
+     - It additionally enforces a base class order of (Abstract, abc.ABC) to preemptively prevent common mro conflicts.
+
+    If not mixed-in with an ABCMeta, it will update __abstractmethods__ itself.
+    """
+
+    __slots__ = ()
+
+    __abstractmethods__: ta.ClassVar[ta.FrozenSet[str]] = frozenset()
+
+    #
+
+    def __forceabstract__(self):
+        raise TypeError
+
+    # This is done manually, rather than through @abc.abstractmethod, to mask it from static analysis.
+    setattr(__forceabstract__, _IS_ABSTRACT_METHOD_ATTR, True)
+
+    #
+
+    def __init_subclass__(cls, **kwargs: ta.Any) -> None:
+        setattr(
+            cls,
+            _FORCE_ABSTRACT_ATTR,
+            getattr(Abstract, _FORCE_ABSTRACT_ATTR) if Abstract in cls.__bases__ else False,
+        )
+
+        super().__init_subclass__(**kwargs)
+
+        if not (Abstract in cls.__bases__ or abc.ABC in cls.__bases__):
+            if ams := compute_abstract_methods(cls):
+                amd = {
+                    a: mcls
+                    for mcls in cls.__mro__[::-1]
+                    for a in ams
+                    if a in mcls.__dict__
+                }
+
+                raise AbstractTypeError(
+                    f'Cannot subclass abstract class {cls.__name__} with abstract methods: ' +
+                    ', '.join(sorted([
+                        '.'.join([
+                            *([
+                                *([m] if (m := getattr(c, '__module__')) else []),
+                                getattr(c, '__qualname__', getattr(c, '__name__')),
+                            ] if c is not None else '?'),
+                            a,
+                        ])
+                        for a in ams
+                        for c in [amd.get(a)]
+                    ])),
+                )
+
+        xbi = (Abstract, abc.ABC)  # , ta.Generic ?
+        bis = [(cls.__bases__.index(b), b) for b in xbi if b in cls.__bases__]
+        if bis != sorted(bis):
+            raise TypeError(
+                f'Abstract subclass {cls.__name__} must have proper base class order of '
+                f'({", ".join(getattr(b, "__name__") for b in xbi)}), got: '
+                f'({", ".join(getattr(b, "__name__") for _, b in sorted(bis))})',
+            )
+
+        if not isinstance(cls, abc.ABCMeta):
+            update_abstracts(cls, force=True)
+
+
+########################################
+# ../check.py
+"""
+TODO:
+ - def maybe(v: lang.Maybe[T])
+ - def not_ ?
+ - ** class @dataclass Raise - user message should be able to be an exception type or instance or factory
+"""
+
+
+##
+
+
+class Checks:
+    def __init__(self) -> None:
+        super().__init__()
+
+        self._config_lock = threading.RLock()
+        self._on_raise_fns: ta.Sequence[CheckOnRaiseFn] = []
+        self._exception_factory: CheckExceptionFactory = Checks.default_exception_factory
+        self._args_renderer: ta.Optional[CheckArgsRenderer] = None
+        self._late_configure_fns: ta.Sequence[CheckLateConfigureFn] = []
+
+    @staticmethod
+    def default_exception_factory(exc_cls: ta.Type[Exception], *args, **kwargs) -> Exception:
+        return exc_cls(*args, **kwargs)  # noqa
+
+    #
+
+    def register_on_raise(self, fn: CheckOnRaiseFn) -> None:
+        with self._config_lock:
+            self._on_raise_fns = [*self._on_raise_fns, fn]
+
+    def unregister_on_raise(self, fn: CheckOnRaiseFn) -> None:
+        with self._config_lock:
+            self._on_raise_fns = [e for e in self._on_raise_fns if e != fn]
+
+    #
+
+    def register_on_raise_breakpoint_if_env_var_set(self, key: str) -> None:
+        import os
+
+        def on_raise(exc: Exception) -> None:  # noqa
+            if key in os.environ:
+                breakpoint()  # noqa
+
+        self.register_on_raise(on_raise)
+
+    #
+
+    def set_exception_factory(self, factory: CheckExceptionFactory) -> None:
+        self._exception_factory = factory
+
+    def set_args_renderer(self, renderer: ta.Optional[CheckArgsRenderer]) -> None:
+        self._args_renderer = renderer
+
+    #
+
+    def register_late_configure(self, fn: CheckLateConfigureFn) -> None:
+        with self._config_lock:
+            self._late_configure_fns = [*self._late_configure_fns, fn]
+
+    def _late_configure(self) -> None:
+        if not self._late_configure_fns:
+            return
+
+        with self._config_lock:
+            if not (lc := self._late_configure_fns):
+                return
+
+            for fn in lc:
+                fn(self)
+
+            self._late_configure_fns = []
+
+    #
+
+    class _ArgsKwargs:
+        def __init__(self, *args, **kwargs):
+            self.args = args
+            self.kwargs = kwargs
+
+    def _raise(
+            self,
+            exception_type: ta.Type[Exception],
+            default_message: str,
+            message: CheckMessage,
+            ak: _ArgsKwargs = _ArgsKwargs(),
+            *,
+            render_fmt: ta.Optional[str] = None,
+    ) -> ta.NoReturn:
+        exc_args = ()
+        if callable(message):
+            message = ta.cast(ta.Callable, message)(*ak.args, **ak.kwargs)
+            if isinstance(message, tuple):
+                message, *exc_args = message  # type: ignore
+
+        if message is None:
+            message = default_message
+
+        self._late_configure()
+
+        if render_fmt is not None and (af := self._args_renderer) is not None:
+            rendered_args = af(render_fmt, *ak.args)
+            if rendered_args is not None:
+                message = f'{message} : {rendered_args}'
+
+        exc = self._exception_factory(
+            exception_type,
+            message,
+            *exc_args,
+            *ak.args,
+            **ak.kwargs,
+        )
+
+        for fn in self._on_raise_fns:
+            fn(exc)
+
+        raise exc
+
+    #
+
+    def _unpack_isinstance_spec(self, spec: ta.Any) -> tuple:
+        if isinstance(spec, type):
+            return (spec,)
+        if not isinstance(spec, tuple):
+            spec = (spec,)
+        if None in spec:
+            spec = tuple(filter(None, spec)) + (None.__class__,)  # noqa
+        if ta.Any in spec:
+            spec = (object,)
+        return spec
+
+    @ta.overload
+    def isinstance(self, v: ta.Any, spec: ta.Type[T], msg: CheckMessage = None) -> T:
+        ...
+
+    @ta.overload
+    def isinstance(self, v: ta.Any, spec: ta.Any, msg: CheckMessage = None) -> ta.Any:
+        ...
+
+    def isinstance(self, v, spec, msg=None):
+        if not isinstance(v, self._unpack_isinstance_spec(spec)):
+            self._raise(
+                TypeError,
+                'Must be instance',
+                msg,
+                Checks._ArgsKwargs(v, spec),
+                render_fmt='not isinstance(%s, %s)',
+            )
+
+        return v
+
+    @ta.overload
+    def of_isinstance(self, spec: ta.Type[T], msg: CheckMessage = None) -> ta.Callable[[ta.Any], T]:
+        ...
+
+    @ta.overload
+    def of_isinstance(self, spec: ta.Any, msg: CheckMessage = None) -> ta.Callable[[ta.Any], ta.Any]:
+        ...
+
+    def of_isinstance(self, spec, msg=None):
+        def inner(v):
+            return self.isinstance(v, self._unpack_isinstance_spec(spec), msg)
+
+        return inner
+
+    def cast(self, v: ta.Any, cls: ta.Type[T], msg: CheckMessage = None) -> T:
+        if not isinstance(v, cls):
+            self._raise(
+                TypeError,
+                'Must be instance',
+                msg,
+                Checks._ArgsKwargs(v, cls),
+            )
+
+        return v
+
+    def of_cast(self, cls: ta.Type[T], msg: CheckMessage = None) -> ta.Callable[[T], T]:
+        def inner(v):
+            return self.cast(v, cls, msg)
+
+        return inner
+
+    def not_isinstance(self, v: T, spec: ta.Any, msg: CheckMessage = None) -> T:  # noqa
+        if isinstance(v, self._unpack_isinstance_spec(spec)):
+            self._raise(
+                TypeError,
+                'Must not be instance',
+                msg,
+                Checks._ArgsKwargs(v, spec),
+                render_fmt='isinstance(%s, %s)',
+            )
+
+        return v
+
+    def of_not_isinstance(self, spec: ta.Any, msg: CheckMessage = None) -> ta.Callable[[T], T]:
+        def inner(v):
+            return self.not_isinstance(v, self._unpack_isinstance_spec(spec), msg)
+
+        return inner
+
+    ##
+
+    def issubclass(self, v: ta.Type[T], spec: ta.Any, msg: CheckMessage = None) -> ta.Type[T]:  # noqa
+        if not issubclass(v, spec):
+            self._raise(
+                TypeError,
+                'Must be subclass',
+                msg,
+                Checks._ArgsKwargs(v, spec),
+                render_fmt='not issubclass(%s, %s)',
+            )
+
+        return v
+
+    def not_issubclass(self, v: ta.Type[T], spec: ta.Any, msg: CheckMessage = None) -> ta.Type[T]:
+        if issubclass(v, spec):
+            self._raise(
+                TypeError,
+                'Must not be subclass',
+                msg,
+                Checks._ArgsKwargs(v, spec),
+                render_fmt='issubclass(%s, %s)',
+            )
+
+        return v
+
+    #
+
+    def in_(self, v: T, c: ta.Container[T], msg: CheckMessage = None) -> T:
+        if v not in c:
+            self._raise(
+                ValueError,
+                'Must be in',
+                msg,
+                Checks._ArgsKwargs(v, c),
+                render_fmt='%s not in %s',
+            )
+
+        return v
+
+    def not_in(self, v: T, c: ta.Container[T], msg: CheckMessage = None) -> T:
+        if v in c:
+            self._raise(
+                ValueError,
+                'Must not be in',
+                msg,
+                Checks._ArgsKwargs(v, c),
+                render_fmt='%s in %s',
+            )
+
+        return v
+
+    def empty(self, v: SizedT, msg: CheckMessage = None) -> SizedT:
+        if len(v) != 0:
+            self._raise(
+                ValueError,
+                'Must be empty',
+                msg,
+                Checks._ArgsKwargs(v),
+                render_fmt='%s',
+            )
+
+        return v
+
+    def iterempty(self, v: ta.Iterable[T], msg: CheckMessage = None) -> ta.Iterable[T]:
+        it = iter(v)
+        try:
+            next(it)
+        except StopIteration:
+            pass
+        else:
+            self._raise(
+                ValueError,
+                'Must be empty',
+                msg,
+                Checks._ArgsKwargs(v),
+                render_fmt='%s',
+            )
+
+        return v
+
+    def not_empty(self, v: SizedT, msg: CheckMessage = None) -> SizedT:
+        if len(v) == 0:
+            self._raise(
+                ValueError,
+                'Must not be empty',
+                msg,
+                Checks._ArgsKwargs(v),
+                render_fmt='%s',
+            )
+
+        return v
+
+    def unique(self, it: ta.Iterable[T], msg: CheckMessage = None) -> ta.Iterable[T]:
+        dupes = [e for e, c in collections.Counter(it).items() if c > 1]
+        if dupes:
+            self._raise(
+                ValueError,
+                'Must be unique',
+                msg,
+                Checks._ArgsKwargs(it, dupes),
+            )
+
+        return it
+
+    def single(self, obj: ta.Iterable[T], msg: CheckMessage = None) -> T:
+        try:
+            [value] = obj
+        except ValueError:
+            self._raise(
+                ValueError,
+                'Must be single',
+                msg,
+                Checks._ArgsKwargs(obj),
+                render_fmt='%s',
+            )
+
+        return value
+
+    def opt_single(self, obj: ta.Iterable[T], msg: CheckMessage = None) -> ta.Optional[T]:
+        it = iter(obj)
+        try:
+            value = next(it)
+        except StopIteration:
+            return None
+
+        try:
+            next(it)
+        except StopIteration:
+            return value  # noqa
+
+        self._raise(
+            ValueError,
+            'Must be empty or single',
+            msg,
+            Checks._ArgsKwargs(obj),
+            render_fmt='%s',
+        )
+
+        raise RuntimeError  # noqa
+
+    #
+
+    def none(self, v: ta.Any, msg: CheckMessage = None) -> None:
+        if v is not None:
+            self._raise(
+                ValueError,
+                'Must be None',
+                msg,
+                Checks._ArgsKwargs(v),
+                render_fmt='%s',
+            )
+
+    def not_none(self, v: ta.Optional[T], msg: CheckMessage = None) -> T:
+        if v is None:
+            self._raise(
+                ValueError,
+                'Must not be None',
+                msg,
+                Checks._ArgsKwargs(v),
+                render_fmt='%s',
+            )
+
+        return v
+
+    #
+
+    def equal(self, v: T, o: ta.Any, msg: CheckMessage = None) -> T:
+        if o != v:
+            self._raise(
+                ValueError,
+                'Must be equal',
+                msg,
+                Checks._ArgsKwargs(v, o),
+                render_fmt='%s != %s',
+            )
+
+        return v
+
+    def not_equal(self, v: T, o: ta.Any, msg: CheckMessage = None) -> T:
+        if o == v:
+            self._raise(
+                ValueError,
+                'Must not be equal',
+                msg,
+                Checks._ArgsKwargs(v, o),
+                render_fmt='%s == %s',
+            )
+
+        return v
+
+    def is_(self, v: T, o: ta.Any, msg: CheckMessage = None) -> T:
+        if o is not v:
+            self._raise(
+                ValueError,
+                'Must be the same',
+                msg,
+                Checks._ArgsKwargs(v, o),
+                render_fmt='%s is not %s',
+            )
+
+        return v
+
+    def is_not(self, v: T, o: ta.Any, msg: CheckMessage = None) -> T:
+        if o is v:
+            self._raise(
+                ValueError,
+                'Must not be the same',
+                msg,
+                Checks._ArgsKwargs(v, o),
+                render_fmt='%s is %s',
+            )
+
+        return v
+
+    def callable(self, v: T, msg: CheckMessage = None) -> T:  # noqa
+        if not callable(v):
+            self._raise(
+                TypeError,
+                'Must be callable',
+                msg,
+                Checks._ArgsKwargs(v),
+                render_fmt='%s',
+            )
+
+        return v
+
+    def non_empty_str(self, v: ta.Optional[str], msg: CheckMessage = None) -> str:
+        if not isinstance(v, str) or not v:
+            self._raise(
+                ValueError,
+                'Must be non-empty str',
+                msg,
+                Checks._ArgsKwargs(v),
+                render_fmt='%s',
+            )
+
+        return v
+
+    def replacing(self, expected: ta.Any, old: ta.Any, new: T, msg: CheckMessage = None) -> T:
+        if old != expected:
+            self._raise(
+                ValueError,
+                'Must be replacing',
+                msg,
+                Checks._ArgsKwargs(expected, old, new),
+                render_fmt='%s -> %s -> %s',
+            )
+
+        return new
+
+    def replacing_none(self, old: ta.Any, new: T, msg: CheckMessage = None) -> T:
+        if old is not None:
+            self._raise(
+                ValueError,
+                'Must be replacing None',
+                msg,
+                Checks._ArgsKwargs(old, new),
+                render_fmt='%s -> %s',
+            )
+
+        return new
+
+    #
+
+    def arg(self, v: bool, msg: CheckMessage = None) -> None:
+        if not v:
+            self._raise(
+                RuntimeError,
+                'Argument condition not met',
+                msg,
+                Checks._ArgsKwargs(v),
+                render_fmt='%s',
+            )
+
+    def state(self, v: bool, msg: CheckMessage = None) -> None:
+        if not v:
+            self._raise(
+                RuntimeError,
+                'State condition not met',
+                msg,
+                Checks._ArgsKwargs(v),
+                render_fmt='%s',
+            )
+
+
+check = Checks()
+
+
+########################################
+# ../reflect.py
+
+
+##
+
+
+_GENERIC_ALIAS_TYPES = (
+    ta._GenericAlias,  # type: ignore  # noqa
+    *([ta._SpecialGenericAlias] if hasattr(ta, '_SpecialGenericAlias') else []),  # noqa
+)
+
+
+def is_generic_alias(obj: ta.Any, *, origin: ta.Any = None) -> bool:
+    return (
+        isinstance(obj, _GENERIC_ALIAS_TYPES) and
+        (origin is None or ta.get_origin(obj) is origin)
+    )
+
+
+is_callable_alias = functools.partial(is_generic_alias, origin=ta.Callable)
+
+
+##
+
+
+_UNION_ALIAS_ORIGINS = frozenset([
+    ta.get_origin(ta.Optional[int]),
+    *(
+        [
+            ta.get_origin(int | None),
+            ta.get_origin(getattr(ta, 'TypeVar')('_T') | None),
+        ] if sys.version_info >= (3, 10) else ()
+    ),
+])
+
+
+def is_union_alias(obj: ta.Any) -> bool:
+    return ta.get_origin(obj) in _UNION_ALIAS_ORIGINS
+
+
+#
+
+
+def is_optional_alias(spec: ta.Any) -> bool:
+    return (
+        is_union_alias(spec) and
+        len(ta.get_args(spec)) == 2 and
+        any(a in (None, type(None)) for a in ta.get_args(spec))
+    )
+
+
+def get_optional_alias_arg(spec: ta.Any) -> ta.Any:
+    [it] = [it for it in ta.get_args(spec) if it not in (None, type(None))]
+    return it
+
+
+##
+
+
+def is_new_type(spec: ta.Any) -> bool:
+    if isinstance(ta.NewType, type):
+        return isinstance(spec, ta.NewType)
+    else:
+        # Before https://github.com/python/cpython/commit/c2f33dfc83ab270412bf243fb21f724037effa1a
+        return isinstance(spec, types.FunctionType) and spec.__code__ is ta.NewType.__code__.co_consts[1]  # type: ignore  # noqa
+
+
+def get_new_type_supertype(spec: ta.Any) -> ta.Any:
+    return spec.__supertype__
+
+
+##
+
+
+def is_literal_type(spec: ta.Any) -> bool:
+    if hasattr(ta, '_LiteralGenericAlias'):
+        return isinstance(spec, ta._LiteralGenericAlias)  # noqa
+    else:
+        return (
+            isinstance(spec, ta._GenericAlias) and  # type: ignore  # noqa
+            spec.__origin__ is ta.Literal
+        )
+
+
+def get_literal_type_args(spec: ta.Any) -> ta.Iterable[ta.Any]:
+    return spec.__args__
+
+
+########################################
+# ../maybes.py
+
+
+##
+
+
+@functools.total_ordering
+class Maybe(ta.Generic[T]):
+    class ValueNotPresentError(BaseException):
+        pass
+
+    #
+
+    @property
+    @abc.abstractmethod
+    def present(self) -> bool:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def must(self) -> T:
+        raise NotImplementedError
+
+    #
+
+    @abc.abstractmethod
+    def __repr__(self) -> str:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __hash__(self) -> int:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __eq__(self, other) -> bool:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def __lt__(self, other) -> bool:
+        raise NotImplementedError
+
+    #
+
+    @ta.final
+    def __ne__(self, other):
+        return not (self == other)
+
+    @ta.final
+    def __iter__(self) -> ta.Iterator[T]:
+        if self.present:
+            yield self.must()
+
+    @ta.final
+    def __bool__(self) -> ta.NoReturn:
+        raise TypeError
+
+    #
+
+    @ta.final
+    def if_present(self, consumer: ta.Callable[[T], None]) -> None:
+        if self.present:
+            consumer(self.must())
+
+    @ta.final
+    def filter(self, predicate: ta.Callable[[T], bool]) -> 'Maybe[T]':
+        if self.present and predicate(self.must()):
+            return self
+        else:
+            return Maybe.empty()
+
+    @ta.final
+    def map(self, mapper: ta.Callable[[T], U]) -> 'Maybe[U]':
+        if self.present:
+            return Maybe.just(mapper(self.must()))
+        else:
+            return Maybe.empty()
+
+    @ta.final
+    def flat_map(self, mapper: ta.Callable[[T], 'Maybe[U]']) -> 'Maybe[U]':
+        if self.present:
+            if not isinstance(v := mapper(self.must()), Maybe):
+                raise TypeError(v)
+            return v
+        else:
+            return Maybe.empty()
+
+    @ta.final
+    def or_else(self, other: ta.Union[T, U]) -> ta.Union[T, U]:
+        if self.present:
+            return self.must()
+        else:
+            return other
+
+    @ta.final
+    def or_else_get(self, supplier: ta.Callable[[], ta.Union[T, U]]) -> ta.Union[T, U]:
+        if self.present:
+            return self.must()
+        else:
+            return supplier()
+
+    @ta.final
+    def or_else_raise(self, exception_supplier: ta.Callable[[], Exception]) -> T:
+        if self.present:
+            return self.must()
+        else:
+            raise exception_supplier()
+
+    #
+
+    @classmethod
+    def of_optional(cls, v: ta.Optional[T]) -> 'Maybe[T]':
+        if v is not None:
+            return cls.just(v)
+        else:
+            return cls.empty()
+
+    @classmethod
+    def just(cls, v: T) -> 'Maybe[T]':
+        return _JustMaybe(v)
+
+    _empty: ta.ClassVar['Maybe']
+
+    @classmethod
+    def empty(cls) -> 'Maybe[T]':
+        return Maybe._empty
+
+
+##
+
+
+class _Maybe(Maybe[T], Abstract):
+    def __lt__(self, other):
+        if not isinstance(other, _Maybe):
+            return NotImplemented
+        sp = self.present
+        op = other.present
+        if self.present and other.present:
+            return self.must() < other.must()
+        else:
+            return op and not sp
+
+
+@ta.final
+class _JustMaybe(_Maybe[T]):
+    __slots__ = ('_v', '_hash')
+
+    def __init__(self, v: T) -> None:
+        self._v = v
+
+    @property
+    def present(self) -> bool:
+        return True
+
+    def must(self) -> T:
+        return self._v
+
+    #
+
+    def __repr__(self) -> str:
+        return f'just({self._v!r})'
+
+    _hash: int
+
+    def __hash__(self) -> int:
+        try:
+            return self._hash
+        except AttributeError:
+            pass
+        h = self._hash = hash((_JustMaybe, self._v))
+        return h
+
+    def __eq__(self, other):
+        return (
+            self.__class__ is other.__class__ and
+            self._v == other._v  # noqa
+        )
+
+
+@ta.final
+class _EmptyMaybe(_Maybe[T]):
+    __slots__ = ()
+
+    @property
+    def present(self) -> bool:
+        return False
+
+    def must(self) -> T:
+        raise Maybe.ValueNotPresentError
+
+    #
+
+    def __repr__(self) -> str:
+        return 'empty()'
+
+    def __hash__(self) -> int:
+        return hash(_EmptyMaybe)
+
+    def __eq__(self, other):
+        return self.__class__ is other.__class__
+
+
+Maybe._empty = _EmptyMaybe()  # noqa
+
+
+##
+
+
+setattr(Maybe, 'just', _JustMaybe)  # noqa
+setattr(Maybe, 'empty', functools.partial(operator.attrgetter('_empty'), Maybe))
+
+
+########################################
+# inject.py
+
+
+###
+# types
+
+
+@dc.dataclass(frozen=True)
+class InjectorKey(ta.Generic[T]):
+    # Before PEP-560 typing.Generic was a metaclass with a __new__ that takes a 'cls' arg, so instantiating a dataclass
+    # with kwargs (such as through dc.replace) causes `TypeError: __new__() got multiple values for argument 'cls'`.
+    # See:
+    #  - https://github.com/python/cpython/commit/d911e40e788fb679723d78b6ea11cabf46caed5a
+    #  - https://gist.github.com/wrmsr/4468b86efe9f373b6b114bfe85b98fd3
+    cls_: InjectorKeyCls
+
+    tag: ta.Any = None
+    array: bool = False
+
+
+def is_valid_injector_key_cls(cls: ta.Any) -> bool:
+    return isinstance(cls, type) or is_new_type(cls)
+
+
+def check_valid_injector_key_cls(cls: T) -> T:
+    if not is_valid_injector_key_cls(cls):
+        raise TypeError(cls)
+    return cls
+
+
+##
+
+
+class InjectorProvider(Abstract):
+    @abc.abstractmethod
+    def provider_fn(self) -> InjectorProviderFn:
+        raise NotImplementedError
+
+
+##
+
+
+@dc.dataclass(frozen=True)
+class InjectorBinding:
+    key: InjectorKey
+    provider: InjectorProvider
+
+    def __post_init__(self) -> None:
+        check.isinstance(self.key, InjectorKey)
+        check.isinstance(self.provider, InjectorProvider)
+
+
+class InjectorBindings(Abstract):
+    @abc.abstractmethod
+    def bindings(self) -> ta.Iterator[InjectorBinding]:
+        raise NotImplementedError
+
+##
+
+
+class Injector(Abstract):
+    @abc.abstractmethod
+    def try_provide(self, key: ta.Any) -> Maybe[ta.Any]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def provide(self, key: ta.Any) -> ta.Any:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def provide_kwargs(
+            self,
+            obj: ta.Any,
+            *,
+            skip_args: int = 0,
+            skip_kwargs: ta.Optional[ta.Iterable[ta.Any]] = None,
+    ) -> ta.Mapping[str, ta.Any]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def inject(
+            self,
+            obj: ta.Any,
+            *,
+            args: ta.Optional[ta.Sequence[ta.Any]] = None,
+            kwargs: ta.Optional[ta.Mapping[str, ta.Any]] = None,
+    ) -> ta.Any:
+        raise NotImplementedError
+
+    def __getitem__(
+            self,
+            target: ta.Union[InjectorKey[T], ta.Type[T]],
+    ) -> T:
+        return self.provide(target)
+
+
+###
+# exceptions
+
+
+class InjectorError(Exception):
+    pass
+
+
+@dc.dataclass()
+class InjectorKeyError(InjectorError):
+    key: InjectorKey
+
+    source: ta.Any = None
+    name: ta.Optional[str] = None
+
+
+class UnboundInjectorKeyError(InjectorKeyError):
+    pass
+
+
+class DuplicateInjectorKeyError(InjectorKeyError):
+    pass
+
+
+class CyclicDependencyInjectorKeyError(InjectorKeyError):
+    pass
+
+
+###
+# keys
+
+
+def as_injector_key(o: ta.Any) -> InjectorKey:
+    if o is inspect.Parameter.empty:
+        raise TypeError(o)
+    if isinstance(o, InjectorKey):
+        return o
+    if is_valid_injector_key_cls(o):
+        return InjectorKey(o)
+    raise TypeError(o)
+
+
+###
+# providers
+
+
+@dc.dataclass(frozen=True)
+class FnInjectorProvider(InjectorProvider):
+    fn: ta.Any
+
+    def __post_init__(self) -> None:
+        check.not_isinstance(self.fn, type)
+
+    def provider_fn(self) -> InjectorProviderFn:
+        def pfn(i: Injector) -> ta.Any:
+            return i.inject(self.fn)
+
+        return pfn
+
+
+@dc.dataclass(frozen=True)
+class CtorInjectorProvider(InjectorProvider):
+    cls_: type
+
+    def __post_init__(self) -> None:
+        check.isinstance(self.cls_, type)
+
+    def provider_fn(self) -> InjectorProviderFn:
+        def pfn(i: Injector) -> ta.Any:
+            return i.inject(self.cls_)
+
+        return pfn
+
+
+@dc.dataclass(frozen=True)
+class ConstInjectorProvider(InjectorProvider):
+    v: ta.Any
+
+    def provider_fn(self) -> InjectorProviderFn:
+        return lambda _: self.v
+
+
+@dc.dataclass(frozen=True)
+class SingletonInjectorProvider(InjectorProvider):
+    p: InjectorProvider
+
+    def __post_init__(self) -> None:
+        check.isinstance(self.p, InjectorProvider)
+
+    def provider_fn(self) -> InjectorProviderFn:
+        v = not_set = object()
+
+        def pfn(i: Injector) -> ta.Any:
+            nonlocal v
+            if v is not_set:
+                v = ufn(i)
+            return v
+
+        ufn = self.p.provider_fn()
+        return pfn
+
+
+@dc.dataclass(frozen=True)
+class LinkInjectorProvider(InjectorProvider):
+    k: InjectorKey
+
+    def __post_init__(self) -> None:
+        check.isinstance(self.k, InjectorKey)
+
+    def provider_fn(self) -> InjectorProviderFn:
+        def pfn(i: Injector) -> ta.Any:
+            return i.provide(self.k)
+
+        return pfn
+
+
+@dc.dataclass(frozen=True)
+class ArrayInjectorProvider(InjectorProvider):
+    ps: ta.Sequence[InjectorProvider]
+
+    def provider_fn(self) -> InjectorProviderFn:
+        ps = [p.provider_fn() for p in self.ps]
+
+        def pfn(i: Injector) -> ta.Any:
+            rv = []
+            for ep in ps:
+                o = ep(i)
+                rv.append(o)
+            return rv
+
+        return pfn
+
+
+###
+# bindings
+
+
+@dc.dataclass(frozen=True)
+class _InjectorBindings(InjectorBindings):
+    bs: ta.Optional[ta.Sequence[InjectorBinding]] = None
+    ps: ta.Optional[ta.Sequence[InjectorBindings]] = None
+
+    def bindings(self) -> ta.Iterator[InjectorBinding]:
+        if self.bs is not None:
+            yield from self.bs
+        if self.ps is not None:
+            for p in self.ps:
+                yield from p.bindings()
+
+
+def as_injector_bindings(*args: InjectorBindingOrBindings) -> InjectorBindings:
+    bs: ta.List[InjectorBinding] = []
+    ps: ta.List[InjectorBindings] = []
+
+    for a in args:
+        if isinstance(a, InjectorBindings):
+            ps.append(a)
+        elif isinstance(a, InjectorBinding):
+            bs.append(a)
+        else:
+            raise TypeError(a)
+
+    return _InjectorBindings(
+        bs or None,
+        ps or None,
+    )
+
+
+##
+
+
+def build_injector_provider_map(bs: InjectorBindings) -> ta.Mapping[InjectorKey, InjectorProvider]:
+    pm: ta.Dict[InjectorKey, InjectorProvider] = {}
+    am: ta.Dict[InjectorKey, ta.List[InjectorProvider]] = {}
+
+    for b in bs.bindings():
+        if b.key.array:
+            al = am.setdefault(b.key, [])
+            if isinstance(b.provider, ArrayInjectorProvider):
+                al.extend(b.provider.ps)
+            else:
+                al.append(b.provider)
+        else:
+            if b.key in pm:
+                raise KeyError(b.key)
+            pm[b.key] = b.provider
+
+    if am:
+        for k, aps in am.items():
+            pm[k] = ArrayInjectorProvider(aps)
+
+    return pm
+
+
+###
+# overrides
+
+
+@dc.dataclass(frozen=True)
+class OverridesInjectorBindings(InjectorBindings):
+    p: InjectorBindings
+    m: ta.Mapping[InjectorKey, InjectorBinding]
+
+    def bindings(self) -> ta.Iterator[InjectorBinding]:
+        for b in self.p.bindings():
+            yield self.m.get(b.key, b)
+
+
+def injector_override(p: InjectorBindings, *args: InjectorBindingOrBindings) -> InjectorBindings:
+    m: ta.Dict[InjectorKey, InjectorBinding] = {}
+
+    for b in as_injector_bindings(*args).bindings():
+        if b.key in m:
+            raise DuplicateInjectorKeyError(b.key)
+        m[b.key] = b
+
+    return OverridesInjectorBindings(p, m)
+
+
+###
+# scopes
+
+
+class InjectorScope(Abstract):
+    def __init__(
+            self,
+            *,
+            _i: Injector,
+    ) -> None:
+        super().__init__()
+
+        self._i = _i
+
+        all_seeds: ta.Iterable[_InjectorScopeSeed] = self._i.provide(InjectorKey(_InjectorScopeSeed, array=True))
+        self._sks = {s.k for s in all_seeds if s.sc is type(self)}
+
+    #
+
+    @dc.dataclass(frozen=True)
+    class State:
+        seeds: ta.Dict[InjectorKey, ta.Any]
+        provisions: ta.Dict[InjectorKey, ta.Any] = dc.field(default_factory=dict)
+
+    def new_state(self, vs: ta.Mapping[InjectorKey, ta.Any]) -> State:
+        vs = dict(vs)
+        check.equal(set(vs.keys()), self._sks)
+        return InjectorScope.State(vs)
+
+    #
+
+    @abc.abstractmethod
+    def state(self) -> State:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def enter(self, vs: ta.Mapping[InjectorKey, ta.Any]) -> ta.ContextManager[None]:
+        raise NotImplementedError
+
+
+class ExclusiveInjectorScope(InjectorScope, Abstract):
+    _st: ta.Optional[InjectorScope.State] = None
+
+    def state(self) -> InjectorScope.State:
+        return check.not_none(self._st)
+
+    @contextlib.contextmanager
+    def enter(self, vs: ta.Mapping[InjectorKey, ta.Any]) -> ta.Iterator[None]:
+        check.none(self._st)
+        self._st = self.new_state(vs)
+        try:
+            yield
+        finally:
+            self._st = None
+
+
+class ContextvarInjectorScope(InjectorScope, Abstract):
+    _cv: contextvars.ContextVar
+
+    def __init_subclass__(cls, **kwargs: ta.Any) -> None:
+        super().__init_subclass__(**kwargs)
+
+        check.not_in(Abstract, cls.__bases__)
+        check.not_in(abc.ABC, cls.__bases__)
+        check.state(not hasattr(cls, '_cv'))
+        cls._cv = contextvars.ContextVar(f'{cls.__name__}_cv')
+
+    def state(self) -> InjectorScope.State:
+        return self._cv.get()
+
+    @contextlib.contextmanager
+    def enter(self, vs: ta.Mapping[InjectorKey, ta.Any]) -> ta.Iterator[None]:
+        try:
+            self._cv.get()
+        except LookupError:
+            pass
+        else:
+            raise RuntimeError(f'Scope already entered: {self}')
+        st = self.new_state(vs)
+        tok = self._cv.set(st)
+        try:
+            yield
+        finally:
+            self._cv.reset(tok)
+
+
+#
+
+
+@dc.dataclass(frozen=True)
+class ScopedInjectorProvider(InjectorProvider):
+    p: InjectorProvider
+    k: InjectorKey
+    sc: ta.Type[InjectorScope]
+
+    def __post_init__(self) -> None:
+        check.isinstance(self.p, InjectorProvider)
+        check.isinstance(self.k, InjectorKey)
+        check.issubclass(self.sc, InjectorScope)
+
+    def provider_fn(self) -> InjectorProviderFn:
+        def pfn(i: Injector) -> ta.Any:
+            st = i[self.sc].state()
+            try:
+                return st.provisions[self.k]
+            except KeyError:
+                pass
+            v = ufn(i)
+            st.provisions[self.k] = v
+            return v
+
+        ufn = self.p.provider_fn()
+        return pfn
+
+
+@dc.dataclass(frozen=True)
+class _ScopeSeedInjectorProvider(InjectorProvider):
+    k: InjectorKey
+    sc: ta.Type[InjectorScope]
+
+    def __post_init__(self) -> None:
+        check.isinstance(self.k, InjectorKey)
+        check.issubclass(self.sc, InjectorScope)
+
+    def provider_fn(self) -> InjectorProviderFn:
+        def pfn(i: Injector) -> ta.Any:
+            st = i[self.sc].state()
+            return st.seeds[self.k]
+        return pfn
+
+
+def bind_injector_scope(sc: ta.Type[InjectorScope]) -> InjectorBindingOrBindings:
+    return InjectorBinder.bind(sc, singleton=True)
+
+
+#
+
+
+@dc.dataclass(frozen=True)
+class _InjectorScopeSeed:
+    sc: ta.Type['InjectorScope']
+    k: InjectorKey
+
+    def __post_init__(self) -> None:
+        check.issubclass(self.sc, InjectorScope)
+        check.isinstance(self.k, InjectorKey)
+
+
+def bind_injector_scope_seed(k: ta.Any, sc: ta.Type[InjectorScope]) -> InjectorBindingOrBindings:
+    kk = as_injector_key(k)
+    return as_injector_bindings(
+        InjectorBinding(kk, _ScopeSeedInjectorProvider(kk, sc)),
+        InjectorBinder.bind(_InjectorScopeSeed(sc, kk), array=True),
+    )
+
+
+###
+# inspection
+
+
+class _InjectionInspection(ta.NamedTuple):
+    signature: inspect.Signature
+    type_hints: ta.Mapping[str, ta.Any]
+    args_offset: int
+
+
+_INJECTION_INSPECTION_CACHE: ta.MutableMapping[ta.Any, _InjectionInspection] = weakref.WeakKeyDictionary()
+
+
+def _do_injection_inspect(obj: ta.Any) -> _InjectionInspection:
+    tgt = obj
+
+    # inspect.signature(eval_str=True) was added in 3.10 and we have to support 3.8, so we have to get_type_hints to
+    # eval str annotations *in addition to* getting the signature for parameter information.
+    uw = tgt
+    has_partial = False
+    while True:
+        if isinstance(uw, functools.partial):
+            uw = uw.func
+            has_partial = True
+        else:
+            if (uw2 := inspect.unwrap(uw)) is uw:
+                break
+            uw = uw2
+
+    has_args_offset = False
+
+    if isinstance(tgt, type) and tgt.__new__ is not object.__new__:
+        # Python 3.8's inspect.signature can't handle subclasses overriding __new__, always generating *args/**kwargs.
+        #  - https://bugs.python.org/issue40897
+        #  - https://github.com/python/cpython/commit/df7c62980d15acd3125dfbd81546dad359f7add7
+        tgt = tgt.__init__  # type: ignore[misc]
+        has_args_offset = True
+
+    if tgt in (object.__init__, object.__new__):
+        # inspect strips self for types but not the underlying methods.
+        def dummy(self):
+            pass
+        tgt = dummy
+        has_args_offset = True
+
+    if has_partial and has_args_offset:
+        # TODO: unwrap partials masking parameters like modern python
+        raise InjectorError(
+            'Injector inspection does not currently support both an args offset and a functools.partial: '
+            f'{obj}',
+        )
+
+    return _InjectionInspection(
+        inspect.signature(tgt),
+        ta.get_type_hints(uw),
+        1 if has_args_offset else 0,
+    )
+
+
+def _injection_inspect(obj: ta.Any) -> _InjectionInspection:
+    try:
+        return _INJECTION_INSPECTION_CACHE[obj]
+    except TypeError:
+        return _do_injection_inspect(obj)
+    except KeyError:
+        pass
+    insp = _do_injection_inspect(obj)
+    _INJECTION_INSPECTION_CACHE[obj] = insp
+    return insp
+
+
+class InjectionKwarg(ta.NamedTuple):
+    name: str
+    key: InjectorKey
+    has_default: bool
+
+
+class InjectionKwargsTarget(ta.NamedTuple):
+    obj: ta.Any
+    kwargs: ta.Sequence[InjectionKwarg]
+
+
+def build_injection_kwargs_target(
+        obj: ta.Any,
+        *,
+        skip_args: int = 0,
+        skip_kwargs: ta.Optional[ta.Iterable[str]] = None,
+        raw_optional: bool = False,
+) -> InjectionKwargsTarget:
+    insp = _injection_inspect(obj)
+
+    params = list(insp.signature.parameters.values())
+
+    skip_names: ta.Set[str] = set()
+    if skip_kwargs is not None:
+        skip_names.update(check.not_isinstance(skip_kwargs, str))
+
+    seen: ta.Set[InjectorKey] = set()
+    kws: ta.List[InjectionKwarg] = []
+    for p in params[insp.args_offset + skip_args:]:
+        if p.name in skip_names:
+            continue
+
+        if p.annotation is inspect.Signature.empty:
+            if p.default is not inspect.Parameter.empty:
+                raise KeyError(f'{obj}, {p.name}')
+            continue
+
+        if p.kind not in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY):
+            raise TypeError(insp)
+
+        # 3.8 inspect.signature doesn't eval_str but typing.get_type_hints does, so prefer that.
+        ann = insp.type_hints.get(p.name, p.annotation)
+        if (
+                not raw_optional and
+                is_optional_alias(ann)
+        ):
+            ann = get_optional_alias_arg(ann)
+
+        k = as_injector_key(ann)
+
+        if k in seen:
+            raise DuplicateInjectorKeyError(k)
+        seen.add(k)
+
+        kws.append(InjectionKwarg(
+            p.name,
+            k,
+            p.default is not inspect.Parameter.empty,
+        ))
+
+    return InjectionKwargsTarget(
+        obj,
+        kws,
+    )
+
+
+###
+# injector
+
+
+_INJECTOR_INJECTOR_KEY: InjectorKey[Injector] = InjectorKey(Injector)
+
+
+@dc.dataclass(frozen=True)
+class _InjectorEager:
+    key: InjectorKey
+
+
+_INJECTOR_EAGER_ARRAY_KEY: InjectorKey[_InjectorEager] = InjectorKey(_InjectorEager, array=True)
+
+
+class _Injector(Injector):
+    _DEFAULT_BINDINGS: ta.ClassVar[ta.List[InjectorBinding]] = []
+
+    def __init__(self, bs: InjectorBindings, p: ta.Optional[Injector] = None) -> None:
+        super().__init__()
+
+        self._bs = check.isinstance(bs, InjectorBindings)
+        self._p: ta.Optional[Injector] = check.isinstance(p, (Injector, type(None)))
+
+        self._pfm = {
+            k: v.provider_fn()
+            for k, v in build_injector_provider_map(as_injector_bindings(
+                *self._DEFAULT_BINDINGS,
+                bs,
+            )).items()
+        }
+
+        if _INJECTOR_INJECTOR_KEY in self._pfm:
+            raise DuplicateInjectorKeyError(_INJECTOR_INJECTOR_KEY)
+
+        self.__cur_req: ta.Optional[_Injector._Request] = None
+
+        if _INJECTOR_EAGER_ARRAY_KEY in self._pfm:
+            for e in self.provide(_INJECTOR_EAGER_ARRAY_KEY):
+                self.provide(e.key)
+
+    class _Request:
+        def __init__(self, injector: '_Injector') -> None:
+            super().__init__()
+
+            self._injector = injector
+            self._provisions: ta.Dict[InjectorKey, Maybe] = {}
+            self._seen_keys: ta.Set[InjectorKey] = set()
+
+        def handle_key(self, key: InjectorKey) -> Maybe[Maybe]:
+            try:
+                return Maybe.just(self._provisions[key])
+            except KeyError:
+                pass
+            if key in self._seen_keys:
+                raise CyclicDependencyInjectorKeyError(key)
+            self._seen_keys.add(key)
+            return Maybe.empty()
+
+        def handle_provision(self, key: InjectorKey, mv: Maybe) -> Maybe:
+            check.in_(key, self._seen_keys)
+            check.not_in(key, self._provisions)
+            self._provisions[key] = mv
+            return mv
+
+    @contextlib.contextmanager
+    def _current_request(self) -> ta.Generator[_Request, None, None]:
+        if (cr := self.__cur_req) is not None:
+            yield cr
+            return
+
+        cr = self._Request(self)
+        try:
+            self.__cur_req = cr
+            yield cr
+        finally:
+            self.__cur_req = None
+
+    def try_provide(self, key: ta.Any) -> Maybe[ta.Any]:
+        key = as_injector_key(key)
+
+        cr: _Injector._Request
+        with self._current_request() as cr:
+            if (rv := cr.handle_key(key)).present:
+                return rv.must()
+
+            if key == _INJECTOR_INJECTOR_KEY:
+                return cr.handle_provision(key, Maybe.just(self))
+
+            fn = self._pfm.get(key)
+            if fn is not None:
+                return cr.handle_provision(key, Maybe.just(fn(self)))
+
+            if self._p is not None:
+                pv = self._p.try_provide(key)
+                if pv is not None:
+                    return cr.handle_provision(key, Maybe.empty())
+
+            return cr.handle_provision(key, Maybe.empty())
+
+    def provide(self, key: ta.Any) -> ta.Any:
+        v = self.try_provide(key)
+        if v.present:
+            return v.must()
+        raise UnboundInjectorKeyError(key)
+
+    def provide_kwargs(
+            self,
+            obj: ta.Any,
+            *,
+            skip_args: int = 0,
+            skip_kwargs: ta.Optional[ta.Iterable[ta.Any]] = None,
+    ) -> ta.Mapping[str, ta.Any]:
+        kt = build_injection_kwargs_target(
+            obj,
+            skip_args=skip_args,
+            skip_kwargs=skip_kwargs,
+        )
+
+        ret: ta.Dict[str, ta.Any] = {}
+        for kw in kt.kwargs:
+            if kw.has_default:
+                if not (mv := self.try_provide(kw.key)).present:
+                    continue
+                v = mv.must()
+            else:
+                v = self.provide(kw.key)
+            ret[kw.name] = v
+        return ret
+
+    def inject(
+            self,
+            obj: ta.Any,
+            *,
+            args: ta.Optional[ta.Sequence[ta.Any]] = None,
+            kwargs: ta.Optional[ta.Mapping[str, ta.Any]] = None,
+    ) -> ta.Any:
+        provided = self.provide_kwargs(
+            obj,
+            skip_args=len(args) if args is not None else 0,
+            skip_kwargs=kwargs if kwargs is not None else None,
+        )
+
+        return obj(
+            *(args if args is not None else ()),
+            **(kwargs if kwargs is not None else {}),
+            **provided,
+        )
+
+
+###
+# binder
+
+
+class InjectorBinder:
+    def __new__(cls, *args, **kwargs):  # noqa
+        raise TypeError
+
+    _FN_TYPES: ta.ClassVar[ta.Tuple[type, ...]] = (
+        types.FunctionType,
+        types.MethodType,
+
+        classmethod,
+        staticmethod,
+
+        functools.partial,
+        functools.partialmethod,
+    )
+
+    @classmethod
+    def _is_fn(cls, obj: ta.Any) -> bool:
+        return isinstance(obj, cls._FN_TYPES)
+
+    @classmethod
+    def bind_as_fn(cls, icls: ta.Type[T]) -> ta.Type[T]:
+        check.isinstance(icls, type)
+        if icls not in cls._FN_TYPES:
+            cls._FN_TYPES = (*cls._FN_TYPES, icls)
+        return icls
+
+    _BANNED_BIND_TYPES: ta.ClassVar[ta.Tuple[type, ...]] = (
+        InjectorProvider,
+    )
+
+    @classmethod
+    def bind(
+            cls,
+            obj: ta.Any,
+            *,
+            key: ta.Any = None,
+            tag: ta.Any = None,
+            array: ta.Optional[bool] = None,  # noqa
+
+            to_fn: ta.Any = None,
+            to_ctor: ta.Any = None,
+            to_const: ta.Any = None,
+            to_key: ta.Any = None,
+
+            in_: ta.Optional[ta.Type[InjectorScope]] = None,
+            singleton: bool = False,
+
+            eager: bool = False,
+    ) -> InjectorBindingOrBindings:
+        if obj is None or obj is inspect.Parameter.empty:
+            raise TypeError(obj)
+        if isinstance(obj, cls._BANNED_BIND_TYPES):
+            raise TypeError(obj)
+
+        #
+
+        if key is not None:
+            key = as_injector_key(key)
+
+        #
+
+        has_to = (
+            to_fn is not None or
+            to_ctor is not None or
+            to_const is not None or
+            to_key is not None
+        )
+        if isinstance(obj, InjectorKey):
+            if key is None:
+                key = obj
+        elif isinstance(obj, type):
+            if not has_to:
+                to_ctor = obj
+            if key is None:
+                key = InjectorKey(obj)
+        elif cls._is_fn(obj) and not has_to:
+            to_fn = obj
+            if key is None:
+                insp = _injection_inspect(obj)
+                key_cls: ta.Any = check_valid_injector_key_cls(check.not_none(insp.type_hints.get('return')))
+                key = InjectorKey(key_cls)
+        else:
+            if to_const is not None:
+                raise TypeError('Cannot bind instance with to_const')
+            to_const = obj
+            if key is None:
+                key = InjectorKey(type(obj))
+        del has_to
+
+        #
+
+        if tag is not None:
+            if key.tag is not None:
+                raise TypeError('Tag already set')
+            key = dc.replace(key, tag=tag)
+
+        if array is not None:
+            key = dc.replace(key, array=array)
+
+        #
+
+        providers: ta.List[InjectorProvider] = []
+        if to_fn is not None:
+            providers.append(FnInjectorProvider(to_fn))
+        if to_ctor is not None:
+            providers.append(CtorInjectorProvider(to_ctor))
+        if to_const is not None:
+            providers.append(ConstInjectorProvider(to_const))
+        if to_key is not None:
+            providers.append(LinkInjectorProvider(as_injector_key(to_key)))
+        if not providers:
+            raise TypeError('Must specify provider')
+        if len(providers) > 1:
+            raise TypeError('May not specify multiple providers')
+        provider = check.single(providers)
+
+        #
+
+        pws: ta.List[ta.Any] = []
+        if in_ is not None:
+            check.issubclass(in_, InjectorScope)
+            check.not_in(Abstract, in_.__bases__)
+            pws.append(functools.partial(ScopedInjectorProvider, k=key, sc=in_))
+        if singleton:
+            pws.append(SingletonInjectorProvider)
+        if len(pws) > 1:
+            raise TypeError('May not specify multiple provider wrappers')
+        elif pws:
+            provider = check.single(pws)(provider)
+
+        #
+
+        binding = InjectorBinding(key, provider)
+
+        #
+
+        extras: ta.List[InjectorBinding] = []
+
+        if eager:
+            extras.append(bind_injector_eager_key(key))
+
+        #
+
+        if extras:
+            return as_injector_bindings(binding, *extras)
+        else:
+            return binding
+
+
+###
+# injection helpers
+
+
+def make_injector_factory(
+        fn: ta.Callable[..., T],
+        cls: U,
+        ann: ta.Any = None,
+) -> ta.Callable[..., U]:
+    if ann is None:
+        ann = cls
+
+    def outer(injector: Injector) -> ann:
+        def inner(*args, **kwargs):
+            return injector.inject(fn, args=args, kwargs=kwargs)
+        return cls(inner)  # type: ignore
+
+    return outer
+
+
+def bind_injector_array(
+        obj: ta.Any = None,
+        *,
+        tag: ta.Any = None,
+) -> InjectorBindingOrBindings:
+    key = as_injector_key(obj)
+    if tag is not None:
+        if key.tag is not None:
+            raise ValueError('Must not specify multiple tags')
+        key = dc.replace(key, tag=tag)
+
+    if key.array:
+        raise ValueError('Key must not be array')
+
+    return InjectorBinding(
+        dc.replace(key, array=True),
+        ArrayInjectorProvider([]),
+    )
+
+
+def make_injector_array_type(
+        ele: ta.Union[InjectorKey, InjectorKeyCls],
+        cls: U,
+        ann: ta.Any = None,
+) -> ta.Callable[..., U]:
+    if isinstance(ele, InjectorKey):
+        if not ele.array:
+            raise InjectorError('Provided key must be array', ele)
+        key = ele
+    else:
+        key = dc.replace(as_injector_key(ele), array=True)
+
+    if ann is None:
+        ann = cls
+
+    def inner(injector: Injector) -> ann:
+        return cls(injector.provide(key))  # type: ignore[operator]
+
+    return inner
+
+
+def bind_injector_eager_key(key: ta.Any) -> InjectorBinding:
+    return InjectorBinding(_INJECTOR_EAGER_ARRAY_KEY, ConstInjectorProvider(_InjectorEager(as_injector_key(key))))
+
+
+###
+# api
+
+
+class InjectionApi:
+    # keys
+
+    def as_key(self, o: ta.Any) -> InjectorKey:
+        return as_injector_key(o)
+
+    def array(self, o: ta.Any) -> InjectorKey:
+        return dc.replace(as_injector_key(o), array=True)
+
+    def tag(self, o: ta.Any, t: ta.Any) -> InjectorKey:
+        return dc.replace(as_injector_key(o), tag=t)
+
+    # bindings
+
+    def as_bindings(self, *args: InjectorBindingOrBindings) -> InjectorBindings:
+        return as_injector_bindings(*args)
+
+    # overrides
+
+    def override(self, p: InjectorBindings, *args: InjectorBindingOrBindings) -> InjectorBindings:
+        return injector_override(p, *args)
+
+    # scopes
+
+    def bind_scope(self, sc: ta.Type[InjectorScope]) -> InjectorBindingOrBindings:
+        return bind_injector_scope(sc)
+
+    def bind_scope_seed(self, k: ta.Any, sc: ta.Type[InjectorScope]) -> InjectorBindingOrBindings:
+        return bind_injector_scope_seed(k, sc)
+
+    # injector
+
+    def create_injector(self, *args: InjectorBindingOrBindings, parent: ta.Optional[Injector] = None) -> Injector:
+        return _Injector(as_injector_bindings(*args), parent)
+
+    # binder
+
+    def bind(
+            self,
+            obj: ta.Any,
+            *,
+            key: ta.Any = None,
+            tag: ta.Any = None,
+            array: ta.Optional[bool] = None,  # noqa
+
+            to_fn: ta.Any = None,
+            to_ctor: ta.Any = None,
+            to_const: ta.Any = None,
+            to_key: ta.Any = None,
+
+            in_: ta.Optional[ta.Type[InjectorScope]] = None,
+            singleton: bool = False,
+
+            eager: bool = False,
+    ) -> InjectorBindingOrBindings:
+        return InjectorBinder.bind(
+            obj,
+
+            key=key,
+            tag=tag,
+            array=array,
+
+            to_fn=to_fn,
+            to_ctor=to_ctor,
+            to_const=to_const,
+            to_key=to_key,
+
+            in_=in_,
+            singleton=singleton,
+
+            eager=eager,
+        )
+
+    # helpers
+
+    def bind_factory(
+            self,
+            fn: ta.Callable[..., T],
+            cls_: U,
+            ann: ta.Any = None,
+    ) -> InjectorBindingOrBindings:
+        return self.bind(make_injector_factory(fn, cls_, ann))
+
+    def bind_array(
+            self,
+            obj: ta.Any = None,
+            *,
+            tag: ta.Any = None,
+    ) -> InjectorBindingOrBindings:
+        return bind_injector_array(obj, tag=tag)
+
+    def bind_array_type(
+            self,
+            ele: ta.Union[InjectorKey, InjectorKeyCls],
+            cls_: U,
+            ann: ta.Any = None,
+    ) -> InjectorBindingOrBindings:
+        return self.bind(make_injector_array_type(ele, cls_, ann))
+
+
+inj = InjectionApi()