Make does_styling attr public. Bump version to 1.6.

This is more often what's intended when is_a_tty is examined. While a caller could keep track of what he's passed to the Terminal constructor, it is often more convenient to have the info available directly on the instance, which we're already passing around everywhere.

4 files changed, 21 insertions, 13 deletions

diff --git a/README.rst b/README.rst
index 0b2300b..8c7cd68 100644
--- a/README.rst
+++ b/README.rst
@@ -375,15 +375,15 @@ If you want to override this--like if you anticipate your program being piped
 through ``less -r``, which handles terminal escapes just fine--pass
 ``force_styling=True`` to the ``Terminal`` constructor.
 
-In any case, there is an ``is_a_tty`` attribute on ``Terminal`` that lets you
-see whether the attached stream seems to be a terminal. If it's false, you
-might refrain from drawing progress bars and other frippery, since you're
-apparently headed into a pipe::
+In any case, there is a ``does_styling`` attribute on ``Terminal`` that lets
+you see whether your capabilities will return actual, working formatting codes.
+If it's false, you should refrain from drawing progress bars and other frippery
+and just stick to content, since you're apparently headed into a pipe::
 
     from blessings import Terminal
 
     term = Terminal()
-    if term.is_a_tty:
+    if term.does_styling:
         with term.location(0, term.height - 1):
             print 'Progress: [=======>   ]'
     print term.bold('Important stuff')
@@ -433,6 +433,10 @@ Blessings is under the MIT License. See the LICENSE file.
 Version History
 ===============
 
+1.6
+  * Add ``does_styling`` attribute. This takes ``force_styling`` into account
+    and should replace most uses of ``is_a_tty``.
+
 1.5.1
   * Clean up fabfile, removing the redundant ``test`` command.
   * Add Travis support.
diff --git a/blessings/__init__.py b/blessings/__init__.py
index 725602e..e13b70e 100644
--- a/blessings/__init__.py
+++ b/blessings/__init__.py
@@ -40,9 +40,13 @@ class Terminal(object):
         around with the terminal; it's almost always needed when the terminal
         is and saves sticking lots of extra args on client functions in
         practice.
+      ``does_styling``
+        Whether this ``Terminal`` attempts to emit capabilities. This is
+        influenced by ``is_a_tty`` and by the ``force_styling`` arg to the
+        constructor. You can examine this value to decide whether to draw
+        progress bars or other frippery.
       ``is_a_tty``
-        Whether ``stream`` appears to be a terminal. You can examine this value
-        to decide whether to draw progress bars or other frippery.
+        Whether ``stream`` appears to be a terminal.
 
     """
     def __init__(self, kind=None, stream=None, force_styling=False):
@@ -83,8 +87,8 @@ class Terminal(object):
             stream_descriptor = None
 
         self.is_a_tty = stream_descriptor is not None and isatty(stream_descriptor)
-        self._does_styling = ((self.is_a_tty or force_styling) and
-                              force_styling is not None)
+        self.does_styling = ((self.is_a_tty or force_styling) and
+                             force_styling is not None)
 
         # The desciptor to direct terminal initialization sequences to.
         # sys.__stdout__ seems to always have a descriptor of 1, even if output
@@ -92,7 +96,7 @@ class Terminal(object):
         self._init_descriptor = (sys.__stdout__.fileno()
                                  if stream_descriptor is None
                                  else stream_descriptor)
-        if self._does_styling:
+        if self.does_styling:
             # Make things like tigetstr() work. Explicit args make setupterm()
             # work even when -s is passed to nosetests. Lean toward sending
             # init sequences to the stream if it has a file descriptor, and
@@ -168,7 +172,7 @@ class Terminal(object):
         Return values are always Unicode.
 
         """
-        resolution = self._resolve_formatter(attr) if self._does_styling else NullCallableString()
+        resolution = self._resolve_formatter(attr) if self.does_styling else NullCallableString()
         setattr(self, attr, resolution)  # Cache capability codes.
         return resolution
 
diff --git a/docs/conf.py b/docs/conf.py
index 4a64708..e9ed9eb 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -50,7 +50,7 @@ copyright = u'2011, Erik Rose'
 # built documents.
 #
 # The short X.Y version.
-version = '1.5'
+version = '1.6'
 # The full version, including alpha/beta/rc tags.
 release = version
 
diff --git a/setup.py b/setup.py
index ba705da..ec4cfd1 100644
--- a/setup.py
+++ b/setup.py
@@ -16,7 +16,7 @@ if sys.version_info >= (3,):
 
 setup(
     name='blessings',
-    version='1.5.1',
+    version='1.6',
     description='A thin, practical wrapper around terminal coloring, styling, and positioning',
     long_description=open('README.rst').read(),
     author='Erik Rose',