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
|
# -*- 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, \
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
:Parameters:
func : callable
Function which takes a GIInfoStruct and returns
documentation for it.
"""
global _generate_doc_string_func
_generate_doc_string_func = func
def get_doc_string_generator():
return _generate_doc_string_func
def generate_doc_string(info):
"""Generator a doc string given a GIInfoStruct
This passes the info struct to the currently registered doc string
generator and returns the result.
"""
return _generate_doc_string_func(info)
def split_function_info_args(info):
"""Split a functions args into a tuple of two lists.
Note that args marked as Direction.INOUT will be in both lists.
:Returns:
Tuple of (in_args, out_args)
"""
in_args = []
out_args = []
for arg in info.get_arguments():
direction = arg.get_direction()
if direction in (Direction.IN, Direction.INOUT):
in_args.append(arg)
if direction in (Direction.OUT, Direction.INOUT):
out_args.append(arg)
return (in_args, out_args)
_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_function_signature(info):
"""Default doc string generator"""
in_args, out_args = split_function_info_args(info)
in_args_strs = []
if isinstance(info, VFuncInfo):
in_args_strs = ['self']
elif isinstance(info, FunctionInfo):
if info.is_method():
in_args_strs = ['self']
elif info.is_constructor():
in_args_strs = ['cls']
hint_blacklist = ('void',)
# Build a lists of indices prior to adding the docs because
# because it is possible the index retrieved comes before in
# argument being used.
ignore_indices = set()
user_data_indices = set()
for arg in in_args:
ignore_indices.add(arg.get_destroy())
ignore_indices.add(arg.get_type().get_array_length())
user_data_indices.add(arg.get_closure())
for i, arg in enumerate(in_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)
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(out_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.get_name(), in_args_str, ', '.join(out_args_strs))
else:
return '%s(%s)' % (info.get_name(), in_args_str)
set_doc_string_generator(_generate_callable_info_function_signature)
|
