Deprecate inject and introduce register to register classes (#30)

* Deprecate inject

* Implement #30

* 0.5.5

Author: pwwang

README.md

@@ -19,7 +19,7 @@ pip install varname
 - Fetching variable names directly using `nameof`
 - A value wrapper to store the variable name that a value is assigned to using `Wrapper`
 - Detecting next immediate attribute name using `will`
-- Injecting `__varname__` to objects
+- Injecting `__varname__` to classes
 - A `debug` function to print variables with their names and values.
 
 ## Credits
@@ -213,26 +213,21 @@ awesome.permit() # AttributeError: Should do something with AwesomeClass object
 awesome.permit().do() == 'I am doing!'
 ```
 
-### Injecting `__varname__`
+### Injecting `__varname__` to classes
 
 ```python
-from varname import inject
+from varname import inject_varname
 
-class MyList(list):
+@inject_varname
+class Dict(dict):
     pass
 
-a = inject(MyList())
-b = inject(MyList())
-
+a = Dict(a=1)
+b = Dict(b=2)
 a.__varname__ == 'a'
 b.__varname__ == 'b'
-
-a == b
-
-# other methods not affected
-a.append(1)
-b.append(1)
-a == b
+a.update(b)
+a == {'a':1, 'b':2}
 ```
 
 ### Debugging with `debug`

docs/CHANGELOG.md

@@ -1,3 +1,6 @@
+## v0.5.5
+- Deprecate inject and use inject_varname decorator instead
+
 ## v0.5.4
 - Allow `varname.varname` to receive multiple variables on the left-hand side
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.masonry.api"
 
 [tool.poetry]
 name = "varname"
-version = "0.5.4"
+version = "0.5.5"
 description = "Dark magics about variable names in python."
 authors = [ "pwwang <[email protected]>",]
 license = "MIT"

tests/test_varname.py

@@ -572,3 +572,18 @@ def test_debug(capsys):
     assert 'DEBUG: a=1\n' == capsys.readouterr().out
     debug(a, b, merge=True)
     assert 'DEBUG: a=1, b=<object' in capsys.readouterr().out
+
+def test_inject_varname():
+
+    @inject_varname
+    class Foo:
+        def __init__(self, a=1):
+            self.a = a
+
+    f = Foo()
+    assert f.__varname__ == 'f'
+    assert f.a == 1
+
+    f2 = Foo(2)
+    assert f2.__varname__ == 'f2'
+    assert f2.a == 2

varname.py

@@ -3,16 +3,17 @@
 import dis
 import sys
 import warnings
-from typing import Union, Tuple, Any, Optional
+from typing import Callable, Union, Tuple, Any, Optional
 from types import FrameType, CodeType
 from collections import namedtuple as standard_namedtuple
+from functools import wraps
 from functools import lru_cache
 
 import executing
 
-__version__ = "0.5.4"
+__version__ = "0.5.5"
 __all__ = [
-    "VarnameRetrievingError", "varname", "will",
+    "VarnameRetrievingError", "varname", "will", "inject_varname",
     "inject", "nameof", "namedtuple", "Wrapper", "debug"
 ]
 
@@ -151,6 +152,62 @@ def will(caller: int = 1, raise_exc: bool = True) -> Optional[str]:
     # ast.Attribute
     return node.attr
 
+def inject_varname(
+        cls: type = None, *,
+        caller: int = 1,
+        multi_vars: bool = False,
+        raise_exc: bool = True
+) -> Union[type, Callable[[type], type]]:
+    """A decorator to inject __varname__ attribute to a class
+
+    Args:
+        caller: The call stack index, indicating where this class
+            is instantiated relative to where the variable is finally retrieved
+        multi_vars: Whether allow multiple variables on left-hand side (LHS).
+            If `True`, this function returns a tuple of the variable names,
+            even there is only one variable on LHS.
+            If `False`, and multiple variables on LHS, a
+            `VarnameRetrievingError` will be raised.
+        raise_exc: Whether we should raise an exception if failed
+            to retrieve the name.
+
+    Examples:
+        >>> @inject_varname
+        >>> class Foo: pass
+        >>> foo = Foo()
+        >>> # foo.__varname__ == 'foo'
+
+    Returns:
+        The wrapper function or the class itself if it is specified explictly.
+    """
+    if cls is not None:
+        # Used as @inject_varname directly
+        return inject_varname(
+            caller=caller,
+            multi_vars=multi_vars,
+            raise_exc=raise_exc
+        )(cls)
+
+    # Used as @inject_varname(multi_vars=..., raise_exc=...)
+    def wrapper(cls):
+        """The wrapper function to wrap a class and inject `__varname__`"""
+        orig_init = cls.__init__
+
+        @wraps(cls.__init__)
+        def wrapped_init(self, *args, **kwargs):
+            """Wrapped init function to replace the original one"""
+            self.__varname__ = varname(
+                caller=caller,
+                multi_vars=multi_vars,
+                raise_exc=raise_exc
+            )
+            orig_init(self, *args, **kwargs)
+
+        cls.__init__ = wrapped_init
+        return cls
+
+    return wrapper
+
 def inject(obj: object) -> object:
     """Inject attribute `__varname__` to an object
 
@@ -181,6 +238,9 @@ def inject(obj: object) -> object:
     Returns:
         The object with __varname__ injected
     """
+    warnings.warn("Function inject will be removed in 0.6.0. Use "
+                  "varname.inject_varname to decorate your class.",
+                  DeprecationWarning)
     vname = varname()
     try:
         setattr(obj, '__varname__', vname)