From 70f063f3c100e113b81777b99cabffb141d8bd00 Mon Sep 17 00:00:00 2001 From: Kit Randel Date: Fri, 23 Oct 2015 15:39:36 +1300 Subject: [PATCH 1/7] Ensure string validators are resolved to object before adding to docstring. --- cornice/ext/sphinxext.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/cornice/ext/sphinxext.py b/cornice/ext/sphinxext.py index 46802e6b..cda76ad7 100644 --- a/cornice/ext/sphinxext.py +++ b/cornice/ext/sphinxext.py @@ -167,6 +167,9 @@ def _render_service(self, service): method_node += attrs_node for validator in args.get('validators', ()): + ob = args['klass'] + if is_string(validator) and ob is not None: + validator = getattr(ob, validator) if validator.__doc__ is not None: docstring += trim(validator.__doc__) From 3ed484ff52559e2613ee17042d0cb278b37c27db Mon Sep 17 00:00:00 2001 From: Kit Randel Date: Fri, 23 Oct 2015 16:24:53 +1300 Subject: [PATCH 2/7] Add failing test test_string_validator_resolved. --- cornice/ext/sphinxext.py | 2 +- cornice/tests/ext/dummy/views.py | 7 ++++++- cornice/tests/ext/test_sphinxext.py | 15 +++++++++++++-- 3 files changed, 20 insertions(+), 4 deletions(-) diff --git a/cornice/ext/sphinxext.py b/cornice/ext/sphinxext.py index cda76ad7..65689af5 100644 --- a/cornice/ext/sphinxext.py +++ b/cornice/ext/sphinxext.py @@ -167,7 +167,7 @@ def _render_service(self, service): method_node += attrs_node for validator in args.get('validators', ()): - ob = args['klass'] + ob = args.get('klass') if is_string(validator) and ob is not None: validator = getattr(ob, validator) if validator.__doc__ is not None: diff --git a/cornice/tests/ext/dummy/views.py b/cornice/tests/ext/dummy/views.py index 9a4b4303..7d535242 100644 --- a/cornice/tests/ext/dummy/views.py +++ b/cornice/tests/ext/dummy/views.py @@ -22,9 +22,14 @@ def get_info(request): return _USERS[username] +def validate(request): + return request + + def includeme(config): # FIXME this should also work in includeme - user_info = Service(name='users', path='/{username}/info') + user_info = Service(name='users', path='/{username}/info', + validators=('validate')) user_info.add_view('get', get_info) config.add_cornice_service(user_info) diff --git a/cornice/tests/ext/test_sphinxext.py b/cornice/tests/ext/test_sphinxext.py index 26682a13..ee3c5a2a 100644 --- a/cornice/tests/ext/test_sphinxext.py +++ b/cornice/tests/ext/test_sphinxext.py @@ -34,5 +34,16 @@ def test_dummy(self): directive.options['services'] = ['users', "thing_service"] ret = directive.run() self.assertEqual(len(ret), 2) - self.assertTrue('Users service at' in str(ret[0])) - self.assertTrue('Thing_Service service at ' in str(ret[1])) + self.assertIn('Users service at', str(ret[0])) + self.assertIn('Thing_Service service at ', str(ret[1])) + + def test_string_validator_resolved(self): + # A validator defined as a string should be parsed as an obj. + param = mock.Mock() + param.document.settings.env.new_serialno.return_value = 1 + directive = ServiceDirective( + 'test', [], {}, [], 1, 1, 'test', param, 1) + directive.options['app'] = 'cornice.tests.ext.dummy' + directive.options['services'] = ['users', "thing_service"] + ret = directive.run() + self.assertNotIn("str(object='') -> string", str(ret[0])) From c738444a59430e8ca1b54fb8ef020ec47753bd6e Mon Sep 17 00:00:00 2001 From: Kit Randel Date: Fri, 23 Oct 2015 16:29:04 +1300 Subject: [PATCH 3/7] Refactor directive to setUp. --- cornice/tests/ext/test_sphinxext.py | 26 ++++++++++++-------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/cornice/tests/ext/test_sphinxext.py b/cornice/tests/ext/test_sphinxext.py index ee3c5a2a..55a107d2 100644 --- a/cornice/tests/ext/test_sphinxext.py +++ b/cornice/tests/ext/test_sphinxext.py @@ -18,6 +18,16 @@ def test_rendering(self): class TestServiceDirective(TestCase): + def setUp(self): + super(TestServiceDirective, self).setUp() + param = mock.Mock() + param.document.settings.env.new_serialno.return_value = 1 + + self.directive = ServiceDirective( + 'test', [], {}, [], 1, 1, 'test', param, 1) + self.directive.options['app'] = 'cornice.tests.ext.dummy' + self.directive.options['services'] = ['users', "thing_service"] + def test_module_reload(self): directive = ServiceDirective( 'test', [], {}, [], 1, 1, 'test', mock.Mock(), 1) @@ -26,24 +36,12 @@ def test_module_reload(self): self.assertEqual(ret, []) def test_dummy(self): - param = mock.Mock() - param.document.settings.env.new_serialno.return_value = 1 - directive = ServiceDirective( - 'test', [], {}, [], 1, 1, 'test', param, 1) - directive.options['app'] = 'cornice.tests.ext.dummy' - directive.options['services'] = ['users', "thing_service"] - ret = directive.run() + ret = self.directive.run() self.assertEqual(len(ret), 2) self.assertIn('Users service at', str(ret[0])) self.assertIn('Thing_Service service at ', str(ret[1])) def test_string_validator_resolved(self): # A validator defined as a string should be parsed as an obj. - param = mock.Mock() - param.document.settings.env.new_serialno.return_value = 1 - directive = ServiceDirective( - 'test', [], {}, [], 1, 1, 'test', param, 1) - directive.options['app'] = 'cornice.tests.ext.dummy' - directive.options['services'] = ['users', "thing_service"] - ret = directive.run() + ret = self.directive.run() self.assertNotIn("str(object='') -> string", str(ret[0])) From 125233c72e65c5e2931388073cf74ffa7a80177c Mon Sep 17 00:00:00 2001 From: Kit Randel Date: Fri, 23 Oct 2015 16:32:43 +1300 Subject: [PATCH 4/7] Further minor refactoring. --- cornice/tests/ext/test_sphinxext.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/cornice/tests/ext/test_sphinxext.py b/cornice/tests/ext/test_sphinxext.py index 55a107d2..519b2f7f 100644 --- a/cornice/tests/ext/test_sphinxext.py +++ b/cornice/tests/ext/test_sphinxext.py @@ -29,10 +29,10 @@ def setUp(self): self.directive.options['services'] = ['users', "thing_service"] def test_module_reload(self): - directive = ServiceDirective( - 'test', [], {}, [], 1, 1, 'test', mock.Mock(), 1) - directive.options['modules'] = ['cornice'] - ret = directive.run() + self.directive.options['app'] = None + self.directive.options['services'] = None + self.directive.options['modules'] = ['cornice'] + ret = self.directive.run() self.assertEqual(ret, []) def test_dummy(self): From 5f3fe6ae11461fbc5f9df88869b858ca56218527 Mon Sep 17 00:00:00 2001 From: Kit Randel Date: Tue, 27 Oct 2015 10:04:08 +1300 Subject: [PATCH 5/7] Factor out object resolution from string. --- cornice/ext/sphinxext.py | 30 ++++++++++++++++------------- cornice/tests/ext/dummy/views.py | 5 +++-- cornice/tests/ext/test_sphinxext.py | 4 +++- 3 files changed, 23 insertions(+), 16 deletions(-) diff --git a/cornice/ext/sphinxext.py b/cornice/ext/sphinxext.py index 65689af5..cfced705 100644 --- a/cornice/ext/sphinxext.py +++ b/cornice/ext/sphinxext.py @@ -97,6 +97,16 @@ def run(self): return [self._render_service(s) for s in services] + def _resolve_obj_to_docstring(self, obj, args): + # Resolve a view or validator to an object if type string + # and return docstring. + if is_string(obj) and 'klass' in args: + ob = args['klass'] + obj_ = getattr(ob, obj.lower()) + return format_docstring(obj_) + else: + return format_docstring(obj) + def _render_service(self, service): service_id = "service-%d" % self.env.new_serialno('service') service_node = nodes.section(ids=[service_id]) @@ -108,6 +118,7 @@ def _render_service(self, service): service_node += rst2node(trim(service.description)) for method, view, args in service.definitions: + if method == 'HEAD': # Skip head - this is essentially duplicating the get docs. continue @@ -115,13 +126,7 @@ def _render_service(self, service): method_node = nodes.section(ids=[method_id]) method_node += nodes.title(text=method) - if is_string(view): - if 'klass' in args: - ob = args['klass'] - view_ = getattr(ob, view.lower()) - docstring = trim(view_.__doc__ or "") + '\n' - else: - docstring = trim(view.__doc__ or "") + '\n' + docstring = self._resolve_obj_to_docstring(view, args) if 'schema' in args: schema = args['schema'] @@ -167,11 +172,7 @@ def _render_service(self, service): method_node += attrs_node for validator in args.get('validators', ()): - ob = args.get('klass') - if is_string(validator) and ob is not None: - validator = getattr(ob, validator) - if validator.__doc__ is not None: - docstring += trim(validator.__doc__) + docstring += self._resolve_obj_to_docstring(validator, args) if 'accept' in args: accept = to_list(args['accept']) @@ -206,12 +207,15 @@ def _render_service(self, service): method_node += response service_node += method_node - return service_node # Utils +def format_docstring(obj): + """Return trimmed docstring with newline from object.""" + return trim(obj.__doc__ or "") + '\n' + def trim(docstring): """ diff --git a/cornice/tests/ext/dummy/views.py b/cornice/tests/ext/dummy/views.py index 7d535242..064cc24e 100644 --- a/cornice/tests/ext/dummy/views.py +++ b/cornice/tests/ext/dummy/views.py @@ -12,17 +12,18 @@ def __init__(self, request, context=None): self.context = context def collection_get(self): - """returns yay""" + """Returns yay.""" return 'yay' def get_info(request): - "returns the user data" + """Returns the user data.""" username = request.matchdict['username'] return _USERS[username] def validate(request): + """Dummy validation.""" return request diff --git a/cornice/tests/ext/test_sphinxext.py b/cornice/tests/ext/test_sphinxext.py index 519b2f7f..5cee96cd 100644 --- a/cornice/tests/ext/test_sphinxext.py +++ b/cornice/tests/ext/test_sphinxext.py @@ -42,6 +42,8 @@ def test_dummy(self): self.assertIn('Thing_Service service at ', str(ret[1])) def test_string_validator_resolved(self): - # A validator defined as a string should be parsed as an obj. + # A validator defined as a string should be parsed as an obj, + # ensuring the docstring contains validator.__doc__ rather + # than str.__doc__. ret = self.directive.run() self.assertNotIn("str(object='') -> string", str(ret[0])) From 006b904b0961b71841127ddb858b9ffaaea4701c Mon Sep 17 00:00:00 2001 From: Kit Randel Date: Tue, 27 Oct 2015 10:14:52 +1300 Subject: [PATCH 6/7] Render empty string if object can't be resolved via klass. --- cornice/ext/sphinxext.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/cornice/ext/sphinxext.py b/cornice/ext/sphinxext.py index cfced705..7acd141c 100644 --- a/cornice/ext/sphinxext.py +++ b/cornice/ext/sphinxext.py @@ -100,10 +100,13 @@ def run(self): def _resolve_obj_to_docstring(self, obj, args): # Resolve a view or validator to an object if type string # and return docstring. - if is_string(obj) and 'klass' in args: - ob = args['klass'] - obj_ = getattr(ob, obj.lower()) - return format_docstring(obj_) + if is_string(obj): + if 'klass' in args: + ob = args['klass'] + obj_ = getattr(ob, obj.lower()) + return format_docstring(obj_) + else: + return '' else: return format_docstring(obj) From 4e14ab29230483c44470fb2be43600679709c7ff Mon Sep 17 00:00:00 2001 From: Kit Randel Date: Thu, 5 Nov 2015 08:57:11 +1300 Subject: [PATCH 7/7] Whitespace. --- cornice/ext/sphinxext.py | 1 - 1 file changed, 1 deletion(-) diff --git a/cornice/ext/sphinxext.py b/cornice/ext/sphinxext.py index 7acd141c..27e2497b 100644 --- a/cornice/ext/sphinxext.py +++ b/cornice/ext/sphinxext.py @@ -121,7 +121,6 @@ def _render_service(self, service): service_node += rst2node(trim(service.description)) for method, view, args in service.definitions: - if method == 'HEAD': # Skip head - this is essentially duplicating the get docs. continue