def block_h_from_data_type(self, data_type, protocol=None): assert is_user_defined_type(data_type), \ 'Expected user-defined type, got %r' % type(data_type) if not protocol: extensions = [] if data_type.parent_type and is_struct_type(data_type): extensions.append(fmt_class_prefix(data_type.parent_type)) else: if is_union_type(data_type): # Use a handwritten base class extensions.append('NSObject') else: extensions.append('NSObject') extend_suffix = ' : {}'.format( ', '.join(extensions)) if extensions else '' else: base = fmt_class_prefix(data_type.parent_type) if ( data_type.parent_type and not is_union_type(data_type)) else 'NSObject' extend_suffix = ' : {} <{}>'.format(base, ', '.join(protocol)) with self.block( '@interface {}{}'.format( fmt_class_prefix(data_type), extend_suffix), delim=('', '@end'), dent=0): self.emit() yield
def _get_namespace_route_imports(self, namespace, include_route_args=True, include_route_deep_args=False): result = [] def _unpack_and_store_data_type(data_type): data_type, _ = unwrap_nullable(data_type) if is_list_type(data_type): while is_list_type(data_type): data_type, _ = unwrap_nullable(data_type.data_type) if not is_void_type(data_type) and is_user_defined_type(data_type): result.append(data_type) for route in namespace.routes: if include_route_args: data_type, _ = unwrap_nullable(route.arg_data_type) _unpack_and_store_data_type(data_type) elif include_route_deep_args: data_type, _ = unwrap_nullable(route.arg_data_type) if is_union_type(data_type) or is_list_type(data_type): _unpack_and_store_data_type(data_type) elif not is_void_type(data_type): for field in data_type.all_fields: data_type, _ = unwrap_nullable(field.data_type) if (is_struct_type(data_type) or is_union_type(data_type) or is_list_type(data_type)): _unpack_and_store_data_type(data_type) _unpack_and_store_data_type(route.result_data_type) _unpack_and_store_data_type(route.error_data_type) return result
def _get_namespace_route_imports(self, namespace, include_route_args=True, include_route_deep_args=False): result = [] def _unpack_and_store_data_type(data_type): data_type, _ = unwrap_nullable(data_type) if is_list_type(data_type): while is_list_type(data_type): data_type = data_type.data_type if not is_void_type(data_type) and is_user_defined_type(data_type): result.append(data_type) for route in namespace.routes: if include_route_args: data_type, _ = unwrap_nullable(route.arg_data_type) _unpack_and_store_data_type(data_type) elif include_route_deep_args: data_type, _ = unwrap_nullable(route.arg_data_type) if is_union_type(data_type) or is_list_type(data_type): _unpack_and_store_data_type(data_type) elif not is_void_type(data_type): for field in data_type.all_fields: data_type, _ = unwrap_nullable(field.data_type) if (is_struct_type(data_type) or is_union_type(data_type) or is_list_type(data_type)): _unpack_and_store_data_type(data_type) _unpack_and_store_data_type(route.result_data_type) _unpack_and_store_data_type(route.error_data_type) return result
def block_h_from_data_type(self, data_type, protocol=None): assert is_user_defined_type(data_type), \ 'Expected user-defined type, got %r' % type(data_type) if not protocol: extensions = [] if data_type.parent_type and is_struct_type(data_type): extensions.append(fmt_class_prefix(data_type.parent_type)) else: if is_union_type(data_type): # Use a handwritten base class extensions.append('NSObject') else: extensions.append('NSObject') extend_suffix = ' : {}'.format( ', '.join(extensions)) if extensions else '' else: base = fmt_class_prefix(data_type.parent_type) if ( data_type.parent_type and not is_union_type(data_type)) else 'NSObject' extend_suffix = ' : {} <{}>'.format(base, ', '.join(protocol)) with self.block('@interface {}{}'.format(fmt_class_prefix(data_type), extend_suffix), delim=('', '@end'), dent=0): self.emit() yield
def _get_route_args(self, namespace, route, tag=False): # pylint: disable=unused-argument """Returns a list of name / value string pairs representing the arguments for a particular route.""" data_type, _ = unwrap_nullable(route.arg_data_type) if is_struct_type(data_type): arg_list = [] for field in data_type.all_fields: arg_list.append((fmt_var(field.name), fmt_type( field.data_type, tag=tag, has_default=field.has_default))) doc_list = [(fmt_var(f.name), self.process_doc(f.doc, self._docf)) for f in data_type.fields if f.doc] elif is_union_type(data_type): arg_list = [(fmt_var(data_type.name), fmt_type( route.arg_data_type, tag=tag))] doc_list = [(fmt_var(data_type.name), self.process_doc(data_type.doc, self._docf) if data_type.doc else 'The {} union'.format( fmt_class(data_type .name)))] else: arg_list = [] doc_list = [] return arg_list, doc_list
def _generate_struct_builder(self, struct): fields = [ "%s %s" % (fmt_var(field.name), fmt_type(field.data_type, struct.namespace, use_interface=True)) for field in struct.all_required_fields ] self.emit('// New{0} returns a new {0} instance'.format(struct.name)) signature = "func New{0}({1}) *{0}".format(struct.name, ', '.join(fields)) with self.block(signature): self.emit('s := new({0})'.format(struct.name)) for field in struct.all_required_fields: field_name = fmt_var(field.name) self.emit("s.{0} = {0}".format(field_name)) for field in struct.all_optional_fields: if field.has_default: if is_primitive_type(field.data_type): default = field.default if is_boolean_type(field.data_type): default = str(default).lower() self.emit('s.{0} = {1}'.format(fmt_var(field.name), default)) elif is_union_type(field.data_type): self.emit('s.%s = &%s{Tagged:dropbox.Tagged{"%s"}}' % (fmt_var(field.name), fmt_type(field.data_type, struct.namespace).lstrip('*'), field.default.tag_name)) self.emit('return s') self.emit()
def _generate_custom_annotation_processors(self, ns, data_type, extra_annotations=()): """ Generates code that will run a custom function 'processor' on every field with a custom annotation, no matter how deep (recursively) it might be located in data_type (incl. in elements of lists or maps). If extra_annotations is passed, it's assumed to be a list of custom annotation applied directly onto data_type (e.g. because it's a field in a struct). Yields pairs of (annotation_type, code) where code is code that evaluates to a function that should be executed with an instance of data_type as the only parameter, and whose return value should replace that instance. """ # annotations applied to members of this type dt, _, _ = unwrap(data_type) if is_struct_type(dt) or is_union_type(dt): annotation_types_seen = set() for annotation in get_custom_annotations_recursive(dt): if annotation.annotation_type not in annotation_types_seen: yield (annotation.annotation_type, generate_func_call( 'bb.make_struct_annotation_processor', args=[ class_name_for_annotation_type( annotation.annotation_type, ns), 'processor' ])) annotation_types_seen.add(annotation.annotation_type) elif is_list_type(dt): for annotation_type, recursive_processor in self._generate_custom_annotation_processors( ns, dt.data_type): # every member needs to be replaced---use handwritten processor yield (annotation_type, generate_func_call('bb.make_list_annotation_processor', args=[recursive_processor])) elif is_map_type(dt): for annotation_type, recursive_processor in self._generate_custom_annotation_processors( ns, dt.value_data_type): # every value needs to be replaced---use handwritten processor yield (annotation_type, generate_func_call( 'bb.make_map_value_annotation_processor', args=[recursive_processor])) # annotations applied directly to this type (through aliases or # passed in from the caller) for annotation in itertools.chain( get_custom_annotations_for_alias(data_type), extra_annotations): yield (annotation.annotation_type, generate_func_call( 'bb.partially_apply', args=[ 'processor', self._generate_custom_annotation_instance( ns, annotation) ]))
def _generate_init_imports_h(self, data_type): self.emit('#import <Foundation/Foundation.h>') self.emit() self.emit('#import "DBSerializableProtocol.h"') if data_type.parent_type and not is_union_type(data_type): self.emit(fmt_import(fmt_class_prefix(data_type.parent_type))) self.emit()
def _generate_data_type(self, data_type): generate_doc(self, data_type) if is_struct_type(data_type): self._generate_struct(data_type) if data_type.has_enumerated_subtypes(): self._generate_base_type(data_type) elif is_union_type(data_type): self._generate_union(data_type) else: self.logger.info("Unhandled data type", data_type)
def _generate_type(self, data_type, indent_spaces, extra_args): """ Generates a TypeScript type for the given type. """ if is_alias(data_type): self._generate_alias_type(data_type) elif is_struct_type(data_type): self._generate_struct_type(data_type, indent_spaces, extra_args) elif is_union_type(data_type): self._generate_union_type(data_type, indent_spaces)
def _generate_base_namespace_module(self, api, namespace): """Creates a module for the namespace. All data types and routes are represented as Python classes.""" self.cur_namespace = namespace generate_module_header(self) if namespace.doc is not None: self.emit('"""') self.emit_raw(namespace.doc) self.emit('"""') self.emit() self.emit("from __future__ import unicode_literals") self.emit_raw(validators_import) # Generate import statements for all referenced namespaces. self._generate_imports_for_referenced_namespaces(namespace) for annotation_type in namespace.annotation_types: self._generate_annotation_type_class(namespace, annotation_type) for data_type in namespace.linearize_data_types(): if isinstance(data_type, Struct): self._generate_struct_class(namespace, data_type) elif isinstance(data_type, Union): self._generate_union_class(namespace, data_type) else: raise TypeError('Cannot handle type %r' % type(data_type)) for alias in namespace.linearize_aliases(): self._generate_alias_definition(namespace, alias) # Generate the struct->subtype tag mapping at the end so that # references to later-defined subtypes don't cause errors. for data_type in namespace.linearize_data_types(): if is_struct_type(data_type): self._generate_struct_class_reflection_attributes( namespace, data_type) if data_type.has_enumerated_subtypes(): self._generate_enumerated_subtypes_tag_mapping( namespace, data_type) elif is_union_type(data_type): self._generate_union_class_reflection_attributes( namespace, data_type) self._generate_union_class_symbol_creators(data_type) for data_type in namespace.linearize_data_types(): if is_struct_type(data_type): self._generate_struct_attributes_defaults(namespace, data_type) self._generate_routes(api.route_schema, namespace)
def _class_declaration_for_type(self, ns, data_type): assert is_user_defined_type(data_type), \ 'Expected struct, got %r' % type(data_type) if data_type.parent_type: extends = class_name_for_data_type(data_type.parent_type, ns) else: if is_union_type(data_type): # Use a handwritten base class extends = 'bb.Union' else: extends = 'object' return 'class {}({}):'.format( class_name_for_data_type(data_type), extends)
def _class_declaration_for_type(self, ns, data_type): assert is_user_defined_type(data_type), \ 'Expected struct, got %r' % type(data_type) if data_type.parent_type: extends = class_name_for_data_type(data_type.parent_type, ns) else: if is_union_type(data_type): # Use a handwritten base class extends = 'bb.Union' else: extends = 'object' return 'class {}({}):'.format(class_name_for_data_type(data_type), extends)
def make_test_field(field_name, stone_type, rust_generator, reference_impls): rust_name = rust_generator.field_name_raw( field_name) if field_name is not None else None typ, option = ir.unwrap_nullable(stone_type) inner = None value = None if ir.is_struct_type(typ): if typ.has_enumerated_subtypes(): variant = typ.get_enumerated_subtypes()[0] inner = TestPolymorphicStruct(rust_generator, typ, reference_impls, variant) else: inner = TestStruct(rust_generator, typ, reference_impls) value = inner.value elif ir.is_union_type(typ): # Pick the first tag. # We could generate tests for them all, but it would lead to a huge explosion of tests, and # the types themselves are tested elsewhere. if len(typ.fields) == 0: # there must be a parent type; go for it variant = typ.all_fields[0] else: variant = typ.fields[0] inner = TestUnion(rust_generator, typ, reference_impls, variant) value = inner.value elif ir.is_list_type(typ): inner = TestList(rust_generator, typ.data_type, reference_impls) value = [inner.value] elif ir.is_map_type(typ): inner = TestMap(rust_generator, typ, reference_impls) value = inner.value elif ir.is_string_type(typ): if typ.pattern: value = Unregex(typ.pattern, typ.min_length).generate() elif typ.min_length: value = 'a' * typ.min_length else: value = 'something' elif ir.is_numeric_type(typ): value = typ.max_value or typ.maximum or 1e307 elif ir.is_boolean_type(typ): value = True elif ir.is_timestamp_type(typ): value = datetime.datetime.utcfromtimestamp(2**33 - 1) elif ir.is_bytes_type(typ): value = bytes([0, 1, 2, 3, 4, 5]) elif not ir.is_void_type(typ): raise RuntimeError(u'Error: unhandled field type of {}: {}'.format( field_name, typ)) return TestField(rust_name, value, inner, typ, option)
def _generate_base_namespace_module(self, api, namespace): """Creates a module for the namespace. All data types and routes are represented as Python classes.""" self.cur_namespace = namespace self.emit('# -*- coding: utf-8 -*-') self.emit('# Auto-generated by Stone, do not modify.') # Silly way to not type ATgenerated in our code to avoid having this # file marked as auto-generated by our code review tool. self.emit('# @{}'.format('generated')) self.emit('# flake8: noqa') self.emit('# pylint: skip-file') if namespace.doc is not None: self.emit('"""') self.emit_raw(namespace.doc) self.emit('"""') self.emit() self.emit_raw(validators_import) # Generate import statements for all referenced namespaces. self._generate_imports_for_referenced_namespaces(namespace) for data_type in namespace.linearize_data_types(): if isinstance(data_type, Struct): self._generate_struct_class(namespace, data_type) elif isinstance(data_type, Union): self._generate_union_class(namespace, data_type) else: raise TypeError('Cannot handle type %r' % type(data_type)) for alias in namespace.linearize_aliases(): self._generate_alias_definition(namespace, alias) # Generate the struct->subtype tag mapping at the end so that # references to later-defined subtypes don't cause errors. for data_type in namespace.linearize_data_types(): if is_struct_type(data_type): self._generate_struct_class_reflection_attributes( namespace, data_type) if data_type.has_enumerated_subtypes(): self._generate_enumerated_subtypes_tag_mapping( namespace, data_type) elif is_union_type(data_type): self._generate_union_class_reflection_attributes( namespace, data_type) self._generate_union_class_symbol_creators(data_type) self._generate_routes(api.route_schema, namespace)
def _generate_base_namespace_module(self, api, namespace): """Creates a module for the namespace. All data types and routes are represented as Python classes.""" self.cur_namespace = namespace self.emit('# -*- coding: utf-8 -*-') self.emit('# Auto-generated by Stone, do not modify.') self.emit( '# @{}'.format('generated')) # `format` means this file won't # be marked as generated self.emit('# flake8: noqa') self.emit('# pylint: skip-file') if namespace.doc is not None: self.emit('"""') self.emit_raw(namespace.doc) self.emit('"""') self.emit() self.emit_raw(validators_import) # Generate import statements for all referenced namespaces. self._generate_imports_for_referenced_namespaces(namespace) for data_type in namespace.linearize_data_types(): if isinstance(data_type, Struct): self._generate_struct_class(namespace, data_type) elif isinstance(data_type, Union): self._generate_union_class(namespace, data_type) else: raise TypeError('Cannot handle type %r' % type(data_type)) for alias in namespace.linearize_aliases(): self._generate_alias_definition(namespace, alias) # Generate the struct->subtype tag mapping at the end so that # references to later-defined subtypes don't cause errors. for data_type in namespace.linearize_data_types(): if is_struct_type(data_type): self._generate_struct_class_reflection_attributes( namespace, data_type) if data_type.has_enumerated_subtypes(): self._generate_enumerated_subtypes_tag_mapping( namespace, data_type) elif is_union_type(data_type): self._generate_union_class_reflection_attributes( namespace, data_type) self._generate_union_class_symbol_creators(data_type) self._generate_routes(api.route_schema, namespace)
def _generate_base_namespace_module(self, api, namespace): self.emit_raw(base) routes_base = 'Datatypes and serializers for the {} namespace'.format(namespace.name) self.emit_wrapped_text(routes_base, prefix='/// ', width=120) with self.block('open class {}'.format(fmt_class(namespace.name))): for data_type in namespace.linearize_data_types(): if is_struct_type(data_type): self._generate_struct_class(namespace, data_type) self.emit() elif is_union_type(data_type): self._generate_union_type(namespace, data_type) self.emit() if namespace.routes: self._generate_route_objects(api.route_schema, namespace)
def _get_route_args(self, namespace, route): data_type = route.arg_data_type arg_type = fmt_type(data_type) if is_struct_type(data_type): arg_list = self._struct_init_args(data_type, namespace=namespace) doc_list = [(fmt_var(f.name), self.process_doc(f.doc, self._docf) if f.doc else undocumented) for f in data_type.fields if f.doc] elif is_union_type(data_type): arg_list = [(fmt_var(data_type.name), '{}.{}'.format( fmt_class(namespace.name), fmt_class(data_type.name)))] doc_list = [(fmt_var(data_type.name), self.process_doc(data_type.doc, self._docf) if data_type.doc else 'The {} union'.format(fmt_class(data_type.name)))] else: arg_list = [] if is_void_type(data_type) else [('request', arg_type)] doc_list = [] return arg_list, doc_list
def _struct_init_args(self, data_type, namespace=None): # pylint: disable=unused-argument args = [] for field in data_type.all_fields: name = fmt_var(field.name) value = fmt_type(field.data_type) data_type, nullable = unwrap_nullable(field.data_type) if field.has_default: if is_union_type(data_type): default = '.{}'.format(fmt_var(field.default.tag_name)) else: default = fmt_obj(field.default) value += ' = {}'.format(default) elif nullable: value += ' = nil' arg = (name, value) args.append(arg) return args
def make_test_value(self, typ): if ir.is_struct_type(typ): if typ.has_enumerated_subtypes(): return [ TestPolymorphicStruct(self, typ, self.reference_impls, variant) for variant in typ.get_enumerated_subtypes() ] else: return [TestStruct(self, typ, self.reference_impls)] elif ir.is_union_type(typ): return [ TestUnion(self, typ, self.reference_impls, variant) for variant in typ.all_fields ] else: raise RuntimeError( u'ERROR: type {} is neither struct nor union'.format(typ))
def make_test_value(self, typ): if ir.is_struct_type(typ): if typ.has_enumerated_subtypes(): return [TestPolymorphicStruct(self, typ, self.reference_impls, variant) for variant in typ.get_enumerated_subtypes()] else: vals = [TestStruct(self, typ, self.reference_impls)] if typ.all_optional_fields: # If any fields are optional, also emit a test struct that lacks all optional fields. # This helps catch backwards-compat issues as well as checking serialization of None. vals += [TestStruct(self, typ, self.reference_impls, no_optional_fields=True)] return vals elif ir.is_union_type(typ): return [TestUnion(self, typ, self.reference_impls, variant) for variant in typ.all_fields] else: raise RuntimeError(u'ERROR: type {} is neither struct nor union' .format(typ))
def _generate_route_method_decl(self, namespace, route, arg_data_type, request_binary_body, method_name_suffix=None, extra_args=None): """Generates the method prototype for a route.""" method_name = fmt_func(route.name) namespace_name = fmt_func(namespace.name) if method_name_suffix: method_name += method_name_suffix args = ['self'] if extra_args: args += extra_args if request_binary_body: args.append('f') if is_struct_type(arg_data_type): for field in arg_data_type.all_fields: if is_nullable_type(field.data_type): args.append('{}=None'.format(field.name)) elif field.has_default: # TODO(kelkabany): Decide whether we really want to set the # default in the argument list. This will send the default # over the wire even if it isn't overridden. The benefit is # it locks in a default even if it is changed server-side. if is_user_defined_type(field.data_type): ns = field.data_type.namespace else: ns = None arg = '{}={}'.format( field.name, self._generate_python_value(ns, field.default)) args.append(arg) else: args.append(field.name) elif is_union_type(arg_data_type): args.append('arg') elif not is_void_type(arg_data_type): raise AssertionError('Unhandled request type: %r' % arg_data_type) self.generate_multiline_list( args, 'def {}_{}'.format(namespace_name, method_name), ':')
def _generate_route_m(self, route, namespace, route_args, extra_args, task_type_name, func_suffix): """Generates route method implementation for the given route.""" user_args = list(route_args) transport_args = [ ('route', 'route'), ('arg', 'arg' if not is_void_type(route.arg_data_type) else 'nil'), ] for name, value, typ in extra_args: user_args.append((name, typ)) transport_args.append((name, value)) with self.block_func( func='{}{}'.format(fmt_var(route.name), func_suffix), args=fmt_func_args_declaration(user_args), return_type='{} *'.format(task_type_name)): self.emit('DBRoute *route = {}.{};'.format( fmt_route_obj_class(namespace.name), fmt_route_var(namespace.name, route.name))) if is_union_type(route.arg_data_type): self.emit('{} *arg = {};'.format( fmt_class_prefix(route.arg_data_type), fmt_var(route.arg_data_type.name))) elif not is_void_type(route.arg_data_type): init_call = fmt_func_call( caller=fmt_alloc_call( caller=fmt_class_prefix(route.arg_data_type)), callee=self._cstor_name_from_fields_names(route_args), args=fmt_func_args([(f[0], f[0]) for f in route_args])) self.emit('{} *arg = {};'.format( fmt_class_prefix(route.arg_data_type), init_call)) request_call = fmt_func_call( caller='self.client', callee='request{}'.format( fmt_camel_upper(route.attrs.get('style'))), args=fmt_func_args(transport_args)) self.emit('return {};'.format(request_call)) self.emit()
def _generate_route_m(self, route, namespace, route_args, extra_args, task_type_name, func_suffix): """Generates route method implementation for the given route.""" user_args = list(route_args) transport_args = [ ('route', 'route'), ('arg', 'arg' if not is_void_type(route.arg_data_type) else 'nil'), ] for name, value, typ in extra_args: user_args.append((name, typ)) transport_args.append((name, value)) with self.block_func( func='{}{}'.format(fmt_route_func(route), func_suffix), args=fmt_func_args_declaration(user_args), return_type='{} *'.format(task_type_name)): self.emit('DBRoute *route = {}.{};'.format( fmt_route_obj_class(namespace.name), fmt_route_var(namespace.name, route))) if is_union_type(route.arg_data_type): self.emit('{} *arg = {};'.format( fmt_class_prefix(route.arg_data_type), fmt_var(route.arg_data_type.name))) elif not is_void_type(route.arg_data_type): init_call = fmt_func_call( caller=fmt_alloc_call( caller=fmt_class_prefix(route.arg_data_type)), callee=self._cstor_name_from_fields_names(route_args), args=fmt_func_args([(f[0], f[0]) for f in route_args])) self.emit('{} *arg = {};'.format( fmt_class_prefix(route.arg_data_type), init_call)) request_call = fmt_func_call( caller='self.client', callee='request{}'.format( fmt_camel_upper(route.attrs.get('style'))), args=fmt_func_args(transport_args)) self.emit('return {};'.format(request_call)) self.emit()
def _generate_route_method_decl( self, namespace, route, arg_data_type, request_binary_body, method_name_suffix=None, extra_args=None): """Generates the method prototype for a route.""" method_name = fmt_func(route.name) namespace_name = fmt_func(namespace.name) if method_name_suffix: method_name += method_name_suffix args = ['self'] if extra_args: args += extra_args if request_binary_body: args.append('f') if is_struct_type(arg_data_type): for field in arg_data_type.all_fields: if is_nullable_type(field.data_type): args.append('{}=None'.format(field.name)) elif field.has_default: # TODO(kelkabany): Decide whether we really want to set the # default in the argument list. This will send the default # over the wire even if it isn't overridden. The benefit is # it locks in a default even if it is changed server-side. if is_user_defined_type(field.data_type): ns = field.data_type.namespace else: ns = None arg = '{}={}'.format( field.name, self._generate_python_value(ns, field.default)) args.append(arg) else: args.append(field.name) elif is_union_type(arg_data_type): args.append('arg') elif not is_void_type(arg_data_type): raise AssertionError('Unhandled request type: %r' % arg_data_type) self.generate_multiline_list( args, 'def {}_{}'.format(namespace_name, method_name), ':')
def _generate_docstring_for_func(self, namespace, arg_data_type, result_data_type=None, error_data_type=None, overview=None, extra_request_args=None, extra_return_arg=None, footer=None): """ Generates a docstring for a function or method. This function is versatile. It will create a docstring using all the data that is provided. :param arg_data_type: The data type describing the argument to the route. The data type should be a struct, and each field will be treated as an input parameter of the method. :param result_data_type: The data type of the route result. :param error_data_type: The data type of the route result in the case of an error. :param str overview: A description of the route that will be located at the top of the docstring. :param extra_request_args: [(field name, field type, field doc), ...] Describes any additional parameters for the method that aren't a field in arg_data_type. :param str extra_return_arg: Name of an additional return type that. If this is specified, it is assumed that the return of the function will be a tuple of return_data_type and extra_return-arg. :param str footer: Additional notes at the end of the docstring. """ fields = [] if is_void_type(arg_data_type) else arg_data_type.fields if not fields and not overview: # If we don't have an overview or any input parameters, we skip the # docstring altogether. return self.emit('"""') if overview: self.emit_wrapped_text(overview) # Description of all input parameters if extra_request_args or fields: if overview: # Add a blank line if we had an overview self.emit() if extra_request_args: for name, data_type_name, doc in extra_request_args: if data_type_name: field_doc = ':param {} {}: {}'.format(data_type_name, name, doc) self.emit_wrapped_text(field_doc, subsequent_prefix=' ') else: self.emit_wrapped_text( ':param {}: {}'.format(name, doc), subsequent_prefix=' ') if is_struct_type(arg_data_type): for field in fields: if field.doc: if is_user_defined_type(field.data_type): field_doc = ':param {}: {}'.format( field.name, self.process_doc(field.doc, self._docf)) else: field_doc = ':param {} {}: {}'.format( self._format_type_in_doc(namespace, field.data_type), field.name, self.process_doc(field.doc, self._docf), ) self.emit_wrapped_text( field_doc, subsequent_prefix=' ') if is_user_defined_type(field.data_type): # It's clearer to declare the type of a composite on # a separate line since it references a class in # another module self.emit(':type {}: {}'.format( field.name, self._format_type_in_doc(namespace, field.data_type), )) else: # If the field has no docstring, then just document its # type. field_doc = ':type {}: {}'.format( field.name, self._format_type_in_doc(namespace, field.data_type), ) self.emit_wrapped_text(field_doc) elif is_union_type(arg_data_type): if arg_data_type.doc: self.emit_wrapped_text(':param arg: {}'.format( self.process_doc(arg_data_type.doc, self._docf)), subsequent_prefix=' ') self.emit(':type arg: {}'.format( self._format_type_in_doc(namespace, arg_data_type))) if overview and not (extra_request_args or fields): # Only output an empty line if we had an overview and haven't # started a section on declaring types. self.emit() if extra_return_arg: # Special case where the function returns a tuple. The first # element is the JSON response. The second element is the # the extra_return_arg param. args = [] if is_void_type(result_data_type): args.append('None') else: rtype = self._format_type_in_doc(namespace, result_data_type) args.append(rtype) args.append(extra_return_arg) self.generate_multiline_list(args, ':rtype: ') else: if is_void_type(result_data_type): self.emit(':rtype: None') else: rtype = self._format_type_in_doc(namespace, result_data_type) self.emit(':rtype: {}'.format(rtype)) if not is_void_type(error_data_type) and error_data_type.fields: self.emit(':raises: :class:`{}`'.format(self.args.error_class_path)) self.emit() # To provide more clarity to a dev who reads the docstring, suggest # the route's error class. This is confusing, however, because we # don't know where the error object that's raised will store # the more detailed route error defined in stone. error_class_name = self.args.error_class_path.rsplit('.', 1)[-1] self.emit('If this raises, {} will contain:'.format(error_class_name)) with self.indent(): self.emit(self._format_type_in_doc(namespace, error_data_type)) if footer: self.emit() self.emit_wrapped_text(footer) self.emit('"""')
def _generate_route_helper(self, namespace, route, download_to_file=False): """Generate a Python method that corresponds to a route. :param namespace: Namespace that the route belongs to. :param stone.ir.ApiRoute route: IR node for the route. :param bool download_to_file: Whether a special version of the route that downloads the response body to a file should be generated. This can only be used for download-style routes. """ arg_data_type = route.arg_data_type result_data_type = route.result_data_type request_binary_body = route.attrs.get('style') == 'upload' response_binary_body = route.attrs.get('style') == 'download' if download_to_file: assert response_binary_body, 'download_to_file can only be set ' \ 'for download-style routes.' self._generate_route_method_decl(namespace, route, arg_data_type, request_binary_body, method_name_suffix='_to_file', extra_args=['download_path']) else: self._generate_route_method_decl(namespace, route, arg_data_type, request_binary_body) with self.indent(): extra_request_args = None extra_return_arg = None footer = None if request_binary_body: extra_request_args = [('f', 'bytes', 'Contents to upload.')] elif download_to_file: extra_request_args = [('download_path', 'str', 'Path on local machine to save file.')] if response_binary_body and not download_to_file: extra_return_arg = ':class:`requests.models.Response`' footer = DOCSTRING_CLOSE_RESPONSE if route.doc: func_docstring = self.process_doc(route.doc, self._docf) else: func_docstring = None self._generate_docstring_for_func( namespace, arg_data_type, result_data_type, route.error_data_type, overview=func_docstring, extra_request_args=extra_request_args, extra_return_arg=extra_return_arg, footer=footer, ) self._maybe_generate_deprecation_warning(route) # Code to instantiate a class for the request data type if is_void_type(arg_data_type): self.emit('arg = None') elif is_struct_type(arg_data_type): self.generate_multiline_list( [f.name for f in arg_data_type.all_fields], before='arg = {}.{}'.format( fmt_namespace(arg_data_type.namespace.name), fmt_class(arg_data_type.name)), ) elif not is_union_type(arg_data_type): raise AssertionError('Unhandled request type %r' % arg_data_type) # Code to make the request args = [ '{}.{}'.format(fmt_namespace(namespace.name), fmt_func(route.name, version=route.version)), "'{}'".format(namespace.name), 'arg'] if request_binary_body: args.append('f') else: args.append('None') self.generate_multiline_list(args, 'r = self.request', compact=False) if download_to_file: self.emit('self._save_body_to_file(download_path, r[1])') if is_void_type(result_data_type): self.emit('return None') else: self.emit('return r[0]') else: if is_void_type(result_data_type): self.emit('return None') else: self.emit('return r') self.emit()
def generate(self, api): print(u'Generating Python reference code') self.reference.generate(api) with self.output_to_relative_path('reference/__init__.py'): self.emit(u'# this is the Stone-generated reference Python SDK') print(u'Loading reference code:') sys.path.insert(0, self.target_path) from reference.stone_serializers import json_encode for ns in api.namespaces: print('\t' + ns) python_ns = ns if ns == 'async': # hack to work around 'async' being a Python3 keyword python_ns = 'async_' self.reference_impls[ns] = __import__('reference.'+python_ns).__dict__[python_ns] print(u'Generating test code') for ns in api.namespaces.values(): ns_name = self.namespace_name(ns) with self.output_to_relative_path(ns_name + '.rs'): self._emit_header() for typ in ns.data_types: type_name = self.struct_name(typ) # the general idea here is to instantiate each type using # the reference Python code, put some random data in the # fields, serialize it to JSON, emit the JSON into the Rust # test, have Rust deserialize it, and emit assertions that # the fields match. Then have Rust re-serialize to JSON and # desereialize it again, then check the fields of the # newly-deserialized struct. This verifies Rust's # serializer. is_serializable = True test_value = None if ir.is_struct_type(typ): if typ.has_enumerated_subtypes(): # TODO: generate tests for all variants # for now, just pick the first variant variant = typ.get_enumerated_subtypes()[0] test_value = TestPolymorphicStruct( self, typ, self.reference_impls, variant) else: test_value = TestStruct(self, typ, self.reference_impls) elif ir.is_union_type(typ): # TODO: generate tests for all variants # for now, just pick the first variant # prefer choosing from this type and not the parent if we can variants = [field for field in typ.fields if not field.catch_all] if len(variants) == 0: # fall back to parent type's variants variants = [field for field in typ.all_fields if not field.catch_all] if not variants: # Rust code will refuse to serialize a type with no variants (or only # the catch-all variant), so don't bother testing that is_serializable = False variant = typ.all_fields[0] # this assumes there's at least one else: variant = variants[0] test_value = TestUnion(self, typ, self.reference_impls, variant) else: raise RuntimeError(u'ERROR: type {} is neither struct nor union' .format(typ)) pyname = fmt_py_class(typ.name) json = json_encode( self.reference_impls[ns.name].__dict__[pyname + '_validator'], test_value.value, Permissions()) with self._test_fn(type_name): self.emit(u'let json = r#"{}"#;'.format(json)) self.emit(u'let x = ::serde_json::from_str::<::dropbox_sdk::{}::{}>(json).unwrap();' .format(ns_name, self.struct_name(typ))) test_value.emit_asserts(self, 'x') if is_serializable: # now serialize it back to JSON, deserialize it again, and test # it again. self.emit() self.emit(u'let json2 = ::serde_json::to_string(&x).unwrap();') de = u'::serde_json::from_str::<::dropbox_sdk::{}::{}>(&json2).unwrap()' \ .format(ns_name, self.struct_name(typ)) if typ.all_fields: self.emit(u'let x2 = {};'.format(de)) test_value.emit_asserts(self, 'x2') else: self.emit(u'{};'.format(de)) else: # assert that serializing it returns an error self.emit(u'assert!(::serde_json::to_string(&x).is_err());') self.emit() # for typ # .rs test file # for ns with self.output_to_relative_path('mod.rs'): self._emit_header() for ns in api.namespaces: self.emit(u'#[cfg(feature = "dbx_{}")]'.format(ns)) self.emit(u'mod {};'.format(self.namespace_name_raw(ns))) self.emit()
def _generate_union_helper(self, u): name = u.name namespace = u.namespace # Unions can be inherited, but don't need to be polymorphic. # So let's flatten out all the inherited fields. fields = u.all_fields if is_struct_type(u) and u.has_enumerated_subtypes(): name = fmt_var(name, export=False) + 'Union' fields = u.get_enumerated_subtypes() with self.block('type %s struct' % name): self.emit('dropbox.Tagged') for field in fields: if is_void_type(field.data_type): continue self._generate_field(field, union_field=True, namespace=namespace) self.emit() self.emit('// Valid tag values for %s' % fmt_var(u.name)) with self.block('const', delim=('(', ')')): for field in fields: self.emit('%s%s = "%s"' % (fmt_var(u.name), fmt_var(field.name), field.name)) self.emit() num_void_fields = sum([is_void_type(f.data_type) for f in fields]) # Simple structure, no need in UnmarshalJSON if len(fields) == num_void_fields: return self.emit('// UnmarshalJSON deserializes into a %s instance' % name) with self.block('func (u *%s) UnmarshalJSON(body []byte) error' % name): with self.block('type wrap struct'): self.emit('dropbox.Tagged') for field in fields: if is_void_type(field.data_type) or \ is_primitive_type(field.data_type): continue self._generate_field(field, union_field=True, namespace=namespace, raw=True) self.emit('var w wrap') self.emit('var err error') with self.block('if err = json.Unmarshal(body, &w); err != nil'): self.emit('return err') self.emit('u.Tag = w.Tag') with self.block('switch u.Tag'): for field in fields: if is_void_type(field.data_type): continue field_name = fmt_var(field.name) with self.block('case "%s":' % field.name, delim=(None, None)): if is_union_type(field.data_type): self.emit( 'err = json.Unmarshal(w.{0}, &u.{0})'.format( field_name)) elif is_struct_type(field.data_type) and \ field.data_type.has_enumerated_subtypes(): self.emit( "u.{0}, err = Is{1}FromJSON(body)".format( field_name, field.data_type.name)) else: self.emit( 'err = json.Unmarshal(body, &u.{0})'.format( field_name)) with self.block("if err != nil"): self.emit("return err") self.emit('return nil') self.emit()
def _emit_route(self, namespace, route, req_obj_name, extra_args=None, extra_docs=None): arg_list, doc_list = self._get_route_args(namespace, route) extra_args = extra_args or [] extra_docs = extra_docs or [] arg_type = fmt_type(route.arg_data_type) func_name = fmt_func(route.name) if route.doc: route_doc = self.process_doc(route.doc, self._docf) else: route_doc = 'The {} route'.format(func_name) self.emit_wrapped_text(route_doc, prefix='/// ', width=120) self.emit('///') for name, doc in doc_list + extra_docs: param_doc = '- parameter {}: {}'.format(name, doc if doc is not None else undocumented) self.emit_wrapped_text(param_doc, prefix='/// ', width=120) self.emit('///') output = (' - returns: Through the response callback, the caller will ' + 'receive a `{}` object on success or a `{}` object on failure.') output = output.format(fmt_type(route.result_data_type), fmt_type(route.error_data_type)) self.emit_wrapped_text(output, prefix='/// ', width=120) func_args = [ ('route', '{}.{}'.format(fmt_class(namespace.name), func_name)), ] client_args = [] return_args = [('route', 'route')] for name, value, typ in extra_args: arg_list.append((name, typ)) func_args.append((name, value)) client_args.append((name, value)) rtype = fmt_serial_type(route.result_data_type) etype = fmt_serial_type(route.error_data_type) self._maybe_generate_deprecation_warning(route) with self.function_block('@discardableResult open func {}'.format(func_name), args=self._func_args(arg_list, force_first=False), return_type='{}<{}, {}>'.format(req_obj_name, rtype, etype)): self.emit('let route = {}.{}'.format(fmt_class(namespace.name), func_name)) if is_struct_type(route.arg_data_type): args = [(name, name) for name, _ in self._struct_init_args(route.arg_data_type)] func_args += [('serverArgs', '{}({})'.format(arg_type, self._func_args(args)))] self.emit('let serverArgs = {}({})'.format(arg_type, self._func_args(args))) elif is_union_type(route.arg_data_type): self.emit('let serverArgs = {}'.format(fmt_var(route.arg_data_type.name))) if not is_void_type(route.arg_data_type): return_args += [('serverArgs', 'serverArgs')] return_args += client_args txt = 'return client.request({})'.format( self._func_args(return_args, not_init=True) ) self.emit(txt) self.emit()
def _generate_type(self, data_type, extra_parameters): if is_struct_type(data_type): self._generate_struct(data_type, extra_parameters) elif is_union_type(data_type): self._generate_union(data_type)
def _emit_route(self, namespace, route, req_obj_name, extra_args=None, extra_docs=None): arg_list, doc_list = self._get_route_args(namespace, route) extra_args = extra_args or [] extra_docs = extra_docs or [] arg_type = fmt_type(route.arg_data_type) func_name = fmt_func(route.name, route.version) if route.doc: route_doc = self.process_doc(route.doc, self._docf) else: route_doc = 'The {} route'.format(func_name) self.emit_wrapped_text(route_doc, prefix='/// ', width=120) self.emit('///') for name, doc in doc_list + extra_docs: param_doc = '- parameter {}: {}'.format( name, doc if doc is not None else undocumented) self.emit_wrapped_text(param_doc, prefix='/// ', width=120) self.emit('///') output = ( ' - returns: Through the response callback, the caller will ' + 'receive a `{}` object on success or a `{}` object on failure.') output = output.format(fmt_type(route.result_data_type), fmt_type(route.error_data_type)) self.emit_wrapped_text(output, prefix='/// ', width=120) func_args = [ ('route', '{}.{}'.format(fmt_class(namespace.name), func_name)), ] client_args = [] return_args = [('route', 'route')] for name, value, typ in extra_args: arg_list.append((name, typ)) func_args.append((name, value)) client_args.append((name, value)) rtype = fmt_serial_type(route.result_data_type) etype = fmt_serial_type(route.error_data_type) self._maybe_generate_deprecation_warning(route) with self.function_block( '@discardableResult open func {}'.format(func_name), args=self._func_args(arg_list, force_first=False), return_type='{}<{}, {}>'.format(req_obj_name, rtype, etype)): self.emit('let route = {}.{}'.format(fmt_class(namespace.name), func_name)) if is_struct_type(route.arg_data_type): args = [ (name, name) for name, _ in self._struct_init_args(route.arg_data_type) ] func_args += [ ('serverArgs', '{}({})'.format(arg_type, self._func_args(args))) ] self.emit('let serverArgs = {}({})'.format( arg_type, self._func_args(args))) elif is_union_type(route.arg_data_type): self.emit('let serverArgs = {}'.format( fmt_var(route.arg_data_type.name))) if not is_void_type(route.arg_data_type): return_args += [('serverArgs', 'serverArgs')] return_args += client_args txt = 'return client.request({})'.format( self._func_args(return_args, not_init=True)) self.emit(txt) self.emit()