cpython/Lib/pyclbr.py at main · python/cpython · GitHub

Repository navigation

History

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

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

"""Parse a Python module and describe its classes and functions.

Parse enough of a Python file to recognize imports and class and

function definitions, and to find out the superclasses of a class.

The interface consists of a single function:

readmodule_ex(module, path=None)

where module is the name of a Python module, and path is an optional

list of directories where the module is to be searched. If present,

path is prepended to the system search path sys.path. The return value

is a dictionary. The keys of the dictionary are the names of the

classes and functions defined in the module (including classes that are

defined via the from XXX import YYY construct). The values are

instances of classes Class and Function. One special key/value pair is

present for packages: the key '__path__' has a list as its value which

contains the package search path.

Classes and Functions have a common superclass: _Object. Every instance

has the following attributes:

module -- name of the module;

name -- name of the object;

file -- file in which the object is defined;

lineno -- line in the file where the object's definition starts;

end_lineno -- line in the file where the object's definition ends;

parent -- parent of this object, if any;

children -- nested objects contained in this object.

The 'children' attribute is a dictionary mapping names to objects.

Instances of Function describe functions with the attributes from _Object,

plus the following:

is_async -- if a function is defined with an 'async' prefix

Instances of Class describe classes with the attributes from _Object,

plus the following:

super -- list of super classes (Class instances if possible);

methods -- mapping of method names to beginning line numbers.

If the name of a super class is not recognized, the corresponding

entry in the list of super classes is not a class instance but a

string giving the name of the super class. Since import statements

are recognized and imported modules are scanned as well, this

shouldn't happen often.

"""

import ast

import sys

import importlib.util

__all__ = ["readmodule", "readmodule_ex", "Class", "Function"]

_modules = {} # Initialize cache of modules we've seen.

class _Object:

"Information about Python class or function."

def __init__(self, module, name, file, lineno, end_lineno, parent):

self.module = module

self.name = name

self.file = file

self.lineno = lineno

self.end_lineno = end_lineno

self.parent = parent

self.children = {}

if parent is not None:

parent.children[name] = self

# Odd Function and Class signatures are for back-compatibility.

class Function(_Object):

"Information about a Python function, including methods."

def __init__(self, module, name, file, lineno,

parent=None, is_async=False, *, end_lineno=None):

super().__init__(module, name, file, lineno, end_lineno, parent)

self.is_async = is_async

if isinstance(parent, Class):

parent.methods[name] = lineno

class Class(_Object):

"Information about a Python class."

def __init__(self, module, name, super_, file, lineno,

parent=None, *, end_lineno=None):

super().__init__(module, name, file, lineno, end_lineno, parent)

self.super = super_ or []

self.methods = {}

# These 2 functions are used in these tests

# Lib/test/test_pyclbr, Lib/idlelib/idle_test/test_browser.py

def _nest_function(ob, func_name, lineno, end_lineno, is_async=False):

"Return a Function after nesting within ob."

return Function(ob.module, func_name, ob.file, lineno,

parent=ob, is_async=is_async, end_lineno=end_lineno)

def _nest_class(ob, class_name, lineno, end_lineno, super=None):

"Return a Class after nesting within ob."

return Class(ob.module, class_name, super, ob.file, lineno,

parent=ob, end_lineno=end_lineno)

def readmodule(module, path=None):

"""Return Class objects for the top-level classes in module.

This is the original interface, before Functions were added.

"""

res = {}

for key, value in _readmodule(module, path or []).items():

if isinstance(value, Class):

res[key] = value

return res

def readmodule_ex(module, path=None):

"""Return a dictionary with all functions and classes in module.

Search for module in PATH + sys.path.

If possible, include imported superclasses.

Do this by reading source, without importing (and executing) it.

"""

return _readmodule(module, path or [])

def _readmodule(module, path, inpackage=None):

"""Do the hard work for readmodule[_ex].

If inpackage is given, it must be the dotted name of the package in

which we are searching for a submodule, and then PATH must be the

package search path; otherwise, we are searching for a top-level

module, and path is combined with sys.path.

"""

# Compute the full module name (prepending inpackage if set).

if inpackage is not None:

fullmodule = "%s.%s" % (inpackage, module)

else:

fullmodule = module

# Check in the cache.

if fullmodule in _modules:

return _modules[fullmodule]

# Initialize the dict for this module's contents.

tree = {}

# Check if it is a built-in module; we don't do much for these.

if module in sys.builtin_module_names and inpackage is None:

_modules[module] = tree

return tree

# Check for a dotted module name.

i = module.rfind('.')

if i >= 0:

package = module[:i]

submodule = module[i+1:]

parent = _readmodule(package, path, inpackage)

if inpackage is not None:

package = "%s.%s" % (inpackage, package)

if not '__path__' in parent:

raise ImportError('No package named {}'.format(package))

return _readmodule(submodule, parent['__path__'], package)

# Search the path for the module.

if inpackage is not None:

search_path = path

else:

search_path = path + sys.path

spec = importlib.util._find_spec_from_path(fullmodule, search_path)

if spec is None:

raise ModuleNotFoundError(f"no module named {fullmodule!r}", name=fullmodule)

_modules[fullmodule] = tree

# Is module a package?

if spec.submodule_search_locations is not None:

tree['__path__'] = spec.submodule_search_locations

try:

source = spec.loader.get_source(fullmodule)

except (AttributeError, ImportError):

# If module is not Python source, we cannot do anything.

return tree

else:

if source is None:

return tree

fname = spec.loader.get_filename(fullmodule)

return _create_tree(fullmodule, path, fname, source, tree, inpackage)

class _ModuleBrowser(ast.NodeVisitor):

def __init__(self, module, path, file, tree, inpackage):

self.path = path

self.tree = tree

self.file = file

self.module = module

self.inpackage = inpackage

self.stack = []

def visit_ClassDef(self, node):

bases = []

for base in node.bases:

name = ast.unparse(base)

if name in self.tree:

# We know this super class.

bases.append(self.tree[name])

elif len(names := name.split(".")) > 1:

# Super class form is module.class:

# look in module for class.

*_, module, class_ = names

if module in _modules:

bases.append(_modules[module].get(class_, name))

else:

bases.append(name)

parent = self.stack[-1] if self.stack else None

class_ = Class(self.module, node.name, bases, self.file, node.lineno,

parent=parent, end_lineno=node.end_lineno)

if parent is None:

self.tree[node.name] = class_

self.stack.append(class_)

self.generic_visit(node)

self.stack.pop()

def visit_FunctionDef(self, node, *, is_async=False):

parent = self.stack[-1] if self.stack else None

function = Function(self.module, node.name, self.file, node.lineno,

parent, is_async, end_lineno=node.end_lineno)

if parent is None:

self.tree[node.name] = function

self.stack.append(function)

self.generic_visit(node)

self.stack.pop()

def visit_AsyncFunctionDef(self, node):

self.visit_FunctionDef(node, is_async=True)

def visit_Import(self, node):

if node.col_offset != 0:

return

for module in node.names:

try:

_readmodule(module.name, self.path, self.inpackage)

except ImportError:

_readmodule(module.name, [])

except (ImportError, SyntaxError):

# If we can't find or parse the imported module,

# too bad -- don't die here.

continue

def visit_ImportFrom(self, node):

if node.col_offset != 0:

return

try:

module = "." * node.level

if node.module:

module += node.module

module = _readmodule(module, self.path, self.inpackage)

except (ImportError, SyntaxError):

return

for name in node.names:

if name.name in module:

self.tree[name.asname or name.name] = module[name.name]

elif name.name == "*":

for import_name, import_value in module.items():

if import_name.startswith("_"):

continue

self.tree[import_name] = import_value

def _create_tree(fullmodule, path, fname, source, tree, inpackage):

mbrowser = _ModuleBrowser(fullmodule, path, fname, tree, inpackage)

mbrowser.visit(ast.parse(source))

return mbrowser.tree

def _main():

"Print module output (default this file) for quick visual check."

import os

try:

mod = sys.argv[1]

except:

mod = __file__

if os.path.exists(mod):

path = [os.path.dirname(mod)]

mod = os.path.basename(mod)

if mod.lower().endswith(".py"):

mod = mod[:-3]

else:

path = []

tree = readmodule_ex(mod, path)

lineno_key = lambda a: getattr(a, 'lineno', 0)

objs = sorted(tree.values(), key=lineno_key, reverse=True)

indent_level = 2

while objs:

obj = objs.pop()

if isinstance(obj, list):

# Value is a __path__ key.

continue

if not hasattr(obj, 'indent'):

obj.indent = 0

if isinstance(obj, _Object):

new_objs = sorted(obj.children.values(),

key=lineno_key, reverse=True)

for ob in new_objs:

ob.indent = obj.indent + indent_level

objs.extend(new_objs)

if isinstance(obj, Class):

print("{}class {} {} {}"

.format(' ' * obj.indent, obj.name, obj.super, obj.lineno))

elif isinstance(obj, Function):

print("{}def {} {}".format(' ' * obj.indent, obj.name, obj.lineno))

if __name__ == "__main__":

_main()

cpython/Lib/pyclbr.py at main · python/cpython · GitHub

Repository navigation

Expand file tree

Breadcrumbs

pyclbr.py

Latest commit

History

Breadcrumbs

pyclbr.py

File metadata and controls