From ad2d0f4cc43f83c50bf16a2d540217e23224188a Mon Sep 17 00:00:00 2001 From: Yu-Jie Lin Date: Wed, 28 Aug 2013 19:21:09 +0800 Subject: deprecate fooBarXyz functions --- CHANGES.rst | 6 ++- docs/usage.rst | 2 +- smartypants.py | 131 ++++++++++++++++++++++++++++++++++++++--------- tests/test_deprecated.py | 13 +++++ 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) -- cgit v1.2.1