highlighting, uprev, readme

Author: samuelcolvin

README.rst

@@ -10,7 +10,9 @@ Install
 
 Just::
 
-    pip install devtools
+    pip install devtools[pygments]
+
+(``pygments`` is not required but if it's available output will be highlighted and easier to read.)
 
 Usage
 -----
@@ -24,7 +26,28 @@ Usage
 
 Outputs::
 
-   test.py:4 <module>: whatever = [1, 2, 3] (list)
+   test.py:4 <module>:
+     whatever: [1, 2, 3] (list)
+
+
+That's only the tip of the iceberg, for example `demo.py </demo.py>`_:
+
+.. code:: python
+
+   import numpy as np
+
+   data = {
+       'foo': np.array(range(20)),
+       'bar': {'apple', 'banana', 'carrot', 'grapefruit'},
+       'spam': [{'a': i, 'b': (i for i in range(3))} for i in range(3)],
+       'sentence': 'this is just a boring sentence.\n' * 4
+   }
+
+   debug(data)
+
+outputs:
+
+.. image:: ./demo.py.png
 
 Usage without Import
 --------------------

demo.py

@@ -0,0 +1,10 @@
+import numpy as np
+
+data = {
+    'foo': np.array(range(20)),
+    'bar': {'apple', 'banana', 'carrot', 'grapefruit'},
+    'spam': [{'a': i, 'b': (i for i in range(3))} for i in range(3)],
+    'sentence': 'this is just a boring sentence.\n' * 4
+}
+
+debug(data)

demo.py.png

@@ -12,13 +12,20 @@
 
 __all__ = ['Debug', 'debug']
 CWD = Path('.').resolve()
-pformat = PrettyFormat()
 
 
 def env_true(var_name, alt='FALSE'):
     return os.getenv(var_name, alt).upper() in {'1', 'TRUE'}
 
 
+pformat = PrettyFormat(
+    indent_step=int(os.getenv('PY_DEVTOOLS_INDENT', 4)),
+    simple_cutoff=int(os.getenv('PY_DEVTOOLS_SIMPLE_CUTOFF', 10)),
+    width=int(os.getenv('PY_DEVTOOLS_SIMPLE_TERM_WIDTH', 80)),
+    yield_from_generators=env_true('PY_DEVTOOLS_YIELD_FROM_GEN', 'TRUE'),
+)
+
+
 class DebugArgument:
     __slots__ = 'value', 'name', 'extra'
 
@@ -30,17 +37,17 @@ def __init__(self, value, *, name=None, **extra):
             self.extra.append(('len', len(value)))
         self.extra += [(k, v) for k, v in extra.items() if v is not None]
 
-    def str(self, colours=False) -> str:
+    def str(self, colour=False, highlight=False) -> str:
         s = ''
         if self.name:
-            s = sformat(self.name, sformat.blue, apply=colours) + ': '
-        s += pformat(self.value, indent=2)
+            s = sformat(self.name, sformat.blue, apply=colour) + ': '
+        s += pformat(self.value, indent=2, highlight=highlight)
         suffix = (
             ' ({0.value.__class__.__name__}) {1}'
             .format(self, ' '.join('{}={}'.format(k, v) for k, v in self.extra))
             .rstrip(' ')  # trailing space if extra is empty
         )
-        s += sformat(suffix, sformat.dim, apply=colours)
+        s += sformat(suffix, sformat.dim, apply=colour)
         return s
 
     def __str__(self) -> str:
@@ -60,16 +67,16 @@ def __init__(self, *, filename: str, lineno: int, frame: str, arguments: List[De
         self.frame = frame
         self.arguments = arguments
 
-    def str(self, colours=False) -> str:
-        if colours:
+    def str(self, colour=False, highlight=False) -> str:
+        if colour:
             prefix = '{}:{} {}\n  '.format(
                 sformat(self.filename, sformat.magenta),
                 sformat(self.lineno, sformat.green),
                 sformat(self.frame, sformat.green, sformat.italic)
             )
         else:
             prefix = '{0.filename}:{0.lineno} {0.frame}\n  '.format(self)
-        return prefix + '\n  '.join(a.str(colours) for a in self.arguments)
+        return prefix + '\n  '.join(a.str(colour, highlight) for a in self.arguments)
 
     def __str__(self) -> str:
         return self.str()
@@ -89,10 +96,12 @@ class Debug:
 
     def __init__(self, *,
                  warnings: Optional[bool]=None,
-                 colours: Optional[bool]=None,
+                 colour: Optional[bool]=None,
+                 highlight: Optional[bool]=None,
                  frame_context_length: int=50):
         self._warnings = self._env_bool(warnings, 'PY_DEVTOOLS_WARNINGS')
-        self._colours = self._env_bool(colours, 'PY_DEVTOOLS_COLOURS')
+        self._colour = self._env_bool(colour, 'PY_DEVTOOLS_COLOUR')
+        self._highlight = self._env_bool(highlight, 'PY_DEVTOOLS_HIGHLIGHT')
         # 50 lines should be enough to make sure we always get the entire function definition
         self._frame_context_length = frame_context_length
 
@@ -106,7 +115,7 @@ def _env_bool(cls, value, env_name, env_default='TRUE'):
     def __call__(self, *args, file_=None, flush_=True, **kwargs) -> None:
         d_out = self._process(args, kwargs, r'debug *\(')
         colours_possible = isatty(file_)
-        s = d_out.str(self._colours and colours_possible)
+        s = d_out.str(self._colour and colours_possible, self._highlight and colours_possible)
         print(s, file=file_, flush=flush_)
 
     def format(self, *args, **kwargs) -> DebugOutput:

devtools/debug.py

@@ -6,7 +6,7 @@
 from .ansi import isatty
 
 try:
-    from pygments import highlight
+    import pygments
     from pygments.lexers import PythonLexer
     from pygments.formatters import Terminal256Formatter
 except ImportError:  # pragma: no cover
@@ -23,20 +23,18 @@
 
 class PrettyFormat:
     def __init__(self,
-                 colours=False,
                  indent_step=4,
                  indent_char=' ',
                  repr_strings=False,
                  simple_cutoff=10,
-                 max_width=120,
+                 width=120,
                  yield_from_generators=True):
-        self._colours = colours
         self._indent_step = indent_step
         self._c = indent_char
         self._repr_strings = repr_strings
         self._repr_generators = not yield_from_generators
         self._simple_cutoff = simple_cutoff
-        self._max_width = max_width
+        self._width = width
         self._type_lookup = [
             (dict, self._format_dict),
             ((tuple, list, set), self._format_list_like),
@@ -45,12 +43,13 @@ def __init__(self,
             (collections.Generator, self._format_generators),
         ]
 
-    def __call__(self, value: Any, *, indent: int=0, indent_first: bool=False):
+    def __call__(self, value: Any, *, indent: int=0, indent_first: bool=False, highlight: bool=False):
         self._stream = io.StringIO()
         self._format(value, indent_current=indent, indent_first=indent_first)
         s = self._stream.getvalue()
-        if self._colours and pyg_lexer:
-            s = highlight(s, lexer=pyg_lexer, formatter=pyg_formatter)
+        if highlight and pyg_lexer:
+            # apparently highlight adds a trailing new line we don't want
+            s = pygments.highlight(s, lexer=pyg_lexer, formatter=pyg_formatter).rstrip('\n')
         return s
 
     def _format(self, value: Any, indent_current: int, indent_first: bool):
@@ -105,7 +104,7 @@ def _format_str(self, value: str, value_repr: str, indent_current: int, indent_n
                 self._stream.write(value_repr)
 
     def _format_bytes(self, value: bytes, value_repr: str, indent_current: int, indent_new: int):
-        wrap = self._max_width - indent_new - 3
+        wrap = self._width - indent_new - 3
         if len(value) < wrap:
             self._stream.write(value_repr)
         else:
@@ -131,9 +130,9 @@ def _format_generators(self, value: Generator, value_repr: str, indent_current:
 
     def _format_raw(self, value: Any, value_repr: str, indent_current: int, indent_new: int):
         lines = value_repr.splitlines(True)
-        if len(lines) > 1 or (len(value_repr) + indent_current) >= self._max_width:
+        if len(lines) > 1 or (len(value_repr) + indent_current) >= self._width:
             self._stream.write('(\n')
-            wrap_at = self._max_width - indent_new
+            wrap_at = self._width - indent_new
             prefix = indent_new * self._c
             for line in lines:
                 sub_lines = textwrap.wrap(line, wrap_at)
@@ -145,8 +144,7 @@ def _format_raw(self, value: Any, value_repr: str, indent_current: int, indent_n
 
 
 pformat = PrettyFormat()
-_ppformat = PrettyFormat(colours=isatty())
 
 
-def pprint(s):
-    print(_ppformat(s), flush=True)
+def pprint(s, file=None):
+    print(pformat(s, highlight=isatty(file)), file=file, flush=True)

devtools/prettier.py

@@ -2,4 +2,4 @@
 
 __all__ = ['VERSION']
 
-VERSION = StrictVersion('0.0.2')
+VERSION = StrictVersion('0.1.0')

devtools/version.py

@@ -36,5 +36,8 @@
     license='MIT',
     packages=['devtools'],
     python_requires='>=3.5',
+    extras_require={
+        'pygments': ['Pygments>=2.2.0'],
+    },
     zip_safe=True,
 )

setup.py

@@ -28,11 +28,10 @@ def test_print(capsys):
 
 
 def test_colours():
-    pformat_ = PrettyFormat(colours=True)
-    v = pformat_({1: 2, 3: 4})
+    v = pformat({1: 2, 3: 4}, highlight=True)
     assert v.startswith('\x1b'), repr(v)
     v2 = strip_ansi(v)
-    assert v2.rstrip('\n') == pformat({1: 2, 3: 4}), repr(v2)
+    assert v2 == pformat({1: 2, 3: 4}), repr(v2)
 
 
 def test_list():
@@ -89,7 +88,7 @@ def test_generator_no_yield():
 
 
 def test_str():
-    pformat_ = PrettyFormat(max_width=12)
+    pformat_ = PrettyFormat(width=12)
     v = pformat_(string.ascii_lowercase + '\n' + string.digits)
     assert v == (
         "(\n"
@@ -105,7 +104,7 @@ def test_str_repr():
 
 
 def test_bytes():
-    pformat_ = PrettyFormat(max_width=12)
+    pformat_ = PrettyFormat(width=12)
     v = pformat_(string.ascii_lowercase.encode())
     assert v == """(
     b'abcde'