clear-skies 2.0.3__py3-none-any.whl → 2.0.5__py3-none-any.whl

clearskies/di/di.py

@@ -1,968 +0,0 @@
-import datetime
-import inspect
-import os
-import re
-import sys
-from types import ModuleType
-from typing import Any, Callable
-
-import requests
-from requests.adapters import HTTPAdapter
-from requests.packages.urllib3.util.retry import Retry  # type: ignore
-
-import clearskies.input_outputs.input_output
-import clearskies.secrets
-from clearskies.di.additional_config import AdditionalConfig
-from clearskies.di.additional_config_auto_import import AdditionalConfigAutoImport
-from clearskies.environment import Environment
-from clearskies.functional import string
-
-
-class Di:
-    """
-    Build a dependency injection object.
-
-    The dependency injection (DI) container is a key part of clearskies, so understanding how to both configure
-    them and get dependencies for your classes is important.  Note however that you don't often have
-    to interact with the dependency injection container directly.  All of the configuration options for
-    the DI container are also available to all the contexts, which is typically how you will build clearskies
-    applications.  So, while you can create a DI container and use it directly, typically you'll just follow
-    the same basic techniques to configure your context and use that to run your application.
-
-    These are the main ways to configure the DI container:
-
-     1. Import classes - each imported class is assigned an injection name based on the class name.
-     2. Import modules - clearskies will iterate over the module and import all the classes and AdditionalConfigAutoImport classes it finds.
-     3. Import AdditionalConfig classes - these allow you to programmatically define dependencies.
-     4. Specify bindings - this allows you to provide any kind of value with whatever name you want.
-     5. Specify class overrides - these allow you to swap out classes directly.
-     6. Extending the Di class - this allows you to provide a default set of values.
-
-    When the DI system builds a class or calls a function, those classes and functions can themselves request any value
-    configured inside the DI container.  There are three ways to request the desired dependencies:
-
-     1. By type hinting a class on any arguments (excluding python built-ins)
-     2. By specifying the name of a registered dependency
-     3. By extending the `clearskies.di.AutoFillProps` class and creating class properties from the `clearskies.di.inject_from` module
-
-    Note that when a class is built/function is called by the DI container, keyword arguments are not allowed
-    (because the DI container doesn't know whether or not it should provide optional arguments).  In addition,
-    the DI container must be able to resolve all positional arguments.  If the class requests an argument
-    that the DI system does not recognize, an error will be thrown.  Finally, it's a common pattern in clearskies
-    for some portion of the system to accept functions that will be called by the DI container.  When this happens,
-    it's possible for clearskies to provide additional values that may be useful when executing the function.
-    The areas that accept functions like this also document the additional dependency injection names that are available.
-
-    Given the variety of ways that dependencies can be specified, it's important to understand the order the priority that
-    clearskies uses to determine what value to provide in case there is more than one source.  That order is:
-
-     1. Positional arguments with type hints:
-        1. The override class if the type-hinted class has a registered override
-        2. A value provided by an AdditionalConfig that can provide the type-hinted class
-        3. The class itself if the class has been added explicitly via add_classes or implicitly via add_modules
-        4. A clearskies built-in for predefined types
-     2. All other positional arguments will have values provided based on the argument name and will receive
-        1. Things set via `add_binding(name, value)`
-        2. Class added via `add_classes` or `add_modules` which are made available according to their Di name
-        3. An AdditionalConfig class with a corresponding `provide_[name]` function
-        4. A clearskies built-in for predefined names
-
-    Here is the list of predefined values with their names and types:
-
-    | Injection Name       | Injection Type                                          | Value                                                                                     |
-    |----------------------|---------------------------------------------------------|-------------------------------------------------------------------------------------------|
-    | di                   | -                                                       | The active Di container                                                                   |
-    | now                  | -                                                       | The current time in a datetime object, without timezone                                   |
-    | utcnow               | -                                                       | The current time in a datetime object, with timezone set to UTC                           |
-    | requests             | requests.Session                                        | A requests object configured to allow a small number of retries                           |
-    | input_output         | clearskies.input_outputs.InputOutput                    | The clearskies builtin used for receiving and sending data to the client                  |
-    | uuid                 | -                                                       | `import uuid` - the uuid module builtin to python                                         |
-    | environment          | clearskies.Environment                                  | A clearskies helper that access config info from the environment or a .env file           |
-    | sys                  | -                                                       | `import sys` - the sys module builtin to python                                           |
-    | oai3_schema_resolver | -                                                       | Used by the autodoc system                                                                |
-    | connection_details   | -                                                       | A dictionary containing credentials that pymysql should use when connecting to a database |
-    | connection           | -                                                       | A pymysql connection object                                                               |
-    | cursor               | -                                                       | A pymysql cursor object                                                                   |
-
-    Note: for dependencies with an injection name but no injection type, this means that to inject those values you
-    must name your argument with the given injection name.  In all of the above cases though you can still add type
-    hints if desired.  So, for instance, you can declare an argument of `utcnow: datetime.datetime`.  clearskies
-    will ignore the type hint (since `datetime.datetime` isn't a type with a predefined value in clearskies) and
-    identify the value based on the name of the argument.
-
-    Note: multiple `AdditionalConfig` classes can be added to the Di container, and so a single injection name or class
-    can potentially be provided by multiple AdditionalConfig classes.  AdditionalConfig classes are checked in the
-    reverse of the order they were addded in - classes added last are checked first when trying to find values.
-
-    Note: When importing modules, any classes that inherit from `AdditionalConfigAutoImport` are automatically added
-    to the list of additional config classes.  These classes are added at the top of the list, so they are lower
-    priority than any classes you add via `add_additional_configs` or the `additional_configs` argument of the Di
-    constructor.
-
-    Note: Once a value is constructed, it is cached by the Di container and will automatically be provided for future
-    references of that same Di name or class.  Arguments injected in a constructor will always receive the cached
-    value.  If you want a "fresh" value of a given dependency, you have to attach instances from the
-    `clearskies.di.inject` module onto class proprties.  The instances in the `inject` module generally
-    give options for cache control.
-
-    Here's an example that brings most of these pieces together.  Once again, note that we're directly using
-    the Di contianer to build class/call functions, while normally you configure the Di container via your context
-    and then clearskies itself will build your class or call your functions as needed.  Full explanation comes after
-    the example.
-
-    ```python
-    from clearskies.di import Di, AdditionalConfig
-
-
-    class SomeClass:
-        def __init__(self, my_value: int):
-            self.my_value = my_value
-
-
-    class MyClass:
-        def __init__(self, some_specific_value: int, some_class: SomeClass):
-            # `some_specific_value` is defined in both `MyProvider` and `MyOtherProvider`
-            # `some_class` will be injected from the type hint, and the actual instance is made by our
-            # `MyProvider`
-            self.final_value = some_specific_value * some_class.my_value
-
-
-    class VeryNeedy:
-        def __init__(self, my_class, some_other_value: str):
-            # We're relying on the automatic conversion of class names to snake_case, so clearskies
-            # will connect `my_class` to `MyClass`, which we provided directly to the Di container.
-
-            # some_other_value is specified as a binding
-            self.my_class = my_class
-            self.some_other_value = some_other_value
-
-
-    class MyOtherProvider(AdditionalConfig):
-        def provide_some_specific_value(self):
-            # the order of additional configs will cause this function to be invoked
-            # (and hence some_specific_value will be `10`) despite the fact that MyProvider
-            # also has a `provide_` function with the same name.
-            return 10
-
-
-    class MyProvider(AdditionalConfig):
-        def provide_some_specific_value(self):
-            # note that the name of our function matches the name of the argument
-            # expected by MyClass.__init__.  Again though, we won't get called because
-            # the order the AdditionalConfigs are loaded gives `MyOtherProvider` priority.
-            return 5
-
-        def can_build_class(self, class_to_check: type) -> bool:
-            # this lets the DI container know that if someone wants an instance
-            # of SomeClass, we can build it.
-            return class_to_check == SomeClass
-
-        def build_class(self, class_to_provide: type, argument_name: str, di, context: str = ""):
-            if class_to_provide == SomeClass:
-                return SomeClass(5)
-            raise ValueError(
-                f"I was asked to build a class I didn't expect '{class_to_provide.__name__}'"
-            )
-
-
-    di = Di(
-        classes=[MyClass, VeryNeedy, SomeClass],
-        additional_configs=[MyProvider(), MyOtherProvider()],
-        bindings={
-            "some_other_value": "dog",
-        },
-    )
-
-
-    def my_function(my_fancy_argument: VeryNeedy):
-        print(f"Jane owns {my_fancy_argument.my_class.final_value}:")
-        print(f"{my_fancy_argument.some_other_value}s")
-
-
-    print(di.call_function(my_function))
-    # prints 'Jane owns 50 dogs'
-    ```
-
-    When `call_function` is executed on `my_function`, the di system checks the calling arguments of `my_function`
-    and runs through the priority list above to populate them.  `my_function` has one argument -
-    `my_fancy_argument: VeryNeedy`, which it resolves as so:
-
-     1. The type hint (`VeryNeedy`) matches an imported class.  Therefore, clearskies will build an instance of VeryNeedy and
-        provide it for `my_fancy_argument`.
-     2. clearskies inpsects the constructor for `VeryNeedy` and finds two arguments, `my_class` and `some_other_value: str`,
-        which it attempts to build.
-        1. `my_class` has no type hint, so clearskies falls back on name-based resolution.  A class called `MyClass` was imported,
-           and per standard naming convention, this automatically becomes available via the name `my_class`.  Thus, clearskies
-           prepares to build an instance of `MyClass`. `MyClass` has two arguments: `some_specific_value: int` and
-           `some_class: SomeClass`
-           1. For `some_specific_value`, the Di service falls back on named-based resolution (because it will never try to
-              provide values for type-hints of built-in types).  Both `MyOtherProvider` and `MyProvider` have a method called
-              `provide_some_specific_value`, so both can be used to provide this value.  Since `MyOtherProvider` was added to
-              the Di container last, it takes priority.  Therefore, clearskies calls `MyOtherProvider.provide_some_specific_value`
-              to create the value that it will populate into the `some_specific_value` parameter.
-           2. For `some_class: SomeClass`, clearskies evaluates the type-hint.  It works through the additional configs and, since
-              `MyProvider` returns True when `can_build_class` is called with  `SomeClass`, the Di container will use this
-              additional config to create the value for the `some_class` argument.  Therefore, clearskies calls
-              `MyProvider.build_class(SomeClass, 'some_class', di)` and the return value is used for the `some_class` argument.
-        2. `some_other_value` uses a built-in for a type hint, so clearskies falls back on name-based resolution.  It falls back
-           on the registered binding of `"dog"` to the name `"some_other_value"`, so clearskies provides `"dog"`.
-    """
-
-    _added_modules: dict[int, bool] = {}
-    _additional_configs: list[AdditionalConfig] = []
-    _bindings: dict[str, Any] = {}
-    _building: dict[int, str] = {}
-    _classes: dict[str, dict[str, int | type]] = {}
-    _prepared: dict[str, Any] = {}
-    _class_overrides_by_name: dict[str, type] = {}
-    _class_overrides_by_class: dict[type, Any] = {}
-    _type_hint_disallow_list = [int, float, str, dict, list, datetime.datetime]
-    _now: datetime.datetime | None = None
-    _utcnow: datetime.datetime | None = None
-    _predefined_classes_name_map: dict[type, str] = {
-        requests.Session: "requests",
-        clearskies.input_outputs.input_output.InputOutput: "input_output",
-        Environment: "environment",
-    }
-
-    def __init__(
-        self,
-        classes: type | list[type] = [],
-        modules: ModuleType | list[ModuleType] = [],
-        bindings: dict[str, Any] = {},
-        additional_configs: AdditionalConfig | list[AdditionalConfig] = [],
-        class_overrides: dict[type, Any] = {},
-        overrides: dict[str, type] = {},
-        now: datetime.datetime | None = None,
-        utcnow: datetime.datetime | None = None,
-    ):
-        """
-        Create a dependency injection container.
-
-        For details on the parameters, see the related methods:
-
-        classes -> di.add_classes()
-        modules -> di.add_modules()
-        bindings -> di.add_binding()
-        additional_configs -> di.add_additional_configs()
-        class_overrides -> di.add_class_override()
-        """
-        self._added_modules = {}
-        self._additional_configs = []
-        self._bindings = {}
-        self._building = {}
-        self._classes = {}
-        self._class_overrides_by_name = {}
-        self._class_overrides_by_class = {}
-        self._prepared = {}
-        if classes is not None:
-            self.add_classes(classes)
-        if modules is not None:
-            self.add_modules(modules)
-        if bindings is not None:
-            for key, value in bindings.items():
-                self.add_binding(key, value)
-        if additional_configs is not None:
-            self.add_additional_configs(additional_configs)
-        if class_overrides:
-            for key, value in class_overrides.items():  # type: ignore
-                self.add_class_override(key, value)  # type: ignore
-        if overrides:
-            for key, value in overrides.items():
-                self.add_override(key, value)
-        if now:
-            self.set_now(now)
-        if utcnow:
-            self.set_utcnow(utcnow)
-
-    def add_classes(self, classes: type | list[type]) -> None:
-        """
-        Record any class that should be made available for injection.
-
-        All classes that come in here become available via their injection name, which is calculated
-        by converting the class name from TitleCase to snake_case.  e.g. the following class:
-
-        ```python
-        class MyClass:
-            pass
-        ```
-
-        gets an injection name of `my_class`.  Also, clearskies will only resolve and reject based on type hints
-        if those classes are first added via `add_classes`.  See the following example:
-
-        ```python
-        from clearskies.di import Di
-
-        class MyClass:
-            name = "Simple Demo"
-
-        di = Di(classes=[MyClass])
-        # equivalent: di.add_classes(MyClass), di.add_classes([MyClass])
-
-        def my_function(my_class):
-            print(my_class.name)
-
-        def my_function_with_type_hinting(the_name_no_longer_matters: MyClass):
-            print(my-class.name)
-
-        # both print 'Simple Demo'
-        di.call_function(my_function)
-        di.call_function(my_function_with_type_hinting)
-        ```
-        """
-        if not isinstance(classes, list):
-            classes = [classes]
-        for add_class in classes:
-            name = string.camel_case_to_snake_case(add_class.__name__)
-            self._classes[name] = {"id": id(add_class), "class": add_class}
-            self._classes[add_class] = {"id": id(add_class), "class": add_class}  # type: ignore
-
-            # if this is a model class then also add a plural version of its name
-            # to the DI configuration
-            if hasattr(add_class, "id_column_name"):
-                self._classes[string.make_plural(name)] = {"id": id(add_class), "class": add_class}
-
-    def add_modules(
-        self, modules: ModuleType | list[ModuleType], root: str | None = None, is_root: bool = True
-    ) -> None:
-        """
-        Add a module to the dependency injection container.
-
-        clearskies will iterate through the module, adding all imported classes into the dependency injection container.
-
-        So, consider the following file structure inside a module:
-
-        ```
-        my_module/
-            __init__.py
-            my_sub_module/
-                __init__.py
-                my_class.py
-        ```
-
-        Assuming that the submodule and class are imported at each level (e.g. my_module/__init__.py imports my_sub_module,
-        and my_sub_module/__init__.py imports my_class.py) then you can:
-
-        ```python
-        from clearksies.di import Di
-        import my_module
-
-        di = Di()
-        di.add_modules([
-            my_module
-        ])  # also equivalent: di.add_modules(my_module), or Di(modules=[my_module])
-
-
-        def my_function(my_class):
-            pass
-
-
-        di.call_function(my_function)
-        ```
-
-        `my_function` will be called and `my_class` will automatically be populated with an instance of
-        `my_module.sub_module.my_class.MyClass`.
-
-        Note that MyClass will be able to declare its own dependencies per normal dependency injection rules.
-        See the main docblock in the clearskies.di.Di class for more details about how all the pieces work together.
-        """
-        if not isinstance(modules, list):
-            modules = [modules]
-
-        for module in modules:
-            # skip internal python modules
-            if not hasattr(module, "__file__") or not module.__file__:
-                continue
-            module_id = id(module)
-            if is_root:
-                root = os.path.dirname(module.__file__)
-            root_len = len(root) if root else 0
-            if module_id in self._added_modules:
-                continue
-            self._added_modules[module_id] = True
-
-            for name, item in module.__dict__.items():
-                if inspect.isclass(item):
-                    try:
-                        class_root = os.path.dirname(inspect.getfile(item))
-                    except TypeError:
-                        # built-ins will end up here
-                        continue
-                    if class_root[:root_len] != root:
-                        continue
-                    if issubclass(item, AdditionalConfigAutoImport):
-                        init_args = inspect.getfullargspec(item)
-                        nargs = len(init_args.args) if init_args.args else 0
-                        nkwargs = len(init_args.defaults) if init_args.defaults else 0
-                        if nargs - 1 - nkwargs > 0:
-                            raise ValueError(
-                                "Error auto-importing additional config "
-                                + item.__name__
-                                + ": auto imported configs can only have keyword arguments."
-                            )
-                        self.add_additional_configs([item()])
-                        continue
-                    self.add_classes([item])
-                if inspect.ismodule(item):
-                    if not hasattr(item, "__file__") or not item.__file__:
-                        continue
-                    child_root = os.path.dirname(item.__file__)
-                    if child_root[:root_len] != root:
-                        continue
-                    if module.__name__ == "clearskies":
-                        break
-                    self.add_modules([item], root=root, is_root=False)
-
-    def add_additional_configs(self, additional_configs: AdditionalConfig | list[AdditionalConfig]) -> None:
-        """
-        Add an additional config instance to the dependency injection container.
-
-        Additional config class provide an additional way to provide dependencies into the dependency
-        injection system.  For more details about how to use them, see both base classes:
-
-         1. clearskies.di.additional_config.AdditionalConfig
-         2. clearskies.di.additional_config_auto_import.AdditionalConfigAutoImport
-
-        To use this method:
-
-        ```python
-        import clearskies.di
-
-
-        class MyConfig(clearskies.di.AdditionalConfig):
-            def provide_some_value(self):
-                return 2
-
-            def provide_another_value(self, some_value):
-                return some_value * 2
-
-
-        di = clearskies.di.Di()
-        di.add_additional_configs([MyConfig()])
-        # equivalents:
-        # di.add_additional_configs(MyConfig())
-        # di = clearskies.di.Di(additional_configs=[MyConfig()])
-
-
-        def my_function(another_value):
-            print(another_value)  # prints 4
-
-
-        di.call_function(my_function)
-        ```
-        """
-        if not isinstance(additional_configs, list):
-            additional_configs = [additional_configs]
-        self._additional_configs.extend(additional_configs)
-
-    def add_binding(self, key, value):
-        """
-        Provide a specific value for name-based injection.
-
-        This method attaches a value to a specific dependency injection name.
-
-        ```python
-        import clearskies.di
-
-        di = clearskies.di.Di()
-        di.add_binding("my_name", 12345)
-        # equivalent:
-        # di = clearskies.di.Di(bindings={"my_name": 12345})
-
-
-        def my_function(my_name):
-            print(my_name)  # prints 12345
-
-
-        di.call_function(my_function)
-        ```
-        """
-        if key in self._building:
-            raise KeyError(f"Attempt to set binding for '{key}' while '{key}' was already being built")
-
-        # classes are placed in self._bindings, but any other prepared value goes straight into self._prepared
-        if inspect.isclass(value):
-            self._bindings[key] = value
-            if key in self._prepared:
-                del self._prepared[key]
-        else:
-            self._prepared[key] = value
-
-    def add_class_override(self, class_to_override: type, replacement: Any) -> None:
-        """
-        Override a class for type-based injection.
-
-        This function allows you to replace/mock class provided when relying on type hinting for injection.
-        This is most often (but not exclusively) used for mocking out classes during texting.  Note that
-        this only overrides that specific class - not classes that extend it.
-
-        Example:
-        ```python
-        from clearskies.import Di
-
-        class TypeHintedClass:
-            my_value = 5
-
-        class ReplacementClass:
-            my_value = 10
-
-        di = Di()
-        di.add_classes(TypeHintedClass)
-        di.add_class_override(TypeHintedClass, ReplacementClass)
-        # also di = Di(class_overrides={TypeHintedClass: ReplacementClass})
-
-        def my_function(some_value: TypeHintedClass):
-            print(some_value.my_value) # prints 10
-
-        di.call_function(my_function)
-        ```
-        """
-        if not inspect.isclass(class_to_override):
-            raise ValueError(
-                "Invalid value passed to add_class_override for 'class_or_name' parameter: it was neither a name nor a class"
-            )
-
-        self._class_overrides_by_class[class_to_override] = replacement
-
-    def has_class_override(self, class_to_check: type) -> bool:
-        return class_to_check in self._class_overrides_by_class
-
-    def get_override_by_class(self, object_to_override: Any) -> Any:
-        if object_to_override.__class__ not in self._class_overrides_by_class:
-            return object_to_override
-
-        override = self._class_overrides_by_class[object_to_override.__class__]
-        if inspect.isclass(override):
-            return self.build_class(override)
-        if hasattr(override, "injectable_properties"):
-            override.injectable_properties(self)
-        return override
-
-    def add_override(self, name: str, replacement_class: type) -> None:
-        """Override a specific injection name by specifying a class that should be injected in its place."""
-        if not inspect.isclass(replacement_class):
-            raise ValueError(
-                "Invalid value passed to add_override for 'replacement_class' parameter: a class should be passed but I got a "
-                + str(type(replacement_class))
-            )
-
-        self._class_overrides_by_name[name] = replacement_class
-
-    def set_now(self, now: datetime.datetime) -> None:
-        """Set the current time which will be passed along to any dependency arguments named `now`."""
-        if now.tzinfo is not None:
-            raise ValueError(
-                "set_now() was passed a datetime object with timezone information - it should only be given timezone-naive datetime objects.  Maybe you meant to use di.set_utcnow()"
-            )
-        self._now = now
-
-    def set_utcnow(self, utcnow: datetime.datetime) -> None:
-        """Set the current time which will be passed along to any dependency arguments named `utcnow`."""
-        if not utcnow.tzinfo:
-            raise ValueError(
-                "set_utcnow() was passed a datetime object without timezone information - it should only be given timezone-aware datetime objects.  Maybe you meant to use di.set_now()"
-            )
-        self._utcnow = utcnow
-
-    def build(self, thing: Any, context: str | None = None, cache: bool = False) -> Any:
-        """
-        Have the dependency injection container build a value for you.
-
-        This will accept either a dependency injection name or a class.
-        """
-        if inspect.isclass(thing):
-            return self.build_class(thing, context=context, cache=cache)
-        elif type(thing) == str:
-            return self.build_from_name(thing, context=context, cache=cache)
-        elif callable(thing):
-            raise ValueError("build received a callable: you probably want to use di.call_function()")
-
-        # if we got here then our thing is already and object of some sort and doesn't need anything further
-        return thing
-
-    def build_from_name(self, name: str, context: str | None = None, cache: bool = False) -> Any:
-        """
-        Build a dependency based on its name.
-
-        Order of priority:
-          1. Things set via `add_binding(name, value)`
-          2. Class added via `add_classes` or `add_modules` which are made available according to their Di name
-          3. An AdditionalConfig class with a corresponding `provide_[name]` function
-          4. The Di class itself if it has a matching `provide_[name]` function (aka the builtins)
-        """
-        if name in self._prepared and cache:
-            return self._prepared[name]
-
-        if name in self._bindings:
-            built_value = self.build(self._bindings[name], context=context)
-            if cache:
-                self._prepared[name] = built_value
-            return built_value
-
-        if name in self._classes or name in self._class_overrides_by_name:
-            class_to_build = (
-                self._class_overrides_by_name[name]
-                if name in self._class_overrides_by_name
-                else self._classes[name]["class"]
-            )  # type: ignore
-            built_value = self.build_class(class_to_build, context=context)  # type: ignore
-            if cache:
-                self._prepared[name] = built_value  # type: ignore
-            return built_value
-
-        # additional configs are meant to override ones that come before, with most recent ones
-        # taking precedence.  Therefore, start at the end (e.g. FILO instead of FIFO, except nothing actually leaves)
-        for index in range(len(self._additional_configs) - 1, -1, -1):
-            additional_config = self._additional_configs[index]
-            if not additional_config.can_build(name):
-                continue
-            built_value = additional_config.build(name, self, context if context else "")
-            if cache and additional_config.can_cache(name, self, context if context else ""):
-                self._prepared[name] = built_value
-            return built_value
-
-        if hasattr(self, f"provide_{name}"):
-            built_value = self.call_function(getattr(self, f"provide_{name}"))
-            if cache and self.can_cache(name, context if context else ""):
-                self._prepared[name] = built_value
-            return built_value
-
-        # why twice?  When a "concrete" value is bound directly to a DI name, it is just
-        # put directly in the cache.  Therefore, if cache=False, we won't find it (which is a bug).
-        # Therefore, if we get to the very bottom, haven't found anything, but it is in the
-        # cache: well, it's time to use the cache.
-        if name in self._prepared:
-            return self._prepared[name]
-
-        context_note = f" for {context}" if context else ""
-        raise ValueError(
-            f"I was asked to build {name}{context_note} but there is no added class, configured binding, "
-            + f"or a corresponding 'provide_{name}' method for this name."
-        )
-
-    def build_argument(self, argument_name: str, type_hint: type | None, context: str = "", cache: bool = True) -> Any:
-        """
-        Build an argument given the name and type hint.
-
-        Runs through the resolution order described in the docblock at the top of the Di class to build an argument given
-        its name and type-hint.
-        """
-        built_value = self.build_class_from_type_hint(argument_name, type_hint, context=context, cache=True)
-        if built_value is not None:
-            return built_value
-        return self.build_from_name(argument_name, context=context, cache=True)
-
-    def build_class(self, class_to_build: type, context=None, cache=True) -> Any:
-        """
-        Build a class.
-
-        The class constructor cannot accept any kwargs.   See self._disallow_kwargs for more details
-        """
-        if class_to_build in self._prepared and cache:
-            return self._prepared[class_to_build]  # type: ignore
-        my_class_name = class_to_build.__name__
-
-        init_args = inspect.getfullargspec(class_to_build)
-        if init_args.defaults is not None:
-            self._disallow_kwargs(f"build class '{class_to_build.__name__}'")
-
-        # ignore the first argument because that is just `self`
-        build_arguments = init_args.args[1:]
-        if not build_arguments:
-            if hasattr(class_to_build, "injectable_properties"):
-                class_to_build.injectable_properties(self)
-            built_value = class_to_build()
-            if cache:
-                self._prepared[class_to_build] = built_value  # type: ignore
-            return built_value
-
-        # self._building will help us keep track of what we're already building, and what we are building it for.
-        # This is partly to give better error messages, but mainly to detect cyclical dependency trees.
-        # We use id(class_to_build) because this uniquely identifies a class (while the name won't, since two
-        # different classes can have the same name but be in different modules).  Therefore, before we start
-        # building a class, see if its id is in self._building, raise an error if so, or continue if not.
-        class_id = id(class_to_build)
-        if class_id in self._building:
-            original_context_label = (
-                f"'{self._building[class_id]}'" if self._building[class_id] is not None else "itself"
-            )
-            raise ValueError(
-                f"Circular dependencies detected while building '{my_class_name}' because '"
-                + f"{my_class_name} is a dependency of both '{context}' and {original_context_label}"
-            )
-
-        self._building[class_id] = context
-        # Turn on caching when building the automatic dependencies that get injected into a class constructor
-        args = [
-            self.build_argument(
-                build_argument, init_args.annotations.get(build_argument, None), context=my_class_name, cache=True
-            )
-            for build_argument in build_arguments
-        ]
-
-        del self._building[class_id]
-
-        built_value = class_to_build(*args)
-        if hasattr(built_value, "injectable_properties"):
-            built_value.injectable_properties(self)
-        if cache:
-            self._prepared[class_to_build] = built_value  # type: ignore
-        return built_value
-
-    def build_class_from_type_hint(
-        self, argument_name: str, class_to_build: type | None, context: str = "", cache: bool = True
-    ) -> Any | None:
-        """
-        Build an argument from a type hint.
-
-        Note that in many cases we can't actually build the thing.  It may be a type hint of a built-in or some other value
-        that we're not configured to deal with.  In that case, just return None and the calling method will deal with it.
-
-        This follows the resolution order defined in the docblock of the Di class.
-        """
-        # these first checks just verify that it is something that we can actually build
-        if not class_to_build:
-            return None
-        if not callable(class_to_build):
-            return None
-        if inspect.isabstract(class_to_build):
-            return None
-
-        # then first things first: check our class overrides
-        if class_to_build in self._class_overrides_by_class:
-            return self.build_class(self._class_overrides_by_class[class_to_build], context=context, cache=cache)
-
-        # next check our additional config classes
-        built_value = None
-        can_cache = False
-        for index in range(len(self._additional_configs) - 1, -1, -1):
-            additional_config = self._additional_configs[index]
-            if not additional_config.can_build_class(class_to_build):
-                continue
-
-            built_value = additional_config.build_class(class_to_build, argument_name, self, context=context)
-            can_cache = additional_config.can_cache_class(class_to_build, self, context)
-            break
-
-        # a small handful of predefined classes
-        if class_to_build in self._predefined_classes_name_map:
-            dependency_name = self._predefined_classes_name_map[class_to_build]
-            built_value = self.call_function(getattr(self, f"provide_{dependency_name}"))
-            can_cache = self.can_cache(dependency_name, context if context else "")
-
-        # finally, if we found something, cache and/or return it
-        if built_value is not None:
-            if cache and can_cache:
-                self._prepared[class_to_build] = built_value  # type: ignore
-            return built_value
-
-        # last but not least we build the class itself as long as it has been imported into the Di system
-        if class_to_build in self._classes:
-            return self.build_class(class_to_build, context=context, cache=cache)
-
-        return None
-
-    def call_function(self, callable_to_execute: Callable, **kwargs):
-        """
-        Call a function, building any positional arguments and providing them.
-
-        Any kwargs passed to call_function will populate the equivalent dependencies.
-
-        ```python
-        from clearskies.di import Di
-
-        di = Di(bindings={"some_name": "hello"})
-
-
-        def my_function(some_name, some_other_name):
-            print(f"{some_name} {some_other_value}")  # prints 'hello world'
-
-
-        di.call_function(my_function, some_other_value="world")
-        ```
-        """
-        args_data = inspect.getfullargspec(callable_to_execute)
-
-        # we need to decide if we've been passed a bound method, because then we need to ignore the
-        # first argument (aka `self`).  The simplest way to do this is to check for the `__self__` attr,
-        # but this will be fooled by methods with decorators.  There doesn't seem to be a good solution to this
-        # that works in all cases: https://stackoverflow.com/a/50074581/1921979
-        call_arguments = args_data.args
-        if hasattr(callable_to_execute, "__self__"):
-            call_arguments = call_arguments[1:]
-
-        # separate out args and kwargs.  kwargs for the function are only allowed to come out of the kwargs
-        # we were passed.  If the function has a kwarg that we don't have, then ignore it.
-        # args come out of dependencies or the kwargs passed to us.  If an arg is missing, then throw an error.
-        nargs = len(call_arguments)
-        nkwargs = len(args_data.defaults) if args_data.defaults else 0
-        arg_names = call_arguments[: nargs - nkwargs]
-        kwarg_names = call_arguments[nargs - nkwargs :]
-
-        callable_args = [
-            (
-                kwargs[arg]
-                if arg in kwargs
-                else self.build_argument(
-                    arg, args_data.annotations.get(arg, None), context=callable_to_execute.__name__, cache=True
-                )
-            )
-            for arg in arg_names
-        ]
-        callable_kwargs = {}
-        for kwarg_name in kwarg_names:
-            if kwarg_name not in kwargs:
-                continue
-            callable_kwargs[kwarg_name] = kwargs[kwarg_name]
-
-        return callable_to_execute(*callable_args, **callable_kwargs)
-
-    def _disallow_kwargs(self, action):
-        """
-        Raise an exception.
-
-        This is used to raise an exception and stop building a class if its constructor accepts kwargs. To be clear,
-        we actually can support kwargs - it just doesn't make much sense.  The issue is that keywords are
-        optional, so a dependency injection framework doesn't know what to do with them.  Ignore them?  Provide them?
-        The behavior is unclear, and therefore, bug prone.
-
-        If you need to create a class that accepts kwargs in its constructor you can do  that though - just override
-        this method in your DI class and don't raise an exception.  If you do that, everything will still work but
-        nothing will be provided for your kwargs.
-
-        Another option would be to do a self.build_from_name on the kwargs names, but only provide the kwarg
-        if the name is something that the DI container can actually provide (and otherwise just let it fall back
-        on the default).  However, I'm not convinced that will be a helpful use case, so I'm not implementing
-        it right now.
-        """
-        raise ValueError(f"Cannot {action} because it has keyword arguments.")
-
-    def can_cache(self, name: str, context: str) -> bool:
-        """Control whether or not to cache a value built by the DI container."""
-        if name == "now" or name == "utcnow":
-            return False
-        return True
-
-    def provide_di(self):
-        return self
-
-    def provide_requests(self):
-        retry_strategy = Retry(
-            total=3,
-            status_forcelist=[429, 500, 502, 503, 504],
-            backoff_factor=1,
-            allowed_methods=["GET", "POST", "DELETE", "OPTIONS", "PATCH"],
-        )
-        adapter = HTTPAdapter(max_retries=retry_strategy)
-        session = requests.Session()
-        session.mount("https://", adapter)
-        session.mount("http://", adapter)
-        return session
-
-    def provide_sys(self):
-        import sys
-
-        return sys
-
-    def provide_environment(self):
-        return Environment(os.getcwd() + "/.env", os.environ, {})
-
-    def provide_connection_no_autocommit(self, connection_details):
-        # I should probably just switch things so that autocommit is *off* by default
-        # and only have one of these, but for now I'm being lazy.
-        try:
-            import pymysql
-        except:
-            raise ValueError(
-                "The cursor requires pymysql to be installed.  This is an optional dependency of clearskies, so to include it do a `pip install 'clear-skies[mysql]'`"
-            )
-
-        return pymysql.connect(
-            user=connection_details["username"],
-            password=connection_details["password"],
-            host=connection_details["host"],
-            database=connection_details["database"],
-            port=connection_details.get("port", 3306),
-            ssl_ca=connection_details.get("ssl_ca", None),
-            autocommit=False,
-            connect_timeout=2,
-            cursorclass=pymysql.cursors.DictCursor,
-        )
-
-    def provide_connection(self, connection_details):
-        try:
-            import pymysql
-        except:
-            raise ValueError(
-                "The cursor requires pymysql to be installed.  This is an optional dependency of clearskies, so to include it do a `pip install 'clear-skies[mysql]'`"
-            )
-
-        return pymysql.connect(
-            user=connection_details["username"],
-            password=connection_details["password"],
-            host=connection_details["host"],
-            database=connection_details["database"],
-            port=connection_details.get("port", 3306),
-            ssl_ca=connection_details.get("ssl_ca", None),
-            autocommit=True,
-            connect_timeout=2,
-            cursorclass=pymysql.cursors.DictCursor,
-        )
-
-    def provide_connection_details(self, environment):
-        try:
-            port = environment.get("db_port")
-        except:
-            port = 3306
-
-        try:
-            ssl_ca = environment.get("db_ssl_ca")
-        except:
-            ssl_ca = None
-
-        return {
-            "username": environment.get("db_username"),
-            "password": environment.get("db_password"),
-            "host": environment.get("db_host"),
-            "database": environment.get("db_database"),
-            "port": port,
-            "ssl_ca": ssl_ca,
-        }
-
-    def provide_cursor(self, connection):
-        return connection.cursor()
-
-    def provide_now(self):
-        return datetime.datetime.now() if self._now is None else self._now
-
-    def provide_utcnow(self):
-        return datetime.datetime.now(datetime.timezone.utc) if self._utcnow is None else self._utcnow
-
-    def provide_input_output(self):
-        raise AttributeError(
-            "The dependency injector requested an InputOutput but none has been configured.  Alternatively, if you directly called `di.build('input_output')` then try again with `di.build('input_output', cache=True)`"
-        )
-
-    def provide_oai3_schema_resolver(self):
-        from clearskies import autodoc
-
-        return autodoc.formats.oai3_json.OAI3SchemaResolver()
-
-    def provide_uuid(self):
-        import uuid
-
-        return uuid
-
-    def provide_secrets(self):
-        return clearskies.secrets.Secrets()
-
-    def provide_memory_backend_default_data(self):
-        return []
-
-    def provide_global_table_prefix(self):
-        return ""
-
-    def provide_akeyless(self):
-        import akeyless  # type: ignore
-
-        return akeyless