Add BlankProvider as placeholder

This can be used to store required configuration
such as domains and passwords.

Author: scottzach1

README.md

@@ -32,7 +32,7 @@ from pif import wiring, providers
 
 
 @wiring.injected  # <- automatically injects providers.Provider default arguments!
-def my_function(a: str = providers.Factory[str](lambda: "hello world")):
+def my_function(a: str = providers.ExistingSingleton("hello world")):
     return a
 
 
@@ -48,7 +48,7 @@ With this approach you can wire all methods in the specified modules.
 from pif import wiring, providers
 
 
-def my_function(a: str = providers.Factory[str](lambda: "hello world")):
+def my_function(a: str = providers.ExistingSingleton("hello world")):
     return a
 
 
@@ -65,12 +65,13 @@ services for testing or dynamically patching application behavior based on appli
 
 #### Standard Overriding
 
-If you want to patch a value all you need to do is call `.override()` on the provider in question.
+If you want to patch a value all you need to do is call `.override()` on the provider in question. If you are wanting to
+override an existing singleton you may call the convenience method `.override_existing()`.
 
 ```python
 from pif import wiring, providers
 
-StringProvider = providers.Factory[str](lambda: "hello world")
+StringProvider = providers.ExistingSingleton("hello world")
 
 
 @wiring.injected
@@ -81,7 +82,7 @@ def my_function(a: str = StringProvider):
 if __name__ == "__main__":
     assert "hello world" == my_function()
 
-    override = StringProvider.override(providers.Factory[str](lambda: "overridden_1"))
+    override = StringProvider.override_existing("overridden_1")
 
     assert "overridden_1"
 ```
@@ -93,7 +94,7 @@ If you want more control around the override lifecycles then you may use the `Ov
 ```python
 from pif import wiring, providers
 
-StringProvider = providers.Factory[str](lambda: "hello world")
+StringProvider = providers.ExistingSingleton("hello world")
 
 
 @wiring.injected
@@ -104,13 +105,13 @@ def my_function(a: str = StringProvider):
 if __name__ == "__main__":
     assert "hello world" == my_function()
 
-    OverrideProvider = providers.Factory[str](lambda: "overridden_1")
+    OverrideProvider = providers.ExistingSingleton("overridden_1")
 
-    with StringProvider.override(OverrideProvider):
+    with StringProvider.override_existing(OverrideProvider):
         assert "overridden_1" == my_function()
 
-        with OverrideProvider.override(providers.Factory[str]("overridden_2")):
-            assert "overridden_2" == my_function() # You can even stack overrides!!
+        with OverrideProvider.override_existing("overridden_2"):
+            assert "overridden_2" == my_function()  # You can even stack overrides!!
 
         assert "overridden_1" == my_function()
 

pif/exceptions.py

@@ -0,0 +1,22 @@
+class PifException(Exception):
+    """
+    Any custom exception thrown by the Python Injection Framework (PIF).
+    """
+
+    msg: str
+
+    def __init__(self, msg: str = None, *args):
+        super().__init__(*args)
+        self.msg = msg or self.__doc__
+
+    def __str__(self):
+        return self.msg
+
+    def __repr__(self):
+        return f"<{type(self)}({self.msg!r})>"
+
+
+class BlankProviderException(PifException):
+    """
+    Attempted to evaluate a BlankProvider. Make sure to override this first!
+    """

pif/providers.py

@@ -14,6 +14,8 @@
 import functools
 from typing import Callable, Self
 
+from pif import exceptions
+
 
 class Provider[T](abc.ABC):
     """
@@ -44,6 +46,12 @@ def override[U: Provider | None](self, provider: U) -> Override[U]:
         """
         return Override(self, provider)
 
+    def override_existing[U](self, value: U) -> Override[Provider[T]]:
+        """
+        Override the current provider with an existing singleton.
+        """
+        return self.override(ExistingSingleton(value))
+
 
 class Override[ProviderT: Provider]:
     """
@@ -72,6 +80,17 @@ def __exit__(self, exc_type, exc_val, exc_tb):
         self.disable()
 
 
+class BlankProvider(Provider):
+    """
+    A placeholder for a provider.
+    """
+
+    __slots__ = tuple()
+
+    def _evaluate(self) -> None:
+        raise exceptions.BlankProviderException()
+
+
 class ExistingSingleton[T](Provider):
     """
     Provide an existing object instance.

tests/test_providers.py

@@ -1,4 +1,6 @@
-from pif import providers
+import pytest
+
+from pif import exceptions, providers
 
 
 def test_override_standard_shallow():
@@ -108,3 +110,92 @@ def test_override_contextmanager_nested():
     assert provide_a() == "a"
     assert provide_b() == "b"
     assert provide_c() == "c"
+
+
+def test_blank_provider():
+    """
+    Checking the blank provider raises a BlankProviderException when it hasn't been overridden.
+    """
+    provider = providers.BlankProvider()
+
+    with pytest.raises(exceptions.BlankProviderException):
+        provider()
+
+    with provider.override_existing("some_value"):
+        assert provider() == "some_value"
+
+    with pytest.raises(exceptions.BlankProviderException):
+        provider()
+
+
+def test_existing_singleton():
+    """
+    Checking the existing singleton provider returns the exact same object.
+    """
+    obj_1 = object()
+    obj_2 = object()
+
+    provider = providers.ExistingSingleton(obj_1)
+
+    assert obj_1 is not obj_2
+    assert obj_1 is provider()
+    assert obj_1 is provider()
+
+    with provider.override_existing(obj_2):
+        assert obj_2 is not obj_1
+        assert obj_2 is provider()
+        assert obj_2 is provider()
+
+    assert obj_1 is not obj_2
+    assert obj_1 is provider()
+    assert obj_1 is provider()
+
+
+def test_singleton():
+    """
+    Checking the singleton provider creates only once.
+    """
+    provider = providers.Singleton[dict](dict, a=1, b=2)
+
+    dict_1 = provider()
+    dict_2 = provider()
+
+    with provider.override(providers.Singleton[dict](dict, a=1, b=2)):
+        dict_alt = provider()
+
+    dict_3 = provider()
+
+    assert dict_1 == {"a": 1, "b": 2}
+    assert dict_1 is not {"a": 1, "b": 2}
+    assert dict_2 is dict_1
+    assert dict_3 is dict_1
+
+    assert dict_1 == dict_alt
+    assert dict_1 is not dict_alt
+
+
+def test_factory():
+    """
+    Checking the factory provider creates every single time.
+    """
+    provider = providers.Factory[dict](dict, a=1, b=2)
+
+    dict_1 = provider()
+    dict_2 = provider()
+
+    with provider.override(providers.Factory[dict](dict, a=1, b=2)):
+        dict_alt = provider()
+
+    dict_3 = provider()
+
+    assert dict_1 == {"a": 1, "b": 2}
+    assert dict_1 is not {"a": 1, "b": 2}
+
+    assert dict_2 == dict_1
+    assert dict_2 is not dict_1
+
+    assert dict_3 == dict_1
+    assert dict_3 is not dict_1
+
+    assert dict_alt == dict_1
+    assert dict_alt is not dict_1