/usr/lib/python2.7/dist-packages/gi/docstring.py is in python-gi 3.12.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | # -*- 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:
if info.may_return_null():
argstr += ' or None'
out_args_strs.append(return_hint)
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):
doc = '\n:Constructors:\n\n::\n\n' # start with \n to avoid auto indent of other lines
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'
return doc
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)
|