Add inject function

Author: pwwang

README.md

@@ -16,6 +16,7 @@ pip install python-varname
 - A value wrapper to store the variable name that a value is assigned to (added in `v0.1.1`)
 - Detecting next immediate attribute name (added in `v0.1.4`)
 - Shortcut for `collections.namedtuple` (added in `v0.1.6`)
+- Injecting `__varname__` to objects (added in `v0.1.7`)
 
 ## Usage
 
@@ -185,6 +186,28 @@ from varname import namedtuple
 Name = namedtuple(['first', 'last'])
 ```
 
+### Injecting `__varname__`
+
+```python
+from varname import inject
+
+class MyList(list):
+    pass
+
+a = inject(MyList())
+b = inject(MyList())
+
+a.__varname__ == 'a'
+b.__varname__ == 'b'
+
+a == b
+
+# other methods not affected
+a.append(1)
+b.append(1)
+a == b
+```
+
 ## Limitations
 - Working in `ipython REPL` but not in standard `python console`
 - You have to know at which stack the function/class will be called

tests/test_varname.py

@@ -5,6 +5,7 @@
                      VarnameRetrievingError,
                      Wrapper,
                      will,
+                     inject,
                      namedtuple,
                      _get_executing,
                      nameof)
@@ -365,3 +366,20 @@ def test_namedtuple():
     Name = namedtuple(['first', 'last'])
     name = Name('Bill', 'Gates')
     assert isinstance(name, Name)
+
+def test_inject():
+
+    with pytest.raises(VarnameRetrievingError):
+        a = inject(1)
+
+    class A(list):
+        pass
+
+    a = inject(A())
+    b = inject(A())
+    assert a.__varname__ == 'a'
+    assert b.__varname__ == 'b'
+    assert a == b
+    a.append(1)
+    b.append(1)
+    assert a == b

varname.py

@@ -144,6 +144,29 @@ def i_will():
 
     return ret
 
+def inject(obj):
+    """Inject attribute `__varname__` to an object
+
+    Args:
+        obj: An object that can be injected
+
+    Warns:
+        VarnameRetrievingWarning: When `__varname__` already exists
+
+    Raises:
+        VarnameRetrievingError: When `__varname__` is unable to
+            be set as an attribute
+
+    Returns:
+        obj: The object with __varname__ injected
+    """
+    vname = varname()
+    try:
+        setattr(obj, '__varname__', vname)
+    except AttributeError:
+        raise VarnameRetrievingError('Unable to inject __varname__.')
+    return obj
+
 def nameof(*args):
     """Get the names of the variables passed in