Allow varname.varname to receive multiple variables on the left-hand side (#29)

* Allow `varname.varname` to receive multiple variables on the left-hand side

* Fix typo in test

* Add tests for mismatch nvars for varname.varname

* Fix the numbers in mismatch nvars test for varname.varname

* Update docs for varname.varname

* Make docs clearer

* Make docs clearer

* Change behavor of nvars=None for varname

* Update varname.py

Co-authored-by: Alex Hall <[email protected]>

* Add tests for hierarchical LHS for varname

* Change nvars to multi_vars and make it boolean

* Add test for attributes on LHS for varname

* Fix docs for varname; add StringOrTuple for type hints

* Fix type hints

Co-authored-by: Alex Hall <[email protected]>

Author: pwwang

README.md

@@ -92,6 +92,22 @@ Special thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this
     k2 = k.copy() # k2.id == 'k2'
     ```
 
+- Multiple variables on Left-hand side
+
+    ```python
+    # since v0.5.4
+
+    def func():
+        return varname(multi_vars=True)
+
+    a = func() # a == ('a', )
+    a, b = func() # (a, b) == ('a', 'b')
+    [a, b] = func() # (a, b) == ('a', 'b')
+
+    # hierarchy is also possible
+    a, (b, c) = func() # (a, b, c) == ('a', 'b', 'c')
+    ```
+
 - Some unusual use
 
     ```python

docs/CHANGELOG.md

@@ -1,3 +1,6 @@
+## v0.5.4
+- Allow `varname.varname` to receive multiple variables on the left-hand side
+
 ## v0.5.3
 - Add `debug` function
 - Deprecate `namedtuple` (will be removed in `0.6.0`)

pyproject.toml

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

tests/test_varname.py

@@ -168,18 +168,48 @@ def func2():
 
     assert func2() == ('p1', 'p2')
 
-def test_only_one_lhs():
+def test_single_var_lhs_error():
     """Only one variable to receive the name on LHS"""
 
     def function():
         return varname()
 
-    with pytest.raises(VarnameRetrievingError):
+    with pytest.raises(VarnameRetrievingError,
+                       match='Expecting a single variable on left-hand side'):
         x, y = function()
     with pytest.raises(VarnameRetrievingError):
         x, y = function(), function()
-    with pytest.raises(VarnameRetrievingError):
-        [x] = function()
+
+    # This is now supported in 0.5.4
+    # with pytest.raises(VarnameRetrievingError):
+    #     [x] = function()
+
+def test_multi_vars_lhs():
+    """Tests multiple variables on the left hand side"""
+
+    def function():
+        return varname(multi_vars=True)
+
+    a, b = function()
+    assert (a, b) == ('a', 'b')
+    [a, b] = function()
+    assert (a, b) == ('a', 'b')
+    a = function()
+    assert a == ('a', )
+    # hierarchy
+    a, (b, c) = function()
+    assert (a, b, c) == ('a', 'b', 'c')
+    # with attributes
+    x = lambda: 1
+    a, (b, x.c) = function()
+    assert (a, b, x.c) == ('a', 'b', 'c')
+
+    # Not all LHS are variables
+    with pytest.raises(
+        VarnameRetrievingError,
+        match='Can only get name of a variable or attribute, not Starred'
+    ):
+        a, *b = function()
 
 def test_raise():
 

varname.py

@@ -10,7 +10,7 @@
 
 import executing
 
-__version__ = "0.5.3"
+__version__ = "0.5.4"
 __all__ = [
     "VarnameRetrievingError", "varname", "will",
     "inject", "nameof", "namedtuple", "Wrapper", "debug"
@@ -19,22 +19,33 @@
 class VarnameRetrievingError(Exception):
     """When failed to retrieve the varname"""
 
-def varname(caller: int = 1, raise_exc: bool = True) -> Optional[str]:
+def varname(
+        caller: int = 1,
+        multi_vars: bool = False,
+        raise_exc: bool = True
+) -> Optional[Union[str, Tuple[Union[str, tuple]]]]:
     """Get the variable name that assigned by function/class calls
 
     Args:
         caller: The call stack index, indicating where this function
             is called 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.
 
     Returns:
         The variable name, or `None` when `raise_exc` is `False` and
             we failed to retrieve the variable name.
+        A tuple or a hierarchy (tuple of tuples) of variable names
+            when `multi_vars` is `True`.
 
     Raises:
-        VarnameRetrievingError: When there is invalid variable used on the
-            left of the assign node. (e.g: `a.b = func()`) or
+        VarnameRetrievingError: When there is invalid variables or
+            invalid number of variables used on the LHS; or
             when we are unable to retrieve the variable name and `raise_exc`
             is set to `True`.
 
@@ -63,7 +74,21 @@ def varname(caller: int = 1, raise_exc: bool = True) -> Optional[str]:
                       "on the very left will be used.",
                       UserWarning)
     target = node.targets[0]
-    return _node_name(target)
+
+    names = _node_name(target)
+
+    if not isinstance(names, tuple):
+        names = (names, )
+
+    if multi_vars:
+        return names
+
+    if len(names) > 1:
+        raise VarnameRetrievingError(
+            f"Expecting a single variable on left-hand side, got {len(names)}."
+        )
+
+    return names[0]
 
 def will(caller: int = 1, raise_exc: bool = True) -> Optional[str]:
     """Detect the attribute name right immediately after a function call.
@@ -408,7 +433,7 @@ def _lookfor_parent_assign(node: ast.AST) -> Optional[ast.Assign]:
             return node
     return None
 
-def _node_name(node: ast.AST) -> str:
+def _node_name(node: ast.AST) -> Optional[Union[str, Tuple[Union[str, tuple]]]]:
     """Get the node node name.
 
     Raises VarnameRetrievingError when failed
@@ -417,6 +442,8 @@ def _node_name(node: ast.AST) -> str:
         return node.id
     if isinstance(node, ast.Attribute):
         return node.attr
+    if isinstance(node, (ast.List, ast.Tuple)):
+        return tuple(_node_name(elem) for elem in node.elts)
 
     raise VarnameRetrievingError(
         f"Can only get name of a variable or attribute, "