deprecate fooBarXyz functions

4 files changed, 125 insertions, 27 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 19ae366..3c06258 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -7,7 +7,8 @@ Versions without timestamps mean they are future releases.
     - drop Pyblosxom support
     - drop str-type ``attr``
         - use ``Attr.default`` instead of ``default_smartypants_attr``
-    - drop ``smartyPants()``
+    - drop fooBarXyz functions, such as  ``smartyPants()``, ``educateQuotes``,
+      and ``processEscapes``
 
 development:
     - add documentation generation
@@ -25,6 +26,9 @@ development:
         If you want the same behavior with default attributes, you need to use
         ``Attr.q | Attr.b | Attr.i | Attr.e``.
 
+    - deprecate fooBarXyz functions, such as ``educateQuotes`` and
+      ``processEscapes``
+
 1.8.1: 2013-08-20T02:27:35Z
 
     - fix deprecated ``smartyPants`` returns nothing (#2)
diff --git a/docs/usage.rst b/docs/usage.rst
index d747830..560cdf0 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -75,4 +75,4 @@ If you need to use literal straight quotes (or plain hyphens and periods), for
 example, text like ``6'2"`` may become ``6‘2”``. To avoid such situation, you
 can use backslash escapes like ``6\'2\"``.
 
-.. seealso:: :func:`smartypants.processEscapes` for a complete list of backslash escapes.
+.. seealso:: :func:`smartypants.process_escapes` for a complete list of backslash escapes.
diff --git a/smartypants.py b/smartypants.py
index 5688b1c..5ad9cbe 100755
--- a/smartypants.py
+++ b/smartypants.py
@@ -31,21 +31,21 @@ class _Attr(object):
     """
     flag for normal quotes (``"``) and (``'``) to curly ones.
 
-    .. seealso:: :func:`educateQuotes`
+    .. seealso:: :func:`convert_quotes`
     """
 
     b = 0b000000010
     """
     flag for double quotes (````backticks''``) to curly ones.
 
-    .. seealso:: :func:`educateBackticks`
+    .. seealso:: :func:`convert_backticks`
     """
     B = 0b000000110
     """
     flag for double quotes (````backticks''``) and single quotes
     (```single'``) to curly ones.
 
-    .. seealso:: :func:`educateBackticks` and :func:`educateSingleBackticks`
+    .. seealso:: :func:`convert_backticks` and :func:`convert_single_backticks`
     """
     mask_b = b | B
 
@@ -53,21 +53,21 @@ class _Attr(object):
     """
     flag for dashes (``--``) to em-dashes.
 
-    .. seealso:: :func:`educateDashes`
+    .. seealso:: :func:`convert_dashes`
     """
     D = 0b000011000
     """
     flag for old-school typewriter dashes (``--``) to en-dashes and dashes
     (``---``) to em-dashes.
 
-    .. seealso:: :func:`educateDashesOldSchool`
+    .. seealso:: :func:`convert_dashes_oldschool`
     """
     i = 0b000101000
     """
     flag for inverted old-school typewriter dashes (``--``) to em-dashes and
     dashes (``---``) to en-dashes.
 
-    .. seealso:: :func:`educateDashesOldSchoolInverted`
+    .. seealso:: :func:`convert_dashes_oldschool_inverted`
     """
     mask_d = d | D | i
 
@@ -75,7 +75,7 @@ class _Attr(object):
     """
     flag for dashes (``...``) to ellipses.
 
-    .. seealso:: :func:`educateEllipses`
+    .. seealso:: :func:`convert_ellipses`
     """
     w = 0b010000000
     """
@@ -316,28 +316,28 @@ def smartypants(text, attr=None):
             # Remember last char of this token before processing.
             last_char = t[-1:]
             if not in_pre:
-                t = processEscapes(t)
+                t = process_escapes(t)
 
                 if convert_quot:
                     t = re.sub('"', '"', t)
 
                 if do_dashes:
                     if do_dashes == Attr.d:
-                        t = educateDashes(t)
+                        t = convert_dashes(t)
                     if do_dashes == Attr.D:
-                        t = educateDashesOldSchool(t)
+                        t = convert_dashes_oldschool(t)
                     if do_dashes == Attr.i:
-                        t = educateDashesOldSchoolInverted(t)
+                        t = convert_dashes_oldschool_inverted(t)
 
                 if do_ellipses:
-                    t = educateEllipses(t)
+                    t = convert_ellipses(t)
 
                 # Note: backticks need to be processed before quotes.
                 if do_backticks == Attr.b:
-                    t = educateBackticks(t)
+                    t = convert_backticks(t)
 
                 if do_backticks == Attr.B:
-                    t = educateSingleBackticks(t)
+                    t = convert_single_backticks(t)
 
                 if do_quotes:
                     if t == "'":
@@ -355,10 +355,10 @@ def smartypants(text, attr=None):
 
                     else:
                         # Normal case:
-                        t = educateQuotes(t)
+                        t = convert_quotes(t)
 
                 if do_stupefy:
-                    t = stupefyEntities(t)
+                    t = stupefy_entities(t)
 
             prev_token_last_char = last_char
             result.append(t)
@@ -367,10 +367,19 @@ def smartypants(text, attr=None):
 
 
 def educateQuotes(text):
+
+    msg = 'educateQuotes will be removed at Version 2.0.0'
+    warnings.filterwarnings('once', msg, DeprecationWarning)
+    warnings.warn(msg, DeprecationWarning)
+
+    return convert_quotes(text)
+
+
+def convert_quotes(text):
     """
     Convert quotes in *text* into HTML curly quote entities.
 
-    >>> print(educateQuotes('"Isn\\'t this fun?"'))
+    >>> print(convert_quotes('"Isn\\'t this fun?"'))
     “Isn’t this fun?”
     """
 
@@ -461,11 +470,20 @@ def educateQuotes(text):
 
 
 def educateBackticks(text):
+
+    msg = 'educateBackticks will be removed at Version 2.0.0'
+    warnings.filterwarnings('once', msg, DeprecationWarning)
+    warnings.warn(msg, DeprecationWarning)
+
+    return convert_backticks(text)
+
+
+def convert_backticks(text):
     """
     Convert ````backticks''``-style double quotes in *text* into HTML curly
     quote entities.
 
-    >>> print(educateBackticks("``Isn't this fun?''"))
+    >>> print(convert_backticks("``Isn't this fun?''"))
     “Isn't this fun?”
     """
 
@@ -475,11 +493,20 @@ def educateBackticks(text):
 
 
 def educateSingleBackticks(text):
+
+    msg = 'educateSingleBackticks will be removed at Version 2.0.0'
+    warnings.filterwarnings('once', msg, DeprecationWarning)
+    warnings.warn(msg, DeprecationWarning)
+
+    return convert_single_backticks(text)
+
+
+def convert_single_backticks(text):
     """
     Convert ```backticks'``-style single quotes in *text* into HTML curly
     quote entities.
 
-    >>> print(educateSingleBackticks("`Isn't this fun?'"))
+    >>> print(convert_single_backticks("`Isn't this fun?'"))
     ‘Isn’t this fun?’
     """
 
@@ -489,11 +516,20 @@ def educateSingleBackticks(text):
 
 
 def educateDashes(text):
+
+    msg = 'educateDashes will be removed at Version 2.0.0'
+    warnings.filterwarnings('once', msg, DeprecationWarning)
+    warnings.warn(msg, DeprecationWarning)
+
+    return convert_dashes(text)
+
+
+def convert_dashes(text):
     """
     Convert ``--`` in *text* into em-dash HTML entities.
 
     >>> quote = 'Nothing endures but change. -- Heraclitus'
-    >>> print(educateDashes(quote))
+    >>> print(convert_dashes(quote))
     Nothing endures but change. — Heraclitus
     """
 
@@ -502,12 +538,21 @@ def educateDashes(text):
 
 
 def educateDashesOldSchool(text):
+
+    msg = 'educateDashesOldSchool will be removed at Version 2.0.0'
+    warnings.filterwarnings('once', msg, DeprecationWarning)
+    warnings.warn(msg, DeprecationWarning)
+
+    return convert_dashes_oldschool(text)
+
+
+def convert_dashes_oldschool(text):
     """
     Convert ``--`` and ``---`` in *text* into en-dash and em-dash HTML
     entities, respectively.
 
     >>> quote = 'Life itself is the proper binge. --- Julia Child (1912--2004)'
-    >>> print(educateDashesOldSchool(quote))
+    >>> print(convert_dashes_oldschool(quote))
     Life itself is the proper binge. — Julia Child (1912–2004)
     """
 
@@ -517,6 +562,15 @@ def educateDashesOldSchool(text):
 
 
 def educateDashesOldSchoolInverted(text):
+
+    msg = 'educateDashesOldSchoolInverted will be removed at Version 2.0.0'
+    warnings.filterwarnings('once', msg, DeprecationWarning)
+    warnings.warn(msg, DeprecationWarning)
+
+    return convert_dashes_oldschool_inverted(text)
+
+
+def convert_dashes_oldschool_inverted(text):
     """
     Convert ``--`` and ``---`` in *text* into em-dash and en-dash HTML
     entities, respectively.
@@ -524,7 +578,7 @@ def educateDashesOldSchoolInverted(text):
     Two reasons why:
 
     * First, unlike the en- and em-dash syntax supported by
-      :func:`educateDashesOldSchool`, it's compatible with existing entries
+      :func:`convert_dashes_oldschool`, it's compatible with existing entries
       written before SmartyPants 1.1, back when ``--`` was only used for
       em-dashes.
     * Second, em-dashes are more common than en-dashes, and so it sort of
@@ -532,7 +586,7 @@ def educateDashesOldSchoolInverted(text):
       Swartz for the idea.)
 
     >>> quote = 'Dare to be naïve. -- Buckminster Fuller (1895---1983)'
-    >>> print(educateDashesOldSchoolInverted(quote))
+    >>> print(convert_dashes_oldschool_inverted(quote))
     Dare to be naïve. — Buckminster Fuller (1895–1983)
     """
 
@@ -542,10 +596,19 @@ def educateDashesOldSchoolInverted(text):
 
 
 def educateEllipses(text):
+
+    msg = 'educateEllipses will be removed at Version 2.0.0'
+    warnings.filterwarnings('once', msg, DeprecationWarning)
+    warnings.warn(msg, DeprecationWarning)
+
+    return convert_ellipses(text)
+
+
+def convert_ellipses(text):
     """
     Convert ``...`` in *text* into ellipsis HTML entities
 
-    >>> print(educateEllipses('Huh...?'))
+    >>> print(convert_ellipses('Huh...?'))
     Huh…?
     """
 
@@ -555,10 +618,19 @@ def educateEllipses(text):
 
 
 def stupefyEntities(text):
+
+    msg = 'stupefyEntities will be removed at Version 2.0.0'
+    warnings.filterwarnings('once', msg, DeprecationWarning)
+    warnings.warn(msg, DeprecationWarning)
+
+    return stupefy_entities(text)
+
+
+def stupefy_entities(text):
     """
     Convert SmartyPants HTML entities in *text* into their ASCII counterparts.
 
-    >>> print(stupefyEntities('“Hello — world.”'))
+    >>> print(stupefy_entities('“Hello — world.”'))
     "Hello -- world."
     """
 
@@ -577,6 +649,15 @@ def stupefyEntities(text):
 
 
 def processEscapes(text):
+
+    msg = 'processEscapes will be removed at Version 2.0.0'
+    warnings.filterwarnings('once', msg, DeprecationWarning)
+    warnings.warn(msg, DeprecationWarning)
+
+    return process_escapes(text)
+
+
+def process_escapes(text):
     r"""
     Processe the following backslash escape sequences in *text*. This is useful
     if you want to force a "dumb" quote or other character to appear.
diff --git a/tests/test_deprecated.py b/tests/test_deprecated.py
index 1990f1f..35c04d8 100644
--- a/tests/test_deprecated.py
+++ b/tests/test_deprecated.py
@@ -5,6 +5,7 @@
 import unittest
 import warnings
 
+import smartypants as sps
 from smartypants import Attr, smartypants as sp, smartyPants as sP
 
 
@@ -38,3 +39,15 @@ class SmartyPantsDeprecatedTestCase(unittest.TestCase):
             self.assertEquals(T, E)
 
             self.assertEquals(len(w), 1)
+
+    def test_educateQuotes(self):
+
+        TEXT = '"foo" -- bar'
+
+        with warnings.catch_warnings(record=True) as w:
+
+            T = sps.educateQuotes(TEXT)
+            E = '“foo” -- bar'
+            self.assertEquals(T, E)
+
+            self.assertEquals(len(w), 1)