Change the API, deprecate the old dict arguments. See also: https://code.google.com/p/python-creole/wiki/API_changes_v1

9 files changed, 120 insertions, 54 deletions

diff --git a/creole/__init__.py b/creole/__init__.py
index 2f988ac..36a7b55 100644
--- a/creole/__init__.py
+++ b/creole/__init__.py
@@ -20,12 +20,13 @@
 
 from __future__ import division, absolute_import, print_function, unicode_literals
 
-__version__ = (0, 9, 1)
+__version__ = (1, 0, 0, "pre")
 __api__ = (1, 0) # Creole 1.0 spec - http://wikicreole.org/
 
 
 import os
 import sys
+import warnings
 
 from creole.creole2html.emitter import HtmlEmitter
 from creole.creole2html.parser import BlockRules, CreoleParser
@@ -43,47 +44,83 @@ VERSION_STRING = '.'.join(str(part) for part in __version__)
 API_STRING = '.'.join(str(integer) for integer in __api__)
 
 
-def creole2html(markup_string, debug=False, parser_kwargs={}, emitter_kwargs={}):
+def creole2html(markup_string, debug=False,
+        parser_kwargs={}, emitter_kwargs={},
+        block_rules=None, blog_line_breaks=True,
+        macros=None, verbose=None, stderr=None,
+    ):
     """
     convert creole markup into html code
 
     >>> creole2html('This is **creole //markup//**!')
     '<p>This is <strong>creole <i>markup</i></strong>!</p>'
+    
+    Info: parser_kwargs and emitter_kwargs are deprecated
     """
     assert isinstance(markup_string, TEXT_TYPE), "given markup_string must be unicode!"
 
+    parser_kwargs2 = {
+        "block_rules": block_rules,
+        "blog_line_breaks": blog_line_breaks,
+    }
+    if parser_kwargs:
+        warnings.warn("parser_kwargs argument in creole2html would be removed in the future!", PendingDeprecationWarning)
+        parser_kwargs2.update(parser_kwargs)
+
     # Create document tree from creole markup
-    document = CreoleParser(markup_string, **parser_kwargs).parse()
+    document = CreoleParser(markup_string, **parser_kwargs2).parse()
     if debug:
         document.debug()
 
+    emitter_kwargs2 = {
+        "macros": macros,
+        "verbose": verbose,
+        "stderr": stderr,
+    }
+    if emitter_kwargs:
+        warnings.warn("emitter_kwargs argument in creole2html would be removed in the future!", PendingDeprecationWarning)
+        emitter_kwargs2.update(emitter_kwargs)
+
     # Build html code from document tree
     #print("creole2html HtmlEmitter kwargs:", emitter_kwargs)
-    return HtmlEmitter(document, **emitter_kwargs).emit()
+    return HtmlEmitter(document, **emitter_kwargs2).emit()
 
 
-def parse_html(html_string, debug=False, **parser_kwargs):
+def parse_html(html_string, debug=False):
     """ create the document tree from html code """
     assert isinstance(html_string, TEXT_TYPE), "given html_string must be unicode!"
 
-    h2c = HtmlParser(debug, **parser_kwargs)
+    h2c = HtmlParser(debug=debug)
     document_tree = h2c.feed(html_string)
     if debug:
         h2c.debug()
     return document_tree
 
 
-def html2creole(html_string, debug=False, parser_kwargs={}, emitter_kwargs={}):
+def html2creole(html_string, debug=False,
+        parser_kwargs={}, emitter_kwargs={},
+        unknown_emit=None
+    ):
     """
     convert html code into creole markup
 
     >>> html2creole('<p>This is <strong>creole <i>markup</i></strong>!</p>')
     'This is **creole //markup//**!'
     """
-    document_tree = parse_html(html_string, debug, **parser_kwargs)
+    if parser_kwargs:
+        warnings.warn("parser_kwargs argument in html2creole would be removed in the future!", PendingDeprecationWarning)
+
+    document_tree = parse_html(html_string, debug=debug)
+
+    emitter_kwargs2 = {
+        "unknown_emit": unknown_emit,
+    }
+    if emitter_kwargs:
+        warnings.warn("emitter_kwargs argument in html2creole would be removed in the future!", PendingDeprecationWarning)
+        emitter_kwargs2.update(emitter_kwargs)
 
     # create creole markup from the document tree
-    emitter = CreoleEmitter(document_tree, debug=debug, **emitter_kwargs)
+    emitter = CreoleEmitter(document_tree, debug=debug, **emitter_kwargs2)
     return emitter.emit()
 
 
diff --git a/creole/creole2html/emitter.py b/creole/creole2html/emitter.py
index 0542f65..38d5f4b 100644
--- a/creole/creole2html/emitter.py
+++ b/creole/creole2html/emitter.py
@@ -25,11 +25,19 @@ class HtmlEmitter:
     Generate HTML output for the document
     tree consisting of DocNodes.
     """
-    def __init__(self, root, macros=None, verbose=1, stderr=sys.stderr):
+    def __init__(self, root, macros=None, verbose=None, stderr=None):
         self.root = root
         self.macros = macros
-        self.verbose = verbose
-        self.stderr = stderr
+
+        if verbose is None:
+            self.verbose = 1
+        else:
+            self.verbose = verbose
+
+        if stderr is None:
+            self.stderr = sys.stderr
+        else:
+            self.stderr = stderr
 
     def get_text(self, node):
         """Try to emit whatever text is in the node."""
diff --git a/creole/creole2html/parser.py b/creole/creole2html/parser.py
index a8157e6..3cf263f 100644
--- a/creole/creole2html/parser.py
+++ b/creole/creole2html/parser.py
@@ -59,12 +59,14 @@ class CreoleParser:
     inline_re = re.compile('|'.join(INLINE_RULES), INLINE_FLAGS)
 
 
-    def __init__(self, raw, block_rules=BlockRules, blog_line_breaks=True):
+    def __init__(self, raw, block_rules=None, blog_line_breaks=True):
         assert isinstance(raw, TEXT_TYPE)
         self.raw = raw
 
+        if block_rules is None:
+            block_rules = BlockRules(blog_line_breaks=blog_line_breaks)
+
         # setup block element rules:
-        block_rules = block_rules(blog_line_breaks=blog_line_breaks)
         self.block_re = re.compile('|'.join(block_rules.rules), block_rules.re_flags)
 
         self.blog_line_breaks = blog_line_breaks
diff --git a/creole/shared/base_emitter.py b/creole/shared/base_emitter.py
index 0de1beb..fe1b334 100644
--- a/creole/shared/base_emitter.py
+++ b/creole/shared/base_emitter.py
@@ -25,10 +25,13 @@ class BaseEmitter(object):
     Build from a document_tree (html2creole.parser.HtmlParser instance) a
     creole markup text.
     """
-    def __init__(self, document_tree, unknown_emit=transparent_unknown_nodes, debug=False):
+    def __init__(self, document_tree, unknown_emit=None, debug=False):
         self.root = document_tree
 
-        self._unknown_emit = unknown_emit
+        if unknown_emit is None:
+            self._unknown_emit = transparent_unknown_nodes
+        else:
+            self._unknown_emit = unknown_emit
 
         self.last = None
         self.debugging = debug
diff --git a/creole/tests/test_creole2html.py b/creole/tests/test_creole2html.py
index dc93561..2e12b21 100644
--- a/creole/tests/test_creole2html.py
+++ b/creole/tests/test_creole2html.py
@@ -326,9 +326,7 @@ class TestCreole2htmlMarkup(BaseCreoleTest):
             the|text
             <p>the end</p>
         """,
-            emitter_kwargs={
-                "macros":test_macros,
-            }
+            macros=test_macros,
         )
 
     def test_macro_html1(self):
@@ -345,9 +343,7 @@ class TestCreole2htmlMarkup(BaseCreoleTest):
                 
                 <p>inline: &#x7B;...&#x7D; code</p>
             """,
-            emitter_kwargs={
-                "macros":example_macros,
-            }
+            macros=example_macros,
         )
 
     def test_macro_not_exist1(self):
@@ -376,7 +372,7 @@ class TestCreole2htmlMarkup(BaseCreoleTest):
             </p>
         """
 
-        self.assert_creole2html(source_string, should_string, emitter_kwargs={"verbose":1})
+        self.assert_creole2html(source_string, should_string, verbose=1)
 
         #----------------------------------------------------------------------
         # Test with verbose=2 ans a StringIO stderr handler
@@ -389,7 +385,7 @@ class TestCreole2htmlMarkup(BaseCreoleTest):
                 <p>wrong macro line:<br />
                 [Error: Wrong macro arguments: '>Some funky page summary.<</summary' for macro 'summary' (maybe wrong macro tag syntax?)]
                 </p>
-            """,
+            """, #verbose=True
         )
 
     def test_macro_not_exist2(self):
@@ -411,10 +407,7 @@ class TestCreole2htmlMarkup(BaseCreoleTest):
             
             <p>inline macro:<br />
             </p>
-        """,
-            emitter_kwargs={
-                "verbose":0,
-            }
+        """, verbose=False
         )
 
     def test_image(self):
diff --git a/creole/tests/test_cross_compare_creole.py b/creole/tests/test_cross_compare_creole.py
index 60486c3..9127b66 100644
--- a/creole/tests/test_cross_compare_creole.py
+++ b/creole/tests/test_cross_compare_creole.py
@@ -428,15 +428,10 @@ class CrossCompareCreoleTests(BaseCreoleTest):
 
             <p>555<x />666</p>
         """,
-            # use macro in creole2html emitter
-            html_emitter_kwargs={
-                "macros":example_macros,
-
-            },
-            # escape unknown tags with <<html>> in html2creole emitter
-            creole_emitter_kwargs={
-                "unknown_emit":use_html_macro,
-            }
+            # use macro in creole2html emitter:
+            macros=example_macros,
+            # escape unknown tags with <<html>> in html2creole emitter:
+            unknown_emit=use_html_macro,
         )
 
     def test_entities(self):
diff --git a/creole/tests/test_html2creole.py b/creole/tests/test_html2creole.py
index 14aab93..0b38ad5 100644
--- a/creole/tests/test_html2creole.py
+++ b/creole/tests/test_html2creole.py
@@ -66,7 +66,7 @@ class TestHtml2CreoleMarkup(BaseCreoleTest):
         self.assertRaises(NotImplementedError,
             html2creole,
             html_string="<unknwon>",
-            emitter_kwargs={"unknown_emit":raise_unknown_node}
+            unknown_emit=raise_unknown_node
         )
 
     def test_use_html_macro(self):
@@ -85,7 +85,7 @@ class TestHtml2CreoleMarkup(BaseCreoleTest):
 
             <p>555<unknown />666</p>
         """,
-            emitter_kwargs={"unknown_emit":use_html_macro}
+            unknown_emit=use_html_macro
         )
 
     def test_escape_unknown_nodes(self):
@@ -104,7 +104,7 @@ class TestHtml2CreoleMarkup(BaseCreoleTest):
 
             <p>555<unknown />666</p>
         """,
-            emitter_kwargs={"unknown_emit":escape_unknown_nodes}
+            unknown_emit=escape_unknown_nodes
         )
 
     def test_escape_unknown_nodes2(self):
@@ -119,7 +119,7 @@ class TestHtml2CreoleMarkup(BaseCreoleTest):
             var js_sha_link='<p>***</p>';
             </script>
         """,
-            emitter_kwargs={"unknown_emit":escape_unknown_nodes}
+            unknown_emit=escape_unknown_nodes
         )
 
     def test_transparent_unknown_nodes(self):
@@ -132,7 +132,7 @@ class TestHtml2CreoleMarkup(BaseCreoleTest):
             //baz//, **quux**
         """, """
             <form class="foo" id="bar"><label><em>baz</em></label>, <strong>quux</strong></form>
-        """, emitter_kwargs={"unknown_emit":transparent_unknown_nodes}
+        """, unknown_emit=transparent_unknown_nodes
         )
 
     def test_transparent_unknown_nodes2(self):
@@ -144,7 +144,7 @@ class TestHtml2CreoleMarkup(BaseCreoleTest):
             FOO var a='<em>STRONG</em>'; BAR
         """, """
             <p>FOO <script>var a='<em>STRONG</em>';</script> BAR</p>
-        """, emitter_kwargs={"unknown_emit":transparent_unknown_nodes}
+        """, unknown_emit=transparent_unknown_nodes
         )
 
     def test_transparent_unknown_nodes_block_elements(self):
@@ -160,7 +160,7 @@ class TestHtml2CreoleMarkup(BaseCreoleTest):
         """, """
             <div><em>baz</em>,</div> <fieldset><strong>quux</strong></fieldset>
             <span>spam, </span><label>ham, </label>and eggs
-        """, emitter_kwargs={"unknown_emit":transparent_unknown_nodes}
+        """, unknown_emit=transparent_unknown_nodes
         )
 
     #--------------------------------------------------------------------------        
diff --git a/creole/tests/utils/base_unittest.py b/creole/tests/utils/base_unittest.py
index bfaf30f..f1eaede 100644
--- a/creole/tests/utils/base_unittest.py
+++ b/creole/tests/utils/base_unittest.py
@@ -105,12 +105,17 @@ class BaseCreoleTest(MarkupTest):
             f(member, container, *args, **kwargs)
 
     def assert_creole2html(self, raw_creole, raw_html, \
-            strip_lines=False, debug=False, parser_kwargs={}, emitter_kwargs={}):
+            strip_lines=False, debug=False,
+            parser_kwargs={}, emitter_kwargs={},
+            block_rules=None, blog_line_breaks=True, macros=None, verbose=None, stderr=None,
+        ):
         """
         compare the generated html code from the markup string >creole_string<
         with the >html_string< reference.
         """
         self.assertNotEqual(raw_creole, raw_html)
+        self.assertEqual(parser_kwargs, {}, "parser_kwargs is deprecated!")
+        self.assertEqual(emitter_kwargs, {}, "parser_kwargs is deprecated!")
 
         # prepare whitespace on test strings
         markup_string = self._prepare_text(raw_creole)
@@ -125,7 +130,9 @@ class BaseCreoleTest(MarkupTest):
 
         # convert creole markup into html code
         out_string = creole2html(
-            markup_string, debug, parser_kwargs, emitter_kwargs
+            markup_string, debug,
+            block_rules=block_rules, blog_line_breaks=blog_line_breaks,
+            macros=macros, verbose=verbose, stderr=stderr,
         )
         if debug:
             self._debug_text("assert_creole2html() creole2html", out_string)
@@ -139,11 +146,18 @@ class BaseCreoleTest(MarkupTest):
         self.assertEqual(out_string, html_string, msg="creole2html")
 
     def assert_html2creole(self, raw_creole, raw_html, \
-                strip_lines=False, debug=False, parser_kwargs={}, emitter_kwargs={}):
+                strip_lines=False, debug=False,
+                # OLD API:
+                parser_kwargs={}, emitter_kwargs={},
+                # html2creole:
+                unknown_emit=None
+        ):
         """
         Compare the genereted markup from the given >raw_html< html code, with
         the given >creole_string< reference string.
         """
+        self.assertEqual(parser_kwargs, {}, "parser_kwargs is deprecated!")
+        self.assertEqual(emitter_kwargs, {}, "parser_kwargs is deprecated!")
 #        assert isinstance(raw_html, TEXT_TYPE)
 #        creole_string = unicode(creole_string, encoding="utf8")
 #        raw_html = unicode(raw_html, "utf8")
@@ -160,7 +174,7 @@ class BaseCreoleTest(MarkupTest):
         assert isinstance(html, TEXT_TYPE)
 
         # convert html code into creole markup
-        out_string = html2creole(html, debug, parser_kwargs, emitter_kwargs)
+        out_string = html2creole(html, debug, unknown_emit=unknown_emit)
         if debug:
             self._debug_text("assert_html2creole() html2creole", out_string)
 
@@ -169,28 +183,39 @@ class BaseCreoleTest(MarkupTest):
 
     def cross_compare_creole(self, creole_string, html_string,
                         strip_lines=False, debug=False,
-                        # creole2html:
+                        # creole2html old API:
                         creole_parser_kwargs={}, html_emitter_kwargs={},
-                        # html2creole:
+                        # html2creole old API:
                         html_parser_kwargs={}, creole_emitter_kwargs={},
-                                                                            ):
+
+                        # creole2html new API:
+                        block_rules=None, blog_line_breaks=True, macros=None, stderr=None,
+                        # html2creole:
+                        unknown_emit=None
+        ):
         """
         Cross compare with:
             * creole2html
             * html2creole
         """
+        self.assertEqual(creole_parser_kwargs, {}, "creole_parser_kwargs is deprecated!")
+        self.assertEqual(html_emitter_kwargs, {}, "html_emitter_kwargs is deprecated!")
+        self.assertEqual(html_parser_kwargs, {}, "html_parser_kwargs is deprecated!")
+        self.assertEqual(creole_emitter_kwargs, {}, "creole_emitter_kwargs is deprecated!")
+
         assert isinstance(creole_string, TEXT_TYPE)
         assert isinstance(html_string, TEXT_TYPE)
         self.assertNotEqual(creole_string, html_string)
 
         self.assert_creole2html(
             creole_string, html_string, strip_lines, debug,
-            creole_parser_kwargs, html_emitter_kwargs
+            block_rules=block_rules, blog_line_breaks=blog_line_breaks,
+            macros=macros, stderr=stderr,
         )
 
         self.assert_html2creole(
             creole_string, html_string, strip_lines, debug,
-            html_parser_kwargs, creole_emitter_kwargs
+            unknown_emit=unknown_emit,
         )
 
     def assert_html2textile(self, textile_string, html_string, \
diff --git a/creole/tests/utils/utils.py b/creole/tests/utils/utils.py
index 34e659a..ef202e0 100644
--- a/creole/tests/utils/utils.py
+++ b/creole/tests/utils/utils.py
@@ -56,7 +56,10 @@ class MarkupTest(unittest.TestCase):
 
             #~ first = first.rstrip("\\n")
             #~ second = second.rstrip("\\n")
-            diff = make_diff(first, second)
+            try:
+                diff = make_diff(first, second)
+            except AttributeError:
+                raise self.failureException("%s is not %s" % (repr(first), repr(second)))
 
             if VERBOSE >= 2:
                 print("diff: %r" % diff)