varname 0.12.1__tar.gz → 0.13.0__tar.gz

{varname-0.12.1 → varname-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: varname
-Version: 0.12.1
+Version: 0.13.0
 Summary: Dark magics about variable names in python.
 Home-page: https://github.com/pwwang/python-varname
 License: MIT
@@ -54,6 +54,7 @@ Note if you use `python < 3.8`, install `varname < 0.11`
   - A decorator to register `__varname__` to functions/classes, using `register`
   - A helper function to create dict without explicitly specifying the key-value pairs, using `jsobj`
   - A `debug` function to print variables with their names and values
+  - `exec_code` to replace `exec` where source code is available at runtime
 
 ## Credits
 
@@ -221,7 +222,7 @@ Special thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this
     func = function2()  # func == 'func'
 
     a = lambda: 0
-    a.b = function() # a.b == 'b'
+    a.b = function() # a.b == 'a.b'
     ```
 
 ### The decorator way to register `__varname__` to functions/classes
@@ -346,7 +347,7 @@ func4(y, x, c=z) # prints: ('x', 'z')
 # __getattr__/__getitem__/__setattr/__setitem__/__add__/__lt__, etc.
 class Foo:
     def __setattr__(self, name, value):
-        print(argname("name", "value"))
+        print(argname("name", "value", func=self.__setattr__))
 
 Foo().a = 1 # prints: ("'a'", '1')
 
@@ -406,6 +407,26 @@ debug(a+a)
 debug(a+a, vars_only=True) # ImproperUseError
 ```
 
+### Replacing `exec` with `exec_code`
+
+```python
+from varname import argname
+from varname.helpers import exec_code
+
+class Obj:
+    def __init__(self):
+        self.argnames = []
+
+    def receive(self, arg):
+        self.argnames.append(argname('arg', func=self.receive))
+
+obj = Obj()
+# exec('obj.receive(1)')  # Error
+exec_code('obj.receive(1)')
+exec_code('obj.receive(2)')
+obj.argnames # ['1', '2']
+```
+
 ## Reliability and limitations
 
 `varname` is all depending on `executing` package to look for the node.

{varname-0.12.1 → varname-0.13.0}/README.md

@@ -31,6 +31,7 @@ Note if you use `python < 3.8`, install `varname < 0.11`
   - A decorator to register `__varname__` to functions/classes, using `register`
   - A helper function to create dict without explicitly specifying the key-value pairs, using `jsobj`
   - A `debug` function to print variables with their names and values
+  - `exec_code` to replace `exec` where source code is available at runtime
 
 ## Credits
 
@@ -198,7 +199,7 @@ Special thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this
     func = function2()  # func == 'func'
 
     a = lambda: 0
-    a.b = function() # a.b == 'b'
+    a.b = function() # a.b == 'a.b'
     ```
 
 ### The decorator way to register `__varname__` to functions/classes
@@ -323,7 +324,7 @@ func4(y, x, c=z) # prints: ('x', 'z')
 # __getattr__/__getitem__/__setattr/__setitem__/__add__/__lt__, etc.
 class Foo:
     def __setattr__(self, name, value):
-        print(argname("name", "value"))
+        print(argname("name", "value", func=self.__setattr__))
 
 Foo().a = 1 # prints: ("'a'", '1')
 
@@ -383,6 +384,26 @@ debug(a+a)
 debug(a+a, vars_only=True) # ImproperUseError
 ```
 
+### Replacing `exec` with `exec_code`
+
+```python
+from varname import argname
+from varname.helpers import exec_code
+
+class Obj:
+    def __init__(self):
+        self.argnames = []
+
+    def receive(self, arg):
+        self.argnames.append(argname('arg', func=self.receive))
+
+obj = Obj()
+# exec('obj.receive(1)')  # Error
+exec_code('obj.receive(1)')
+exec_code('obj.receive(2)')
+obj.argnames # ['1', '2']
+```
+
 ## Reliability and limitations
 
 `varname` is all depending on `executing` package to look for the node.

{varname-0.12.1 → varname-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.masonry.api"
 
 [tool.poetry]
 name = "varname"
-version = "0.12.1"
+version = "0.13.0"
 description = "Dark magics about variable names in python."
 authors = [ "pwwang <pwwang@pwwang.com>",]
 license = "MIT"
@@ -42,6 +42,6 @@ show_error_codes = true
 strict_optional = false
 
 [tool.black]
-line-length = 80
+line-length = 88
 target-version = ['py37', 'py38', 'py39', 'py310']
 include = '\.pyi?$'

varname-0.13.0/setup.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+from setuptools import setup
+
+packages = \
+['varname']
+
+package_data = \
+{'': ['*']}
+
+install_requires = \
+['executing>=2.0,<3.0']
+
+extras_require = \
+{'all': ['asttokens==2.*', 'pure_eval==0.*']}
+
+setup_kwargs = {
+    'name': 'varname',
+    'version': '0.13.0',
+    'description': 'Dark magics about variable names in python.',
+    'long_description': '![varname][7]\n\n[![Pypi][3]][4] [![Github][5]][6] [![PythonVers][8]][4] ![Building][10]\n[![Docs and API][9]][15] [![Codacy][12]][13] [![Codacy coverage][14]][13]\n![Downloads][17]\n\nDark magics about variable names in python\n\n[CHANGELOG][16] | [API][15] | [Playground][11] | :fire: [StackOverflow answer][20]\n\n## Installation\n\n```shell\npip install -U varname\n```\n\nNote if you use `python < 3.8`, install `varname < 0.11`\n\n## Features\n\n- Core features:\n\n  - Retrieving names of variables a function/class call is assigned to from inside it, using `varname`.\n  - Retrieving variable names directly, using `nameof`\n  - Detecting next immediate attribute name, using `will`\n  - Fetching argument names/sources passed to a function using `argname`\n\n- Other helper APIs (built based on core features):\n\n  - A value wrapper to store the variable name that a value is assigned to, using `Wrapper`\n  - A decorator to register `__varname__` to functions/classes, using `register`\n  - A helper function to create dict without explicitly specifying the key-value pairs, using `jsobj`\n  - A `debug` function to print variables with their names and values\n  - `exec_code` to replace `exec` where source code is available at runtime\n\n## Credits\n\nThanks goes to these awesome people/projects:\n\n<table>\n  <tr>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/alexmojaki/executing">\n        <img src="https://ui-avatars.com/api/?color=3333ff&background=ffffff&bold=true&name=e&size=400" width="50px;" alt=""/>\n        <br /><sub><b>executing</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/alexmojaki">\n        <img src="https://avatars0.githubusercontent.com/u/3627481?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@alexmojaki</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/breuleux">\n        <img src="https://avatars.githubusercontent.com/u/599820?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@breuleux</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/ElCuboNegro">\n        <img src="https://avatars.githubusercontent.com/u/5524219?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@ElCuboNegro</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/thewchan">\n        <img src="https://avatars.githubusercontent.com/u/49702524?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@thewchan</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/LawsOfSympathy">\n        <img src="https://avatars.githubusercontent.com/u/96355982?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@LawsOfSympathy</b></sub>\n      </a>\n    </td>\n  </tr>\n</table>\n\nSpecial thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this project.\n\n## Usage\n\n### Retrieving the variable names using `varname(...)`\n\n- From inside a function\n\n    ```python\n    from varname import varname\n    def function():\n        return varname()\n\n    func = function()  # func == \'func\'\n    ```\n\n    When there are intermediate frames:\n\n    ```python\n    def wrapped():\n        return function()\n\n    def function():\n        # retrieve the variable name at the 2nd frame from this one\n        return varname(frame=2)\n\n    func = wrapped() # func == \'func\'\n    ```\n\n    Or use `ignore` to ignore the wrapped frame:\n\n    ```python\n    def wrapped():\n        return function()\n\n    def function():\n        return varname(ignore=wrapped)\n\n    func = wrapped() # func == \'func\'\n    ```\n\n    Calls from standard libraries are ignored by default:\n\n    ```python\n    import asyncio\n\n    async def function():\n        return varname()\n\n    func = asyncio.run(function()) # func == \'func\'\n    ```\n\n    Use `strict` to control whether the call should be assigned to\n    the variable directly:\n\n    ```python\n    def function(strict):\n        return varname(strict=strict)\n\n    func = function(True)     # OK, direct assignment, func == \'func\'\n\n    func = [function(True)]   # Not a direct assignment, raises ImproperUseError\n    func = [function(False)]  # OK, func == [\'func\']\n\n    func = function(False), function(False)   # OK, func = (\'func\', \'func\')\n    ```\n\n- Retrieving name of a class instance\n\n    ```python\n    class Foo:\n        def __init__(self):\n            self.id = varname()\n\n        def copy(self):\n            # also able to fetch inside a method call\n            copied = Foo() # copied.id == \'copied\'\n            copied.id = varname() # assign id to whatever variable name\n            return copied\n\n    foo = Foo()   # foo.id == \'foo\'\n\n    foo2 = foo.copy() # foo2.id == \'foo2\'\n    ```\n\n- Multiple variables on Left-hand side\n\n    ```python\n    # since v0.5.4\n    def func():\n        return varname(multi_vars=True)\n\n    a = func() # a == (\'a\',)\n    a, b = func() # (a, b) == (\'a\', \'b\')\n    [a, b] = func() # (a, b) == (\'a\', \'b\')\n\n    # hierarchy is also possible\n    a, (b, c) = func() # (a, b, c) == (\'a\', \'b\', \'c\')\n    ```\n\n- Some unusual use\n\n    ```python\n    def function(**kwargs):\n        return varname(strict=False)\n\n    func = func1 = function()  # func == func1 == \'func1\'\n    # if varname < 0.8: func == func1 == \'func\'\n    # a warning will be shown\n    # since you may not want func to be \'func1\'\n\n    x = function(y = function())  # x == \'x\'\n\n    # get part of the name\n    func_abc = function()[-3:]  # func_abc == \'abc\'\n\n    # function alias supported now\n    function2 = function\n    func = function2()  # func == \'func\'\n\n    a = lambda: 0\n    a.b = function() # a.b == \'a.b\'\n    ```\n\n### The decorator way to register `__varname__` to functions/classes\n\n- Registering `__varname__` to functions\n\n    ```python\n    from varname.helpers import register\n\n    @register\n    def function():\n        return __varname__\n\n    func = function() # func == \'func\'\n    ```\n\n    ```python\n    # arguments also allowed (frame, ignore and raise_exc)\n    @register(frame=2)\n    def function():\n        return __varname__\n\n    def wrapped():\n        return function()\n\n    func = wrapped() # func == \'func\'\n    ```\n\n- Registering `__varname__` as a class property\n\n    ```python\n    @register\n    class Foo:\n        ...\n\n    foo = Foo()\n    # foo.__varname__ == \'foo\'\n    ```\n\n### Getting variable names directly using `nameof`\n\n```python\nfrom varname import varname, nameof\n\na = 1\nnameof(a) # \'a\'\n\nb = 2\nnameof(a, b) # (\'a\', \'b\')\n\ndef func():\n    return varname() + \'_suffix\'\n\nf = func() # f == \'f_suffix\'\nnameof(f)  # \'f\'\n\n# get full names of (chained) attribute calls\nfunc.a = func\nnameof(func.a, vars_only=False) # \'func.a\'\n\nfunc.a.b = 1\nnameof(func.a.b, vars_only=False) # \'func.a.b\'\n```\n\n### Detecting next immediate attribute name\n\n```python\nfrom varname import will\nclass AwesomeClass:\n    def __init__(self):\n        self.will = None\n\n    def permit(self):\n        self.will = will(raise_exc=False)\n        if self.will == \'do\':\n            # let self handle do\n            return self\n        raise AttributeError(\'Should do something with AwesomeClass object\')\n\n    def do(self):\n        if self.will != \'do\':\n            raise AttributeError("You don\'t have permission to do")\n        return \'I am doing!\'\n\nawesome = AwesomeClass()\nawesome.do() # AttributeError: You don\'t have permission to do\nawesome.permit() # AttributeError: Should do something with AwesomeClass object\nawesome.permit().do() == \'I am doing!\'\n```\n\n### Fetching argument names/sources using `argname`\n\n```python\nfrom varname import argname\n\ndef func(a, b=1):\n    print(argname(\'a\'))\n\nx = y = z = 2\nfunc(x) # prints: x\n\n\ndef func2(a, b=1):\n    print(argname(\'a\', \'b\'))\nfunc2(y, b=x) # prints: (\'y\', \'x\')\n\n\n# allow expressions\ndef func3(a, b=1):\n    print(argname(\'a\', \'b\', vars_only=False))\nfunc3(x+y, y+x) # prints: (\'x+y\', \'y+x\')\n\n\n# positional and keyword arguments\ndef func4(*args, **kwargs):\n    print(argname(\'args[1]\', \'kwargs[c]\'))\nfunc4(y, x, c=z) # prints: (\'x\', \'z\')\n\n\n# As of 0.9.0 (see: https://pwwang.github.io/python-varname/CHANGELOG/#v090)\n# Can also fetch the source of the argument for\n# __getattr__/__getitem__/__setattr/__setitem__/__add__/__lt__, etc.\nclass Foo:\n    def __setattr__(self, name, value):\n        print(argname("name", "value", func=self.__setattr__))\n\nFoo().a = 1 # prints: ("\'a\'", \'1\')\n\n```\n\n### Value wrapper\n\n```python\nfrom varname.helpers import Wrapper\n\nfoo = Wrapper(True)\n# foo.name == \'foo\'\n# foo.value == True\nbar = Wrapper(False)\n# bar.name == \'bar\'\n# bar.value == False\n\ndef values_to_dict(*args):\n    return {val.name: val.value for val in args}\n\nmydict = values_to_dict(foo, bar)\n# {\'foo\': True, \'bar\': False}\n```\n\n### Creating dictionary using `jsobj`\n\n```python\nfrom varname.helpers import jsobj\n\na = 1\nb = 2\njsobj(a, b) # {\'a\': 1, \'b\': 2}\njsobj(a, b, c=3) # {\'a\': 1, \'b\': 2, \'c\': 3}\n```\n\n### Debugging with `debug`\n\n```python\nfrom varname.helpers import debug\n\na = \'value\'\nb = [\'val\']\ndebug(a)\n# "DEBUG: a=\'value\'\\n"\ndebug(b)\n# "DEBUG: b=[\'val\']\\n"\ndebug(a, b)\n# "DEBUG: a=\'value\'\\nDEBUG: b=[\'val\']\\n"\ndebug(a, b, merge=True)\n# "DEBUG: a=\'value\', b=[\'val\']\\n"\ndebug(a, repr=False, prefix=\'\')\n# \'a=value\\n\'\n# also debug an expression\ndebug(a+a)\n# "DEBUG: a+a=\'valuevalue\'\\n"\n# If you want to disable it:\ndebug(a+a, vars_only=True) # ImproperUseError\n```\n\n### Replacing `exec` with `exec_code`\n\n```python\nfrom varname import argname\nfrom varname.helpers import exec_code\n\nclass Obj:\n    def __init__(self):\n        self.argnames = []\n\n    def receive(self, arg):\n        self.argnames.append(argname(\'arg\', func=self.receive))\n\nobj = Obj()\n# exec(\'obj.receive(1)\')  # Error\nexec_code(\'obj.receive(1)\')\nexec_code(\'obj.receive(2)\')\nobj.argnames # [\'1\', \'2\']\n```\n\n## Reliability and limitations\n\n`varname` is all depending on `executing` package to look for the node.\nThe node `executing` detects is ensured to be the correct one (see [this][19]).\n\nIt partially works with environments where other AST magics apply, including\n`pytest`, `ipython`, `macropy`, `birdseye`, `reticulate` with `R`, etc. Neither\n`executing` nor `varname` is 100% working with those environments. Use\nit at your own risk.\n\nFor example:\n\n- This will not work with `pytest`:\n\n  ```python\n  a = 1\n  assert nameof(a) == \'a\' # pytest manipulated the ast here\n\n  # do this instead\n  name_a = nameof(a)\n  assert name_a == \'a\'\n  ```\n\n[1]: https://github.com/pwwang/python-varname\n[2]: https://github.com/HanyuuLu\n[3]: https://img.shields.io/pypi/v/varname?style=flat-square\n[4]: https://pypi.org/project/varname/\n[5]: https://img.shields.io/github/tag/pwwang/python-varname?style=flat-square\n[6]: https://github.com/pwwang/python-varname\n[7]: logo.png\n[8]: https://img.shields.io/pypi/pyversions/varname?style=flat-square\n[9]: https://img.shields.io/github/actions/workflow/status/pwwang/python-varname/docs.yml?branch=master\n[10]: https://img.shields.io/github/actions/workflow/status/pwwang/python-varname/build.yml?branch=master\n[11]: https://mybinder.org/v2/gh/pwwang/python-varname/dev?filepath=playground%2Fplayground.ipynb\n[12]: https://img.shields.io/codacy/grade/6fdb19c845f74c5c92056e88d44154f7?style=flat-square\n[13]: https://app.codacy.com/gh/pwwang/python-varname/dashboard\n[14]: https://img.shields.io/codacy/coverage/6fdb19c845f74c5c92056e88d44154f7?style=flat-square\n[15]: https://pwwang.github.io/python-varname/api/varname\n[16]: https://pwwang.github.io/python-varname/CHANGELOG/\n[17]: https://img.shields.io/pypi/dm/varname?style=flat-square\n[19]: https://github.com/alexmojaki/executing#is-it-reliable\n[20]: https://stackoverflow.com/a/59364138/5088165\n',
+    'author': 'pwwang',
+    'author_email': 'pwwang@pwwang.com',
+    'maintainer': 'None',
+    'maintainer_email': 'None',
+    'url': 'https://github.com/pwwang/python-varname',
+    'packages': packages,
+    'package_data': package_data,
+    'install_requires': install_requires,
+    'extras_require': extras_require,
+    'python_requires': '>=3.8,<4.0',
+}
+
+
+setup(**setup_kwargs)

{varname-0.12.1 → varname-0.13.0}/varname/__init__.py

@@ -13,4 +13,4 @@ from .utils import (
 )
 from .core import varname, nameof, will, argname
 
-__version__ = "0.12.1"
+__version__ = "0.13.0"

{varname-0.12.1 → varname-0.13.0}/varname/helpers.py

@@ -1,9 +1,13 @@
 """Some helper functions builtin based upon core features"""
+from __future__ import annotations
+
 import inspect
 from functools import partial, wraps
+from os import PathLike
 from typing import Any, Callable, Dict, Tuple, Type, Union
 
 from .utils import IgnoreType
+from .ignore import IgnoreList
 from .core import argname, varname
 
 
@@ -220,3 +224,74 @@ def debug(
     else:
         for name_and_value in name_and_values:
             print(f"{prefix}{name_and_value}")
+
+
+def exec_code(
+    code: str,
+    globals: Dict[str, Any] = None,
+    locals: Dict[str, Any] = None,
+    /,
+    sourcefile: PathLike | str = None,
+    frame: int = 1,
+    ignore: IgnoreType = None,
+    **kwargs: Any,
+) -> None:
+    """Execute code where source code is visible at runtime.
+
+    This function is useful when you want to execute some code, where you want to
+    retrieve the AST node of the code at runtime. This function will create a
+    temporary file and write the code into it, then execute the code in the
+    file.
+
+    Examples:
+        >>> from varname import varname
+        >>> def func(): return varname()
+        >>> exec('var = func()')  # VarnameRetrievingError:
+        >>>                       #  Unable to retrieve the ast node.
+        >>> from varname.helpers import code_exec
+        >>> code_exec('var = func()')  # var == 'var'
+
+    Args:
+        code: The code to execute.
+        globals: The globals to use.
+        locals: The locals to use.
+        sourcefile: The source file to write the code into.
+            if not given, a temporary file will be used.
+            This file will be deleted after the code is executed.
+        frame: The call stack index. You can understand this as the number of
+            wrappers around this function. This is used to fetch `globals` and
+            `locals` from where the destination function (include the wrappers
+            of this function)
+            is called.
+        ignore: The intermediate calls to be ignored. See `varname.ignore`
+            Note that if both `globals` and `locals` are given, `frame` and
+            `ignore` will be ignored.
+        **kwargs: The keyword arguments to pass to `exec`.
+    """
+    if sourcefile is None:
+        import tempfile
+
+        with tempfile.NamedTemporaryFile(
+            mode="w", suffix=".py", delete=False
+        ) as f:
+            f.write(code)
+            sourcefile = f.name
+    else:
+        sourcefile = str(sourcefile)
+        with open(sourcefile, "w") as f:
+            f.write(code)
+
+    if globals is None or locals is None:
+        ignore_list = IgnoreList.create(ignore)
+        frame_info = ignore_list.get_frame(frame)
+        if globals is None:
+            globals = frame_info.f_globals
+        if locals is None:
+            locals = frame_info.f_locals
+
+    try:
+        exec(compile(code, sourcefile, "exec"), globals, locals, **kwargs)
+    finally:
+        import os
+
+        os.remove(sourcefile)

{varname-0.12.1 → varname-0.13.0}/varname/utils.py

@@ -185,7 +185,10 @@ def lookfor_parent_assign(node: ast.AST, strict: bool = True) -> AssignType:
     return None
 
 
-def node_name(node: ast.AST) -> Union[str, Tuple[Union[str, Tuple], ...]]:
+def node_name(
+    node: ast.AST,
+    subscript_slice: bool = False,
+) -> Union[str, Tuple[Union[str, Tuple], ...]]:
     """Get the node node name.
 
     Raises ImproperUseError when failed
@@ -193,15 +196,50 @@ def node_name(node: ast.AST) -> Union[str, Tuple[Union[str, Tuple], ...]]:
     if isinstance(node, ast.Name):
         return node.id
     if isinstance(node, ast.Attribute):
-        return node.attr
-    if isinstance(node, (ast.List, ast.Tuple)):
+        return f"{node_name(node.value)}.{node.attr}"
+    if isinstance(node, ast.Constant):
+        return repr(node.value)
+    if isinstance(node, (ast.List, ast.Tuple)) and not subscript_slice:
         return tuple(node_name(elem) for elem in node.elts)
+    if isinstance(node, ast.List):
+        return f"[{', '.join(node_name(elem) for elem in node.elts)}]"  # type: ignore
+    if isinstance(node, ast.Tuple):
+        if len(node.elts) == 1:
+            return f"({node_name(node.elts[0])},)"
+        return f"({', '.join(node_name(elem) for elem in node.elts)})"  # type: ignore
     if isinstance(node, ast.Starred):
         return f"*{node_name(node.value)}"
+    if isinstance(node, ast.Slice):
+        return (
+            f"{node_name(node.lower)}:{node_name(node.upper)}:{node_name(node.step)}"
+            if node.lower is not None
+            and node.upper is not None
+            and node.step is not None
+            else f"{node_name(node.lower)}:{node_name(node.upper)}"
+            if node.lower is not None and node.upper is not None
+            else f"{node_name(node.lower)}:"
+            if node.lower is not None
+            else f":{node_name(node.upper)}"
+            if node.upper is not None
+            else ":"
+        )
+
+    name = type(node).__name__
+    if isinstance(node, ast.Subscript):
+        try:
+            return f"{node_name(node.value)}[{node_name(node.slice, True)}]"
+        except ImproperUseError:
+            name = f"{node_name(node.value)}[{type(node.slice).__name__}]"
 
     raise ImproperUseError(
-        f"Can only get name of a variable or attribute, "
-        f"not {ast.dump(node)}"
+        f"Node {name!r} detected, but only following nodes are supported: \n"
+        "  - ast.Name (e.g. x)\n"
+        "  - ast.Attribute (e.g. x.y, x be other supported nodes)\n"
+        "  - ast.Constant (e.g. 1, 'a')\n"
+        "  - ast.List (e.g. [x, y, z])\n"
+        "  - ast.Tuple (e.g. (x, y, z))\n"
+        "  - ast.Starred (e.g. *x)\n"
+        "  - ast.Subscript with slice of the above nodes (e.g. x[y])"
     )
 
 

varname-0.12.1/setup.py

@@ -1,34 +0,0 @@
-# -*- coding: utf-8 -*-
-from setuptools import setup
-
-packages = \
-['varname']
-
-package_data = \
-{'': ['*']}
-
-install_requires = \
-['executing>=2.0,<3.0']
-
-extras_require = \
-{'all': ['asttokens==2.*', 'pure_eval==0.*']}
-
-setup_kwargs = {
-    'name': 'varname',
-    'version': '0.12.1',
-    'description': 'Dark magics about variable names in python.',
-    'long_description': '![varname][7]\n\n[![Pypi][3]][4] [![Github][5]][6] [![PythonVers][8]][4] ![Building][10]\n[![Docs and API][9]][15] [![Codacy][12]][13] [![Codacy coverage][14]][13]\n![Downloads][17]\n\nDark magics about variable names in python\n\n[CHANGELOG][16] | [API][15] | [Playground][11] | :fire: [StackOverflow answer][20]\n\n## Installation\n\n```shell\npip install -U varname\n```\n\nNote if you use `python < 3.8`, install `varname < 0.11`\n\n## Features\n\n- Core features:\n\n  - Retrieving names of variables a function/class call is assigned to from inside it, using `varname`.\n  - Retrieving variable names directly, using `nameof`\n  - Detecting next immediate attribute name, using `will`\n  - Fetching argument names/sources passed to a function using `argname`\n\n- Other helper APIs (built based on core features):\n\n  - A value wrapper to store the variable name that a value is assigned to, using `Wrapper`\n  - A decorator to register `__varname__` to functions/classes, using `register`\n  - A helper function to create dict without explicitly specifying the key-value pairs, using `jsobj`\n  - A `debug` function to print variables with their names and values\n\n## Credits\n\nThanks goes to these awesome people/projects:\n\n<table>\n  <tr>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/alexmojaki/executing">\n        <img src="https://ui-avatars.com/api/?color=3333ff&background=ffffff&bold=true&name=e&size=400" width="50px;" alt=""/>\n        <br /><sub><b>executing</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/alexmojaki">\n        <img src="https://avatars0.githubusercontent.com/u/3627481?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@alexmojaki</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/breuleux">\n        <img src="https://avatars.githubusercontent.com/u/599820?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@breuleux</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/ElCuboNegro">\n        <img src="https://avatars.githubusercontent.com/u/5524219?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@ElCuboNegro</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/thewchan">\n        <img src="https://avatars.githubusercontent.com/u/49702524?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@thewchan</b></sub>\n      </a>\n    </td>\n    <td align="center" style="min-width: 75px">\n      <a href="https://github.com/LawsOfSympathy">\n        <img src="https://avatars.githubusercontent.com/u/96355982?s=400&v=4" width="50px;" alt=""/>\n        <br /><sub><b>@LawsOfSympathy</b></sub>\n      </a>\n    </td>\n  </tr>\n</table>\n\nSpecial thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this project.\n\n## Usage\n\n### Retrieving the variable names using `varname(...)`\n\n- From inside a function\n\n    ```python\n    from varname import varname\n    def function():\n        return varname()\n\n    func = function()  # func == \'func\'\n    ```\n\n    When there are intermediate frames:\n\n    ```python\n    def wrapped():\n        return function()\n\n    def function():\n        # retrieve the variable name at the 2nd frame from this one\n        return varname(frame=2)\n\n    func = wrapped() # func == \'func\'\n    ```\n\n    Or use `ignore` to ignore the wrapped frame:\n\n    ```python\n    def wrapped():\n        return function()\n\n    def function():\n        return varname(ignore=wrapped)\n\n    func = wrapped() # func == \'func\'\n    ```\n\n    Calls from standard libraries are ignored by default:\n\n    ```python\n    import asyncio\n\n    async def function():\n        return varname()\n\n    func = asyncio.run(function()) # func == \'func\'\n    ```\n\n    Use `strict` to control whether the call should be assigned to\n    the variable directly:\n\n    ```python\n    def function(strict):\n        return varname(strict=strict)\n\n    func = function(True)     # OK, direct assignment, func == \'func\'\n\n    func = [function(True)]   # Not a direct assignment, raises ImproperUseError\n    func = [function(False)]  # OK, func == [\'func\']\n\n    func = function(False), function(False)   # OK, func = (\'func\', \'func\')\n    ```\n\n- Retrieving name of a class instance\n\n    ```python\n    class Foo:\n        def __init__(self):\n            self.id = varname()\n\n        def copy(self):\n            # also able to fetch inside a method call\n            copied = Foo() # copied.id == \'copied\'\n            copied.id = varname() # assign id to whatever variable name\n            return copied\n\n    foo = Foo()   # foo.id == \'foo\'\n\n    foo2 = foo.copy() # foo2.id == \'foo2\'\n    ```\n\n- Multiple variables on Left-hand side\n\n    ```python\n    # since v0.5.4\n    def func():\n        return varname(multi_vars=True)\n\n    a = func() # a == (\'a\',)\n    a, b = func() # (a, b) == (\'a\', \'b\')\n    [a, b] = func() # (a, b) == (\'a\', \'b\')\n\n    # hierarchy is also possible\n    a, (b, c) = func() # (a, b, c) == (\'a\', \'b\', \'c\')\n    ```\n\n- Some unusual use\n\n    ```python\n    def function(**kwargs):\n        return varname(strict=False)\n\n    func = func1 = function()  # func == func1 == \'func1\'\n    # if varname < 0.8: func == func1 == \'func\'\n    # a warning will be shown\n    # since you may not want func to be \'func1\'\n\n    x = function(y = function())  # x == \'x\'\n\n    # get part of the name\n    func_abc = function()[-3:]  # func_abc == \'abc\'\n\n    # function alias supported now\n    function2 = function\n    func = function2()  # func == \'func\'\n\n    a = lambda: 0\n    a.b = function() # a.b == \'b\'\n    ```\n\n### The decorator way to register `__varname__` to functions/classes\n\n- Registering `__varname__` to functions\n\n    ```python\n    from varname.helpers import register\n\n    @register\n    def function():\n        return __varname__\n\n    func = function() # func == \'func\'\n    ```\n\n    ```python\n    # arguments also allowed (frame, ignore and raise_exc)\n    @register(frame=2)\n    def function():\n        return __varname__\n\n    def wrapped():\n        return function()\n\n    func = wrapped() # func == \'func\'\n    ```\n\n- Registering `__varname__` as a class property\n\n    ```python\n    @register\n    class Foo:\n        ...\n\n    foo = Foo()\n    # foo.__varname__ == \'foo\'\n    ```\n\n### Getting variable names directly using `nameof`\n\n```python\nfrom varname import varname, nameof\n\na = 1\nnameof(a) # \'a\'\n\nb = 2\nnameof(a, b) # (\'a\', \'b\')\n\ndef func():\n    return varname() + \'_suffix\'\n\nf = func() # f == \'f_suffix\'\nnameof(f)  # \'f\'\n\n# get full names of (chained) attribute calls\nfunc.a = func\nnameof(func.a, vars_only=False) # \'func.a\'\n\nfunc.a.b = 1\nnameof(func.a.b, vars_only=False) # \'func.a.b\'\n```\n\n### Detecting next immediate attribute name\n\n```python\nfrom varname import will\nclass AwesomeClass:\n    def __init__(self):\n        self.will = None\n\n    def permit(self):\n        self.will = will(raise_exc=False)\n        if self.will == \'do\':\n            # let self handle do\n            return self\n        raise AttributeError(\'Should do something with AwesomeClass object\')\n\n    def do(self):\n        if self.will != \'do\':\n            raise AttributeError("You don\'t have permission to do")\n        return \'I am doing!\'\n\nawesome = AwesomeClass()\nawesome.do() # AttributeError: You don\'t have permission to do\nawesome.permit() # AttributeError: Should do something with AwesomeClass object\nawesome.permit().do() == \'I am doing!\'\n```\n\n### Fetching argument names/sources using `argname`\n\n```python\nfrom varname import argname\n\ndef func(a, b=1):\n    print(argname(\'a\'))\n\nx = y = z = 2\nfunc(x) # prints: x\n\n\ndef func2(a, b=1):\n    print(argname(\'a\', \'b\'))\nfunc2(y, b=x) # prints: (\'y\', \'x\')\n\n\n# allow expressions\ndef func3(a, b=1):\n    print(argname(\'a\', \'b\', vars_only=False))\nfunc3(x+y, y+x) # prints: (\'x+y\', \'y+x\')\n\n\n# positional and keyword arguments\ndef func4(*args, **kwargs):\n    print(argname(\'args[1]\', \'kwargs[c]\'))\nfunc4(y, x, c=z) # prints: (\'x\', \'z\')\n\n\n# As of 0.9.0 (see: https://pwwang.github.io/python-varname/CHANGELOG/#v090)\n# Can also fetch the source of the argument for\n# __getattr__/__getitem__/__setattr/__setitem__/__add__/__lt__, etc.\nclass Foo:\n    def __setattr__(self, name, value):\n        print(argname("name", "value"))\n\nFoo().a = 1 # prints: ("\'a\'", \'1\')\n\n```\n\n### Value wrapper\n\n```python\nfrom varname.helpers import Wrapper\n\nfoo = Wrapper(True)\n# foo.name == \'foo\'\n# foo.value == True\nbar = Wrapper(False)\n# bar.name == \'bar\'\n# bar.value == False\n\ndef values_to_dict(*args):\n    return {val.name: val.value for val in args}\n\nmydict = values_to_dict(foo, bar)\n# {\'foo\': True, \'bar\': False}\n```\n\n### Creating dictionary using `jsobj`\n\n```python\nfrom varname.helpers import jsobj\n\na = 1\nb = 2\njsobj(a, b) # {\'a\': 1, \'b\': 2}\njsobj(a, b, c=3) # {\'a\': 1, \'b\': 2, \'c\': 3}\n```\n\n### Debugging with `debug`\n\n```python\nfrom varname.helpers import debug\n\na = \'value\'\nb = [\'val\']\ndebug(a)\n# "DEBUG: a=\'value\'\\n"\ndebug(b)\n# "DEBUG: b=[\'val\']\\n"\ndebug(a, b)\n# "DEBUG: a=\'value\'\\nDEBUG: b=[\'val\']\\n"\ndebug(a, b, merge=True)\n# "DEBUG: a=\'value\', b=[\'val\']\\n"\ndebug(a, repr=False, prefix=\'\')\n# \'a=value\\n\'\n# also debug an expression\ndebug(a+a)\n# "DEBUG: a+a=\'valuevalue\'\\n"\n# If you want to disable it:\ndebug(a+a, vars_only=True) # ImproperUseError\n```\n\n## Reliability and limitations\n\n`varname` is all depending on `executing` package to look for the node.\nThe node `executing` detects is ensured to be the correct one (see [this][19]).\n\nIt partially works with environments where other AST magics apply, including\n`pytest`, `ipython`, `macropy`, `birdseye`, `reticulate` with `R`, etc. Neither\n`executing` nor `varname` is 100% working with those environments. Use\nit at your own risk.\n\nFor example:\n\n- This will not work with `pytest`:\n\n  ```python\n  a = 1\n  assert nameof(a) == \'a\' # pytest manipulated the ast here\n\n  # do this instead\n  name_a = nameof(a)\n  assert name_a == \'a\'\n  ```\n\n[1]: https://github.com/pwwang/python-varname\n[2]: https://github.com/HanyuuLu\n[3]: https://img.shields.io/pypi/v/varname?style=flat-square\n[4]: https://pypi.org/project/varname/\n[5]: https://img.shields.io/github/tag/pwwang/python-varname?style=flat-square\n[6]: https://github.com/pwwang/python-varname\n[7]: logo.png\n[8]: https://img.shields.io/pypi/pyversions/varname?style=flat-square\n[9]: https://img.shields.io/github/actions/workflow/status/pwwang/python-varname/docs.yml?branch=master\n[10]: https://img.shields.io/github/actions/workflow/status/pwwang/python-varname/build.yml?branch=master\n[11]: https://mybinder.org/v2/gh/pwwang/python-varname/dev?filepath=playground%2Fplayground.ipynb\n[12]: https://img.shields.io/codacy/grade/6fdb19c845f74c5c92056e88d44154f7?style=flat-square\n[13]: https://app.codacy.com/gh/pwwang/python-varname/dashboard\n[14]: https://img.shields.io/codacy/coverage/6fdb19c845f74c5c92056e88d44154f7?style=flat-square\n[15]: https://pwwang.github.io/python-varname/api/varname\n[16]: https://pwwang.github.io/python-varname/CHANGELOG/\n[17]: https://img.shields.io/pypi/dm/varname?style=flat-square\n[19]: https://github.com/alexmojaki/executing#is-it-reliable\n[20]: https://stackoverflow.com/a/59364138/5088165\n',
-    'author': 'pwwang',
-    'author_email': 'pwwang@pwwang.com',
-    'maintainer': 'None',
-    'maintainer_email': 'None',
-    'url': 'https://github.com/pwwang/python-varname',
-    'packages': packages,
-    'package_data': package_data,
-    'install_requires': install_requires,
-    'extras_require': extras_require,
-    'python_requires': '>=3.8,<4.0',
-}
-
-
-setup(**setup_kwargs)