tests: description to tests, more fixtures, renaming

src/fasthook/hook.py

@@ -4,25 +4,42 @@ import collections
 import functools
 import typing
 
+import weakref
+
 
 class Hook:
+    instances: weakref.WeakSet = weakref.WeakSet()
     function: typing.Callable
     registered_level: int = 0
     l10n_flags: int = 0
+    name: str
+
+    def __new__(cls, *_: typing.Any, **__: typing.Any) -> Hook:
+        new_instance = super().__new__(cls)
+        cls.instances.add(new_instance)
+        return new_instance
 
     def __init__(self, function: typing.Callable):
         functools.wraps(function)(self)
         self.function = function
 
-    def __get__(self, instance: typing.Callable, owner: typing.Type) -> typing.Callable:
+    def __get__(self, instance: typing.Callable, owner: typing.Type) -> functools.partial:
         partial = functools.partial(self.function, instance)
         partial.add = self.add  # type: ignore
         return partial
 
-    def __call__(self, *args: typing.Any, **kwargs: typing.Any) -> None:
+    def __call__(self, *args: typing.Any, **kwargs: typing.Any) -> typing.Any:
         """TODO: dispatch on function to add hooks"""
         return self.function(*args, **kwargs)
 
+    @property
+    def __name__(self) -> str:
+        return self.name
+
+    @__name__.setter
+    def __name__(self, name: str) -> None:
+        self.name = name
+
     def match_level(self, flags: int) -> int:
         """
         For match, flags must be
@@ -52,5 +69,5 @@ class Hook:
     dispatch_add: collections.defaultdict = collections.defaultdict(lambda: Hook.add_flags)
     dispatch_add[type(add_function)] = add_function
 
-    def add(self, function_or_flags: typing.Callable) -> typing.Callable:
+    def add(self, function_or_flags: typing.Union[typing.Callable, int]) -> typing.Callable:
         return self.dispatch_add[type(function_or_flags)](self, function_or_flags)

tests/conftest.py

@@ -7,10 +7,15 @@ import fasthook
 
 
 class Flags(enum.IntFlag):
-    country_one = enum.auto()
-    country_two = enum.auto()
-    brand_one = enum.auto()
-    brand_two = enum.auto()
+    country_A = enum.auto()
+    country_B = enum.auto()
+    brand_A = enum.auto()
+    brand_B = enum.auto()
+
+
+@pytest.fixture
+def import_fasthook():
+    return fasthook
 
 
 @pytest.fixture
@@ -20,25 +25,45 @@ def setting_reset():
 
 
 @pytest.fixture
-def hook_setting_country_one(setting_reset):
-    fasthook.Hook.l10n_flags = Flags.country_one
+def config_country(setting_reset):
+    fasthook.Hook.l10n_flags = Flags.country_A
 
 
 @pytest.fixture
-def hook_setting_country_one_brand_one(setting_reset):
-    fasthook.Hook.l10n_flags = Flags.country_one | Flags.brand_one
+def config_country_brand(setting_reset):
+    """configure flags to a simple combination of country and brand, i.e. a market"""
+    fasthook.Hook.l10n_flags = Flags.country_A | Flags.brand_A
 
 
 @pytest.fixture
 def flags() -> typing.Type[Flags]:
+    """return configuration integer enum flags used by hook to dispatch hook implementations"""
     return Flags
 
 
 @pytest.fixture
-def return_default() -> fasthook.Hook:
-    @fasthook.Hook
+def default_hook(import_fasthook) -> fasthook.Hook:
+    @import_fasthook.Hook
     def return_default_():
         """default hook"""
-        return "default"
+        return default_hook.__name__
 
     return return_default_
+
+
+@pytest.fixture
+def inject_country(default_hook, flags) -> typing.Callable:
+    @default_hook.add(flags.country_A)
+    def country():
+        return inject_country.__name__
+
+    return country
+
+
+@pytest.fixture
+def inject_country_brand(default_hook, flags) -> typing.Callable:
+    @default_hook.add(flags.country_A | flags.brand_A)
+    def country_brand():
+        return inject_country_brand.__name__
+
+    return country_brand

tests/test_function.py

@@ -4,69 +4,122 @@ import pytest
 
 
 @pytest.mark.regression
-def test_hook():
-    import fasthook
+def test_hook(import_fasthook):
+    """
+    given
+        - imported fasthook package
+        - and a function that return the name of the default hook
 
-    @fasthook.Hook
+    when apply the hook decorator to the function
+
+    then assert that the hook return its name
+    """
+
+    @import_fasthook.Hook
     def return_default():
-        """default hook"""
-        return "default"
+        return return_default.__name__
 
-    assert return_default() == "default"
+    assert return_default() == "return_default"
 
 
 @pytest.mark.regression
-def test_hook_better_match(return_default, hook_setting_country_one_brand_one, flags):
-    @return_default.add(flags.country_one)
-    def return_first_registered():
+def test_hook_implementation_injection(default_hook, config_country_brand, flags):
+    """
+    given
+        - a default hook that returns its name
+        - a configuration for a specific country and a specific brand
+        - the flags enum used to specify a configuration
+        - and a function that return its name
+
+    when add the function to the hook matching the country
+
+    then assert that the hook return the name of the added function
+    """
+
+    @default_hook.add(flags.country_A)
+    def inject_country():
         """First registered hook, replace default one"""
-        return "first registered"
+        return inject_country.__name__
+
+    assert default_hook() == "inject_country"
 
-    assert return_default() == "first registered"
 
-    @return_default.add(flags.country_one | flags.brand_one)
-    def return_second_registered():
+@pytest.mark.regression
+def test_hook_better_match(default_hook, config_country_brand, flags, inject_country):
+    """
+    given
+        - a default hook that returns its name
+        - a configuration for a specific country and a specific brand
+        - the flags enum used to specify a configuration
+        - an injected function that return its name matching country
+        - and a function that return its name
+
+    when add the function to the hook matching the country and the brand of the configuration
+
+    then assert that the hook return the name of the function that match the country and the brand
+    """
+
+    @default_hook.add(flags.country_A | flags.brand_A)
+    def inject_country_brand():
         """second registered hook, replace first one"""
-        return "second registered"
+        return inject_country_brand.__name__
 
-    assert return_default() == "second registered"
+    assert default_hook() == "inject_country_brand"
 
 
 @pytest.mark.regression
-def test_hook_lesser_match(return_default, hook_setting_country_one_brand_one, flags):
-    @return_default.add(flags.country_one | flags.brand_one)
-    def return_first_registered():
-        """First registered hook, replace default one"""
-        return "first registered"
+def test_hook_fewer_match(default_hook, config_country_brand, flags, inject_country_brand):
+    """
+    given
+        - a default hook that returns its name
+        - a configuration for a specific country and a specific brand
+        - the flags enum used to specify a configuration
+        - an injected function that return its name matching country and brand
+        - and a function that return its name
+
+    when add the function to the hook matching just country
 
-    assert return_default() == "first registered"
+    then assert that the hook return the name of the function that match the country and the brand
+    """
 
-    @return_default.add(flags.country_one)
-    def return_second_registered():
-        """lesser match than first hook, not registered"""
-        return "second registered"
+    @default_hook.add(flags.country_A)
+    def inject_country():
+        """fewer match than first hook, not registered"""
+        return inject_country.__name__
 
-    assert return_default() == "first registered"
+    assert default_hook() == "inject_country_brand"
 
 
 @pytest.mark.regression
-def test_hook_too_specific_use_default(return_default, hook_setting_country_one, flags):
-    @return_default.add(flags.country_one | flags.brand_one)
+def test_hook_too_specific_use_default(default_hook, config_country, flags):
+    """
+    given
+        - a default hook that returns its name
+        - a configuration for a specific country
+        - the flags enum used to specify a configuration
+        - and a function that return its name
+
+    when add the function to the hook matching country but with brand that is not in config
+
+    then assert that the hook return its name
+    """
+
+    @default_hook.add(flags.country_A | flags.brand_A)
     def return_registered():
         """hook not registered because config match only one registration flag"""
-        return "registered"
+        return return_registered.__name__
 
-    assert return_default() == "default"
+    assert default_hook() == "default_hook"
 
 
 @pytest.mark.regression
-def test_hook_no_match_use_default(return_default, hook_setting_country_one, flags):
-    @return_default.add(flags.country_two)
+def test_hook_no_match_use_default(default_hook, config_country, flags):
+    @default_hook.add(flags.country_B)
     def return_registered():
         """Not registered hook"""
         return "registered"
 
-    assert return_default() == "default"
+    assert default_hook() == "default_hook"
 
 
 class Flags(enum.IntFlag):
@@ -83,20 +136,18 @@ class Flags(enum.IntFlag):
         (Flags.country_one, "registered"),
         (Flags.brand_one, "registered"),
         (Flags.country_one | Flags.brand_one, "registered"),
-        (Flags.country_two | Flags.brand_two, "default"),
+        (Flags.country_two | Flags.brand_two, "default_hook"),
     ],
 )
-def test_hook_multiple_add(return_default, flags_int, expected):
-    import fasthook
+def test_hook_multiple_add(import_fasthook, default_hook, flags_int, expected):
+    import_fasthook.Hook.l10n_flags = flags_int
 
-    fasthook.Hook.l10n_flags = flags_int
-
-    @return_default.add(Flags.country_one)
-    @return_default.add(Flags.brand_one)
+    @default_hook.add(Flags.country_one)
+    @default_hook.add(Flags.brand_one)
     def return_registered():
         return "registered"
 
-    assert return_default() == expected
+    assert default_hook() == expected
 
 
 def test_replace_default():
@@ -117,14 +168,14 @@ def test_replace_default():
 
 
 @pytest.mark.regression
-def test_hook_setup_teardown(hook_setting_country_one, flags):
+def test_hook_setup_teardown(config_country, flags):
     import fasthook
 
     @fasthook.Hook
     def setup(x):
         return x
 
-    @setup.add(flags.country_one)
+    @setup.add(flags.country_A)
     def setup_1(x):
         return x + 1
 
@@ -132,7 +183,7 @@ def test_hook_setup_teardown(hook_setting_country_one, flags):
     def teardown(resutl, y):
         return resutl
 
-    @teardown.add(flags.country_one)
+    @teardown.add(flags.country_A)
     def teardown_1(resutl, y):
         return resutl + y
 
@@ -142,3 +193,35 @@ def test_hook_setup_teardown(hook_setting_country_one, flags):
         return teardown(result, x)
 
     assert component(5) == 13  # (5+1 + 1) + 6
+
+
+@pytest.mark.regression
+def test_hook_instances_set():
+    import fasthook
+
+    @fasthook.Hook
+    def return_default_1():
+        """default hook"""
+        return "default_1"
+
+    assert len(fasthook.Hook.instances) == 1
+    assert len(return_default_1.instances) == 1
+
+
+@pytest.mark.regression
+def test_hook_instances_garbage_collector():
+    import fasthook
+
+    @fasthook.Hook
+    def return_default_1():
+        """default hook"""
+        return "default_1"
+
+    @fasthook.Hook
+    def return_default_2():
+        """default hook"""
+        return "default_2"
+
+    assert len(fasthook.Hook.instances) == 2
+    del return_default_1
+    assert len(fasthook.Hook.instances) == 1

tests/test_method.py

@@ -17,7 +17,7 @@ def test_hook_method():
 
 
 @pytest.mark.regression
-def test_hook_another_method_register(hook_setting_country_one, flags):
+def test_hook_another_method_register(config_country, flags):
     import fasthook
 
     class Foobar:
@@ -28,7 +28,7 @@ def test_hook_another_method_register(hook_setting_country_one, flags):
             self.spam += 1
             return self
 
-        @change_value.add(flags.country_one)
+        @change_value.add(flags.country_A)
         def min_1_method_registered(self):
             self.spam -= 1
             return self
@@ -37,7 +37,7 @@ def test_hook_another_method_register(hook_setting_country_one, flags):
 
 
 @pytest.mark.regression
-def test_hook_method_register_fct(hook_setting_country_one, flags):
+def test_hook_method_register_fct(config_country, flags):
     import fasthook
 
     class Foobar:
@@ -48,7 +48,7 @@ def test_hook_method_register_fct(hook_setting_country_one, flags):
             self.spam += 1
             return self
 
-    @Foobar.change_value.add(flags.country_one)
+    @Foobar.change_value.add(flags.country_A)
     def fct_registered(self):
         self.spam -= 1
         return self
@@ -57,7 +57,7 @@ def test_hook_method_register_fct(hook_setting_country_one, flags):
 
 
 @pytest.mark.regression
-def test_method_too_specific_use_default(hook_setting_country_one, flags):
+def test_method_too_specific_use_default(config_country, flags):
     import fasthook
 
     class Foobar:
@@ -68,7 +68,7 @@ def test_method_too_specific_use_default(hook_setting_country_one, flags):
             self.spam += 1
             return self
 
-        @change_value.add(flags.country_one | flags.brand_one)
+        @change_value.add(flags.country_A | flags.brand_A)
         def too_specific_not_registered(self):
             self.spam -= 1
             return self
@@ -77,7 +77,7 @@ def test_method_too_specific_use_default(hook_setting_country_one, flags):
 
 
 @pytest.mark.regression
-def test_method_lesser_match(hook_setting_country_one_brand_one, flags):
+def test_method_lesser_match(config_country_brand, flags):
     import fasthook
 
     class Foobar:
@@ -88,12 +88,12 @@ def test_method_lesser_match(hook_setting_country_one_brand_one, flags):
             self.spam += 1
             return self
 
-        @change_value.add(flags.country_one | flags.brand_one)
+        @change_value.add(flags.country_A | flags.brand_A)
         def better_match_registered(self):
             self.spam -= 1
             return self
 
-        @change_value.add(flags.country_one)
+        @change_value.add(flags.country_A)
         def lesser_match_not_registered(self):
             self.spam += 10
             return self

tests/test_testing.py

@@ -8,12 +8,12 @@ def test_hook_default_testing(flags):
     assert return_default.function() == "default"
 
 
-def test_hook_variance_testing(return_default, flags):
-    @return_default.add(flags.country_one)
+def test_hook_variance_testing(default_hook, flags):
+    @default_hook.add(flags.country_A)
     def return_first_registered():
         return "first_registered"
 
-    @return_default.add(flags.brand_one)
+    @default_hook.add(flags.brand_A)
     def return_second_registered():
         return "second_registered"