Merge lp:~cjwatson/lazr.restful/py3-pretty-print-helpers into lp:lazr.restful

[Colin Watson]

Make pprint_entry/pprint_collection format strings in Python 3 style.

Change lazr.restful.testing.webservice.pprint_entry and lazr.restful.testing.webservice.pprint_collection to print text string representations in the Python 3 style ('text' rather than u'text') on both Python 2 and 3. This makes it easier to write bilingual doctests, although existing callers need to change.

Use these helpers in a few more doctests.

[Ioana Lasc (ilasc)]

review: Approve

=== modified file 'NEWS.rst'
--- NEWS.rst	2020-09-02 08:23:06 +0000
+++ NEWS.rst	2020-09-02 22:01:19 +0000
@@ -2,6 +2,15 @@
 NEWS for lazr.restful
 =====================
 
+0.23.0
+======
+
+Change ``lazr.restful.testing.webservice.pprint_entry`` and
+``lazr.restful.testing.webservice.pprint_collection`` to print text string
+representations in the Python 3 style (``'text'`` rather than ``u'text'``)
+on both Python 2 and 3.  This makes it easier to write bilingual doctests,
+although existing callers need to change.
+
 0.22.2 (2020-09-02)
 ===================
 
 
=== modified file 'src/lazr/restful/docs/webservice.rst'
--- src/lazr/restful/docs/webservice.rst	2020-08-21 16:16:09 +0000
+++ src/lazr/restful/docs/webservice.rst	2020-09-02 22:01:19 +0000
@@ -1409,21 +1409,22 @@
 but since that is not a required field our application used the default
 value (Brazilian) specified in ``CookbookFactoryOperation`` for it.
 
-    >>> sorted(feijoada.items())
-    [(u'author_link',
-      u'http://api.cookbooks.dev/beta/authors/Fernando%20Yokota'),
-     (u'comments_collection_link',
-      u'http://api.cookbooks.dev/beta/cookbooks/Feijoada/comments'),
-     (u'cover_link',
-      u'http://api.cookbooks.dev/beta/cookbooks/Feijoada/cover'),
-     (u'cuisine', u'Brazilian'),
-     (u'http_etag', u'...'),
-     (u'name', u'Feijoada'),
-     (u'recipes_collection_link',
-      u'http://api.cookbooks.dev/beta/cookbooks/Feijoada/recipes'),
-     (u'resource_type_link',
-      u'http://api.cookbooks.dev/beta/#cookbook'),
-     (u'self_link', u'http://api.cookbooks.dev/beta/cookbooks/Feijoada')]
+    >>> from lazr.restful.testing.webservice import (
+    ...     pprint_collection,
+    ...     pprint_entry,
+    ...     )
+
+    >>> pprint_entry(feijoada)
+    author_link: 'http://api.cookbooks.dev/beta/authors/Fernando%20Yokota'
+    comments_collection_link:
+        'http://api.cookbooks.dev/beta/cookbooks/Feijoada/comments'
+    cover_link: 'http://api.cookbooks.dev/beta/cookbooks/Feijoada/cover'
+    cuisine: 'Brazilian'
+    name: 'Feijoada'
+    recipes_collection_link:
+        'http://api.cookbooks.dev/beta/cookbooks/Feijoada/recipes'
+    resource_type_link: 'http://api.cookbooks.dev/beta/#cookbook'
+    self_link: 'http://api.cookbooks.dev/beta/cookbooks/Feijoada'
 
 You can also traverse from an entry to an item in a scoped collection:
 
@@ -1431,16 +1432,14 @@
     ...     quote('/beta/cookbooks/The Joy of Cooking/recipes/Roast chicken'))
     >>> chicken_recipe_resource = request.traverse(app)
     >>> chicken_recipe = load_json(chicken_recipe_resource())
-    >>> sorted(chicken_recipe.items())
-    [(u'comments_collection_link',
-     u'http://api...Joy%20of%20Cooking/recipes/Roast%20chicken/comments'),
-    (u'cookbook_link',
-     u'http://api.cookbooks.dev/beta/cookbooks/The%20Joy%20of%20Cooking'),
-    (u'dish_link', u'http://api.cookbooks.dev/beta/dishes/Roast%20chicken'),
-    (u'http_etag', u'...'),
-    (u'instructions', u'Draw, singe, stuff, and truss...'),
-    (u'self_link',
-     u'http://api.../The%20Joy%20of%20Cooking/recipes/Roast%20chicken')]
+    >>> pprint_entry(chicken_recipe)
+    comments_collection_link:
+        'http://api...Joy%20of%20Cooking/recipes/Roast%20chicken/comments'
+    cookbook_link:
+        'http://api.cookbooks.dev/beta/cookbooks/The%20Joy%20of%20Cooking'
+    dish_link: 'http://api.cookbooks.dev/beta/dishes/Roast%20chicken'
+    instructions: 'Draw, singe, stuff, and truss...'
+    self_link: 'http://api.../The%20Joy%20of%20Cooking/recipes/Roast%20chicken'
 
 Another example traversing to a comment:
 
@@ -1457,12 +1456,11 @@
     ...     roast_chicken_comments_url + '/1')
     >>> comment_one_resource = request.traverse(app)
     >>> comment_one = load_json(comment_one_resource())
-    >>> sorted(comment_one.items())
-    [(u'http_etag', u'...'),
-     (u'resource_type_link', u'http://api.cookbooks.dev/beta/#comment'),
-     (u'self_link',
-      u'http://api...Joy%20of%20Cooking/recipes/Roast%20chicken/comments/1'),
-     (u'text', u'Clear and concise.')]
+    >>> pprint_entry(comment_one)
+    resource_type_link: 'http://api.cookbooks.dev/beta/#comment'
+    self_link:
+        'http://api...Joy%20of%20Cooking/recipes/Roast%20chicken/comments/1'
+    text: 'Clear and concise.'
 
 An entry may expose a number of custom operations through GET. The
 recipe entry exposes a custom GET operation called
@@ -1579,11 +1577,14 @@
     >>> recipes = DummyResultSet()
     >>> request, operation = make_dummy_operation_request(recipes)
     >>> response = operation()
-    >>> for key, value in sorted(simplejson.loads(response).items()):
-    ...     print('%s: %s' % (key, value))
-    entries: [{...}, {...}]
+    >>> pprint_collection(simplejson.loads(response))
     start: ...
     total_size: 2
+    ---
+    ...
+    ---
+    ...
+    ---
 
 When a named operation returns an object that has an ``ICollection``
 implementation, the result is similar: we return a JSON hash describing one
@@ -1591,11 +1592,17 @@
 
     >>> request, operation = make_dummy_operation_request(DishSet())
     >>> response = operation()
-    >>> for key, value in sorted(simplejson.loads(response).items()):
-    ...     print('%s: %s' % (key, value))
-    entries: ...
+    >>> pprint_collection(simplejson.loads(response))
+    resource_type_link: 'http://api.cookbooks.dev/beta/#dishes'
     start: ...
-    total_size: ...
+    total_size: 3
+    ---
+    ...
+    ---
+    ...
+    ---
+    ...
+    ---
 
 If the return value can't be converted into JSON, you'll get an
 exception.
 
=== modified file 'src/lazr/restful/example/base/tests/collection.txt'
--- src/lazr/restful/example/base/tests/collection.txt	2020-02-04 13:17:32 +0000
+++ src/lazr/restful/example/base/tests/collection.txt	2020-09-02 22:01:19 +0000
@@ -125,19 +125,19 @@
     >>> url = quote("/cookbooks/The Joy of Cooking")
     >>> cookbook = webservice.get(url).jsonBody()
     >>> pprint_entry(cookbook)
-    confirmed: u'tag:launchpad.net:2008:redacted'
-    copyright_date: u'1995-01-01'
-    cover_link: u'http://.../cookbooks/The%20Joy%20of%20Cooking/cover'
-    cuisine: u'General'
-    description: u''
+    confirmed: 'tag:launchpad.net:2008:redacted'
+    copyright_date: '1995-01-01'
+    cover_link: 'http://.../cookbooks/The%20Joy%20of%20Cooking/cover'
+    cuisine: 'General'
+    description: ''
     last_printing: None
-    name: u'The Joy of Cooking'
+    name: 'The Joy of Cooking'
     price: 20
-    recipes_collection_link: u'http://.../cookbooks/The%20Joy%20of%20Cooking/recipes'
-    resource_type_link: u'http://...#cookbook'
+    recipes_collection_link: 'http://.../cookbooks/The%20Joy%20of%20Cooking/recipes'
+    resource_type_link: 'http://...#cookbook'
     revision_number: 0
-    self_link: u'http://.../cookbooks/The%20Joy%20of%20Cooking'
-    web_link: u'http://dummyurl/'
+    self_link: 'http://.../cookbooks/The%20Joy%20of%20Cooking'
+    web_link: 'http://dummyurl/'
 
 A collection may be scoped to an element:
 
 
=== modified file 'src/lazr/restful/example/multiversion/tests/operation.txt'
--- src/lazr/restful/example/multiversion/tests/operation.txt	2020-02-04 11:52:59 +0000
+++ src/lazr/restful/example/multiversion/tests/operation.txt	2020-09-02 22:01:19 +0000
@@ -12,7 +12,10 @@
 collections always send a 'total_size' containing the total size of a
 collection.
 
-    >>> from lazr.restful.testing.webservice import WebServiceCaller
+    >>> from lazr.restful.testing.webservice import (
+    ...     pprint_collection,
+    ...     WebServiceCaller,
+    ...     )
     >>> webservice = WebServiceCaller(domain='multiversion.dev')
 
 In the example web service, named operations always send 'total_size'
@@ -52,12 +55,10 @@
     >>> print(sorted(get_collection('3.0', 'by_value', size=100).keys()))
     [u'entries', u'start', u'total_size']
 
-    >>> for key, value in sorted(
-    ...         get_collection('3.0', 'by_value', 'no-such-value').items()):
-    ...     print('%s: %s' % (key, value))
-    entries: []
+    >>> pprint_collection(get_collection('3.0', 'by_value', 'no-such-value'))
     start: 0
     total_size: 0
+    ---
 
 Mutators as named operations
 ----------------------------
 
=== modified file 'src/lazr/restful/testing/webservice.py'
--- src/lazr/restful/testing/webservice.py	2020-08-17 11:46:51 +0000
+++ src/lazr/restful/testing/webservice.py	2020-09-02 22:01:19 +0000
@@ -13,6 +13,7 @@
     'FakeResponse',
     'IGenericEntry',
     'IGenericCollection',
+    'pprint_collection',
     'pprint_entry',
     'simple_renderer',
     'WebServiceTestCase',
@@ -174,6 +175,23 @@
         return default
 
 
+def pformat_value(value):
+    """Pretty-format a single value.
+
+    This is similar to `repr()`, but for doctest compatibility we format
+    text and bytes in a way that looks the same on both Python 2 and 3.
+    JSON strings are always Unicode, never bytes, so this doesn't introduce
+    ambiguity.
+    """
+    if isinstance(value, six.text_type):
+        if "'" in value and '"' not in value:
+            return '"%s"' % value
+        else:
+            return "'%s'" % value.replace("'", "\\'")
+    else:
+        return repr(value)
+
+
 def pprint_entry(json_body):
     """Pretty-print a webservice entry JSON representation.
 
@@ -182,7 +200,7 @@
     """
     for key, value in sorted(json_body.items()):
         if key != 'http_etag':
-            print('%s: %r' % (key, value))
+            print('%s: %s' % (key, pformat_value(value)))
 
 
 def pprint_collection(json_body):
@@ -191,7 +209,7 @@
         if key == 'total_size_link':
             continue
         if key != 'entries':
-            print('%s: %r' % (key, value))
+            print('%s: %s' % (key, pformat_value(value)))
     print('---')
     for entry in json_body['entries']:
         pprint_entry(entry)