[asterisk-commits] dlee: branch dlee/stasis-http r379067 - /team/dlee/stasis-http/cog/
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Mon Jan 14 14:47:53 CST 2013
Author: dlee
Date: Mon Jan 14 14:47:50 2013
New Revision: 379067
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=379067
Log:
Clearer naming in Swagger generator
Modified:
team/dlee/stasis-http/cog/stasis_cog.py
team/dlee/stasis-http/cog/stasis_http_resource.c.cog
team/dlee/stasis-http/cog/stasis_http_resource.h.cog
team/dlee/stasis-http/cog/stasis_http_resources.c.cog
Modified: team/dlee/stasis-http/cog/stasis_cog.py
URL: http://svnview.digium.com/svn/asterisk/team/dlee/stasis-http/cog/stasis_cog.py?view=diff&rev=379067&r1=379066&r2=379067
==============================================================================
--- team/dlee/stasis-http/cog/stasis_cog.py (original)
+++ team/dlee/stasis-http/cog/stasis_cog.py Mon Jan 14 14:47:50 2013
@@ -31,21 +31,24 @@
import re
from collections import OrderedDict
-class ResourcesSourceWriter(object):
- """Writes the resources.c file from Swagger API docs."""
+class ResourceListingSourceWriter(object):
+ """Writes the resources.c file from Swagger API docs.
+ """
def __init__(self, root):
self.root = root
def write(self):
- """Write source code for this resource, and all decendants."""
+ """Write source code for this resource, and all decendants.
+ """
self.write_includes()
# Callbacks are referenced by handlers, so write them first
self.write_callbacks(self.root)
self.write_handlers(self.root)
def write_includes(self):
- """Write the #includes for resources.c"""
+ """Write the #includes for resources.c
+ """
for include in self.root.includes:
cog.outl('#include "%s"' % include)
cog.outl("#include <inttypes.h>")
@@ -53,7 +56,8 @@
cog.outl()
def write_callbacks(self, resource):
- """Write the callback functions for the resource"""
+ """Write the callback functions for the resource
+ """
# Children first, for consistency with handler order
for child in resource.children.itervalues():
self.write_callbacks(child)
@@ -62,7 +66,8 @@
self.write_callback(operation)
def write_callback(self, operation):
- """Writes the Operations's callback function definition"""
+ """Writes the Operations's callback function definition
+ """
cog.outl('static void %s(struct ast_variable *get_params, struct ast_variable *path_vars, struct ast_variable *headers, struct stasis_http_response *response) {' % operation.get_callback_name())
if operation.path_parameters or operation.query_parameters:
cog.outl('\tstruct ast_variable *i;');
@@ -87,7 +92,8 @@
cog.outl()
def write_handlers(self, resource):
- """Write the stasis_rest_handlers for the resource"""
+ """Write the stasis_rest_handlers for the resource
+ """
# Children are referred to by handler, so write them first
for child in resource.children.itervalues():
self.write_handlers(child)
@@ -108,14 +114,16 @@
cog.outl('};')
cog.outl()
-class ResourceHeaderWriter(object):
- """Writes a resource.h file from Swagger API docs."""
+class ApiDeclarationHeaderWriter(object):
+ """Writes the .h for for a Swagger API Declaration file.
+ """
def __init__(self, root):
self.root = root
def write(self):
- """Writes the corresponding header file for this resource's operations."""
+ """Writes the corresponding header file for this resource's operations.
+ """
(name, ext) = os.path.splitext(os.path.basename(cog.outFile))
incl_guard = '_ASTERISK_%s_H' % name.upper()
cog.outl('#ifndef %s' % incl_guard)
@@ -126,7 +134,8 @@
cog.outl('#endif /* %s */' % incl_guard)
def write_structs(self, resource):
- """Write the args structs for the resource's operations."""
+ """Write the args structs for the resource's operations.
+ """
# Children first, so we're in the same order as resources.c
for child in resource.children.itervalues():
self.write_structs(child)
@@ -141,7 +150,8 @@
cog.outl('};')
def write_impl_prototypes(self, resource):
- """Write the prototypes for all the implementation functions in the given resource's operations."""
+ """Write the prototypes for all the implementation functions in the given resource's operations.
+ """
# Children first, so we're in the same order as resources.c
for child in resource.children.itervalues():
self.write_impl_prototypes(child)
@@ -149,21 +159,27 @@
for operation in resource.operations.itervalues():
cog.outl('void %s(struct ast_variable *headers, %s *args, struct stasis_http_response *response);' % (operation.get_impl_name(), operation.get_args_name()))
-class ResourceSourceWriter(object):
- """Writes a resource.c file from Swagger API docs."""
+class ApiDeclarationSourceWriter(object):
+ """Writes the .c for for a Swagger API Declaration file.
+
+ Note that these are stubs to be filled in by the developer, so they are
+ generally only generated if the target file does not exist.
+ """
def __init__(self, root):
self.root = root
def write(self):
- """Writes the corresponding source stubs file for this resource's operations."""
+ """Writes the corresponding source stubs file for this resource's operations.
+ """
(name, ext) = os.path.splitext(os.path.basename(cog.outFile))
cog.outl('#include "asterisk/%s.h"' % name)
cog.outl()
self.write_impl_stubs(self.root)
def write_impl_stubs(self, resource):
- """Write the stubs for all the implementation functions in the given resource's operations."""
+ """Write the stubs for all the implementation functions in the given resource's operations.
+ """
# Children first, so we're in the same order as the header file
for child in resource.children.itervalues():
self.write_impl_stubs(child)
@@ -174,7 +190,16 @@
cog.outl('}')
class Resource(object):
- """Swagger resource"""
+ """Resource from a Swagger API declaration.
+
+ Each path element in the 'path' declarations of 'apis' gets a Resource
+ object associated with it, which specifies the HTTP methods that Resource
+ supports.
+
+ See https://github.com/wordnik/swagger-core/wiki/API-Declaration details on
+ the structions of the API declaration.
+ """
+
def __init__(self, parent_name, path_element):
self.parent_name = parent_name
if path_element.startswith('{') and path_element.endswith('}'):
@@ -194,7 +219,7 @@
if not is_identifier(self.get_name()):
raise ValueError("Invalid path name: %s" % path_element)
- def load_resources(self, resources_file):
+ def load_resource_listing(self, resources_file):
"""Loads resources from a Swagger resources.json file.
"""
assert not self.children, "Should not reload existing resource"
@@ -210,15 +235,15 @@
for api in resources['apis']:
# Path in json is URI relative, so we need to drop the initial /api/
path = api['path'].replace('/api/', '', 1)
- resource_file = os.path.abspath(os.path.join(resources_dir, path)).format(format = 'json')
- (basename, ext) = os.path.splitext(os.path.basename(resource_file))
+ api_declaration_file = os.path.abspath(os.path.join(resources_dir, path)).format(format = 'json')
+ (basename, ext) = os.path.splitext(os.path.basename(api_declaration_file))
self.includes.append('asterisk/stasis_http_%s.h' % basename)
- self.load_resource(resource_file)
-
- def load_resource(self, resource_file):
+ self.load_api_declaration(api_declaration_file)
+
+ def load_api_declaration(self, api_declaration_file):
"""Loads a resource from a single Swagger resource.json file.
"""
- with open(resource_file) as fp:
+ with open(api_declaration_file) as fp:
resource = json.load(fp)
self.author = self.author or resource.get('author')
@@ -240,7 +265,8 @@
defaultValue = param.get('defaultValue'))
def get_name(self):
- """Returns the fully qualified name of this Resource."""
+ """Returns the fully qualified name of this Resource.
+ """
if self.parent_name:
return '%s_%s' % (self.parent_name, self.path_element)
else:
@@ -262,13 +288,15 @@
return r.get_child(path_list[1:])
def add_operation(self, http_method, nickname):
- """Add an operation to this resource"""
+ """Add an operation to this resource.
+ """
op = Operation(http_method, nickname)
self.operations[http_method] = op
return op
class Operation(object):
- """Swagger operation"""
+ """Swagger operation
+ """
def __init__(self, http_method, nickname):
self.http_method = http_method
self.nickname = snakify(nickname)
@@ -291,19 +319,23 @@
return OrderedDict(self.path_parameters.items() + self.query_parameters.items())
def get_callback_name(self):
- """Returns the name of this Operation's callback function"""
+ """Returns the name of this Operation's callback function.
+ """
return "%s_cb" % self.get_impl_name()
def get_impl_name(self):
- """Returns the name of this Operation's callback function"""
+ """Returns the name of this Operation's callback function.
+ """
return "stasis_http_%s" % self.nickname
def get_args_name(self):
- """Returns the name of impl's args struct"""
+ """Returns the name of impl's args struct.
+ """
return "struct ast_%s_args" % self.nickname
class Parameter(object):
- """Swagger operation parameter"""
+ """Swagger operation parameter.
+ """
def __init__(self, name, required, allowMultiple, dataType, defaultValue):
self.name = name
self.required = required
@@ -325,7 +357,8 @@
raise ValueError("Invalid paramater name: %s" % name)
def decoder(self, char_pointer):
- """Returns the C code for decoding this param from a string."""
+ """Returns the C code for decoding this param from a string.
+ """
if self.dataType == 'string':
return char_pointer
elif self.dataType == 'boolean':
@@ -337,7 +370,8 @@
return char_pointer
def snakify(name):
- """Helper to take a camelCase or dash-seperated name and make it snake_case"""
+ """Helper to take a camelCase or dash-seperated name and make it snake_case.
+ """
r = ''
prior_lower = False
for c in name:
@@ -350,7 +384,8 @@
return r
def is_identifier(str):
- """Returns True if given string is a valid C identifier; False otherwise"""
+ """Returns True if given string is a valid C identifier; False otherwise
+ """
return re.match('^[_A-Za-z][_A-Za-z0-9]*$', str) is not None
def do_not_edit(comment_style = 'C'):
@@ -377,32 +412,40 @@
cog.outl(msg)
def write_resource_copyright(prefix, resource):
+ """Write the copyright statement for the given resource.
+ """
root = Resource('', 'stasis')
- root.load_resource(resource)
+ root.load_api_declaration(resource)
if root.copyright is None:
raise ValueError("Missing copyright statement in %s" % resource)
cog.out(prefix)
cog.out(root.copyright)
def write_resource_author(prefix, resource):
+ """Write the author name for the given resource.
+ """
root = Resource('', 'stasis')
- root.load_resource(resource)
+ root.load_api_declaration(resource)
if root.author is None:
raise ValueError("Missing author statement in %s" % resource)
cog.out(prefix)
cog.out(root.author)
def write_resources_copyright(prefix, resources):
+ """Write the copyright statement for the given resources.
+ """
root = Resource('', 'stasis')
- root.load_resources(resources)
+ root.load_resource_listing(resources)
if root.copyright is None:
raise ValueError("Missing copyright statement in %s" % resources)
cog.out(prefix)
cog.out(root.copyright)
def write_resources_author(prefix, resources):
+ """Write the author name for the given resources.
+ """
root = Resource('', 'stasis')
- root.load_resources(resources)
+ root.load_resource_listing(resources)
if root.author is None:
raise ValueError("Missing author statement in %s" % resources)
cog.out(prefix)
Modified: team/dlee/stasis-http/cog/stasis_http_resource.c.cog
URL: http://svnview.digium.com/svn/asterisk/team/dlee/stasis-http/cog/stasis_http_resource.c.cog?view=diff&rev=379067&r1=379066&r2=379067
==============================================================================
--- team/dlee/stasis-http/cog/stasis_http_resource.c.cog (original)
+++ team/dlee/stasis-http/cog/stasis_http_resource.c.cog Mon Jan 14 14:47:50 2013
@@ -38,7 +38,7 @@
import stasis_cog
root = stasis_cog.Resource('', 'stasis')
-root.load_resource(RESOURCE)
-stasis_cog.ResourceSourceWriter(root).write()
+root.load_api_declaration(RESOURCE)
+stasis_cog.ApiDeclarationSourceWriter(root).write()
]]] */
/*[[[end]]]*/
Modified: team/dlee/stasis-http/cog/stasis_http_resource.h.cog
URL: http://svnview.digium.com/svn/asterisk/team/dlee/stasis-http/cog/stasis_http_resource.h.cog?view=diff&rev=379067&r1=379066&r2=379067
==============================================================================
--- team/dlee/stasis-http/cog/stasis_http_resource.h.cog (original)
+++ team/dlee/stasis-http/cog/stasis_http_resource.h.cog Mon Jan 14 14:47:50 2013
@@ -33,7 +33,7 @@
stasis_cog.do_not_edit()
root = stasis_cog.Resource('', 'stasis')
-root.load_resource(RESOURCE)
-stasis_cog.ResourceHeaderWriter(root).write()
+root.load_api_declaration(RESOURCE)
+stasis_cog.ApiDeclarationHeaderWriter(root).write()
]]] */
/*[[[end]]]*/
Modified: team/dlee/stasis-http/cog/stasis_http_resources.c.cog
URL: http://svnview.digium.com/svn/asterisk/team/dlee/stasis-http/cog/stasis_http_resources.c.cog?view=diff&rev=379067&r1=379066&r2=379067
==============================================================================
--- team/dlee/stasis-http/cog/stasis_http_resources.c.cog (original)
+++ team/dlee/stasis-http/cog/stasis_http_resources.c.cog Mon Jan 14 14:47:50 2013
@@ -43,8 +43,8 @@
stasis_cog.do_not_edit()
root = stasis_cog.Resource('', 'stasis')
-root.load_resources(RESOURCES)
-stasis_cog.ResourcesSourceWriter(root).write()
+root.load_resource_listing(RESOURCES)
+stasis_cog.ResourceListingSourceWriter(root).write()
]]] */
/*[[[end]]]*/
More information about the asterisk-commits
mailing list