varname 0.14.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

varname/__init__.py

@@ -11,6 +11,6 @@ from .utils import (
     MaybeDecoratedFunctionWarning,
     UsingExecWarning,
 )
-from .core import varname, will, argname
+from .core import varname, nameof, will, argname
 
-__version__ = "0.14.0"
+__version__ = "0.15.0"

varname/core.py

@@ -3,11 +3,12 @@ from __future__ import annotations
 import ast
 import re
 import warnings
-from typing import List, Union, Tuple, Type, Callable, overload
+from typing import Any, List, Union, Tuple, Type, Callable, overload
 
 from executing import Source
 
 from .utils import (
+    bytecode_nameof,
     get_node,
     get_node_by_frame,
     lookfor_parent_assign,
@@ -217,6 +218,129 @@ def will(frame: int = 1, raise_exc: bool = True) -> str:
     return node.attr
 
 
+@overload
+def nameof(
+    var: Any,
+    *,
+    frame: int = 1,
+    vars_only: bool = True,
+) -> str:  # pragma: no cover
+    ...
+
+
+@overload
+def nameof(
+    var: Any,
+    more_var: Any,
+    /,  # introduced in python 3.8
+    *more_vars: Any,
+    frame: int = 1,
+    vars_only: bool = True,
+) -> Tuple[str, ...]:  # pragma: no cover
+    ...
+
+
+def nameof(
+    var: Any,
+    *more_vars: Any,
+    frame: int = 1,
+    vars_only: bool = True,
+) -> Union[str, Tuple[str, ...]]:
+    """Get the names of the variables passed in
+
+    Examples:
+        >>> a = 1
+        >>> nameof(a) # 'a'
+
+        >>> b = 2
+        >>> nameof(a, b) # ('a', 'b')
+
+        >>> x = lambda: None
+        >>> x.y = 1
+        >>> nameof(x.y, vars_only=False) # 'x.y'
+
+    Note:
+        This function works with the environments where source code is
+        available, in other words, the callee's node can be retrieved by
+        `executing`. In some cases, for example, running code from python
+        shell/REPL or from `exec`/`eval`, we try to fetch the variable name
+        from the bytecode. This requires only a single variable name is passed
+        to this function and no keyword arguments, meaning that getting full
+        names of attribute calls are not supported in such cases.
+
+    Args:
+        var: The variable to retrieve the name of
+        *more_vars: Other variables to retrieve the names of
+        frame: The this function is called from the wrapper of it. `frame=1`
+            means no wrappers.
+            Note that the calls from standard libraries are ignored.
+            Also note that the wrapper has to have signature as this one.
+        vars_only: Whether only allow variables/attributes as arguments or
+            any expressions. If `False`, then the sources of the arguments
+            will be returned.
+
+    Returns:
+        The names/sources of variables/expressions passed in.
+            If a single argument is passed, return the name/source of it.
+            If multiple variables are passed, return a tuple of their
+            names/sources.
+            If the argument is an attribute (e.g. `a.b`) and `vars_only` is
+            `True`, only `"b"` will returned. Set `vars_only` to `False` to
+            get `"a.b"`.
+
+    Raises:
+        VarnameRetrievingError: When the callee's node cannot be retrieved or
+            trying to retrieve the full name of non attribute series calls.
+    """
+    # Frame is anyway used in get_node
+    frameobj = IgnoreList.create(
+        ignore_lambda=False,
+        ignore_varname=False,
+    ).get_frame(frame)
+
+    node = get_node_by_frame(frameobj, raise_exc=True)
+    if not node:
+        # We can't retrieve the node by executing.
+        # It can be due to running code from python/shell, exec/eval or
+        # other environments where sourcecode cannot be reached
+        # make sure we keep it simple (only single variable passed and no
+        # full passed) to use bytecode_nameof
+        #
+        # We don't have to check keyword arguments here, as the instruction
+        # will then be CALL_FUNCTION_KW.
+        if not more_vars:
+            return bytecode_nameof(frameobj.f_code, frameobj.f_lasti)
+
+        # We are anyway raising exceptions, no worries about additional burden
+        # of frame retrieval again
+        source = frameobj.f_code.co_filename
+        if source == "<stdin>":
+            raise VarnameRetrievingError(
+                "Are you trying to call nameof in REPL/python shell? "
+                "In such a case, nameof can only be called with single "
+                "argument and no keyword arguments."
+            )
+        if source == "<string>":
+            raise VarnameRetrievingError(
+                "Are you trying to call nameof from exec/eval? "
+                "In such a case, nameof can only be called with single "
+                "argument and no keyword arguments."
+            )
+        raise VarnameRetrievingError(
+            "Source code unavailable, nameof can only retrieve the name of "
+            "a single variable, and argument `full` should not be specified."
+        )
+
+    out = argname(
+        "var",
+        "*more_vars",
+        func=nameof,
+        frame=frame,
+        vars_only=vars_only,
+    )
+    return out if more_vars else out[0]  # type: ignore
+
+
 @overload
 def argname(
     arg: str,

varname/utils.py

@@ -10,6 +10,7 @@ Attributes:
         `inspect.getmodule(frame)`
 """
 import sys
+import dis
 import ast
 import warnings
 import inspect
@@ -17,7 +18,12 @@ from os import path
 from pathlib import Path
 from functools import lru_cache, singledispatch
 from types import ModuleType, FunctionType, CodeType, FrameType
-from typing import Tuple, Union, List, Mapping, Callable
+from typing import Tuple, Union, List, Mapping, Callable, Dict
+
+if sys.version_info < (3, 10):
+    from typing_extensions import TypeAlias  # pragma: no cover
+else:
+    from typing import TypeAlias
 
 from executing import Source
 
@@ -62,16 +68,16 @@ IgnoreElemType = Union[
 ]
 IgnoreType = Union[IgnoreElemType, List[IgnoreElemType]]
 
-ArgSourceType = Union[ast.AST, str]
-ArgSourceType = Union[ArgSourceType, Tuple[ArgSourceType, ...]]
-ArgSourceType = Union[ArgSourceType, Mapping[str, ArgSourceType]]
+ArgSourceType: TypeAlias = Union[ast.AST, str]
+ArgSourceType: TypeAlias = Union[ArgSourceType, Tuple[ArgSourceType, ...]]
+ArgSourceType: TypeAlias = Union[ArgSourceType, Mapping[str, ArgSourceType]]
 
 if sys.version_info >= (3, 8):
     ASSIGN_TYPES = (ast.Assign, ast.AnnAssign, ast.NamedExpr)
-    AssignType = Union[ASSIGN_TYPES]  # type: ignore
-else:  # pragma: no cover
+    AssignType: TypeAlias = Union[ASSIGN_TYPES]  # type: ignore
+else:  # pragma: no cover  # Python < 3.8
     ASSIGN_TYPES = (ast.Assign, ast.AnnAssign)
-    AssignType = Union[ASSIGN_TYPES]  # type: ignore
+    AssignType: TypeAlias = Union[ASSIGN_TYPES]  # type: ignore
 
 PY311 = sys.version_info >= (3, 11)
 MODULE_IGNORE_ID_NAME = "__varname_ignore_id__"
@@ -166,7 +172,7 @@ def get_node_by_frame(frame: FrameType, raise_exc: bool = True) -> ast.AST:
         raise VarnameRetrievingError(
             "Couldn't retrieve the call node. "
             "This may happen if you're using some other AST magic at the "
-            "same time, such as pytest, macropy, or birdseye."
+            "same time, such as pytest, ipython, macropy, or birdseye."
         )
 
     return None
@@ -243,6 +249,71 @@ def node_name(
     )
 
 
+@lru_cache()
+def bytecode_nameof(code: CodeType, offset: int) -> str:
+    """Cached Bytecode version of nameof
+
+    We are trying this version only when the sourcecode is unavisible. In most
+    cases, this will happen when user is trying to run a script in REPL/
+    python shell, with `eval`, or other circumstances where the code is
+    manipulated to run but sourcecode is not available.
+    """
+    kwargs: Dict[str, bool] = (
+        {"show_caches": True} if sys.version_info[:2] >= (3, 11) else {}
+    )
+
+    instructions = list(dis.get_instructions(code, **kwargs))
+    ((current_instruction_index, current_instruction),) = (
+        (index, instruction)
+        for index, instruction in enumerate(instructions)
+        if instruction.offset == offset
+    )
+
+    while current_instruction.opname == "CACHE":  # pragma: no cover
+        current_instruction_index -= 1
+        current_instruction = instructions[current_instruction_index]
+
+    pos_only_error = VarnameRetrievingError(
+        "'nameof' can only be called with a single positional argument "
+        "when source code is not avaiable."
+    )
+    if current_instruction.opname in (  # pragma: no cover
+        "CALL_FUNCTION_EX",
+        "CALL_FUNCTION_KW",
+    ):
+        raise pos_only_error
+
+    if current_instruction.opname not in (
+        "CALL_FUNCTION",
+        "CALL_METHOD",
+        "CALL",
+        "CALL_KW",
+    ):
+        raise VarnameRetrievingError("Did you call 'nameof' in a weird way?")
+
+    current_instruction_index -= 1
+    name_instruction = instructions[current_instruction_index]
+    while name_instruction.opname in ("CACHE", "PRECALL"):  # pragma: no cover
+        current_instruction_index -= 1
+        name_instruction = instructions[current_instruction_index]
+
+    if name_instruction.opname in ("KW_NAMES", "LOAD_CONST"):  # LOAD_CONST python 3.13
+        raise pos_only_error
+
+    if not name_instruction.opname.startswith("LOAD_"):
+        raise VarnameRetrievingError("Argument must be a variable or attribute")
+
+    name = name_instruction.argrepr
+    if not name.isidentifier():
+        raise VarnameRetrievingError(
+            f"Found the variable name {name!r} which is obviously wrong. "
+            "This may happen if you're using some other AST magic at the "
+            "same time, such as pytest, ipython, macropy, or birdseye."
+        )
+
+    return name
+
+
 def attach_ignore_id_to_module(module: ModuleType) -> None:
     """Attach the ignore id to module
 

{varname-0.14.0.dist-info → varname-0.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: varname
-Version: 0.14.0
+Version: 0.15.0
 Summary: Dark magics about variable names in python.
 License: MIT
 Author: pwwang
@@ -18,6 +18,7 @@ Provides-Extra: all
 Requires-Dist: asttokens (==3.*) ; extra == "all"
 Requires-Dist: executing (>=2.1,<3.0)
 Requires-Dist: pure_eval (==0.*) ; extra == "all"
+Requires-Dist: typing_extensions (>=4.13,<5.0) ; python_version < "3.10"
 Project-URL: Homepage, https://github.com/pwwang/python-varname
 Project-URL: Repository, https://github.com/pwwang/python-varname
 Description-Content-Type: text/markdown
@@ -268,6 +269,31 @@ Special thanks to [@HanyuuLu][2] to give up the name `varname` in pypi for this
     # foo.__varname__ == 'foo'
     ```
 
+### Getting variable names directly using `nameof`
+
+```python
+from varname import varname, nameof
+
+a = 1
+nameof(a) # 'a'
+
+b = 2
+nameof(a, b) # ('a', 'b')
+
+def func():
+    return varname() + '_suffix'
+
+f = func() # f == 'f_suffix'
+nameof(f)  # 'f'
+
+# get full names of (chained) attribute calls
+func.a = func
+nameof(func.a, vars_only=False) # 'func.a'
+
+func.a.b = 1
+nameof(func.a.b, vars_only=False) # 'func.a.b'
+```
+
 ### Detecting next immediate attribute name
 
 ```python

varname-0.15.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+varname/__init__.py,sha256=msPiS0pHXpErWWjXSxkVWqjfjLHHX8zcVgWRBwfJlT4,369
+varname/core.py,sha256=iuipHp0kavT5gR6VEYGDtpOdf23p_aYsll04f7woL0M,19346
+varname/helpers.py,sha256=jZaP-qWQJwi8T2f886eHOj-llXAPHk5SMU6PfVn-9dg,9558
+varname/ignore.py,sha256=-VC3oqag44y2UlAw0ErYKHotx616qJL3Sjb_5y7Tw1c,14400
+varname/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+varname/utils.py,sha256=3Z0bEGbrKOWXsfRO5GeJBqqKNOprK-jO2MpVqYwgnIE,23188
+varname-0.15.0.dist-info/LICENSE,sha256=3bS8O2tMbBPz8rWmZBAOzkHQjcK-b7KwFHyyghEZ-Ak,1063
+varname-0.15.0.dist-info/METADATA,sha256=Z70KEyKxGrsdqNx83lg-9f8dOgFaMZpgTXtwO9rgp3U,13236
+varname-0.15.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+varname-0.15.0.dist-info/RECORD,,

{varname-0.14.0.dist-info → varname-0.15.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.0.1
+Generator: poetry-core 2.1.3
 Root-Is-Purelib: true
 Tag: py3-none-any

varname-0.14.0.dist-info/RECORD

@@ -1,10 +0,0 @@
-varname/__init__.py,sha256=J1-VOils3vUZH4QxbbtCH1likQee7vyTo_ocYxTz-kQ,361
-varname/core.py,sha256=hFDoefsMc4TWBEzM-oMfzuCVFpmSv7iE82-m7cBv5s0,15027
-varname/helpers.py,sha256=jZaP-qWQJwi8T2f886eHOj-llXAPHk5SMU6PfVn-9dg,9558
-varname/ignore.py,sha256=-VC3oqag44y2UlAw0ErYKHotx616qJL3Sjb_5y7Tw1c,14400
-varname/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-varname/utils.py,sha256=l1eIuZhXrrLgS1wM3MbVh10LQChLPOkfHz9F67fQnoY,20580
-varname-0.14.0.dist-info/LICENSE,sha256=3bS8O2tMbBPz8rWmZBAOzkHQjcK-b7KwFHyyghEZ-Ak,1063
-varname-0.14.0.dist-info/METADATA,sha256=jmqGTlr-MZDjGG47OQzeoWOuLVgILhmPzhoaqTZkUQs,12746
-varname-0.14.0.dist-info/WHEEL,sha256=IYZQI976HJqqOpQU6PHkJ8fb3tMNBFjg-Cn-pwAbaFM,88
-varname-0.14.0.dist-info/RECORD,,