def _generate_request(self, namespace, route):
host = route.attrs.get('host', 'api')
style = route.attrs.get('style', 'rpc')
out = self.emit
body = 'nil'
if not is_void_type(route.arg_data_type):
with self.block('if dbx.Config.Verbose'):
out('log.Printf("arg: %v", arg)')
out('b, err := json.Marshal(arg)')
with self.block('if err != nil'):
out('return')
out()
if host != 'content':
body = 'bytes.NewReader(b)'
if style == 'upload':
body = 'content'
out('req, err := http.NewRequest("POST", '
'(*dropbox.Context)(dbx).GenerateURL("{}", "{}", "{}"), {})'.
format(host, namespace.name, route.name, body))
with self.block('if err != nil'):
out('return')
out()
if not is_void_type(route.arg_data_type):
if host == 'content':
out('req.Header.Set("Dropbox-API-Arg", string(b))')
else:
out('req.Header.Set("Content-Type", "application/json")')
if style == 'upload':
out('req.Header.Set("Content-Type",' '"application/octet-stream")')
def _generate_request(self, namespace, route):
host = route.attrs.get('host', 'api')
style = route.attrs.get('style', 'rpc')
out = self.emit
body = 'nil'
if not is_void_type(route.arg_data_type):
with self.block('if dbx.Config.Verbose'):
out('log.Printf("arg: %v", arg)')
out('b, err := json.Marshal(arg)')
with self.block('if err != nil'):
out('return')
out()
if host != 'content':
body = 'bytes.NewReader(b)'
if style == 'upload':
body = 'content'
out('req, err := http.NewRequest("POST", '
'(*dropbox.Context)(dbx).GenerateURL("{}", "{}", "{}"), {})'.format(
host, namespace.name, route.name, body))
with self.block('if err != nil'):
out('return')
out()
if not is_void_type(route.arg_data_type):
if host == 'content':
out('req.Header.Set("Dropbox-API-Arg", string(b))')
else:
out('req.Header.Set("Content-Type", "application/json")')
if style == 'upload':
out('req.Header.Set("Content-Type",' '"application/octet-stream")')
def _generate_union_serializer(self, data_type):
with self.serializer_block(data_type):
with self.serializer_func(data_type), self.block('switch value'):
for field in data_type.all_fields:
field_type = field.data_type
case = '.{}{}'.format(fmt_var(field.name),
'' if is_void_type(field_type) else '(let arg)')
self.emit('case {}:'.format(case))
with self.indent():
if is_void_type(field_type):
self.emit('var d = [String: JSON]()')
elif (is_struct_type(field_type) and
not field_type.has_enumerated_subtypes()):
self.emit('var d = Serialization.getFields({}.serialize(arg))'.format(
fmt_serial_obj(field_type)))
else:
self.emit('var d = ["{}": {}.serialize(arg)]'.format(
field.name,
fmt_serial_obj(field_type)))
self.emit('d[".tag"] = .str("{}")'.format(field.name))
self.emit('return .dictionary(d)')
with self.deserializer_func(data_type):
with self.block("switch json"):
self.emit("case .dictionary(let d):")
with self.indent():
self.emit('let tag = Serialization.getTag(d)')
with self.block('switch tag'):
for field in data_type.all_fields:
field_type = field.data_type
self.emit('case "{}":'.format(field.name))
tag_type = self._tag_type(data_type, field)
with self.indent():
if is_void_type(field_type):
self.emit('return {}'.format(tag_type))
else:
if (is_struct_type(field_type) and
not field_type.has_enumerated_subtypes()):
subdict = 'json'
else:
subdict = 'd["{}"] ?? .null'.format(field.name)
self.emit('let v = {}.deserialize({})'.format(
fmt_serial_obj(field_type), subdict
))
self.emit('return {}(v)'.format(tag_type))
self.emit('default:')
with self.indent():
if data_type.catch_all_field:
self.emit('return {}'.format(
self._tag_type(data_type, data_type.catch_all_field)
))
else:
self.emit('fatalError("Unknown tag \(tag)")')
self.emit("default:")
with self.indent():
self.emit('fatalError("Failed to deserialize")')
def _generate_union_serializer(self, data_type):
with self.serializer_block(data_type):
with self.serializer_func(data_type), self.block('switch value'):
for field in data_type.all_fields:
field_type = field.data_type
case = '.{}{}'.format(fmt_class(field.name),
'' if is_void_type(field_type) else '(let arg)')
self.emit('case {}:'.format(case))
with self.indent():
if is_void_type(field_type):
self.emit('var d = [String: JSON]()')
elif (is_struct_type(field_type) and
not field_type.has_enumerated_subtypes()):
self.emit('var d = Serialization.getFields({}.serialize(arg))'.format(
fmt_serial_obj(field_type)))
else:
self.emit('var d = ["{}": {}.serialize(arg)]'.format(
field.name,
fmt_serial_obj(field_type)))
self.emit('d[".tag"] = .Str("{}")'.format(field.name))
self.emit('return .Dictionary(d)')
with self.deserializer_func(data_type):
with self.block("switch json"):
self.emit("case .Dictionary(let d):")
with self.indent():
self.emit('let tag = Serialization.getTag(d)')
with self.block('switch tag'):
for field in data_type.all_fields:
field_type = field.data_type
self.emit('case "{}":'.format(field.name))
tag_type = self._tag_type(data_type, field)
with self.indent():
if is_void_type(field_type):
self.emit('return {}'.format(tag_type))
else:
if (is_struct_type(field_type) and
not field_type.has_enumerated_subtypes()):
subdict = 'json'
else:
subdict = 'd["{}"] ?? .Null'.format(field.name)
self.emit('let v = {}.deserialize({})'.format(
fmt_serial_obj(field_type), subdict
))
self.emit('return {}(v)'.format(tag_type))
self.emit('default:')
with self.indent():
if data_type.catch_all_field:
self.emit('return {}'.format(
self._tag_type(data_type, data_type.catch_all_field)
))
else:
self.emit('fatalError("Unknown tag \(tag)")')
self.emit("default:")
with self.indent():
self.emit('fatalError("Failed to deserialize")')
def _generate_union_helper(self, u):
name = u.name
namespace = u.namespace
fields = u.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')
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):
with self.block('if err := json.Unmarshal'
'(w.{0}, &u.{0}); err != nil'
.format(field_name)):
self.emit('return err')
else:
with self.block('if err := json.Unmarshal'
'(body, &u.{0}); err != nil'
.format(field_name)):
self.emit('return err')
self.emit('return nil')
self.emit()
def _generate_route_signature(
self,
route,
namespace, # pylint: disable=unused-argument
route_args,
extra_args,
doc_list,
task_type_name,
func_suffix):
"""Generates route method signature for the given route."""
for name, _, typ in extra_args:
route_args.append((name, typ))
deprecated = 'DEPRECATED: ' if route.deprecated else ''
func_name = '{}{}'.format(fmt_var(route.name), func_suffix)
self.emit(comment_prefix)
if route.doc:
route_doc = self.process_doc(route.doc, self._docf)
else:
route_doc = 'The {} route'.format(func_name)
self.emit_wrapped_text(deprecated + route_doc,
prefix=comment_prefix,
width=120)
self.emit(comment_prefix)
for name, doc in doc_list:
self.emit_wrapped_text('@param {} {}'.format(
name, doc if doc else undocumented),
prefix=comment_prefix,
width=120)
self.emit(comment_prefix)
output = (
'@return 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, tag=False, no_ptr=True),
fmt_type(route.error_data_type, tag=False, no_ptr=True))
self.emit_wrapped_text(output, prefix=comment_prefix, width=120)
self.emit(comment_prefix)
result_type_str = fmt_type(route.result_data_type) if not is_void_type(
route.result_data_type) else 'DBNilObject *'
error_type_str = fmt_type(route.error_data_type) if not is_void_type(
route.error_data_type) else 'DBNilObject *'
return_type = '{}<{}, {}> *'.format(task_type_name, result_type_str,
error_type_str)
deprecated = self._get_deprecation_warning(route)
route_signature = fmt_signature(
func=func_name,
args=fmt_func_args_declaration(route_args),
return_type='{} _Nonnull'.format(return_type))
self.emit('{}{};'.format(route_signature, deprecated))
self.emit()
def _generate_route_signature(
self,
route,
namespace, # pylint: disable=unused-argument
route_args,
extra_args,
doc_list,
task_type_name,
func_suffix):
"""Generates route method signature for the given route."""
for name, _, typ in extra_args:
route_args.append((name, typ))
deprecated = 'DEPRECATED: ' if route.deprecated else ''
func_name = '{}{}'.format(fmt_var(route.name), func_suffix)
self.emit(comment_prefix)
if route.doc:
route_doc = self.process_doc(route.doc, self._docf)
else:
route_doc = 'The {} route'.format(func_name)
self.emit_wrapped_text(
deprecated + route_doc, prefix=comment_prefix, width=120)
self.emit(comment_prefix)
for name, doc in doc_list:
self.emit_wrapped_text(
'@param {} {}'.format(name, doc if doc else undocumented),
prefix=comment_prefix,
width=120)
self.emit(comment_prefix)
output = (
'@return 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, tag=False, no_ptr=True),
fmt_type(route.error_data_type, tag=False, no_ptr=True))
self.emit_wrapped_text(output, prefix=comment_prefix, width=120)
self.emit(comment_prefix)
result_type_str = fmt_type(route.result_data_type) if not is_void_type(
route.result_data_type) else 'DBNilObject *'
error_type_str = fmt_type(route.error_data_type) if not is_void_type(
route.error_data_type) else 'DBNilObject *'
return_type = '{}<{}, {}> *'.format(task_type_name, result_type_str,
error_type_str)
deprecated = self._get_deprecation_warning(route)
route_signature = fmt_signature(
func=func_name,
args=fmt_func_args_declaration(route_args),
return_type='{}'.format(return_type))
self.emit('{}{};'.format(route_signature, deprecated))
self.emit()
def _generate_request(self, namespace, route):
out = self.emit
auth = route.attrs.get('auth', '')
host = route.attrs.get('host', 'api')
style = route.attrs.get('style', 'rpc')
body = 'nil'
if not is_void_type(route.arg_data_type):
out('dbx.Config.TryLog("arg: %v", arg)')
out('b, err := json.Marshal(arg)')
with self.block('if err != nil'):
out('return')
out()
if host != 'content':
body = 'bytes.NewReader(b)'
if style == 'upload':
body = 'content'
headers = {}
if not is_void_type(route.arg_data_type):
if host == 'content':
headers["Dropbox-API-Arg"] = "string(b)"
else:
headers["Content-Type"] = '"application/json"'
if style == 'upload':
headers["Content-Type"] = '"application/octet-stream"'
out('headers := map[string]string{')
for k, v in sorted(headers.items()):
out('\t"{}": {},'.format(k, v))
out('}')
if fmt_var(route.name) == "Download":
out('for k, v := range arg.ExtraHeaders { headers[k] = v }')
if auth != 'noauth' and auth != 'team':
with self.block('if dbx.Config.AsMemberID != ""'):
out('headers["Dropbox-API-Select-User"] = dbx.Config.AsMemberID'
)
out()
authed = 'false' if auth == 'noauth' else 'true'
out('req, err := (*dropbox.Context)(dbx).NewRequest("{}", "{}", {}, "{}", "{}", headers, {})'
.format(host, style, authed, namespace.name, route.name, body))
with self.block('if err != nil'):
out('return')
out('dbx.Config.TryLog("req: %v", req)')
out()
def _generate_union_type(self, union_type, indent_spaces):
"""
Generates a TypeScript interface for a stone union.
"""
# Emit an interface for each variant. TypeScript 2.0 supports these tagged unions.
# https://github.com/Microsoft/TypeScript/wiki/What%27s-new-in-TypeScript#tagged-union-types
parent_type = union_type.parent_type
namespace = union_type.namespace
union_type_name = fmt_type_name(union_type, namespace)
variant_type_names = []
if parent_type:
variant_type_names.append(fmt_type_name(parent_type, namespace))
for variant in union_type.fields:
if variant.doc:
self._emit_tsdoc_header(variant.doc)
variant_name = '%s%s' % (union_type_name, fmt_pascal(variant.name))
variant_type_names.append(variant_name)
self.emit('interface %s {' % variant_name)
with self.indent(dent=indent_spaces):
# Since field contains non-alphanumeric character, we need to enclose
# it in quotation marks.
self.emit("'.tag': '%s';" % variant.name)
if is_void_type(variant.data_type) is False:
self.emit("%s: %s;" % (variant.name, fmt_type(variant.data_type, namespace)))
self.emit('}')
self.emit()
if union_type.doc:
self._emit_tsdoc_header(union_type.doc)
self.emit('type %s = %s;' % (union_type_name, ' | '.join(variant_type_names)))
self.emit()
def _generate_union_class_variant_creators(self, ns, data_type):
"""
Each non-symbol, non-any variant has a corresponding class method that
can be used to construct a union with that variant selected.
"""
for field in data_type.fields:
if not is_void_type(field.data_type):
field_name = fmt_func(field.name)
field_name_reserved_check = fmt_func(field.name, True)
if is_nullable_type(field.data_type):
field_dt = field.data_type.data_type
else:
field_dt = field.data_type
self.emit('@classmethod')
self.emit('def {}(cls, val):'.format(field_name_reserved_check))
with self.indent():
self.emit('"""')
self.emit_wrapped_text(
'Create an instance of this class set to the ``%s`` '
'tag with value ``val``.' % field_name)
self.emit()
self.emit(':param {} val:'.format(
self._python_type_mapping(ns, field_dt)))
self.emit(':rtype: {}'.format(
fmt_class(data_type.name)))
self.emit('"""')
self.emit("return cls('{}', val)".format(field_name))
self.emit()
def _python_type_mapping(self, ns, data_type):
"""Map Stone data types to their most natural equivalent in Python
for documentation purposes."""
if is_string_type(data_type):
return 'str'
elif is_bytes_type(data_type):
return 'bytes'
elif is_boolean_type(data_type):
return 'bool'
elif is_float_type(data_type):
return 'float'
elif is_integer_type(data_type):
return 'long'
elif is_void_type(data_type):
return 'None'
elif is_timestamp_type(data_type):
return 'datetime.datetime'
elif is_alias(data_type):
return self._python_type_mapping(ns, data_type.data_type)
elif is_user_defined_type(data_type):
class_name = class_name_for_data_type(data_type)
if data_type.namespace.name != ns.name:
return '%s.%s_validator' % (
data_type.namespace.name, class_name)
else:
return class_name
elif is_list_type(data_type):
# PyCharm understands this description format for a list
return 'list of [{}]'.format(self._python_type_mapping(
ns, data_type.data_type))
elif is_nullable_type(data_type):
return 'Optional[{}]'.format(
self._python_type_mapping(ns, data_type.data_type))
else:
raise TypeError('Unknown data type %r' % data_type)
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 _emit_route(self, namespace, route, 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 = self._swift_type_mapping(route.arg_data_type)
func_name = fmt_func(route.name)
self.emit('/**')
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:
if not doc:
doc = 'Undocumented'
self.emit_wrapped_text('- parameter {}: {}'.format(name, doc), prefix=' ', width=120)
self.emit()
self.emit_wrapped_text(' - returns: Through the response callback, the caller will ' +
'receive a `{}` object on success or a `{}` object on ' +
'failure.'.format(
self._swift_type_mapping(route.result_data_type),
self._swift_type_mapping(route.error_data_type)),
prefix=' ', width=120)
self.emit('*/')
route_type = self.STYLE_MAPPING[route.attrs.get('style')]
rtype = self._swift_type_mapping(route.result_data_type,
serializer=True)
etype = self._swift_type_mapping(route.error_data_type,
serializer=True)
host_ident = route.attrs.get('host', 'meta')
func_args = [
('client', 'self.client'),
('host', '"'+host_ident+'"'),
('route', '"/{}/{}"'.format(namespace.name, route.name)),
('params', '{}.serialize({})'.format(
self._serializer_obj(route.arg_data_type),
'' if is_void_type(route.arg_data_type) else 'request')),
('responseSerializer', self._serializer_obj(route.result_data_type)),
('errorSerializer', self._serializer_obj(route.error_data_type)),
]
for name, typ, value in extra_args:
arg_list.append((name, typ))
func_args.append((name, value))
with self.function_block('public func {}'.format(func_name),
args=self._func_args(arg_list, force_first=True),
return_type='Stone{}Request<{}, {}>'.format(route_type,
rtype,
etype)):
if is_struct_type(route.arg_data_type):
args = [(name, name) for name, _ in self._struct_init_args(route.arg_data_type)]
self.emit('let request = {}({})'.format(arg_type, self._func_args(args)))
self.emit('return Stone{}Request({})'.format(route_type, self._func_args(func_args)))
def _generate_union_class_variant_creators(self, ns, data_type):
"""
Each non-symbol, non-any variant has a corresponding class method that
can be used to construct a union with that variant selected.
"""
for field in data_type.fields:
if not is_void_type(field.data_type):
field_name = fmt_func(field.name)
field_name_reserved_check = fmt_func(field.name, True)
if is_nullable_type(field.data_type):
field_dt = field.data_type.data_type
else:
field_dt = field.data_type
self.emit('@classmethod')
self.emit('def {}(cls, val):'.format(field_name_reserved_check))
with self.indent():
self.emit('"""')
self.emit_wrapped_text(
'Create an instance of this class set to the ``%s`` '
'tag with value ``val``.' % field_name)
self.emit()
self.emit(':param {} val:'.format(
self._python_type_mapping(ns, field_dt)))
self.emit(':rtype: {}'.format(
fmt_class(data_type.name)))
self.emit('"""')
self.emit("return cls('{}', val)".format(field_name))
self.emit()
def _generate_union(self, union_type):
"""
Emits a JSDoc @typedef for a union type.
"""
union_name = fmt_type_name(union_type)
self._emit_jsdoc_header(union_type.doc)
self.emit(' * @typedef {Object} %s' % union_name)
variant_types = []
for variant in union_type.all_fields:
variant_types.append("'%s'" % variant.name)
variant_data_type, _, _ = unwrap(variant.data_type)
# Don't emit fields for void types.
if not is_void_type(variant_data_type):
variant_doc = ' - Available if .tag is %s.' % variant.name
if variant.doc:
variant_doc += ' ' + variant.doc
self.emit_wrapped_text(
'@property {%s} [%s]%s' % (
fmt_type(variant_data_type),
variant.name,
variant_doc,
),
prefix=' * ',
)
jsdoc_tag_union = fmt_jsdoc_union(variant_types)
self.emit(' * @property {%s} .tag - Tag identifying the union variant.' % jsdoc_tag_union)
self.emit(' */')
def _python_type_mapping(self, ns, data_type):
"""Map Stone data types to their most natural equivalent in Python
for documentation purposes."""
if is_string_type(data_type):
return 'str'
elif is_bytes_type(data_type):
return 'bytes'
elif is_boolean_type(data_type):
return 'bool'
elif is_float_type(data_type):
return 'float'
elif is_integer_type(data_type):
return 'long'
elif is_void_type(data_type):
return 'None'
elif is_timestamp_type(data_type):
return 'datetime.datetime'
elif is_alias(data_type):
return self._python_type_mapping(ns, data_type.data_type)
elif is_user_defined_type(data_type):
class_name = class_name_for_data_type(data_type)
if data_type.namespace.name != ns.name:
return '%s.%s_validator' % (
data_type.namespace.name, class_name)
else:
return class_name
elif is_list_type(data_type):
# PyCharm understands this description format for a list
return 'list of [{}]'.format(self._python_type_mapping(
ns, data_type.data_type))
elif is_nullable_type(data_type):
return 'Optional[{}]'.format(
self._python_type_mapping(ns, data_type.data_type))
else:
raise TypeError('Unknown data type %r' % data_type)
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 _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('public func {}'.format(func_name),
args=self._func_args(arg_list, force_first=True),
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
self.emit('return client.request({})'.format(self._func_args(return_args, not_init=True)))
self.emit()
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)
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)
def map_stone_type_to_python_type(ns, data_type, override_dict=None):
# type: (ApiNamespace, DataType, typing.Optional[OverrideDefaultTypesDict]) -> str
"""
Args:
override_dict: lets you override the default behavior for a given type by hooking into
a callback. (Currently only hooked up for stone's List and Nullable)
"""
override_dict = override_dict or {}
if is_string_type(data_type):
return 'str'
elif is_bytes_type(data_type):
return 'bytes'
elif is_boolean_type(data_type):
return 'bool'
elif is_float_type(data_type):
return 'float'
elif is_integer_type(data_type):
return 'long'
elif is_void_type(data_type):
return 'None'
elif is_timestamp_type(data_type):
timestamp_override = override_dict.get(Timestamp, None)
if timestamp_override:
return timestamp_override(ns, data_type, override_dict)
return 'datetime.datetime'
elif is_alias(data_type):
alias_type = cast(Alias, data_type)
return map_stone_type_to_python_type(ns, alias_type.data_type,
override_dict)
elif is_user_defined_type(data_type):
user_defined_type = cast(UserDefined, data_type)
class_name = class_name_for_data_type(user_defined_type)
if user_defined_type.namespace.name != ns.name:
return '%s.%s_validator' % (user_defined_type.namespace.name,
class_name)
else:
return class_name
elif is_list_type(data_type):
list_type = cast(List, data_type)
if List in override_dict:
return override_dict[List](ns, list_type.data_type, override_dict)
# PyCharm understands this description format for a list
return 'list of [{}]'.format(
map_stone_type_to_python_type(ns, list_type.data_type,
override_dict))
elif is_nullable_type(data_type):
nullable_type = cast(Nullable, data_type)
if Nullable in override_dict:
return override_dict[Nullable](ns, nullable_type.data_type,
override_dict)
return 'Optional[{}]'.format(
map_stone_type_to_python_type(ns, nullable_type.data_type,
override_dict))
else:
raise TypeError('Unknown data type %r' % data_type)
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.replace(' _Nonnull',
'').replace(' _Nullable', '')))
transport_args.append((name, value))
route_result_type = fmt_type(
route.result_data_type,
tag=False) if not is_void_type(route.result_data_type) else ''
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_validator_constructor(ns, data_type):
"""
Given a Stone data type, returns a string that can be used to construct
the appropriate validation object in Python.
"""
dt, nullable_dt = unwrap_nullable(data_type)
if is_list_type(dt):
v = generate_func_call(
'bv.List',
args=[
generate_validator_constructor(ns, dt.data_type)],
kwargs=[
('min_items', dt.min_items),
('max_items', dt.max_items)],
)
elif is_numeric_type(dt):
v = generate_func_call(
'bv.{}'.format(dt.name),
kwargs=[
('min_value', dt.min_value),
('max_value', dt.max_value)],
)
elif is_string_type(dt):
pattern = None
if dt.pattern is not None:
pattern = repr(dt.pattern)
v = generate_func_call(
'bv.String',
kwargs=[
('min_length', dt.min_length),
('max_length', dt.max_length),
('pattern', pattern)],
)
elif is_timestamp_type(dt):
v = generate_func_call(
'bv.Timestamp',
args=[repr(dt.format)],
)
elif is_user_defined_type(dt):
v = fmt_class(dt.name) + '_validator'
if ns.name != dt.namespace.name:
v = '{}.{}'.format(dt.namespace.name, v)
elif is_alias(dt):
# Assume that the alias has already been declared elsewhere.
name = fmt_class(dt.name) + '_validator'
if ns.name != dt.namespace.name:
name = '{}.{}'.format(dt.namespace.name, name)
v = name
elif is_boolean_type(dt) or is_bytes_type(dt) or is_void_type(dt):
v = generate_func_call('bv.{}'.format(dt.name))
else:
raise AssertionError('Unsupported data type: %r' % dt)
if nullable_dt:
return generate_func_call('bv.Nullable', args=[v])
else:
return v
def _generate_route_signature(self, namespace, route):
req = fmt_type(route.arg_data_type, namespace)
res = fmt_type(route.result_data_type, namespace, use_interface=True)
fn = fmt_var(route.name)
style = route.attrs.get('style', 'rpc')
arg = '' if is_void_type(route.arg_data_type) else 'arg {req}'
ret = '(err error)' if is_void_type(route.result_data_type) else \
'(res {res}, err error)'
signature = '{fn}(' + arg + ') ' + ret
if style == 'download':
signature = '{fn}(' + arg + \
') (res {res}, content io.ReadCloser, err error)'
elif style == 'upload':
signature = '{fn}(' + arg + ', content io.Reader) ' + ret
if is_void_type(route.arg_data_type):
signature = '{fn}(content io.Reader) ' + ret
return signature.format(fn=fn, req=req, res=res)
def _generate_route_signature(self, namespace, route):
req = fmt_type(route.arg_data_type, namespace)
res = fmt_type(route.result_data_type, namespace, use_interface=True)
fn = fmt_var(route.name)
style = route.attrs.get('style', 'rpc')
arg = '' if is_void_type(route.arg_data_type) else 'arg {req}'
ret = '(err error)' if is_void_type(route.result_data_type) else \
'(res {res}, err error)'
signature = '{fn}(' + arg + ') ' + ret
if style == 'download':
signature = '{fn}(' + arg + \
') (res {res}, content io.ReadCloser, err error)'
elif style == 'upload':
signature = '{fn}(' + arg + ', content io.Reader) ' + ret
if is_void_type(route.arg_data_type):
signature = '{fn}(content io.Reader) ' + ret
return signature.format(fn=fn, req=req, res=res)
def generate_validator_constructor(ns, data_type):
"""
Given a Stone data type, returns a string that can be used to construct
the appropriate validation object in Python.
"""
dt, nullable_dt = unwrap_nullable(data_type)
if is_list_type(dt):
v = generate_func_call(
'bv.List',
args=[
generate_validator_constructor(ns, dt.data_type)],
kwargs=[
('min_items', dt.min_items),
('max_items', dt.max_items)],
)
elif is_numeric_type(dt):
v = generate_func_call(
'bv.{}'.format(dt.name),
kwargs=[
('min_value', dt.min_value),
('max_value', dt.max_value)],
)
elif is_string_type(dt):
pattern = None
if dt.pattern is not None:
pattern = repr(dt.pattern)
v = generate_func_call(
'bv.String',
kwargs=[
('min_length', dt.min_length),
('max_length', dt.max_length),
('pattern', pattern)],
)
elif is_timestamp_type(dt):
v = generate_func_call(
'bv.Timestamp',
args=[repr(dt.format)],
)
elif is_user_defined_type(dt):
v = fmt_class(dt.name) + '_validator'
if ns.name != dt.namespace.name:
v = '{}.{}'.format(dt.namespace.name, v)
elif is_alias(dt):
# Assume that the alias has already been declared elsewhere.
name = fmt_class(dt.name) + '_validator'
if ns.name != dt.namespace.name:
name = '{}.{}'.format(dt.namespace.name, name)
v = name
elif is_boolean_type(dt) or is_bytes_type(dt) or is_void_type(dt):
v = generate_func_call('bv.{}'.format(dt.name))
else:
raise AssertionError('Unsupported data type: %r' % dt)
if nullable_dt:
return generate_func_call('bv.Nullable', args=[v])
else:
return v
def _get_route_args(self, namespace, route):
arg_type = self._swift_type_mapping(route.arg_data_type)
if is_struct_type(route.arg_data_type):
arg_list = self._struct_init_args(route.arg_data_type, namespace=namespace)
doc_list = [(fmt_var(f.name), self.process_doc(f.doc, self._docf))
for f in route.arg_data_type.fields if f.doc]
else:
arg_list = [] if is_void_type(route.arg_data_type) else [('request', arg_type)]
doc_list = []
return arg_list, doc_list
def _format_type_in_doc(self, namespace, data_type):
"""
Returns a string that can be recognized by Sphinx as a type reference
in a docstring.
"""
if is_void_type(data_type):
return 'None'
elif is_user_defined_type(data_type):
return ':class:`{}.{}.{}`'.format(
self.args.types_package, namespace.name, fmt_type(data_type))
else:
return fmt_type(data_type)
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_union_class_symbol_creators(self, data_type):
"""
Class attributes that represent a symbol are set after the union class
definition.
"""
class_name = fmt_class(data_type.name)
lineno = self.lineno
for field in data_type.fields:
if is_void_type(field.data_type):
field_name = fmt_func(field.name)
self.emit("{0}.{1} = {0}('{1}')".format(class_name, field_name))
if lineno != self.lineno:
self.emit()
def _generate_union_class_symbol_creators(self, data_type):
"""
Class attributes that represent a symbol are set after the union class
definition.
"""
class_name = fmt_class(data_type.name)
lineno = self.lineno
for field in data_type.fields:
if is_void_type(field.data_type):
field_name = fmt_func(field.name)
self.emit("{0}.{1} = {0}('{1}')".format(class_name, field_name))
if lineno != self.lineno:
self.emit()
def _format_type_in_doc(self, namespace, data_type):
"""
Returns a string that can be recognized by Sphinx as a type reference
in a docstring.
"""
if is_void_type(data_type):
return 'None'
elif is_user_defined_type(data_type):
return ':class:`{}.{}.{}`'.format(self.args.types_package,
namespace.name,
fmt_type(data_type))
else:
return fmt_type(data_type)
def _generate_union_class(self, ns, data_type):
# type: (ApiNamespace, Union) -> None
"""Defines a Python class that represents a union in Stone."""
self.emit(self._class_declaration_for_type(ns, data_type))
with self.indent():
self.emit('"""')
if data_type.doc:
self.emit_wrapped_text(
self.process_doc(data_type.doc, self._docf))
self.emit()
self.emit_wrapped_text(
'This class acts as a tagged union. Only one of the ``is_*`` '
'methods will return true. To get the associated value of a '
'tag (if one exists), use the corresponding ``get_*`` method.')
if data_type.has_documented_fields():
self.emit()
for field in data_type.fields:
if not field.doc:
continue
if is_void_type(field.data_type):
ivar_doc = ':ivar {}: {}'.format(
fmt_var(field.name),
self.process_doc(field.doc, self._docf))
elif is_user_defined_type(field.data_type):
ivar_doc = ':ivar {} {}: {}'.format(
fmt_class(field.data_type.name),
fmt_var(field.name),
self.process_doc(field.doc, self._docf))
else:
ivar_doc = ':ivar {} {}: {}'.format(
self._python_type_mapping(ns, field.data_type),
fmt_var(field.name), field.doc)
self.emit_wrapped_text(ivar_doc, subsequent_prefix=' ')
self.emit('"""')
self.emit()
self._generate_union_class_vars(data_type)
self._generate_union_class_variant_creators(ns, data_type)
self._generate_union_class_is_set(data_type)
self._generate_union_class_get_helpers(ns, data_type)
self._generate_union_class_repr(data_type)
self.emit('{0}_validator = bv.Union({0})'.format(
class_name_for_data_type(data_type)
))
self.emit()
def _generate_union_class(self, ns, data_type):
# type: (ApiNamespace, Union) -> None
"""Defines a Python class that represents a union in Stone."""
self.emit(self._class_declaration_for_type(ns, data_type))
with self.indent():
self.emit('"""')
if data_type.doc:
self.emit_wrapped_text(
self.process_doc(data_type.doc, self._docf))
self.emit()
self.emit_wrapped_text(
'This class acts as a tagged union. Only one of the ``is_*`` '
'methods will return true. To get the associated value of a '
'tag (if one exists), use the corresponding ``get_*`` method.')
if data_type.has_documented_fields():
self.emit()
for field in data_type.fields:
if not field.doc:
continue
if is_void_type(field.data_type):
ivar_doc = ':ivar {}: {}'.format(
fmt_var(field.name),
self.process_doc(field.doc, self._docf))
elif is_user_defined_type(field.data_type):
ivar_doc = ':ivar {} {}: {}'.format(
fmt_class(field.data_type.name),
fmt_var(field.name),
self.process_doc(field.doc, self._docf))
else:
ivar_doc = ':ivar {} {}: {}'.format(
self._python_type_mapping(ns, field.data_type),
fmt_var(field.name), field.doc)
self.emit_wrapped_text(ivar_doc, subsequent_prefix=' ')
self.emit('"""')
self.emit()
self._generate_union_class_vars(data_type)
self._generate_union_class_variant_creators(ns, data_type)
self._generate_union_class_is_set(data_type)
self._generate_union_class_get_helpers(ns, data_type)
self._generate_union_class_repr(data_type)
self.emit('{0}_validator = bv.Union({0})'.format(
class_name_for_data_type(data_type)
))
self.emit()
def _generate_union_class_vars(self, ns, data_type):
# type: (ApiNamespace, Union) -> None
lineno = self.lineno
# Generate stubs for class variables so that IDEs like PyCharms have an
# easier time detecting their existence.
for field in data_type.fields:
if is_void_type(field.data_type):
field_name = fmt_var(field.name)
field_type = class_name_for_data_type(data_type, ns)
self.emit('{field_name} = ... # type: {field_type}'.format(
field_name=field_name,
field_type=field_type,
))
if lineno != self.lineno:
self.emit()
def _swift_type_mapping(self, data_type, serializer=False):
suffix = 'Serializer' if serializer else ''
if is_nullable_type(data_type):
data_type = data_type.data_type
nullable = True
else:
nullable = False
if is_list_type(data_type):
ret = 'Array{}<{}>'.format(
suffix,
self._swift_type_mapping(data_type.data_type, serializer)
)
suffix = ''
elif is_string_type(data_type):
ret = 'String'
elif is_timestamp_type(data_type):
ret = 'NSDate'
elif is_boolean_type(data_type):
ret = 'Bool'
elif is_bytes_type(data_type):
ret = 'NSData'
elif is_void_type(data_type):
ret = 'Void'
elif isinstance(data_type, Int32):
ret = 'Int32'
elif isinstance(data_type, Int64):
ret = 'Int64'
elif isinstance(data_type, UInt32):
ret = 'UInt32'
elif isinstance(data_type, UInt64):
ret = 'UInt64'
elif isinstance(data_type, Float32):
ret = 'Float'
elif isinstance(data_type, Float64):
ret = 'Double'
elif is_user_defined_type(data_type):
ret = '{}.{}'.format(fmt_class(data_type.namespace.name),
self.class_data_type(data_type))
ret += suffix
if nullable:
if serializer:
ret = 'NullableSerializer<{}>'.format(ret)
else:
ret += '?'
return ret
def _generate_union_class_vars(self, ns, data_type):
# type: (ApiNamespace, Union) -> None
lineno = self.lineno
# Generate stubs for class variables so that IDEs like PyCharms have an
# easier time detecting their existence.
for field in data_type.fields:
if is_void_type(field.data_type):
field_name = fmt_var(field.name)
field_type = class_name_for_data_type(data_type, ns)
self.emit('{field_name} = ... # type: {field_type}'.format(
field_name=field_name,
field_type=field_type,
))
if lineno != self.lineno:
self.emit()
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 _generate_union_class_get_helpers(self, ns, data_type):
# type: (ApiNamespace, Union) -> None
"""
Generates the following section in the 'union Shape' example:
def get_circle(self) -> float: ...
"""
for field in data_type.fields:
field_name = fmt_func(field.name)
if not is_void_type(field.data_type):
# generate getter for field
val_type = self.map_stone_type_to_pep484_type(ns, field.data_type)
self.emit('def get_{field_name}(self) -> {val_type}: ...'.format(
field_name=field_name,
val_type=val_type,
))
self.emit()
def _generate_result(self, route):
out = self.emit
if is_struct_type(route.result_data_type) and \
route.result_data_type.has_enumerated_subtypes():
out('var tmp %sUnion' % fmt_var(route.result_data_type.name, export=False))
with self.block('err = json.Unmarshal(body, &tmp);'
'if err != nil'):
out('return')
with self.block('switch tmp.Tag'):
for t in route.result_data_type.get_enumerated_subtypes():
with self.block('case "%s":' % t.name, delim=(None, None)):
self.emit('res = tmp.%s' % fmt_var(t.name))
elif not is_void_type(route.result_data_type):
with self.block('err = json.Unmarshal(body, &res);'
'if err != nil'):
out('return')
out()
out('return')
def _generate_method(self, namespace, route):
"""Generate a method declaration for a Stone route"""
if route.doc:
self._emit_docstring(route.doc)
method_name = route_method_name(namespace.name, route.name)
if data_type.is_void_type(route.arg_data_type):
arg_str = ''
else:
arg_str = 'arg: {}'.format(format_type(route.arg_data_type))
# Methods in Stone are parameterized by (arg type, return type, error
# type) The TypeScript `Promise` type however is only parameterized by
# one type, so although we generate interface definitions for the error
# types, they are not used to parameterize the result here.
self.emit('{}({}): Promise<{}>;'.format(
method_name, arg_str, format_type(route.result_data_type)))
def _generate_result(self, route):
out = self.emit
if is_struct_type(route.result_data_type) and \
route.result_data_type.has_enumerated_subtypes():
out('var tmp %sUnion' %
fmt_var(route.result_data_type.name, export=False))
with self.block('err = json.Unmarshal(body, &tmp);'
'if err != nil'):
out('return')
with self.block('switch tmp.Tag'):
for t in route.result_data_type.get_enumerated_subtypes():
with self.block('case "%s":' % t.name, delim=(None, None)):
self.emit('res = tmp.%s' % fmt_var(t.name))
elif not is_void_type(route.result_data_type):
with self.block('err = json.Unmarshal(body, &res);'
'if err != nil'):
out('return')
out()
out('return')
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 fmt_route_type(data_type, tag=False, has_default=False):
data_type, nullable = unwrap_nullable(data_type)
if is_user_defined_type(data_type):
result = '{} *'.format(fmt_class_prefix(data_type))
else:
result = _primitive_table_user_interface.get(
data_type.__class__, fmt_class(data_type.name))
if is_list_type(data_type):
data_type, _ = unwrap_nullable(data_type.data_type)
result = result + '<{}> *'.format(fmt_type(data_type))
if is_user_defined_type(data_type) and tag:
if nullable or has_default:
result += ' _Nullable'
elif not is_void_type(data_type):
result += ' _Nonnull'
return result
def fmt_route_type(data_type, tag=False, has_default=False):
data_type, nullable = unwrap_nullable(data_type)
if is_user_defined_type(data_type):
result = '{} *'.format(fmt_class_prefix(data_type))
else:
result = _primitive_table_user_interface.get(data_type.__class__,
fmt_class(data_type.name))
if is_list_type(data_type):
data_type, _ = unwrap_nullable(data_type.data_type)
result = result + '<{}> *'.format(fmt_type(data_type))
if is_user_defined_type(data_type) and tag:
if nullable or has_default:
result += ' _Nullable'
elif not is_void_type(data_type):
result += ' _Nonnull'
return result
def _generate_union_class_vars(self, data_type):
"""
Adds a _catch_all_ attribute to each class. Also, adds a placeholder
attribute for the construction of union members of void type.
"""
lineno = self.lineno
if data_type.catch_all_field:
self.emit("_catch_all = '%s'" % data_type.catch_all_field.name)
elif not data_type.parent_type:
self.emit('_catch_all = None')
# Generate stubs for class variables so that IDEs like PyCharms have an
# easier time detecting their existence.
for field in data_type.fields:
if is_void_type(field.data_type):
field_name = fmt_var(field.name)
self.emit('# Attribute is overwritten below the class definition')
self.emit('{} = None'.format(field_name))
if lineno != self.lineno:
self.emit()
def _generate_union_class_vars(self, data_type):
"""
Adds a _catch_all_ attribute to each class. Also, adds a placeholder
attribute for the construction of union members of void type.
"""
lineno = self.lineno
if data_type.catch_all_field:
self.emit("_catch_all = '%s'" % data_type.catch_all_field.name)
elif not data_type.parent_type:
self.emit('_catch_all = None')
# Generate stubs for class variables so that IDEs like PyCharms have an
# easier time detecting their existence.
for field in data_type.fields:
if is_void_type(field.data_type):
field_name = fmt_var(field.name)
self.emit('# Attribute is overwritten below the class definition')
self.emit('{} = None'.format(field_name))
if lineno != self.lineno:
self.emit()
def _generate_union_class_variant_creators(self, ns, data_type):
# type: (ApiNamespace, Union) -> None
"""
Generate the following section in the 'union Shape' example:
@classmethod
def circle(cls, val: float) -> Shape: ...
"""
union_type = class_name_for_data_type(data_type)
for field in data_type.fields:
if not is_void_type(field.data_type):
field_name_reserved_check = fmt_func(field.name, True)
val_type = self.map_stone_type_to_pep484_type(ns, field.data_type)
self.emit('@classmethod')
self.emit('def {field_name}(cls, val: {val_type}) -> {union_type}: ...'.format(
field_name=field_name_reserved_check,
val_type=val_type,
union_type=union_type,
))
self.emit()
def fmt_type(data_type, tag=False, has_default=False, no_ptr=False):
data_type, nullable = unwrap_nullable(data_type)
if is_user_defined_type(data_type):
base = '{}' if no_ptr else '{} *'
result = base.format(fmt_class_prefix(data_type))
else:
result = _primitive_table.get(data_type.__class__,
fmt_class(data_type.name))
if is_list_type(data_type):
data_type, _ = unwrap_nullable(data_type.data_type)
base = '<{}>' if no_ptr else '<{}> *'
result = result + base.format(fmt_type(data_type))
if tag:
if nullable or has_default:
result += ' _Nullable'
elif not is_void_type(data_type):
result += ' _Nonnull'
return result
def _serializer_obj(self, data_type):
if is_nullable_type(data_type):
data_type = data_type.data_type
nullable = True
else:
nullable = False
if is_list_type(data_type):
ret = 'ArraySerializer({})'.format(
self._serializer_obj(data_type.data_type))
elif is_string_type(data_type):
ret = 'Serialization._StringSerializer'
elif is_timestamp_type(data_type):
ret = 'NSDateSerializer("{}")'.format(data_type.format)
elif is_boolean_type(data_type):
ret = 'Serialization._BoolSerializer'
elif is_bytes_type(data_type):
ret = 'Serialization._NSDataSerializer'
elif is_void_type(data_type):
ret = 'Serialization._VoidSerializer'
elif isinstance(data_type, Int32):
ret = 'Serialization._Int32Serializer'
elif isinstance(data_type, Int64):
ret = 'Serialization._Int64Serializer'
elif isinstance(data_type, UInt32):
ret = 'Serialization._UInt32Serializer'
elif isinstance(data_type, UInt64):
ret = 'Serialization._UInt64Serializer'
elif isinstance(data_type, Float32):
ret = 'Serialization._FloatSerializer'
elif isinstance(data_type, Float64):
ret = 'Serialization._DoubleSerializer'
elif is_user_defined_type(data_type):
ret = "{}.{}Serializer()".format(fmt_class(data_type.namespace.name),
self.class_data_type(data_type))
if nullable:
ret = 'NullableSerializer({})'.format(ret)
return ret
def fmt_type(data_type, tag=False, has_default=False, no_ptr=False):
data_type, nullable = unwrap_nullable(data_type)
if is_user_defined_type(data_type):
base = '{}' if no_ptr else '{} *'
result = base.format(fmt_class_prefix(data_type))
else:
result = _primitive_table.get(
data_type.__class__, fmt_class(data_type.name))
if is_list_type(data_type):
data_type, _ = unwrap_nullable(data_type.data_type)
base = '<{}>' if no_ptr else '<{}> *'
result = result + base.format(fmt_type(data_type))
if tag:
if nullable or has_default:
result += ' _Nullable'
elif not is_void_type(data_type):
result += ' _Nonnull'
return result
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 _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 _generate_union_class_get_helpers(self, ns, data_type):
"""
These are the getters used to access the value of a variant, once
the tag has been switched on.
"""
for field in data_type.fields:
field_name = fmt_func(field.name)
if not is_void_type(field.data_type):
# generate getter for field
self.emit('def get_{}(self):'.format(field_name))
with self.indent():
if is_nullable_type(field.data_type):
field_dt = field.data_type.data_type
else:
field_dt = field.data_type
self.emit('"""')
if field.doc:
self.emit_wrapped_text(
self.process_doc(field.doc, self._docf))
self.emit()
self.emit("Only call this if :meth:`is_%s` is true." %
field_name)
# Sphinx wants an extra line between the text and the
# rtype declaration.
self.emit()
self.emit(':rtype: {}'.format(
self._python_type_mapping(ns, field_dt)))
self.emit('"""')
self.emit('if not self.is_{}():'.format(field_name))
with self.indent():
self.emit(
'raise AttributeError("tag \'{}\' not set")'.format(
field_name))
self.emit('return self._value')
self.emit()
def _generate_union_helper(self, u):
name = u.name
namespace = u.namespace
fields = u.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 _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:`dropbox.exceptions.ApiError`')
self.emit()
# To provide more clarity to a dev who reads the docstring, state
# the error class that will be returned in the reason field of an
# ApiError object.
self.emit('If this raises, ApiError.reason is of type:')
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('"""')
