Coverage for gi/docstring.py: 0%

# Coverage for gi/docstring.py : 0%

## 91 statements 0 run 91 missing 0 excluded

Hot-keys on this page

r m x p toggle line displays

j k next/prev highlighted chunk

0 (zero) top of page

1 (one) first highlighted chunk

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 | # -*- Mode: Python; py-indent-offset: 4 -*- # vim: tabstop=4 shiftwidth=4 expandtab # # Copyright (C) 2013 Simon Feltman <sfeltman@gnome.org> # # docstring.py: documentation string generator for gi. # # This library is free software; you can redistribute it and/or # modify it under the terms of the GNU Lesser General Public # License as published by the Free Software Foundation; either # version 2.1 of the License, or (at your option) any later version. # # This library is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU # Lesser General Public License for more details. # # You should have received a copy of the GNU Lesser General Public # License along with this library; if not, write to the Free Software # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 # USA from ._gi import \ VFuncInfo, \ FunctionInfo, \ CallableInfo, \ ObjectInfo, \ StructInfo, \ Direction, \ TypeTag #: Module storage for currently registered doc string generator function. _generate_doc_string_func = None def set_doc_string_generator(func): """Set doc string generator function :param callable func: Callable which takes a GIInfoStruct and returns documentation for it. """ global _generate_doc_string_func _generate_doc_string_func = func def get_doc_string_generator(): """Returns the currently registered doc string generator.""" return _generate_doc_string_func def generate_doc_string(info): """Generate a doc string given a GIInfoStruct. :param gi.types.BaseInfo info: GI info instance to generate documentation for. :returns: Generated documentation as a string. :rtype: str This passes the info struct to the currently registered doc string generator and returns the result. """ return _generate_doc_string_func(info) _type_tag_to_py_type = {TypeTag.BOOLEAN: bool, TypeTag.INT8: int, TypeTag.UINT8: int, TypeTag.INT16: int, TypeTag.UINT16: int, TypeTag.INT32: int, TypeTag.UINT32: int, TypeTag.INT64: int, TypeTag.UINT64: int, TypeTag.FLOAT: float, TypeTag.DOUBLE: float, TypeTag.GLIST: list, TypeTag.GSLIST: list, TypeTag.ARRAY: list, TypeTag.GHASH: dict, TypeTag.UTF8: str, TypeTag.FILENAME: str, TypeTag.UNICHAR: str, TypeTag.INTERFACE: None, TypeTag.GTYPE: None, TypeTag.ERROR: None, TypeTag.VOID: None, } def _get_pytype_hint(gi_type): type_tag = gi_type.get_tag() py_type = _type_tag_to_py_type.get(type_tag, None) if py_type and hasattr(py_type, '__name__'): return py_type.__name__ elif type_tag == TypeTag.INTERFACE: iface = gi_type.get_interface() info_name = iface.get_name() if not info_name: return gi_type.get_tag_as_string() return '%s.%s' % (iface.get_namespace(), info_name) return gi_type.get_tag_as_string() def _generate_callable_info_doc(info): in_args_strs = [] if isinstance(info, VFuncInfo): in_args_strs = ['self'] elif isinstance(info, FunctionInfo): if info.is_method(): in_args_strs = ['self'] args = info.get_arguments() hint_blacklist = ('void',) # Build lists of indices prior to adding the docs because it is possible # the index retrieved comes before input arguments being used. ignore_indices = set() user_data_indices = set() for arg in args: ignore_indices.add(arg.get_destroy()) ignore_indices.add(arg.get_type().get_array_length()) user_data_indices.add(arg.get_closure()) # Build input argument strings for i, arg in enumerate(args): if arg.get_direction() == Direction.OUT: continue # skip exclusively output args if i in ignore_indices: continue argstr = arg.get_name() hint = _get_pytype_hint(arg.get_type()) if hint not in hint_blacklist: argstr += ':' + hint if arg.may_be_null() or i in user_data_indices: # allow-none or user_data from a closure argstr += '=None' elif arg.is_optional(): argstr += '=<optional>' in_args_strs.append(argstr) in_args_str = ', '.join(in_args_strs) # Build return + output argument strings out_args_strs = [] return_hint = _get_pytype_hint(info.get_return_type()) if not info.skip_return() and return_hint and return_hint not in hint_blacklist: argstr = return_hint if info.may_return_null(): argstr += ' or None' out_args_strs.append(argstr) for i, arg in enumerate(args): if arg.get_direction() == Direction.IN: continue # skip exclusively input args if i in ignore_indices: continue argstr = arg.get_name() hint = _get_pytype_hint(arg.get_type()) if hint not in hint_blacklist: argstr += ':' + hint out_args_strs.append(argstr) if out_args_strs: return '%s(%s) -> %s' % (info.__name__, in_args_str, ', '.join(out_args_strs)) else: return '%s(%s)' % (info.__name__, in_args_str) def _generate_class_info_doc(info): header = '\n:Constructors:\n\n::\n\n' # start with \n to avoid auto indent of other lines doc = '' if isinstance(info, StructInfo): # Don't show default constructor for disguised (0 length) structs if info.get_size() > 0: doc += ' ' + info.get_name() + '()\n' else: doc += ' ' + info.get_name() + '(**properties)\n' for method_info in info.get_methods(): if method_info.is_constructor(): doc += ' ' + _generate_callable_info_doc(method_info) + '\n' if doc: return header + doc else: return '' def _generate_doc_dispatch(info): if isinstance(info, (ObjectInfo, StructInfo)): return _generate_class_info_doc(info) elif isinstance(info, CallableInfo): return _generate_callable_info_doc(info) return '' set_doc_string_generator(_generate_doc_dispatch)