Python code coverage for Lib/pyclbr.py

#	count	content
1	n/a	"""Parse a Python module and describe its classes and methods.
2	n/a
3	n/a	Parse enough of a Python file to recognize imports and class and
4	n/a	method definitions, and to find out the superclasses of a class.
5	n/a
6	n/a	The interface consists of a single function:
7	n/a	readmodule_ex(module [, path])
8	n/a	where module is the name of a Python module, and path is an optional
9	n/a	list of directories where the module is to be searched. If present,
10	n/a	path is prepended to the system search path sys.path. The return
11	n/a	value is a dictionary. The keys of the dictionary are the names of
12	n/a	the classes defined in the module (including classes that are defined
13	n/a	via the from XXX import YYY construct). The values are class
14	n/a	instances of the class Class defined here. One special key/value pair
15	n/a	is present for packages: the key '__path__' has a list as its value
16	n/a	which contains the package search path.
17	n/a
18	n/a	A class is described by the class Class in this module. Instances
19	n/a	of this class have the following instance variables:
20	n/a	module -- the module name
21	n/a	name -- the name of the class
22	n/a	super -- a list of super classes (Class instances)
23	n/a	methods -- a dictionary of methods
24	n/a	file -- the file in which the class was defined
25	n/a	lineno -- the line in the file on which the class statement occurred
26	n/a	The dictionary of methods uses the method names as keys and the line
27	n/a	numbers on which the method was defined as values.
28	n/a	If the name of a super class is not recognized, the corresponding
29	n/a	entry in the list of super classes is not a class instance but a
30	n/a	string giving the name of the super class. Since import statements
31	n/a	are recognized and imported modules are scanned as well, this
32	n/a	shouldn't happen often.
33	n/a
34	n/a	A function is described by the class Function in this module.
35	n/a	Instances of this class have the following instance variables:
36	n/a	module -- the module name
37	n/a	name -- the name of the class
38	n/a	file -- the file in which the class was defined
39	n/a	lineno -- the line in the file on which the class statement occurred
40	n/a	"""
41	n/a
42	n/a	import io
43	n/a	import sys
44	n/a	import importlib.util
45	n/a	import tokenize
46	n/a	from token import NAME, DEDENT, OP
47	n/a
48	n/a	__all__ = ["readmodule", "readmodule_ex", "Class", "Function"]
49	n/a
50	n/a	_modules = {} # cache of modules we've seen
51	n/a
52	n/a	# each Python class is represented by an instance of this class
53	n/a	class Class:
54	n/a	'''Class to represent a Python class.'''
55	n/a	def __init__(self, module, name, super, file, lineno):
56	n/a	self.module = module
57	n/a	self.name = name
58	n/a	if super is None:
59	n/a	super = []
60	n/a	self.super = super
61	n/a	self.methods = {}
62	n/a	self.file = file
63	n/a	self.lineno = lineno
64	n/a
65	n/a	def _addmethod(self, name, lineno):
66	n/a	self.methods[name] = lineno
67	n/a
68	n/a	class Function:
69	n/a	'''Class to represent a top-level Python function'''
70	n/a	def __init__(self, module, name, file, lineno):
71	n/a	self.module = module
72	n/a	self.name = name
73	n/a	self.file = file
74	n/a	self.lineno = lineno
75	n/a
76	n/a	def readmodule(module, path=None):
77	n/a	'''Backwards compatible interface.
78	n/a
79	n/a	Call readmodule_ex() and then only keep Class objects from the
80	n/a	resulting dictionary.'''
81	n/a
82	n/a	res = {}
83	n/a	for key, value in _readmodule(module, path or []).items():
84	n/a	if isinstance(value, Class):
85	n/a	res[key] = value
86	n/a	return res
87	n/a
88	n/a	def readmodule_ex(module, path=None):
89	n/a	'''Read a module file and return a dictionary of classes.
90	n/a
91	n/a	Search for MODULE in PATH and sys.path, read and parse the
92	n/a	module and return a dictionary with one entry for each class
93	n/a	found in the module.
94	n/a	'''
95	n/a	return _readmodule(module, path or [])
96	n/a
97	n/a	def _readmodule(module, path, inpackage=None):
98	n/a	'''Do the hard work for readmodule[_ex].
99	n/a
100	n/a	If INPACKAGE is given, it must be the dotted name of the package in
101	n/a	which we are searching for a submodule, and then PATH must be the
102	n/a	package search path; otherwise, we are searching for a top-level
103	n/a	module, and PATH is combined with sys.path.
104	n/a	'''
105	n/a	# Compute the full module name (prepending inpackage if set)
106	n/a	if inpackage is not None:
107	n/a	fullmodule = "%s.%s" % (inpackage, module)
108	n/a	else:
109	n/a	fullmodule = module
110	n/a
111	n/a	# Check in the cache
112	n/a	if fullmodule in _modules:
113	n/a	return _modules[fullmodule]
114	n/a
115	n/a	# Initialize the dict for this module's contents
116	n/a	dict = {}
117	n/a
118	n/a	# Check if it is a built-in module; we don't do much for these
119	n/a	if module in sys.builtin_module_names and inpackage is None:
120	n/a	_modules[module] = dict
121	n/a	return dict
122	n/a
123	n/a	# Check for a dotted module name
124	n/a	i = module.rfind('.')
125	n/a	if i >= 0:
126	n/a	package = module[:i]
127	n/a	submodule = module[i+1:]
128	n/a	parent = _readmodule(package, path, inpackage)
129	n/a	if inpackage is not None:
130	n/a	package = "%s.%s" % (inpackage, package)
131	n/a	if not '__path__' in parent:
132	n/a	raise ImportError('No package named {}'.format(package))
133	n/a	return _readmodule(submodule, parent['__path__'], package)
134	n/a
135	n/a	# Search the path for the module
136	n/a	f = None
137	n/a	if inpackage is not None:
138	n/a	search_path = path
139	n/a	else:
140	n/a	search_path = path + sys.path
141	n/a	# XXX This will change once issue19944 lands.
142	n/a	spec = importlib.util._find_spec_from_path(fullmodule, search_path)
143	n/a	_modules[fullmodule] = dict
144	n/a	# is module a package?
145	n/a	if spec.submodule_search_locations is not None:
146	n/a	dict['__path__'] = spec.submodule_search_locations
147	n/a	try:
148	n/a	source = spec.loader.get_source(fullmodule)
149	n/a	if source is None:
150	n/a	return dict
151	n/a	except (AttributeError, ImportError):
152	n/a	# not Python source, can't do anything with this module
153	n/a	return dict
154	n/a
155	n/a	fname = spec.loader.get_filename(fullmodule)
156	n/a
157	n/a	f = io.StringIO(source)
158	n/a
159	n/a	stack = [] # stack of (class, indent) pairs
160	n/a
161	n/a	g = tokenize.generate_tokens(f.readline)
162	n/a	try:
163	n/a	for tokentype, token, start, _end, _line in g:
164	n/a	if tokentype == DEDENT:
165	n/a	lineno, thisindent = start
166	n/a	# close nested classes and defs
167	n/a	while stack and stack[-1][1] >= thisindent:
168	n/a	del stack[-1]
169	n/a	elif token == 'def':
170	n/a	lineno, thisindent = start
171	n/a	# close previous nested classes and defs
172	n/a	while stack and stack[-1][1] >= thisindent:
173	n/a	del stack[-1]
174	n/a	tokentype, meth_name, start = next(g)[0:3]
175	n/a	if tokentype != NAME:
176	n/a	continue # Syntax error
177	n/a	if stack:
178	n/a	cur_class = stack[-1][0]
179	n/a	if isinstance(cur_class, Class):
180	n/a	# it's a method
181	n/a	cur_class._addmethod(meth_name, lineno)
182	n/a	# else it's a nested def
183	n/a	else:
184	n/a	# it's a function
185	n/a	dict[meth_name] = Function(fullmodule, meth_name,
186	n/a	fname, lineno)
187	n/a	stack.append((None, thisindent)) # Marker for nested fns
188	n/a	elif token == 'class':
189	n/a	lineno, thisindent = start
190	n/a	# close previous nested classes and defs
191	n/a	while stack and stack[-1][1] >= thisindent:
192	n/a	del stack[-1]
193	n/a	tokentype, class_name, start = next(g)[0:3]
194	n/a	if tokentype != NAME:
195	n/a	continue # Syntax error
196	n/a	# parse what follows the class name
197	n/a	tokentype, token, start = next(g)[0:3]
198	n/a	inherit = None
199	n/a	if token == '(':
200	n/a	names = [] # List of superclasses
201	n/a	# there's a list of superclasses
202	n/a	level = 1
203	n/a	super = [] # Tokens making up current superclass
204	n/a	while True:
205	n/a	tokentype, token, start = next(g)[0:3]
206	n/a	if token in (')', ',') and level == 1:
207	n/a	n = "".join(super)
208	n/a	if n in dict:
209	n/a	# we know this super class
210	n/a	n = dict[n]
211	n/a	else:
212	n/a	c = n.split('.')
213	n/a	if len(c) > 1:
214	n/a	# super class is of the form
215	n/a	# module.class: look in module for
216	n/a	# class
217	n/a	m = c[-2]
218	n/a	c = c[-1]
219	n/a	if m in _modules:
220	n/a	d = _modules[m]
221	n/a	if c in d:
222	n/a	n = d[c]
223	n/a	names.append(n)
224	n/a	super = []
225	n/a	if token == '(':
226	n/a	level += 1
227	n/a	elif token == ')':
228	n/a	level -= 1
229	n/a	if level == 0:
230	n/a	break
231	n/a	elif token == ',' and level == 1:
232	n/a	pass
233	n/a	# only use NAME and OP (== dot) tokens for type name
234	n/a	elif tokentype in (NAME, OP) and level == 1:
235	n/a	super.append(token)
236	n/a	# expressions in the base list are not supported
237	n/a	inherit = names
238	n/a	cur_class = Class(fullmodule, class_name, inherit,
239	n/a	fname, lineno)
240	n/a	if not stack:
241	n/a	dict[class_name] = cur_class
242	n/a	stack.append((cur_class, thisindent))
243	n/a	elif token == 'import' and start[1] == 0:
244	n/a	modules = _getnamelist(g)
245	n/a	for mod, _mod2 in modules:
246	n/a	try:
247	n/a	# Recursively read the imported module
248	n/a	if inpackage is None:
249	n/a	_readmodule(mod, path)
250	n/a	else:
251	n/a	try:
252	n/a	_readmodule(mod, path, inpackage)
253	n/a	except ImportError:
254	n/a	_readmodule(mod, [])
255	n/a	except:
256	n/a	# If we can't find or parse the imported module,
257	n/a	# too bad -- don't die here.
258	n/a	pass
259	n/a	elif token == 'from' and start[1] == 0:
260	n/a	mod, token = _getname(g)
261	n/a	if not mod or token != "import":
262	n/a	continue
263	n/a	names = _getnamelist(g)
264	n/a	try:
265	n/a	# Recursively read the imported module
266	n/a	d = _readmodule(mod, path, inpackage)
267	n/a	except:
268	n/a	# If we can't find or parse the imported module,
269	n/a	# too bad -- don't die here.
270	n/a	continue
271	n/a	# add any classes that were defined in the imported module
272	n/a	# to our name space if they were mentioned in the list
273	n/a	for n, n2 in names:
274	n/a	if n in d:
275	n/a	dict[n2 or n] = d[n]
276	n/a	elif n == '*':
277	n/a	# don't add names that start with _
278	n/a	for n in d:
279	n/a	if n[0] != '_':
280	n/a	dict[n] = d[n]
281	n/a	except StopIteration:
282	n/a	pass
283	n/a
284	n/a	f.close()
285	n/a	return dict
286	n/a
287	n/a	def _getnamelist(g):
288	n/a	# Helper to get a comma-separated list of dotted names plus 'as'
289	n/a	# clauses. Return a list of pairs (name, name2) where name2 is
290	n/a	# the 'as' name, or None if there is no 'as' clause.
291	n/a	names = []
292	n/a	while True:
293	n/a	name, token = _getname(g)
294	n/a	if not name:
295	n/a	break
296	n/a	if token == 'as':
297	n/a	name2, token = _getname(g)
298	n/a	else:
299	n/a	name2 = None
300	n/a	names.append((name, name2))
301	n/a	while token != "," and "\n" not in token:
302	n/a	token = next(g)[1]
303	n/a	if token != ",":
304	n/a	break
305	n/a	return names
306	n/a
307	n/a	def _getname(g):
308	n/a	# Helper to get a dotted name, return a pair (name, token) where
309	n/a	# name is the dotted name, or None if there was no dotted name,
310	n/a	# and token is the next input token.
311	n/a	parts = []
312	n/a	tokentype, token = next(g)[0:2]
313	n/a	if tokentype != NAME and token != '*':
314	n/a	return (None, token)
315	n/a	parts.append(token)
316	n/a	while True:
317	n/a	tokentype, token = next(g)[0:2]
318	n/a	if token != '.':
319	n/a	break
320	n/a	tokentype, token = next(g)[0:2]
321	n/a	if tokentype != NAME:
322	n/a	break
323	n/a	parts.append(token)
324	n/a	return (".".join(parts), token)
325	n/a
326	n/a	def _main():
327	n/a	# Main program for testing.
328	n/a	import os
329	n/a	from operator import itemgetter
330	n/a	mod = sys.argv[1]
331	n/a	if os.path.exists(mod):
332	n/a	path = [os.path.dirname(mod)]
333	n/a	mod = os.path.basename(mod)
334	n/a	if mod.lower().endswith(".py"):
335	n/a	mod = mod[:-3]
336	n/a	else:
337	n/a	path = []
338	n/a	dict = readmodule_ex(mod, path)
339	n/a	objs = list(dict.values())
340	n/a	objs.sort(key=lambda a: getattr(a, 'lineno', 0))
341	n/a	for obj in objs:
342	n/a	if isinstance(obj, Class):
343	n/a	print("class", obj.name, obj.super, obj.lineno)
344	n/a	methods = sorted(obj.methods.items(), key=itemgetter(1))
345	n/a	for name, lineno in methods:
346	n/a	if name != "__path__":
347	n/a	print(" def", name, lineno)
348	n/a	elif isinstance(obj, Function):
349	n/a	print("def", obj.name, obj.lineno)
350	n/a
351	n/a	if __name__ == "__main__":
352	n/a	_main()