Add number_of_colors attr. Bring release notes up to date.

3 files changed, 54 insertions, 3 deletions

diff --git a/README.rst b/README.rst
index 9a16966..3214d2e 100644
--- a/README.rst
+++ b/README.rst
@@ -337,9 +337,17 @@ Version History
 ===============
 
 1.3
+  * Add ``number_of_colors``, which tells you how many colors the terminal
+    supports.
   * Made ``color(n)`` and ``on_color(n)`` callable to wrap a string, like the
-    named colors can. Also, make them both fall back to the ``setf`` and ``setb``
-    capabilities if the ANSI ``setaf`` and ``setab`` aren't available.
+    named colors can. Also, make them both fall back to the ``setf`` and
+    ``setb`` capabilities if the ANSI ``setaf`` and ``setab`` aren't available.
+  * Allow ``color`` attr to act as an unparametrized string, not just a
+    callable.
+  * Make caching more efficient.
+  * Get rid of a reference cycle between Terminals and FormattingStrings.
+  * Update docs to reflect that terminal addressing (as in ``location()``) is
+    0-based.
 
 1.2
   * Added support for Python 3! We need 3.2.3 or greater, because the curses
diff --git a/blessings/__init__.py b/blessings/__init__.py
index f46ee66..7ebd8ad 100644
--- a/blessings/__init__.py
+++ b/blessings/__init__.py
@@ -1,6 +1,6 @@
 from collections import defaultdict
 import curses
-from curses import tigetstr, setupterm, tparm
+from curses import tigetstr, tigetnum, setupterm, tparm
 from fcntl import ioctl
 try:
     from io import UnsupportedOperation as IOUnsupportedOperation
@@ -208,6 +208,30 @@ class Terminal(object):
         """
         return ParametrizingString(self._background_color, self.normal)
 
+    @property
+    def number_of_colors(self):
+        """Return the number of colors the terminal supports.
+
+        Common values are 0, 8, 16, 88, and 256.
+
+        Though the underlying capability returns -1 when there is no color
+        support, we return 0. This lets you test more Pythonically::
+
+            if term.number_of_colors:
+                ...
+
+        We also return 0 if the terminal won't tell us how many colors it
+        supports, which I think is rare.
+
+        """
+        # This is actually the only remotely useful numeric capability. We
+        # don't name it after the underlying capability, because we deviate
+        # slightly from its behavior, and we might someday wish to give direct
+        # access to it.
+        colors = tigetnum('colors')  # Returns -1 if no color support, -2 if no such cap.
+        #self.__dict__['colors'] = ret  # Cache it. It's not changing. (Doesn't work.)
+        return colors if colors >= 0 else 0
+
     def _resolve_formatter(self, attr):
         """Resolve a sugary or plain capability name, color, or compound formatting function name into a callable capability."""
         if attr in COLORS:
diff --git a/blessings/tests.py b/blessings/tests.py
index aa8d5d8..f37bd72 100644
--- a/blessings/tests.py
+++ b/blessings/tests.py
@@ -15,6 +15,7 @@ from functools import partial
 from StringIO import StringIO
 import sys
 
+from nose import SkipTest
 from nose.tools import eq_
 
 # This tests that __all__ is correct, since we use below everything that should
@@ -156,6 +157,24 @@ def test_naked_color_cap():
     eq_(t.color + '', t.setaf + '')
 
 
+def test_number_of_colors_without_tty():
+    """``number_of_colors`` should return 0 when there's no tty."""
+    # Hypothesis: once setupterm() has run and decided the tty supports 256
+    # colors, it never changes its mind.
+    raise SkipTest
+
+    t = TestTerminal(stream=StringIO())
+    eq_(t.number_of_colors, 0)
+    t = TestTerminal(stream=StringIO(), force_styling=True)
+    eq_(t.number_of_colors, 0)
+
+
+def test_number_of_colors_with_tty():
+    """``number_of_colors`` should work."""
+    t = TestTerminal()
+    eq_(t.number_of_colors, 256)
+
+
 def test_formatting_functions():
     """Test crazy-ass formatting wrappers, both simple and compound."""
     t = TestTerminal()