Method ask

returns/context/requires_context.py:234–313

Get current context to use the dependencies. It is a common scenario when you need to use the environment. For example, you want to do some context-related computation, but you don't have the context instance at your disposal. That's where ``.ask()`` becomes

(cls)

    @classmethod
    def ask(cls) -> RequiresContext[_EnvType_contra, _EnvType_contra]:
        """
        Get current context to use the dependencies.

        It is a common scenario when you need to use the environment.
        For example, you want to do some context-related computation,
        but you don't have the context instance at your disposal.
        That's where ``.ask()`` becomes useful!

        .. code:: python

          >>> from typing_extensions import TypedDict
          >>> class Deps(TypedDict):
          ...     message: str

          >>> def first(lg: bool) -> RequiresContext[int, Deps]:
          ...     # `deps` has `Deps` type here:
          ...     return RequiresContext(
          ...         lambda deps: deps['message'] if lg else 'error',
          ...     )

          >>> def second(text: str) -> RequiresContext[int, Deps]:
          ...     return first(len(text) > 3)

          >>> assert second('abc')({'message': 'ok'}) == 'error'
          >>> assert second('abcd')({'message': 'ok'}) == 'ok'

        And now imagine that you have to change this ``3`` limit.
        And you want to be able to set it via environment as well.
        Ok, let's fix it with the power of ``RequiresContext.ask()``!

        .. code:: python

          >>> from typing_extensions import TypedDict
          >>> class Deps(TypedDict):
          ...     message: str
          ...     limit: int   # note this new field!

          >>> def new_first(lg: bool) -> RequiresContext[int, Deps]:
          ...     # `deps` has `Deps` type here:
          ...     return RequiresContext(
          ...         lambda deps: deps['message'] if lg else 'err',
          ...     )

          >>> def new_second(text: str) -> RequiresContext[int, Deps]:
          ...     return RequiresContext[int, Deps].ask().bind(
          ...         lambda deps: new_first(len(text) > deps.get('limit', 3)),
          ...     )

          >>> assert new_second('abc')({'message': 'ok', 'limit': 2}) == 'ok'
          >>> assert new_second('abcd')({'message': 'ok'}) == 'ok'
          >>> assert new_second('abcd')({'message': 'ok', 'limit': 5}) == 'err'

        That's how ``ask`` works.

        This class contains methods that require
        to explicitly set type annotations. Why?
        Because it is impossible to figure out the type without them.