Add a debug function to print variable name and value together. (#27)

* Add a debug function to print variable name and value together.

* 0.5.3

* Deprecate namedtuple

* Remove namedtuple from readme

Author: pwwang

.pylintrc

@@ -152,7 +152,10 @@ disable=print-statement,
         too-few-public-methods,
         protected-access,
         too-many-instance-attributes,
-        too-many-arguments
+        too-many-arguments,
+        too-many-return-statements,
+        too-many-locals,
+        not-callable
 
 # Enable the message, report, category or checker with the given id(s). You can
 # either give multiple identifier separated by comma (,) or put this option
@@ -308,6 +311,7 @@ good-names=i,
            y,
            z,
            np,
+           gc,
            nn,
            ns,
            t,

README.md

@@ -19,8 +19,8 @@ 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`
-- Shortcut for `collections.namedtuple`
 - Injecting `__varname__` to objects
+- A `debug` function to print variables with their names and values.
 
 ## Credits
 
@@ -197,17 +197,6 @@ awesome.permit() # AttributeError: Should do something with AwesomeClass object
 awesome.permit().do() == 'I am doing!'
 ```
 
-### Shortcut for `collections.namedtuple`
-```python
-# instead of
-from collections import namedtuple
-Name = namedtuple('Name', ['first', 'last'])
-
-# we can do:
-from varname import namedtuple
-Name = namedtuple(['first', 'last'])
-```
-
 ### Injecting `__varname__`
 
 ```python
@@ -230,6 +219,20 @@ b.append(1)
 a == b
 ```
 
+### Debugging with `debug`
+```python
+a = 'value'
+b = object()
+debug(a) # DEBUG: a='value'
+debug(b) # DEBUG: b=<object object at 0x2b70580e5f20>
+debug(a, b)
+# DEBUG: a='value'
+# DEBUG: b=<object object at 0x2b70580e5f20>
+debug(a, b, merge=True)
+# DEBUG: a='value', b=<object object at 0x2b70580e5f20>
+debug(a, repr=False, prefix='') # a=value
+```
+
 ## Reliability and limitations
 `varname` is all depending on `executing` package to look for the node.
 The node `executing` detects is ensured to be the correct one (see [this][19]).

README.rst

@@ -14,8 +14,8 @@
    :target: https://img.shields.io/github/tag/pwwang/python-varname?style=flat-square
    :alt: Github
  <https://github.com/pwwang/python-varname>`_ `
-.. image:: https://img.shields.io/pypi/pyversions/python-varname?style=flat-square
-   :target: https://img.shields.io/pypi/pyversions/python-varname?style=flat-square
+.. image:: https://img.shields.io/pypi/pyversions/varname?style=flat-square
+   :target: https://img.shields.io/pypi/pyversions/varname?style=flat-square
    :alt: PythonVers
  <https://pypi.org/project/varname/>`_ 
 .. image:: https://img.shields.io/github/workflow/status/pwwang/python-varname/Build%20and%20Deploy?style=flat-square
@@ -62,6 +62,7 @@ Features
 * Detecting next immediate attribute name using ``will``
 * Shortcut for ``collections.namedtuple``
 * Injecting ``__varname__`` to objects
+* A ``debug`` function to print variables with their names and values.
 
 Credits
 -------
@@ -291,6 +292,22 @@ Injecting ``__varname__``
    b.append(1)
    a == b
 
+Debugging with ``debug``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
+
+   a = 'value'
+   b = object()
+   debug(a) # DEBUG: a='value'
+   debug(b) # DEBUG: b=<object object at 0x2b70580e5f20>
+   debug(a, b)
+   # DEBUG: a='value'
+   # DEBUG: b=<object object at 0x2b70580e5f20>
+   debug(a, b, merge=True)
+   # DEBUG: a='value', b=<object object at 0x2b70580e5f20>
+   debug(a, repr=False, prefix='') # a=value
+
 Reliability and limitations
 ---------------------------
 

pyproject.toml

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

setup.py

@@ -21,7 +21,7 @@
 setup(
     long_description=readme,
     name='varname',
-    version='0.5.2',
+    version='0.5.3',
     description='Dark magics about variable names in python.',
     python_requires='==3.*,>=3.6.0',
     project_urls={

tests/test_varname.py

@@ -534,3 +534,11 @@ def test_nameof_node_not_retrieved():
     code = compile(source, filename="<string2>", mode="exec")
     with pytest.raises(VarnameRetrievingError, match='Source code unavailable'):
         exec(code)
+
+def test_debug(capsys):
+    a = 1
+    b = object()
+    debug(a)
+    assert 'DEBUG: a=1\n' == capsys.readouterr().out
+    debug(a, b, merge=True)
+    assert 'DEBUG: a=1, b=<object' in capsys.readouterr().out

varname.py

@@ -10,10 +10,10 @@
 
 import executing
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"
 __all__ = [
     "VarnameRetrievingError", "varname", "will",
-    "inject", "nameof", "namedtuple", "Wrapper"
+    "inject", "nameof", "namedtuple", "Wrapper", "debug"
 ]
 
 class VarnameRetrievingError(Exception):
@@ -267,6 +267,42 @@ def nameof(var, *more_vars, # pylint: disable=unused-argument
 
     return ret[0] if not more_vars else tuple(ret)
 
+def debug(var, *more_vars,
+          prefix: str = 'DEBUG: ',
+          merge: bool = False,
+          repr: bool = True) -> None: # pylint: disable=redefined-builtin
+    """Print variable names and values.
+
+    Examples:
+        >>> a = 1
+        >>> b = object
+        >>> print(f'a={a}') # previously, we have to do
+        >>> print(f'{a=}')  # or with python3.8
+        >>> # instead we can do:
+        >>> debug(a) # DEBUG: a=1
+        >>> debug(a, prefix='') # a=1
+        >>> debug(a, b, merge=True) # a=1, b=<object object at 0x2b9a4c89cf00>
+
+    Args:
+        var: The variable to print
+        *more_vars: Other variables to print
+        prefix: A prefix to print for each line
+        merge: Whether merge all variables in one line or not
+        repr: Print the value as `repr(var)`? otherwise `str(var)`
+    """
+    var_names = nameof(var, *more_vars, caller=2, full=True)
+    if not isinstance(var_names, tuple):
+        var_names = (var_names, )
+    variables = (var, *more_vars)
+    name_and_values = [f"{var_name}={variables[i]!r}" if repr
+                       else f"{var_name}={variables[i]}"
+                       for i, var_name in enumerate(var_names)]
+    if merge:
+        print(f"{prefix}{', '.join(name_and_values)}")
+    else:
+        for name_and_value in name_and_values:
+            print(f"{prefix}{name_and_value}")
+
 def namedtuple(*args, **kwargs) -> type:
     """A shortcut for namedtuple
 
@@ -289,6 +325,9 @@ def namedtuple(*args, **kwargs) -> type:
     Returns:
         The namedtuple you desired.
     """
+    warnings.warn("Shortcut for namedtuple is deprecated and "
+                  "will be removed in 0.6.0. Use the standard way instead.",
+                  DeprecationWarning)
     typename = varname(raise_exc=True)
     return standard_namedtuple(typename, *args, **kwargs)