~dkuhlman/python-training-materials/Materials

<h1>31.5. <a class="reference internal" href="#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal">importlib</code></a> – The implementation of <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a><a class="headerlink" href="#module-importlib" title="Permalink to this headline">¶</a></h1>

New in version 3.1.

</div>

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/importlib/__init__.py">Lib/importlib/__init__.py</a>

100

101

102

<h2>31.5.1. Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>

103

The purpose of the <a class="reference internal" href="#module-importlib" title="importlib: The implementation of the import machinery."><code class="xref py py-mod docutils literal">importlib</code></a> package is two-fold. One is to provide the

104

implementation of the <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a> statement (and thus, by extension, the

105

<a class="reference internal" href="functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal">__import__()</code></a> function) in Python source code. This provides an

106

implementation of <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a> which is portable to any Python

107

interpreter. This also provides an implementation which is easier to

108

comprehend than one implemented in a programming language other than Python.

109

Two, the components to implement <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a> are exposed in this

110

package, making it easier for users to create their own custom objects (known

111

generically as an <a class="reference internal" href="../glossary.html#term-importer">importer</a>) to participate in the import process.

112

113

See also

114

115

<dt><a class="reference internal" href="../reference/simple_stmts.html#import">The import statement</a></dt>

116

<dd>The language reference for the <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a> statement.</dd>

117

<dt><a class="reference external" href="http://legacy.python.org/doc/essays/packages.html">Packages specification</a></dt>

118

<dd>Original specification of packages. Some semantics have changed since

119

the writing of this document (e.g. redirecting based on <code class="docutils literal">None</code>

120

in <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal">sys.modules</code></a>).</dd>

121

<dt>The <a class="reference internal" href="#importlib.__import__" title="importlib.__import__"><code class="xref py py-func docutils literal">__import__()</code></a> function</dt>

122

<dd>The <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a> statement is syntactic sugar for this function.</dd>

123

124

<dd>Import on Case-Insensitive Platforms</dd>

125

126

<dd>Defining Python Source Code Encodings</dd>

127

128

<dd>New Import Hooks</dd>

129

130

<dd>Imports: Multi-Line and Absolute/Relative</dd>

131

132

<dd>Main module explicit relative imports</dd>

133

134

<dd>Implicit namespace packages</dd>

135

136

<dd>A ModuleSpec Type for the Import System</dd>

137

138

<dd>Elimination of PYO files</dd>

139

140

<dd>Multi-phase extension module initialization</dd>

141

142

<dd>Using UTF-8 as the Default Source Encoding</dd>

143

144

<dd>PYC Repository Directories</dd>

145

</dl>

146

</div>

147

</div>

148

149

<h2>31.5.2. Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h2>

150

151

152

<code class="descclassname">importlib.</code><code class="descname">__import__</code>(name, globals=None, locals=None, fromlist=(), level=0)<a class="headerlink" href="#importlib.__import__" title="Permalink to this definition">¶</a></dt>

153

<dd>An implementation of the built-in <a class="reference internal" href="functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal">__import__()</code></a> function.

154

155

Note

156

Programmatic importing of modules should use <a class="reference internal" href="#importlib.import_module" title="importlib.import_module"><code class="xref py py-func docutils literal">import_module()</code></a>

157

instead of this function.

158

</div>

159

</dd></dl>

160

161

162

163

<code class="descclassname">importlib.</code><code class="descname">import_module</code>(name, package=None)<a class="headerlink" href="#importlib.import_module" title="Permalink to this definition">¶</a></dt>

164

<dd>Import a module. The name argument specifies what module to

165

import in absolute or relative terms

166

(e.g. either <code class="docutils literal">pkg.mod</code> or <code class="docutils literal">..mod</code>). If the name is

167

specified in relative terms, then the package argument must be set to

168

the name of the package which is to act as the anchor for resolving the

169

package name (e.g. <code class="docutils literal">import_module('..mod', 'pkg.subpkg')</code> will import

170

<code class="docutils literal">pkg.mod</code>).

171

The <a class="reference internal" href="#importlib.import_module" title="importlib.import_module"><code class="xref py py-func docutils literal">import_module()</code></a> function acts as a simplifying wrapper around

172

<a class="reference internal" href="#importlib.__import__" title="importlib.__import__"><code class="xref py py-func docutils literal">importlib.__import__()</code></a>. This means all semantics of the function are

173

derived from <a class="reference internal" href="#importlib.__import__" title="importlib.__import__"><code class="xref py py-func docutils literal">importlib.__import__()</code></a>. The most important difference

174

between these two functions is that <a class="reference internal" href="#importlib.import_module" title="importlib.import_module"><code class="xref py py-func docutils literal">import_module()</code></a> returns the

175

specified package or module (e.g. <code class="docutils literal">pkg.mod</code>), while <a class="reference internal" href="functions.html#__import__" title="__import__"><code class="xref py py-func docutils literal">__import__()</code></a>

176

returns the top-level package or module (e.g. <code class="docutils literal">pkg</code>).

177

If you are dynamically importing a module that was created since the

178

interpreter began execution (e.g., created a Python source file), you may

179

need to call <a class="reference internal" href="#importlib.invalidate_caches" title="importlib.invalidate_caches"><code class="xref py py-func docutils literal">invalidate_caches()</code></a> in order for the new module to be

180

noticed by the import system.

181

182

Changed in version 3.3: Parent packages are automatically imported.

183

</div>

184

</dd></dl>

185

186

187

188

<code class="descclassname">importlib.</code><code class="descname">find_loader</code>(name, path=None)<a class="headerlink" href="#importlib.find_loader" title="Permalink to this definition">¶</a></dt>

189

<dd>Find the loader for a module, optionally within the specified path. If the

190

module is in <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-attr docutils literal">sys.modules</code></a>, then <code class="docutils literal">sys.modules[name].__loader__</code> is

191

returned (unless the loader would be <code class="docutils literal">None</code> or is not set, in which case

192

<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised). Otherwise a search using <a class="reference internal" href="sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-attr docutils literal">sys.meta_path</code></a>

193

is done. <code class="docutils literal">None</code> is returned if no loader is found.

194

A dotted name does not have its parents implicitly imported as that requires

195

loading them and that may not be desired. To properly import a submodule you

196

will need to import all parent packages of the submodule and use the correct

197

argument to path.

198

199

New in version 3.3.

200

</div>

201

202

Changed in version 3.4: If <code class="docutils literal">__loader__</code> is not set, raise <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a>, just like when the

203

attribute is set to <code class="docutils literal">None</code>.

204

</div>

205

206

Deprecated since version 3.4: Use <a class="reference internal" href="#importlib.util.find_spec" title="importlib.util.find_spec"><code class="xref py py-func docutils literal">importlib.util.find_spec()</code></a> instead.

207

</div>

208

</dd></dl>

209

210

211

212

<code class="descclassname">importlib.</code><code class="descname">invalidate_caches</code>()<a class="headerlink" href="#importlib.invalidate_caches" title="Permalink to this definition">¶</a></dt>

213

<dd>Invalidate the internal caches of finders stored at

214

<a class="reference internal" href="sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal">sys.meta_path</code></a>. If a finder implements <code class="docutils literal">invalidate_caches()</code> then it

215

will be called to perform the invalidation. This function should be called

216

if any modules are created/installed while your program is running to

217

guarantee all finders will notice the new module’s existence.

218

219

New in version 3.3.

220

</div>

221

</dd></dl>

222

223

224

225

<code class="descclassname">importlib.</code><code class="descname">reload</code>(module)<a class="headerlink" href="#importlib.reload" title="Permalink to this definition">¶</a></dt>

226

<dd>Reload a previously imported module. The argument must be a module object,

227

so it must have been successfully imported before. This is useful if you

228

have edited the module source file using an external editor and want to try

229

out the new version without leaving the Python interpreter. The return value

230

is the module object (which can be different if re-importing causes a

231

different object to be placed in <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal">sys.modules</code></a>).

232

When <a class="reference internal" href="#importlib.reload" title="importlib.reload"><code class="xref py py-func docutils literal">reload()</code></a> is executed:

233

234

<li>Python module’s code is recompiled and the module-level code re-executed,

235

defining a new set of objects which are bound to names in the module’s

236

dictionary by reusing the <a class="reference internal" href="../glossary.html#term-loader">loader</a> which originally loaded the

237

module. The <code class="docutils literal">init</code> function of extension modules is not called a second

238

time.</li>

239

<li>As with all other objects in Python the old objects are only reclaimed

240

after their reference counts drop to zero.</li>

241

<li>The names in the module namespace are updated to point to any new or

242

changed objects.</li>

243

<li>Other references to the old objects (such as names external to the module) are

244

not rebound to refer to the new objects and must be updated in each namespace

245

where they occur if that is desired.</li>

246

</ul>

247

There are a number of other caveats:

248

When a module is reloaded, its dictionary (containing the module’s global

249

variables) is retained. Redefinitions of names will override the old

250

definitions, so this is generally not a problem. If the new version of a

251

module does not define a name that was defined by the old version, the old

252

definition remains. This feature can be used to the module’s advantage if it

253

maintains a global table or cache of objects — with a <a class="reference internal" href="../reference/compound_stmts.html#try"><code class="xref std std-keyword docutils literal">try</code></a>

254

statement it can test for the table’s presence and skip its initialization if

255

desired:

256

<div class="highlight-python3"><div class="highlight"><pre>try:

257

cache

258

except NameError:

259

cache = {}

260

</pre></div>

261

</div>

262

It is generally not very useful to reload built-in or dynamically loaded

263

modules. Reloading <a class="reference internal" href="sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal">sys</code></a>, <a class="reference internal" href="__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal">__main__</code></a>, <a class="reference internal" href="builtins.html#module-builtins" title="builtins: The module that provides the built-in namespace."><code class="xref py py-mod docutils literal">builtins</code></a> and other

264

key modules is not recommended. In many cases extension modules are not

265

designed to be initialized more than once, and may fail in arbitrary ways

266

when reloaded.

267

If a module imports objects from another module using <a class="reference internal" href="../reference/simple_stmts.html#from"><code class="xref std std-keyword docutils literal">from</code></a> ...

268

<a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a> ..., calling <a class="reference internal" href="#importlib.reload" title="importlib.reload"><code class="xref py py-func docutils literal">reload()</code></a> for the other module does not

269

redefine the objects imported from it — one way around this is to

270

re-execute the <a class="reference internal" href="../reference/simple_stmts.html#from"><code class="xref std std-keyword docutils literal">from</code></a> statement, another is to use <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a>

271

and qualified names (module.name) instead.

272

If a module instantiates instances of a class, reloading the module that

273

defines the class does not affect the method definitions of the instances —

274

they continue to use the old class definition. The same is true for derived

275

classes.

276

277

New in version 3.4.

278

</div>

279

</dd></dl>

280

281

</div>

282

283

<h2>31.5.3. <a class="reference internal" href="#module-importlib.abc" title="importlib.abc: Abstract base classes related to import"><code class="xref py py-mod docutils literal">importlib.abc</code></a> – Abstract base classes related to import<a class="headerlink" href="#module-importlib.abc" title="Permalink to this headline">¶</a></h2>

284

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/importlib/abc.py">Lib/importlib/abc.py</a>

285

286

The <a class="reference internal" href="#module-importlib.abc" title="importlib.abc: Abstract base classes related to import"><code class="xref py py-mod docutils literal">importlib.abc</code></a> module contains all of the core abstract base classes

287

used by <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a>. Some subclasses of the core abstract base classes

288

are also provided to help in implementing the core ABCs.

289

ABC hierarchy:

290

<div class="highlight-python3"><div class="highlight"><pre>object

291

+-- Finder (deprecated)

292

| +-- MetaPathFinder

293

| +-- PathEntryFinder

294

+-- Loader

295

+-- ResourceLoader --------+

296

+-- InspectLoader |

297

+-- ExecutionLoader --+

298

+-- FileLoader

299

+-- SourceLoader

300

</pre></div>

301

</div>

302

303

304

class <code class="descclassname">importlib.abc.</code><code class="descname">Finder</code><a class="headerlink" href="#importlib.abc.Finder" title="Permalink to this definition">¶</a></dt>

305

<dd>An abstract base class representing a <a class="reference internal" href="../glossary.html#term-finder">finder</a>.

306

307

Deprecated since version 3.3: Use <a class="reference internal" href="#importlib.abc.MetaPathFinder" title="importlib.abc.MetaPathFinder"><code class="xref py py-class docutils literal">MetaPathFinder</code></a> or <a class="reference internal" href="#importlib.abc.PathEntryFinder" title="importlib.abc.PathEntryFinder"><code class="xref py py-class docutils literal">PathEntryFinder</code></a> instead.

308

</div>

309

310

311

abstractmethod <code class="descname">find_module</code>(fullname, path=None)<a class="headerlink" href="#importlib.abc.Finder.find_module" title="Permalink to this definition">¶</a></dt>

312

<dd>An abstact method for finding a <a class="reference internal" href="../glossary.html#term-loader">loader</a> for the specified

313

module. Originally specified in <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a>, this method was meant

314

for use in <a class="reference internal" href="sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal">sys.meta_path</code></a> and in the path-based import subsystem.

315

316

Changed in version 3.4: Returns <code class="docutils literal">None</code> when called instead of raising

317

318

</div>

319

</dd></dl>

320

321

</dd></dl>

322

323

324

325

class <code class="descclassname">importlib.abc.</code><code class="descname">MetaPathFinder</code><a class="headerlink" href="#importlib.abc.MetaPathFinder" title="Permalink to this definition">¶</a></dt>

326

<dd>An abstract base class representing a <a class="reference internal" href="../glossary.html#term-meta-path-finder">meta path finder</a>. For

327

compatibility, this is a subclass of <a class="reference internal" href="#importlib.abc.Finder" title="importlib.abc.Finder"><code class="xref py py-class docutils literal">Finder</code></a>.

328

329

New in version 3.3.

330

</div>

331

332

333

<code class="descname">find_spec</code>(fullname, path, target=None)<a class="headerlink" href="#importlib.abc.MetaPathFinder.find_spec" title="Permalink to this definition">¶</a></dt>

334

<dd>An abstract method for finding a <a class="reference internal" href="../glossary.html#term-module-spec">spec</a> for

335

the specified module. If this is a top-level import, path will

336

be <code class="docutils literal">None</code>. Otherwise, this is a search for a subpackage or

337

module and path will be the value of <a class="reference internal" href="../reference/import.html#__path__" title="__path__"><code class="xref py py-attr docutils literal">__path__</code></a> from the

338

parent package. If a spec cannot be found, <code class="docutils literal">None</code> is returned.

339

When passed in, <code class="docutils literal">target</code> is a module object that the finder may

340

use to make a more educated about what spec to return.

341

342

New in version 3.4.

343

</div>

344

</dd></dl>

345

346

347

348

<code class="descname">find_module</code>(fullname, path)<a class="headerlink" href="#importlib.abc.MetaPathFinder.find_module" title="Permalink to this definition">¶</a></dt>

349

<dd>A legacy method for finding a <a class="reference internal" href="../glossary.html#term-loader">loader</a> for the specified

350

module. If this is a top-level import, path will be <code class="docutils literal">None</code>.

351

Otherwise, this is a search for a subpackage or module and path

352

will be the value of <a class="reference internal" href="../reference/import.html#__path__" title="__path__"><code class="xref py py-attr docutils literal">__path__</code></a> from the parent

353

package. If a loader cannot be found, <code class="docutils literal">None</code> is returned.

354

If <a class="reference internal" href="#importlib.abc.MetaPathFinder.find_spec" title="importlib.abc.MetaPathFinder.find_spec"><code class="xref py py-meth docutils literal">find_spec()</code></a> is defined, backwards-compatible functionality is

355

provided.

356

357

Changed in version 3.4: Returns <code class="docutils literal">None</code> when called instead of raising

358

<a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a>. Can use <a class="reference internal" href="#importlib.abc.MetaPathFinder.find_spec" title="importlib.abc.MetaPathFinder.find_spec"><code class="xref py py-meth docutils literal">find_spec()</code></a> to provide

359

functionality.

360

</div>

361

362

Deprecated since version 3.4: Use <a class="reference internal" href="#importlib.abc.MetaPathFinder.find_spec" title="importlib.abc.MetaPathFinder.find_spec"><code class="xref py py-meth docutils literal">find_spec()</code></a> instead.

363

</div>

364

</dd></dl>

365

366

367

368

<code class="descname">invalidate_caches</code>()<a class="headerlink" href="#importlib.abc.MetaPathFinder.invalidate_caches" title="Permalink to this definition">¶</a></dt>

369

<dd>An optional method which, when called, should invalidate any internal

370

cache used by the finder. Used by <a class="reference internal" href="#importlib.invalidate_caches" title="importlib.invalidate_caches"><code class="xref py py-func docutils literal">importlib.invalidate_caches()</code></a>

371

when invalidating the caches of all finders on <a class="reference internal" href="sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal">sys.meta_path</code></a>.

372

373

Changed in version 3.4: Returns <code class="docutils literal">None</code> when called instead of <code class="docutils literal">NotImplemented</code>.

374

</div>

375

</dd></dl>

376

377

</dd></dl>

378

379

380

381

class <code class="descclassname">importlib.abc.</code><code class="descname">PathEntryFinder</code><a class="headerlink" href="#importlib.abc.PathEntryFinder" title="Permalink to this definition">¶</a></dt>

382

<dd>An abstract base class representing a <a class="reference internal" href="../glossary.html#term-path-entry-finder">path entry finder</a>. Though

383

it bears some similarities to <a class="reference internal" href="#importlib.abc.MetaPathFinder" title="importlib.abc.MetaPathFinder"><code class="xref py py-class docutils literal">MetaPathFinder</code></a>, <code class="docutils literal">PathEntryFinder</code>

384

is meant for use only within the path-based import subsystem provided

385

by <code class="xref py py-class docutils literal">PathFinder</code>. This ABC is a subclass of <a class="reference internal" href="#importlib.abc.Finder" title="importlib.abc.Finder"><code class="xref py py-class docutils literal">Finder</code></a> for

386

compatibility reasons only.

387

388

New in version 3.3.

389

</div>

390

391

392

<code class="descname">find_spec</code>(fullname, target=None)<a class="headerlink" href="#importlib.abc.PathEntryFinder.find_spec" title="Permalink to this definition">¶</a></dt>

393

<dd>An abstract method for finding a <a class="reference internal" href="../glossary.html#term-module-spec">spec</a> for

394

the specified module. The finder will search for the module only

395

within the <a class="reference internal" href="../glossary.html#term-path-entry">path entry</a> to which it is assigned. If a spec

396

cannot be found, <code class="docutils literal">None</code> is returned. When passed in, <code class="docutils literal">target</code>

397

is a module object that the finder may use to make a more educated

398

about what spec to return.

399

400

New in version 3.4.

401

</div>

402

</dd></dl>

403

404

405

406

<code class="descname">find_loader</code>(fullname)<a class="headerlink" href="#importlib.abc.PathEntryFinder.find_loader" title="Permalink to this definition">¶</a></dt>

407

<dd>A legacy method for finding a <a class="reference internal" href="../glossary.html#term-loader">loader</a> for the specified

408

module. Returns a 2-tuple of <code class="docutils literal">(loader, portion)</code> where <code class="docutils literal">portion</code>

409

is a sequence of file system locations contributing to part of a namespace

410

package. The loader may be <code class="docutils literal">None</code> while specifying <code class="docutils literal">portion</code> to

411

signify the contribution of the file system locations to a namespace

412

package. An empty list can be used for <code class="docutils literal">portion</code> to signify the loader

413

is not part of a namespace package. If <code class="docutils literal">loader</code> is <code class="docutils literal">None</code> and

414

<code class="docutils literal">portion</code> is the empty list then no loader or location for a namespace

415

package were found (i.e. failure to find anything for the module).

416

If <a class="reference internal" href="#importlib.abc.PathEntryFinder.find_spec" title="importlib.abc.PathEntryFinder.find_spec"><code class="xref py py-meth docutils literal">find_spec()</code></a> is defined then backwards-compatible functionality is

417

provided.

418

419

Changed in version 3.4: Returns <code class="docutils literal">(None, [])</code> instead of raising <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a>.

420

Uses <a class="reference internal" href="#importlib.abc.PathEntryFinder.find_spec" title="importlib.abc.PathEntryFinder.find_spec"><code class="xref py py-meth docutils literal">find_spec()</code></a> when available to provide functionality.

421

</div>

422

423

Deprecated since version 3.4: Use <a class="reference internal" href="#importlib.abc.PathEntryFinder.find_spec" title="importlib.abc.PathEntryFinder.find_spec"><code class="xref py py-meth docutils literal">find_spec()</code></a> instead.

424

</div>

425

</dd></dl>

426

427

428

429

<code class="descname">find_module</code>(fullname)<a class="headerlink" href="#importlib.abc.PathEntryFinder.find_module" title="Permalink to this definition">¶</a></dt>

430

<dd>A concrete implementation of <a class="reference internal" href="#importlib.abc.Finder.find_module" title="importlib.abc.Finder.find_module"><code class="xref py py-meth docutils literal">Finder.find_module()</code></a> which is

431

equivalent to <code class="docutils literal">self.find_loader(fullname)[0]</code>.

432

433

434

</div>

435

</dd></dl>

436

437

438

439

<code class="descname">invalidate_caches</code>()<a class="headerlink" href="#importlib.abc.PathEntryFinder.invalidate_caches" title="Permalink to this definition">¶</a></dt>

440

<dd>An optional method which, when called, should invalidate any internal

441

cache used by the finder. Used by <code class="xref py py-meth docutils literal">PathFinder.invalidate_caches()</code>

442

when invalidating the caches of all cached finders.

443

</dd></dl>

444

445

</dd></dl>

446

447

448

449

class <code class="descclassname">importlib.abc.</code><code class="descname">Loader</code><a class="headerlink" href="#importlib.abc.Loader" title="Permalink to this definition">¶</a></dt>

450

<dd>An abstract base class for a <a class="reference internal" href="../glossary.html#term-loader">loader</a>.

451

See <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> for the exact definition for a loader.

452

453

454

<code class="descname">create_module</code>(spec)<a class="headerlink" href="#importlib.abc.Loader.create_module" title="Permalink to this definition">¶</a></dt>

455

<dd>A method that returns the module object to use when

456

importing a module. This method may return <code class="docutils literal">None</code>,

457

indicating that default module creation semantics should take place.

458

459

New in version 3.4.

460

</div>

461

462

Changed in version 3.5: Starting in Python 3.6, this method will not be optional when

463

<a class="reference internal" href="#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal">exec_module()</code></a> is defined.

464

</div>

465

</dd></dl>

466

467

468

469

<code class="descname">exec_module</code>(module)<a class="headerlink" href="#importlib.abc.Loader.exec_module" title="Permalink to this definition">¶</a></dt>

470

<dd>An abstract method that executes the module in its own namespace

471

when a module is imported or reloaded. The module should already

472

be initialized when exec_module() is called.

473

474

New in version 3.4.

475

</div>

476

</dd></dl>

477

478

479

480

<code class="descname">load_module</code>(fullname)<a class="headerlink" href="#importlib.abc.Loader.load_module" title="Permalink to this definition">¶</a></dt>

481

<dd>A legacy method for loading a module. If the module cannot be

482

loaded, <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a> is raised, otherwise the loaded module is

483

returned.

484

If the requested module already exists in <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal">sys.modules</code></a>, that

485

module should be used and reloaded.

486

Otherwise the loader should create a new module and insert it into

487

<a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal">sys.modules</code></a> before any loading begins, to prevent recursion

488

from the import. If the loader inserted a module and the load fails, it

489

must be removed by the loader from <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal">sys.modules</code></a>; modules already

490

in <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal">sys.modules</code></a> before the loader began execution should be left

491

alone (see <a class="reference internal" href="#importlib.util.module_for_loader" title="importlib.util.module_for_loader"><code class="xref py py-func docutils literal">importlib.util.module_for_loader()</code></a>).

492

The loader should set several attributes on the module.

493

(Note that some of these attributes can change when a module is

494

reloaded):

495

<ul>

496

497

498

<dd>The name of the module.

499

</dd>

500

</dl>

501

</li>

502

503

504

<dd>The path to where the module data is stored (not set for built-in

505

modules).

506

</dd>

507

</dl>

508

</li>

509

510

<dt><a class="reference internal" href="../reference/import.html#__cached__" title="__cached__"><code class="xref py py-attr docutils literal">__cached__</code></a></dt>

511

<dd>The path to where a compiled version of the module is/should be

512

stored (not set when the attribute would be inappropriate).

513

</dd>

514

</dl>

515

</li>

516

517

518

<dd>A list of strings specifying the search path within a

519

package. This attribute is not set on modules.

520

</dd>

521

</dl>

522

</li>

523

524

<dt><a class="reference internal" href="../reference/import.html#__package__" title="__package__"><code class="xref py py-attr docutils literal">__package__</code></a></dt>

525

<dd>The parent package for the module/package. If the module is

526

top-level then it has a value of the empty string. The

527

<a class="reference internal" href="#importlib.util.module_for_loader" title="importlib.util.module_for_loader"><code class="xref py py-func docutils literal">importlib.util.module_for_loader()</code></a> decorator can handle the

528

details for <a class="reference internal" href="../reference/import.html#__package__" title="__package__"><code class="xref py py-attr docutils literal">__package__</code></a>.

529

</dd>

530

</dl>

531

</li>

532

533

<dt><a class="reference internal" href="../reference/import.html#__loader__" title="__loader__"><code class="xref py py-attr docutils literal">__loader__</code></a></dt>

534

<dd>The loader used to load the module. The

535

536

537

</dd>

538

</dl>

539

</li>

540

</ul>

541

When <a class="reference internal" href="#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal">exec_module()</code></a> is available then backwards-compatible

542

functionality is provided.

543

544

Changed in version 3.4: Raise <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a> when called instead of

545

546

547

</div>

548

549

Deprecated since version 3.4: The recommended API for loading a module is <a class="reference internal" href="#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal">exec_module()</code></a>

550

(and <a class="reference internal" href="#importlib.abc.Loader.create_module" title="importlib.abc.Loader.create_module"><code class="xref py py-meth docutils literal">create_module()</code></a>). Loaders should implement

551

it instead of load_module(). The import machinery takes care of

552

all the other responsibilities of load_module() when exec_module()

553

is implemented.

554

</div>

555

</dd></dl>

556

557

558

559

<code class="descname">module_repr</code>(module)<a class="headerlink" href="#importlib.abc.Loader.module_repr" title="Permalink to this definition">¶</a></dt>

560

<dd>A legacy method which when implemented calculates and returns the

561

given module’s repr, as a string. The module type’s default repr() will

562

use the result of this method as appropriate.

563

564

New in version 3.3.

565

</div>

566

567

Changed in version 3.4: Made optional instead of an abstractmethod.

568

</div>

569

570

Deprecated since version 3.4: The import machinery now takes care of this automatically.

571

</div>

572

</dd></dl>

573

574

</dd></dl>

575

576

577

578

class <code class="descclassname">importlib.abc.</code><code class="descname">ResourceLoader</code><a class="headerlink" href="#importlib.abc.ResourceLoader" title="Permalink to this definition">¶</a></dt>

579

<dd>An abstract base class for a <a class="reference internal" href="../glossary.html#term-loader">loader</a> which implements the optional

580

<a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> protocol for loading arbitrary resources from the storage

581

back-end.

582

583

584

abstractmethod <code class="descname">get_data</code>(path)<a class="headerlink" href="#importlib.abc.ResourceLoader.get_data" title="Permalink to this definition">¶</a></dt>

585

<dd>An abstract method to return the bytes for the data located at path.

586

Loaders that have a file-like storage back-end

587

that allows storing arbitrary data

588

can implement this abstract method to give direct access

589

to the data stored. <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> is to be raised if the path cannot

590

be found. The path is expected to be constructed using a module’s

591

<a class="reference internal" href="../reference/import.html#__file__" title="__file__"><code class="xref py py-attr docutils literal">__file__</code></a> attribute or an item from a package’s <a class="reference internal" href="../reference/import.html#__path__" title="__path__"><code class="xref py py-attr docutils literal">__path__</code></a>.

592

593

Changed in version 3.4: Raises <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> instead of <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a>.

594

</div>

595

</dd></dl>

596

597

</dd></dl>

598

599

600

601

class <code class="descclassname">importlib.abc.</code><code class="descname">InspectLoader</code><a class="headerlink" href="#importlib.abc.InspectLoader" title="Permalink to this definition">¶</a></dt>

602

<dd>An abstract base class for a <a class="reference internal" href="../glossary.html#term-loader">loader</a> which implements the optional

603

<a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> protocol for loaders that inspect modules.

604

605

606

<code class="descname">get_code</code>(fullname)<a class="headerlink" href="#importlib.abc.InspectLoader.get_code" title="Permalink to this definition">¶</a></dt>

607

<dd>Return the code object for a module, or <code class="docutils literal">None</code> if the module does not

608

have a code object (as would be the case, for example, for a built-in

609

module). Raise an <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a> if loader cannot find the

610

requested module.

611

612

Note

613

While the method has a default implementation, it is suggested that

614

it be overridden if possible for performance.

615

</div>

616

617

Changed in version 3.4: No longer abstract and a concrete implementation is provided.

618

</div>

619

</dd></dl>

620

621

622

623

abstractmethod <code class="descname">get_source</code>(fullname)<a class="headerlink" href="#importlib.abc.InspectLoader.get_source" title="Permalink to this definition">¶</a></dt>

624

<dd>An abstract method to return the source of a module. It is returned as

625

a text string using <a class="reference internal" href="../glossary.html#term-universal-newlines">universal newlines</a>, translating all

626

recognized line separators into <code class="docutils literal">'\n'</code> characters. Returns <code class="docutils literal">None</code>

627

if no source is available (e.g. a built-in module). Raises

628

<a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a> if the loader cannot find the module specified.

629

630

Changed in version 3.4: Raises <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a> instead of <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a>.

631

</div>

632

</dd></dl>

633

634

635

636

<code class="descname">is_package</code>(fullname)<a class="headerlink" href="#importlib.abc.InspectLoader.is_package" title="Permalink to this definition">¶</a></dt>

637

<dd>An abstract method to return a true value if the module is a package, a

638

false value otherwise. <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a> is raised if the

639

<a class="reference internal" href="../glossary.html#term-loader">loader</a> cannot find the module.

640

641

642

</div>

643

</dd></dl>

644

645

646

647

static <code class="descname">source_to_code</code>(data, path='<string>')<a class="headerlink" href="#importlib.abc.InspectLoader.source_to_code" title="Permalink to this definition">¶</a></dt>

648

<dd>Create a code object from Python source.

649

The data argument can be whatever the <a class="reference internal" href="functions.html#compile" title="compile"><code class="xref py py-func docutils literal">compile()</code></a> function

650

supports (i.e. string or bytes). The path argument should be

651

the “path” to where the source code originated from, which can be an

652

abstract concept (e.g. location in a zip file).

653

With the subsequent code object one can execute it in a module by

654

running <code class="docutils literal">exec(code, module.__dict__)</code>.

655

656

New in version 3.4.

657

</div>

658

659

Changed in version 3.5: Made the method static.

660

</div>

661

</dd></dl>

662

663

664

665

<code class="descname">exec_module</code>(module)<a class="headerlink" href="#importlib.abc.InspectLoader.exec_module" title="Permalink to this definition">¶</a></dt>

666

<dd>Implementation of <a class="reference internal" href="#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal">Loader.exec_module()</code></a>.

667

668

New in version 3.4.

669

</div>

670

</dd></dl>

671

672

673

674

<code class="descname">load_module</code>(fullname)<a class="headerlink" href="#importlib.abc.InspectLoader.load_module" title="Permalink to this definition">¶</a></dt>

675

<dd>Implementation of <a class="reference internal" href="#importlib.abc.Loader.load_module" title="importlib.abc.Loader.load_module"><code class="xref py py-meth docutils literal">Loader.load_module()</code></a>.

676

677

Deprecated since version 3.4: use <a class="reference internal" href="#importlib.abc.InspectLoader.exec_module" title="importlib.abc.InspectLoader.exec_module"><code class="xref py py-meth docutils literal">exec_module()</code></a> instead.

678

</div>

679

</dd></dl>

680

681

</dd></dl>

682

683

684

685

class <code class="descclassname">importlib.abc.</code><code class="descname">ExecutionLoader</code><a class="headerlink" href="#importlib.abc.ExecutionLoader" title="Permalink to this definition">¶</a></dt>

686

<dd>An abstract base class which inherits from <a class="reference internal" href="#importlib.abc.InspectLoader" title="importlib.abc.InspectLoader"><code class="xref py py-class docutils literal">InspectLoader</code></a> that,

687

when implemented, helps a module to be executed as a script. The ABC

688

represents an optional <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> protocol.

689

690

691

abstractmethod <code class="descname">get_filename</code>(fullname)<a class="headerlink" href="#importlib.abc.ExecutionLoader.get_filename" title="Permalink to this definition">¶</a></dt>

692

<dd>An abstract method that is to return the value of <a class="reference internal" href="../reference/import.html#__file__" title="__file__"><code class="xref py py-attr docutils literal">__file__</code></a> for

693

the specified module. If no path is available, <a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a> is

694

raised.

695

If source code is available, then the method should return the path to

696

the source file, regardless of whether a bytecode was used to load the

697

module.

698

699

700

</div>

701

</dd></dl>

702

703

</dd></dl>

704

705

706

707

class <code class="descclassname">importlib.abc.</code><code class="descname">FileLoader</code>(fullname, path)<a class="headerlink" href="#importlib.abc.FileLoader" title="Permalink to this definition">¶</a></dt>

708

<dd>An abstract base class which inherits from <a class="reference internal" href="#importlib.abc.ResourceLoader" title="importlib.abc.ResourceLoader"><code class="xref py py-class docutils literal">ResourceLoader</code></a> and

709

<a class="reference internal" href="#importlib.abc.ExecutionLoader" title="importlib.abc.ExecutionLoader"><code class="xref py py-class docutils literal">ExecutionLoader</code></a>, providing concrete implementations of

710

<a class="reference internal" href="#importlib.abc.ResourceLoader.get_data" title="importlib.abc.ResourceLoader.get_data"><code class="xref py py-meth docutils literal">ResourceLoader.get_data()</code></a> and <a class="reference internal" href="#importlib.abc.ExecutionLoader.get_filename" title="importlib.abc.ExecutionLoader.get_filename"><code class="xref py py-meth docutils literal">ExecutionLoader.get_filename()</code></a>.

711

The fullname argument is a fully resolved name of the module the loader is

712

to handle. The path argument is the path to the file for the module.

713

714

New in version 3.3.

715

</div>

716

717

718

719

<dd>The name of the module the loader can handle.

720

</dd></dl>

721

722

723

724

725

<dd>Path to the file of the module.

726

</dd></dl>

727

728

729

730

<code class="descname">load_module</code>(fullname)<a class="headerlink" href="#importlib.abc.FileLoader.load_module" title="Permalink to this definition">¶</a></dt>

731

<dd>Calls super’s <code class="docutils literal">load_module()</code>.

732

733

Deprecated since version 3.4: Use <a class="reference internal" href="#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal">Loader.exec_module()</code></a> instead.

734

</div>

735

</dd></dl>

736

737

738

739

abstractmethod <code class="descname">get_filename</code>(fullname)<a class="headerlink" href="#importlib.abc.FileLoader.get_filename" title="Permalink to this definition">¶</a></dt>

740

<dd>Returns <a class="reference internal" href="#importlib.abc.FileLoader.path" title="importlib.abc.FileLoader.path"><code class="xref py py-attr docutils literal">path</code></a>.

741

</dd></dl>

742

743

744

745

abstractmethod <code class="descname">get_data</code>(path)<a class="headerlink" href="#importlib.abc.FileLoader.get_data" title="Permalink to this definition">¶</a></dt>

746

<dd>Reads path as a binary file and returns the bytes from it.

747

</dd></dl>

748

749

</dd></dl>

750

751

752

753

class <code class="descclassname">importlib.abc.</code><code class="descname">SourceLoader</code><a class="headerlink" href="#importlib.abc.SourceLoader" title="Permalink to this definition">¶</a></dt>

754

<dd>An abstract base class for implementing source (and optionally bytecode)

755

file loading. The class inherits from both <a class="reference internal" href="#importlib.abc.ResourceLoader" title="importlib.abc.ResourceLoader"><code class="xref py py-class docutils literal">ResourceLoader</code></a> and

756

757

<ul>

758

<li><a class="reference internal" href="#importlib.abc.ResourceLoader.get_data" title="importlib.abc.ResourceLoader.get_data"><code class="xref py py-meth docutils literal">ResourceLoader.get_data()</code></a>

759

</li>

760

761

<dt><a class="reference internal" href="#importlib.abc.ExecutionLoader.get_filename" title="importlib.abc.ExecutionLoader.get_filename"><code class="xref py py-meth docutils literal">ExecutionLoader.get_filename()</code></a></dt>

762

<dd>Should only return the path to the source file; sourceless

763

loading is not supported.

764

</dd>

765

</dl>

766

</li>

767

</ul>

768

The abstract methods defined by this class are to add optional bytecode

769

file support. Not implementing these optional methods (or causing them to

770

raise <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a>) causes the loader to

771

only work with source code. Implementing the methods allows the loader to

772

work with source and bytecode files; it does not allow for sourceless

773

loading where only bytecode is provided. Bytecode files are an

774

optimization to speed up loading by removing the parsing step of Python’s

775

compiler, and so no bytecode-specific API is exposed.

776

777

778

<code class="descname">path_stats</code>(path)<a class="headerlink" href="#importlib.abc.SourceLoader.path_stats" title="Permalink to this definition">¶</a></dt>

779

<dd>Optional abstract method which returns a <a class="reference internal" href="stdtypes.html#dict" title="dict"><code class="xref py py-class docutils literal">dict</code></a> containing

780

metadata about the specified path. Supported dictionary keys are:

781

782

<li><code class="docutils literal">'mtime'</code> (mandatory): an integer or floating-point number

783

representing the modification time of the source code;</li>

784

<li><code class="docutils literal">'size'</code> (optional): the size in bytes of the source code.</li>

785

</ul>

786

Any other keys in the dictionary are ignored, to allow for future

787

extensions. If the path cannot be handled, <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> is raised.

788

789

New in version 3.3.

790

</div>

791

792

Changed in version 3.4: Raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> instead of <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a>.

793

</div>

794

</dd></dl>

795

796

797

798

<code class="descname">path_mtime</code>(path)<a class="headerlink" href="#importlib.abc.SourceLoader.path_mtime" title="Permalink to this definition">¶</a></dt>

799

<dd>Optional abstract method which returns the modification time for the

800

specified path.

801

802

Deprecated since version 3.3: This method is deprecated in favour of <a class="reference internal" href="#importlib.abc.SourceLoader.path_stats" title="importlib.abc.SourceLoader.path_stats"><code class="xref py py-meth docutils literal">path_stats()</code></a>. You don’t

803

have to implement it, but it is still available for compatibility

804

purposes. Raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> if the path cannot be handled.

805

</div>

806

807

808

</div>

809

</dd></dl>

810

811

812

813

814

<dd>Optional abstract method which writes the specified bytes to a file

815

path. Any intermediate directories which do not exist are to be created

816

automatically.

817

When writing to the path fails because the path is read-only

818

(<a class="reference internal" href="errno.html#errno.EACCES" title="errno.EACCES"><code class="xref py py-attr docutils literal">errno.EACCES</code></a>/<a class="reference internal" href="exceptions.html#PermissionError" title="PermissionError"><code class="xref py py-exc docutils literal">PermissionError</code></a>), do not propagate the

819

exception.

820

821

Changed in version 3.4: No longer raises <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a> when called.

822

</div>

823

</dd></dl>

824

825

826

827

<code class="descname">get_code</code>(fullname)<a class="headerlink" href="#importlib.abc.SourceLoader.get_code" title="Permalink to this definition">¶</a></dt>

828

<dd>Concrete implementation of <a class="reference internal" href="#importlib.abc.InspectLoader.get_code" title="importlib.abc.InspectLoader.get_code"><code class="xref py py-meth docutils literal">InspectLoader.get_code()</code></a>.

829

</dd></dl>

830

831

832

833

<code class="descname">exec_module</code>(module)<a class="headerlink" href="#importlib.abc.SourceLoader.exec_module" title="Permalink to this definition">¶</a></dt>

834

835

<div>Concrete implementation of <a class="reference internal" href="#importlib.abc.Loader.exec_module" title="importlib.abc.Loader.exec_module"><code class="xref py py-meth docutils literal">Loader.exec_module()</code></a>.</div></blockquote>

836

837

New in version 3.4.

838

</div>

839

</dd></dl>

840

841

842

843

<code class="descname">load_module</code>(fullname)<a class="headerlink" href="#importlib.abc.SourceLoader.load_module" title="Permalink to this definition">¶</a></dt>

844

<dd>Concrete implementation of <a class="reference internal" href="#importlib.abc.Loader.load_module" title="importlib.abc.Loader.load_module"><code class="xref py py-meth docutils literal">Loader.load_module()</code></a>.

845

846

Deprecated since version 3.4: Use <a class="reference internal" href="#importlib.abc.SourceLoader.exec_module" title="importlib.abc.SourceLoader.exec_module"><code class="xref py py-meth docutils literal">exec_module()</code></a> instead.

847

</div>

848

</dd></dl>

849

850

851

852

<code class="descname">get_source</code>(fullname)<a class="headerlink" href="#importlib.abc.SourceLoader.get_source" title="Permalink to this definition">¶</a></dt>

853

<dd>Concrete implementation of <a class="reference internal" href="#importlib.abc.InspectLoader.get_source" title="importlib.abc.InspectLoader.get_source"><code class="xref py py-meth docutils literal">InspectLoader.get_source()</code></a>.

854

</dd></dl>

855

856

857

858

<code class="descname">is_package</code>(fullname)<a class="headerlink" href="#importlib.abc.SourceLoader.is_package" title="Permalink to this definition">¶</a></dt>

859

<dd>Concrete implementation of <a class="reference internal" href="#importlib.abc.InspectLoader.is_package" title="importlib.abc.InspectLoader.is_package"><code class="xref py py-meth docutils literal">InspectLoader.is_package()</code></a>. A module

860

is determined to be a package if its file path (as provided by

861

<a class="reference internal" href="#importlib.abc.ExecutionLoader.get_filename" title="importlib.abc.ExecutionLoader.get_filename"><code class="xref py py-meth docutils literal">ExecutionLoader.get_filename()</code></a>) is a file named

862

<code class="docutils literal">__init__</code> when the file extension is removed and the module name

863

itself does not end in <code class="docutils literal">__init__</code>.

864

</dd></dl>

865

866

</dd></dl>

867

868

</div>

869

870

<h2>31.5.4. <a class="reference internal" href="#module-importlib.machinery" title="importlib.machinery: Importers and path hooks"><code class="xref py py-mod docutils literal">importlib.machinery</code></a> – Importers and path hooks<a class="headerlink" href="#module-importlib.machinery" title="Permalink to this headline">¶</a></h2>

871

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/importlib/machinery.py">Lib/importlib/machinery.py</a>

872

873

This module contains the various objects that help <a class="reference internal" href="../reference/simple_stmts.html#import"><code class="xref std std-keyword docutils literal">import</code></a>

874

find and load modules.

875

876

877

<code class="descclassname">importlib.machinery.</code><code class="descname">SOURCE_SUFFIXES</code><a class="headerlink" href="#importlib.machinery.SOURCE_SUFFIXES" title="Permalink to this definition">¶</a></dt>

878

<dd>A list of strings representing the recognized file suffixes for source

879

modules.

880

881

New in version 3.3.

882

</div>

883

</dd></dl>

884

885

886

887

<code class="descclassname">importlib.machinery.</code><code class="descname">DEBUG_BYTECODE_SUFFIXES</code><a class="headerlink" href="#importlib.machinery.DEBUG_BYTECODE_SUFFIXES" title="Permalink to this definition">¶</a></dt>

888

<dd>A list of strings representing the file suffixes for non-optimized bytecode

889

modules.

890

891

New in version 3.3.

892

</div>

893

894

Deprecated since version 3.5: Use <a class="reference internal" href="#importlib.machinery.BYTECODE_SUFFIXES" title="importlib.machinery.BYTECODE_SUFFIXES"><code class="xref py py-attr docutils literal">BYTECODE_SUFFIXES</code></a> instead.

895

</div>

896

</dd></dl>

897

898

899

900

<code class="descclassname">importlib.machinery.</code><code class="descname">OPTIMIZED_BYTECODE_SUFFIXES</code><a class="headerlink" href="#importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES" title="Permalink to this definition">¶</a></dt>

901

<dd>A list of strings representing the file suffixes for optimized bytecode

902

modules.

903

904

New in version 3.3.

905

</div>

906

907

908

</div>

909

</dd></dl>

910

911

912

913

<code class="descclassname">importlib.machinery.</code><code class="descname">BYTECODE_SUFFIXES</code><a class="headerlink" href="#importlib.machinery.BYTECODE_SUFFIXES" title="Permalink to this definition">¶</a></dt>

914

<dd>A list of strings representing the recognized file suffixes for bytecode

915

modules (including the leading dot).

916

917

New in version 3.3.

918

</div>

919

920

Changed in version 3.5: The value is no longer dependent on <code class="docutils literal">__debug__</code>.

921

</div>

922

</dd></dl>

923

924

925

926

<code class="descclassname">importlib.machinery.</code><code class="descname">EXTENSION_SUFFIXES</code><a class="headerlink" href="#importlib.machinery.EXTENSION_SUFFIXES" title="Permalink to this definition">¶</a></dt>

927

<dd>A list of strings representing the recognized file suffixes for

928

extension modules.

929

930

New in version 3.3.

931

</div>

932

</dd></dl>

933

934

935

936

<code class="descclassname">importlib.machinery.</code><code class="descname">all_suffixes</code>()<a class="headerlink" href="#importlib.machinery.all_suffixes" title="Permalink to this definition">¶</a></dt>

937

<dd>Returns a combined list of strings representing all file suffixes for

938

modules recognized by the standard import machinery. This is a

939

helper for code which simply needs to know if a filesystem path

940

potentially refers to a module without needing any details on the kind

941

of module (for example, <a class="reference internal" href="inspect.html#inspect.getmodulename" title="inspect.getmodulename"><code class="xref py py-func docutils literal">inspect.getmodulename()</code></a>).

942

943

New in version 3.3.

944

</div>

945

</dd></dl>

946

947

948

949

class <code class="descclassname">importlib.machinery.</code><code class="descname">BuiltinImporter</code><a class="headerlink" href="#importlib.machinery.BuiltinImporter" title="Permalink to this definition">¶</a></dt>

950

<dd>An <a class="reference internal" href="../glossary.html#term-importer">importer</a> for built-in modules. All known built-in modules are

951

listed in <a class="reference internal" href="sys.html#sys.builtin_module_names" title="sys.builtin_module_names"><code class="xref py py-data docutils literal">sys.builtin_module_names</code></a>. This class implements the

952

<a class="reference internal" href="#importlib.abc.MetaPathFinder" title="importlib.abc.MetaPathFinder"><code class="xref py py-class docutils literal">importlib.abc.MetaPathFinder</code></a> and

953

<a class="reference internal" href="#importlib.abc.InspectLoader" title="importlib.abc.InspectLoader"><code class="xref py py-class docutils literal">importlib.abc.InspectLoader</code></a> ABCs.

954

Only class methods are defined by this class to alleviate the need for

955

instantiation.

956

957

Changed in version 3.5: As part of <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0489">PEP 489</a>, the builtin importer now implements

958

<code class="xref py py-meth docutils literal">Loader.create_module()</code> and <code class="xref py py-meth docutils literal">Loader.exec_module()</code>

959

</div>

960

</dd></dl>

961

962

963

964

class <code class="descclassname">importlib.machinery.</code><code class="descname">FrozenImporter</code><a class="headerlink" href="#importlib.machinery.FrozenImporter" title="Permalink to this definition">¶</a></dt>

965

<dd>An <a class="reference internal" href="../glossary.html#term-importer">importer</a> for frozen modules. This class implements the

966

967

968

Only class methods are defined by this class to alleviate the need for

969

instantiation.

970

</dd></dl>

971

972

973

974

class <code class="descclassname">importlib.machinery.</code><code class="descname">WindowsRegistryFinder</code><a class="headerlink" href="#importlib.machinery.WindowsRegistryFinder" title="Permalink to this definition">¶</a></dt>

975

<dd><a class="reference internal" href="../glossary.html#term-finder">Finder</a> for modules declared in the Windows registry. This class

976

implements the <a class="reference internal" href="#importlib.abc.Finder" title="importlib.abc.Finder"><code class="xref py py-class docutils literal">importlib.abc.Finder</code></a> ABC.

977

Only class methods are defined by this class to alleviate the need for

978

instantiation.

979

980

New in version 3.3.

981

</div>

982

</dd></dl>

983

984

985

986

class <code class="descclassname">importlib.machinery.</code><code class="descname">PathFinder</code><a class="headerlink" href="#importlib.machinery.PathFinder" title="Permalink to this definition">¶</a></dt>

987

<dd>A <a class="reference internal" href="../glossary.html#term-finder">Finder</a> for <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a> and package <code class="docutils literal">__path__</code> attributes.

988

This class implements the <a class="reference internal" href="#importlib.abc.MetaPathFinder" title="importlib.abc.MetaPathFinder"><code class="xref py py-class docutils literal">importlib.abc.MetaPathFinder</code></a> ABC.

989

Only class methods are defined by this class to alleviate the need for

990

instantiation.

991

992

993

classmethod <code class="descname">find_spec</code>(fullname, path=None, target=None)<a class="headerlink" href="#importlib.machinery.PathFinder.find_spec" title="Permalink to this definition">¶</a></dt>

994

<dd>Class method that attempts to find a <a class="reference internal" href="../glossary.html#term-module-spec">spec</a>

995

for the module specified by fullname on <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a> or, if

996

defined, on path. For each path entry that is searched,

997

998

is found then it is used as the <a class="reference internal" href="../glossary.html#term-path-entry-finder">path entry finder</a> to look

999

for the module being searched for. If no entry is found in

1000

<a class="reference internal" href="sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal">sys.path_importer_cache</code></a>, then <a class="reference internal" href="sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal">sys.path_hooks</code></a> is

1001

searched for a finder for the path entry and, if found, is stored

1002

in <a class="reference internal" href="sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-data docutils literal">sys.path_importer_cache</code></a> along with being queried about

1003

the module. If no finder is ever found then <code class="docutils literal">None</code> is both

1004

stored in the cache and returned.

1005

1006

New in version 3.4.

1007

</div>

1008

1009

Changed in version 3.5: If the current working directory – represented by an empty string –

1010

is no longer valid then <code class="docutils literal">None</code> is returned but no value is cached

1011

1012

</div>

1013

</dd></dl>

1014

1015

1016

1017

classmethod <code class="descname">find_module</code>(fullname, path=None)<a class="headerlink" href="#importlib.machinery.PathFinder.find_module" title="Permalink to this definition">¶</a></dt>

1018

<dd>A legacy wrapper around <a class="reference internal" href="#importlib.machinery.PathFinder.find_spec" title="importlib.machinery.PathFinder.find_spec"><code class="xref py py-meth docutils literal">find_spec()</code></a>.

1019

1020

Deprecated since version 3.4: Use <a class="reference internal" href="#importlib.machinery.PathFinder.find_spec" title="importlib.machinery.PathFinder.find_spec"><code class="xref py py-meth docutils literal">find_spec()</code></a> instead.

1021

</div>

1022

</dd></dl>

1023

1024

1025

1026

classmethod <code class="descname">invalidate_caches</code>()<a class="headerlink" href="#importlib.machinery.PathFinder.invalidate_caches" title="Permalink to this definition">¶</a></dt>

1027

<dd>Calls <a class="reference internal" href="#importlib.abc.PathEntryFinder.invalidate_caches" title="importlib.abc.PathEntryFinder.invalidate_caches"><code class="xref py py-meth docutils literal">importlib.abc.PathEntryFinder.invalidate_caches()</code></a> on all

1028

finders stored in <a class="reference internal" href="sys.html#sys.path_importer_cache" title="sys.path_importer_cache"><code class="xref py py-attr docutils literal">sys.path_importer_cache</code></a>.

1029

</dd></dl>

1030

1031

1032

Changed in version 3.4: Calls objects in <a class="reference internal" href="sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal">sys.path_hooks</code></a> with the current working

1033

directory for <code class="docutils literal">''</code> (i.e. the empty string).

1034

</div>

1035

</dd></dl>

1036

1037

1038

1039

class <code class="descclassname">importlib.machinery.</code><code class="descname">FileFinder</code>(path, *loader_details)<a class="headerlink" href="#importlib.machinery.FileFinder" title="Permalink to this definition">¶</a></dt>

1040

<dd>A concrete implementation of <a class="reference internal" href="#importlib.abc.PathEntryFinder" title="importlib.abc.PathEntryFinder"><code class="xref py py-class docutils literal">importlib.abc.PathEntryFinder</code></a> which

1041

caches results from the file system.

1042

The path argument is the directory for which the finder is in charge of

1043

searching.

1044

The loader_details argument is a variable number of 2-item tuples each

1045

containing a loader and a sequence of file suffixes the loader recognizes.

1046

The loaders are expected to be callables which accept two arguments of

1047

the module’s name and the path to the file found.

1048

The finder will cache the directory contents as necessary, making stat calls

1049

for each module search to verify the cache is not outdated. Because cache

1050

staleness relies upon the granularity of the operating system’s state

1051

information of the file system, there is a potential race condition of

1052

searching for a module, creating a new file, and then searching for the

1053

module the new file represents. If the operations happen fast enough to fit

1054

within the granularity of stat calls, then the module search will fail. To

1055

prevent this from happening, when you create a module dynamically, make sure

1056

to call <a class="reference internal" href="#importlib.invalidate_caches" title="importlib.invalidate_caches"><code class="xref py py-func docutils literal">importlib.invalidate_caches()</code></a>.

1057

1058

New in version 3.3.

1059

</div>

1060

1061

1062

1063

<dd>The path the finder will search in.

1064

</dd></dl>

1065

1066

1067

1068

<code class="descname">find_spec</code>(fullname, target=None)<a class="headerlink" href="#importlib.machinery.FileFinder.find_spec" title="Permalink to this definition">¶</a></dt>

1069

<dd>Attempt to find the spec to handle fullname within <a class="reference internal" href="#importlib.machinery.FileFinder.path" title="importlib.machinery.FileFinder.path"><code class="xref py py-attr docutils literal">path</code></a>.

1070

1071

New in version 3.4.

1072

</div>

1073

</dd></dl>

1074

1075

1076

1077

<code class="descname">find_loader</code>(fullname)<a class="headerlink" href="#importlib.machinery.FileFinder.find_loader" title="Permalink to this definition">¶</a></dt>

1078

<dd>Attempt to find the loader to handle fullname within <a class="reference internal" href="#importlib.machinery.FileFinder.path" title="importlib.machinery.FileFinder.path"><code class="xref py py-attr docutils literal">path</code></a>.

1079

</dd></dl>

1080

1081

1082

1083

<code class="descname">invalidate_caches</code>()<a class="headerlink" href="#importlib.machinery.FileFinder.invalidate_caches" title="Permalink to this definition">¶</a></dt>

1084

<dd>Clear out the internal cache.

1085

</dd></dl>

1086

1087

1088

1089

classmethod <code class="descname">path_hook</code>(*loader_details)<a class="headerlink" href="#importlib.machinery.FileFinder.path_hook" title="Permalink to this definition">¶</a></dt>

1090

<dd>A class method which returns a closure for use on <a class="reference internal" href="sys.html#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-attr docutils literal">sys.path_hooks</code></a>.

1091

An instance of <a class="reference internal" href="#importlib.machinery.FileFinder" title="importlib.machinery.FileFinder"><code class="xref py py-class docutils literal">FileFinder</code></a> is returned by the closure using the

1092

path argument given to the closure directly and loader_details

1093

indirectly.

1094

If the argument to the closure is not an existing directory,

1095

<a class="reference internal" href="exceptions.html#ImportError" title="ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a> is raised.

1096

</dd></dl>

1097

1098

</dd></dl>

1099

1100

1101

1102

class <code class="descclassname">importlib.machinery.</code><code class="descname">SourceFileLoader</code>(fullname, path)<a class="headerlink" href="#importlib.machinery.SourceFileLoader" title="Permalink to this definition">¶</a></dt>

1103

<dd>A concrete implementation of <a class="reference internal" href="#importlib.abc.SourceLoader" title="importlib.abc.SourceLoader"><code class="xref py py-class docutils literal">importlib.abc.SourceLoader</code></a> by

1104

subclassing <a class="reference internal" href="#importlib.abc.FileLoader" title="importlib.abc.FileLoader"><code class="xref py py-class docutils literal">importlib.abc.FileLoader</code></a> and providing some concrete

1105

implementations of other methods.

1106

1107

New in version 3.3.

1108

</div>

1109

1110

1111

1112

<dd>The name of the module that this loader will handle.

1113

</dd></dl>

1114

1115

1116

1117

1118

<dd>The path to the source file.

1119

</dd></dl>

1120

1121

1122

1123

<code class="descname">is_package</code>(fullname)<a class="headerlink" href="#importlib.machinery.SourceFileLoader.is_package" title="Permalink to this definition">¶</a></dt>

1124

<dd>Return true if <a class="reference internal" href="#importlib.machinery.SourceFileLoader.path" title="importlib.machinery.SourceFileLoader.path"><code class="xref py py-attr docutils literal">path</code></a> appears to be for a package.

1125

</dd></dl>

1126

1127

1128

1129

<code class="descname">path_stats</code>(path)<a class="headerlink" href="#importlib.machinery.SourceFileLoader.path_stats" title="Permalink to this definition">¶</a></dt>

1130

<dd>Concrete implementation of <a class="reference internal" href="#importlib.abc.SourceLoader.path_stats" title="importlib.abc.SourceLoader.path_stats"><code class="xref py py-meth docutils literal">importlib.abc.SourceLoader.path_stats()</code></a>.

1131

</dd></dl>

1132

1133

1134

1135

1136

<dd>Concrete implementation of <a class="reference internal" href="#importlib.abc.SourceLoader.set_data" title="importlib.abc.SourceLoader.set_data"><code class="xref py py-meth docutils literal">importlib.abc.SourceLoader.set_data()</code></a>.

1137

</dd></dl>

1138

1139

1140

1141

<code class="descname">load_module</code>(name=None)<a class="headerlink" href="#importlib.machinery.SourceFileLoader.load_module" title="Permalink to this definition">¶</a></dt>

1142

1143

specifying the name of the module to load is optional.

1144

</dd></dl>

1145

1146

</dd></dl>

1147

1148

1149

1150

class <code class="descclassname">importlib.machinery.</code><code class="descname">SourcelessFileLoader</code>(fullname, path)<a class="headerlink" href="#importlib.machinery.SourcelessFileLoader" title="Permalink to this definition">¶</a></dt>

1151

<dd>A concrete implementation of <a class="reference internal" href="#importlib.abc.FileLoader" title="importlib.abc.FileLoader"><code class="xref py py-class docutils literal">importlib.abc.FileLoader</code></a> which can

1152

import bytecode files (i.e. no source code files exist).

1153

Please note that direct use of bytecode files (and thus not source code

1154

files) inhibits your modules from being usable by all Python

1155

implementations or new versions of Python which change the bytecode

1156

format.

1157

1158

New in version 3.3.

1159

</div>

1160

1161

1162

1163

<dd>The name of the module the loader will handle.

1164

</dd></dl>

1165

1166

1167

1168

1169

<dd>The path to the bytecode file.

1170

</dd></dl>

1171

1172

1173

1174

<code class="descname">is_package</code>(fullname)<a class="headerlink" href="#importlib.machinery.SourcelessFileLoader.is_package" title="Permalink to this definition">¶</a></dt>

1175

<dd>Determines if the module is a package based on <a class="reference internal" href="#importlib.machinery.SourcelessFileLoader.path" title="importlib.machinery.SourcelessFileLoader.path"><code class="xref py py-attr docutils literal">path</code></a>.

1176

</dd></dl>

1177

1178

1179

1180

<code class="descname">get_code</code>(fullname)<a class="headerlink" href="#importlib.machinery.SourcelessFileLoader.get_code" title="Permalink to this definition">¶</a></dt>

1181

<dd>Returns the code object for <a class="reference internal" href="#importlib.machinery.SourcelessFileLoader.name" title="importlib.machinery.SourcelessFileLoader.name"><code class="xref py py-attr docutils literal">name</code></a> created from <a class="reference internal" href="#importlib.machinery.SourcelessFileLoader.path" title="importlib.machinery.SourcelessFileLoader.path"><code class="xref py py-attr docutils literal">path</code></a>.

1182

</dd></dl>

1183

1184

1185

1186

<code class="descname">get_source</code>(fullname)<a class="headerlink" href="#importlib.machinery.SourcelessFileLoader.get_source" title="Permalink to this definition">¶</a></dt>

1187

<dd>Returns <code class="docutils literal">None</code> as bytecode files have no source when this loader is

1188

used.

1189

</dd></dl>

1190

1191

1192

1193

<code class="descname">load_module</code>(name=None)<a class="headerlink" href="#importlib.machinery.SourcelessFileLoader.load_module" title="Permalink to this definition">¶</a></dt>

1194

1195

1196

Concrete implementation of <a class="reference internal" href="#importlib.abc.Loader.load_module" title="importlib.abc.Loader.load_module"><code class="xref py py-meth docutils literal">importlib.abc.Loader.load_module()</code></a> where

1197

specifying the name of the module to load is optional.

1198

</dd></dl>

1199

1200

1201

1202

class <code class="descclassname">importlib.machinery.</code><code class="descname">ExtensionFileLoader</code>(fullname, path)<a class="headerlink" href="#importlib.machinery.ExtensionFileLoader" title="Permalink to this definition">¶</a></dt>

1203

<dd>A concrete implementation of <a class="reference internal" href="#importlib.abc.ExecutionLoader" title="importlib.abc.ExecutionLoader"><code class="xref py py-class docutils literal">importlib.abc.ExecutionLoader</code></a> for

1204

extension modules.

1205

The fullname argument specifies the name of the module the loader is to

1206

support. The path argument is the path to the extension module’s file.

1207

1208

New in version 3.3.

1209

</div>

1210

1211

1212

1213

<dd>Name of the module the loader supports.

1214

</dd></dl>

1215

1216

1217

1218

1219

<dd>Path to the extension module.

1220

</dd></dl>

1221

1222

1223

1224

<code class="descname">create_module</code>(spec)<a class="headerlink" href="#importlib.machinery.ExtensionFileLoader.create_module" title="Permalink to this definition">¶</a></dt>

1225

<dd>Creates the module object from the given specification in accordance

1226

with <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0489">PEP 489</a>.

1227

1228

New in version 3.5.

1229

</div>

1230

</dd></dl>

1231

1232

1233

1234

<code class="descname">exec_module</code>(module)<a class="headerlink" href="#importlib.machinery.ExtensionFileLoader.exec_module" title="Permalink to this definition">¶</a></dt>

1235

<dd>Initializes the given module object in accordance with <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0489">PEP 489</a>.

1236

1237

New in version 3.5.

1238

</div>

1239

</dd></dl>

1240

1241

1242

1243

<code class="descname">is_package</code>(fullname)<a class="headerlink" href="#importlib.machinery.ExtensionFileLoader.is_package" title="Permalink to this definition">¶</a></dt>

1244

<dd>Returns <code class="docutils literal">True</code> if the file path points to a package’s <code class="docutils literal">__init__</code>

1245

module based on <a class="reference internal" href="#importlib.machinery.EXTENSION_SUFFIXES" title="importlib.machinery.EXTENSION_SUFFIXES"><code class="xref py py-attr docutils literal">EXTENSION_SUFFIXES</code></a>.

1246

</dd></dl>

1247

1248

1249

1250

<code class="descname">get_code</code>(fullname)<a class="headerlink" href="#importlib.machinery.ExtensionFileLoader.get_code" title="Permalink to this definition">¶</a></dt>

1251

<dd>Returns <code class="docutils literal">None</code> as extension modules lack a code object.

1252

</dd></dl>

1253

1254

1255

1256

<code class="descname">get_source</code>(fullname)<a class="headerlink" href="#importlib.machinery.ExtensionFileLoader.get_source" title="Permalink to this definition">¶</a></dt>

1257

<dd>Returns <code class="docutils literal">None</code> as extension modules do not have source code.

1258

</dd></dl>

1259

1260

1261

1262

<code class="descname">get_filename</code>(fullname)<a class="headerlink" href="#importlib.machinery.ExtensionFileLoader.get_filename" title="Permalink to this definition">¶</a></dt>

1263

<dd>Returns <a class="reference internal" href="#importlib.machinery.ExtensionFileLoader.path" title="importlib.machinery.ExtensionFileLoader.path"><code class="xref py py-attr docutils literal">path</code></a>.

1264

1265

New in version 3.4.

1266

</div>

1267

</dd></dl>

1268

1269

</dd></dl>

1270

1271

1272

1273

class <code class="descclassname">importlib.machinery.</code><code class="descname">ModuleSpec</code>(name, loader, *, origin=None, loader_state=None, is_package=None)<a class="headerlink" href="#importlib.machinery.ModuleSpec" title="Permalink to this definition">¶</a></dt>

1274

<dd>A specification for a module’s import-system-related state.

1275

1276

New in version 3.4.

1277

</div>

1278

1279

1280

1281

1282

1283

(<code class="docutils literal">__name__</code>)

1284

A string for the fully-qualified name of the module.

1285

1286

1287

<code class="descname">loader</code><a class="headerlink" href="#importlib.machinery.ModuleSpec.loader" title="Permalink to this definition">¶</a></dt>

1288

1289

1290

(<code class="docutils literal">__loader__</code>)

1291

The loader to use for loading. For namespace packages this should be

1292

set to <code class="docutils literal">None</code>.

1293

1294

1295

<code class="descname">origin</code><a class="headerlink" href="#importlib.machinery.ModuleSpec.origin" title="Permalink to this definition">¶</a></dt>

1296

1297

1298

(<code class="docutils literal">__file__</code>)

1299

Name of the place from which the module is loaded, e.g. “builtin” for

1300

built-in modules and the filename for modules loaded from source.

1301

Normally “origin” should be set, but it may be <code class="docutils literal">None</code> (the default)

1302

which indicates it is unspecified.

1303

1304

1305

<code class="descname">submodule_search_locations</code><a class="headerlink" href="#importlib.machinery.ModuleSpec.submodule_search_locations" title="Permalink to this definition">¶</a></dt>

1306

1307

1308

(<code class="docutils literal">__path__</code>)

1309

List of strings for where to find submodules, if a package (<code class="docutils literal">None</code>

1310

otherwise).

1311

1312

1313

<code class="descname">loader_state</code><a class="headerlink" href="#importlib.machinery.ModuleSpec.loader_state" title="Permalink to this definition">¶</a></dt>

1314

1315

1316

Container of extra module-specific data for use during loading (or

1317

<code class="docutils literal">None</code>).

1318

1319

1320

<code class="descname">cached</code><a class="headerlink" href="#importlib.machinery.ModuleSpec.cached" title="Permalink to this definition">¶</a></dt>

1321

1322

1323

(<code class="docutils literal">__cached__</code>)

1324

String for where the compiled module should be stored (or <code class="docutils literal">None</code>).

1325

1326

1327

<code class="descname">parent</code><a class="headerlink" href="#importlib.machinery.ModuleSpec.parent" title="Permalink to this definition">¶</a></dt>

1328

1329

1330

(<code class="docutils literal">__package__</code>)

1331

(Read-only) Fully-qualified name of the package to which the module

1332

belongs as a submodule (or <code class="docutils literal">None</code>).

1333

1334

1335

<code class="descname">has_location</code><a class="headerlink" href="#importlib.machinery.ModuleSpec.has_location" title="Permalink to this definition">¶</a></dt>

1336

1337

1338

Boolean indicating whether or not the module’s “origin”

1339

attribute refers to a loadable location.

1340

</dd></dl>

1341

1342

</div>

1343

1344

<h2>31.5.5. <a class="reference internal" href="#module-importlib.util" title="importlib.util: Utility code for importers"><code class="xref py py-mod docutils literal">importlib.util</code></a> – Utility code for importers<a class="headerlink" href="#module-importlib.util" title="Permalink to this headline">¶</a></h2>

1345

Source code: <a class="reference external" href="https://hg.python.org/cpython/file/3.5/Lib/importlib/util.py">Lib/importlib/util.py</a>

1346

1347

This module contains the various objects that help in the construction of

1348

an <a class="reference internal" href="../glossary.html#term-importer">importer</a>.

1349

1350

1351

<code class="descclassname">importlib.util.</code><code class="descname">MAGIC_NUMBER</code><a class="headerlink" href="#importlib.util.MAGIC_NUMBER" title="Permalink to this definition">¶</a></dt>

1352

<dd>The bytes which represent the bytecode version number. If you need help with

1353

loading/writing bytecode then consider <a class="reference internal" href="#importlib.abc.SourceLoader" title="importlib.abc.SourceLoader"><code class="xref py py-class docutils literal">importlib.abc.SourceLoader</code></a>.

1354

1355

New in version 3.4.

1356

</div>

1357

</dd></dl>

1358

1359

1360

1361

<code class="descclassname">importlib.util.</code><code class="descname">cache_from_source</code>(path, debug_override=None, *, optimization=None)<a class="headerlink" href="#importlib.util.cache_from_source" title="Permalink to this definition">¶</a></dt>

1362

<dd>Return the <a class="pep reference external" href="https://www.python.org/dev/peps/pep-3147">PEP 3147</a>/<a class="pep reference external" href="https://www.python.org/dev/peps/pep-0488">PEP 488</a> path to the byte-compiled file associated

1363

with the source path. For example, if path is <code class="docutils literal">/foo/bar/baz.py</code> the return

1364

value would be <code class="docutils literal">/foo/bar/__pycache__/baz.cpython-32.pyc</code> for Python 3.2.

1365

The <code class="docutils literal">cpython-32</code> string comes from the current magic tag (see

1366

<code class="xref py py-func docutils literal">get_tag()</code>; if <code class="xref py py-attr docutils literal">sys.implementation.cache_tag</code> is not defined then

1367

1368

The optimization parameter is used to specify the optimization level of the

1369

bytecode file. An empty string represents no optimization, so

1370

<code class="docutils literal">/foo/bar/baz.py</code> with an optimization of <code class="docutils literal">''</code> will result in a

1371

bytecode path of <code class="docutils literal">/foo/bar/__pycache__/baz.cpython-32.pyc</code>. <code class="docutils literal">None</code> causes

1372

the interpter’s optimization level to be used. Any other value’s string

1373

representation being used, so <code class="docutils literal">/foo/bar/baz.py</code> with an optimization of

1374

<code class="docutils literal">2</code> will lead to the bytecode path of

1375

<code class="docutils literal">/foo/bar/__pycache__/baz.cpython-32.opt-2.pyc</code>. The string representation

1376

of optimization can only be alphanumeric, else <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised.

1377

The debug_override parameter is deprecated and can be used to override

1378

the system’s value for <code class="docutils literal">__debug__</code>. A <code class="docutils literal">True</code> value is the equivalent of

1379

setting optimization to the empty string. A <code class="docutils literal">False</code> value is the same as

1380

setting optimization to <code class="docutils literal">1</code>. If both debug_override an optimization

1381

are not <code class="docutils literal">None</code> then <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> is raised.

1382

1383

New in version 3.4.

1384

</div>

1385

1386

Changed in version 3.5: The optimization parameter was added and the debug_override parameter

1387

was deprecated.

1388

</div>

1389

</dd></dl>

1390

1391

1392

1393

<code class="descclassname">importlib.util.</code><code class="descname">source_from_cache</code>(path)<a class="headerlink" href="#importlib.util.source_from_cache" title="Permalink to this definition">¶</a></dt>

1394

<dd>Given the path to a <a class="pep reference external" href="https://www.python.org/dev/peps/pep-3147">PEP 3147</a> file name, return the associated source code

1395

file path. For example, if path is

1396

<code class="docutils literal">/foo/bar/__pycache__/baz.cpython-32.pyc</code> the returned path would be

1397

<code class="docutils literal">/foo/bar/baz.py</code>. path need not exist, however if it does not conform

1398

to <a class="pep reference external" href="https://www.python.org/dev/peps/pep-3147">PEP 3147</a> or <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0488">PEP 488</a> format, a <code class="docutils literal">ValueError</code> is raised. If

1399

<code class="xref py py-attr docutils literal">sys.implementation.cache_tag</code> is not defined,

1400

1401

1402

New in version 3.4.

1403

</div>

1404

</dd></dl>

1405

1406

1407

1408

<code class="descclassname">importlib.util.</code><code class="descname">decode_source</code>(source_bytes)<a class="headerlink" href="#importlib.util.decode_source" title="Permalink to this definition">¶</a></dt>

1409

<dd>Decode the given bytes representing source code and return it as a string

1410

with universal newlines (as required by

1411

<a class="reference internal" href="#importlib.abc.InspectLoader.get_source" title="importlib.abc.InspectLoader.get_source"><code class="xref py py-meth docutils literal">importlib.abc.InspectLoader.get_source()</code></a>).

1412

1413

New in version 3.4.

1414

</div>

1415

</dd></dl>

1416

1417

1418

1419

<code class="descclassname">importlib.util.</code><code class="descname">resolve_name</code>(name, package)<a class="headerlink" href="#importlib.util.resolve_name" title="Permalink to this definition">¶</a></dt>

1420

<dd>Resolve a relative module name to an absolute one.

1421

If name has no leading dots, then name is simply returned. This

1422

allows for usage such as

1423

<code class="docutils literal">importlib.util.resolve_name('sys', __package__)</code> without doing a

1424

check to see if the package argument is needed.

1425

<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised if name is a relative module name but

1426

package is a false value (e.g. <code class="docutils literal">None</code> or the empty string).

1427

1428

package (e.g. requesting <code class="docutils literal">..bacon</code> from within the <code class="docutils literal">spam</code> package).

1429

1430

New in version 3.3.

1431

</div>

1432

</dd></dl>

1433

1434

1435

1436

<code class="descclassname">importlib.util.</code><code class="descname">find_spec</code>(name, package=None)<a class="headerlink" href="#importlib.util.find_spec" title="Permalink to this definition">¶</a></dt>

1437

<dd>Find the <a class="reference internal" href="../glossary.html#term-module-spec">spec</a> for a module, optionally relative to

1438

the specified package name. If the module is in <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-attr docutils literal">sys.modules</code></a>,

1439

then <code class="docutils literal">sys.modules[name].__spec__</code> is returned (unless the spec would be

1440

<code class="docutils literal">None</code> or is not set, in which case <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised).

1441

Otherwise a search using <a class="reference internal" href="sys.html#sys.meta_path" title="sys.meta_path"><code class="xref py py-attr docutils literal">sys.meta_path</code></a> is done. <code class="docutils literal">None</code> is

1442

returned if no spec is found.

1443

If name is for a submodule (contains a dot), the parent module is

1444

automatically imported.

1445

name and package work the same as for <code class="xref py py-func docutils literal">import_module()</code>.

1446

1447

New in version 3.4.

1448

</div>

1449

</dd></dl>

1450

1451

1452

1453

<code class="descclassname">importlib.util.</code><code class="descname">module_from_spec</code>(spec)<a class="headerlink" href="#importlib.util.module_from_spec" title="Permalink to this definition">¶</a></dt>

1454

<dd>Create a new module based on spec and <code class="docutils literal">spec.loader.create_module()</code>.

1455

If <code class="docutils literal">spec.loader.create_module()</code> does not return <code class="docutils literal">None</code>, then any

1456

pre-existing attributes will not be reset. Also, no <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal">AttributeError</code></a>

1457

will be raised if triggered while accessing spec or setting an attribute

1458

on the module.

1459

This function is preferred over using <a class="reference internal" href="types.html#types.ModuleType" title="types.ModuleType"><code class="xref py py-class docutils literal">types.ModuleType</code></a> to create a

1460

new module as spec is used to set as many import-controlled attributes on

1461

the module as possible.

1462

1463

New in version 3.5.

1464

</div>

1465

</dd></dl>

1466

1467

1468

1469

<code class="descclassname">@</code><code class="descclassname">importlib.util.</code><code class="descname">module_for_loader</code><a class="headerlink" href="#importlib.util.module_for_loader" title="Permalink to this definition">¶</a></dt>

1470

1471

to handle selecting the proper

1472

module object to load with. The decorated method is expected to have a call

1473

signature taking two positional arguments

1474

(e.g. <code class="docutils literal">load_module(self, module)</code>) for which the second argument

1475

will be the module object to be used by the loader.

1476

Note that the decorator will not work on static methods because of the

1477

assumption of two arguments.

1478

The decorated method will take in the name of the module to be loaded

1479

as expected for a <a class="reference internal" href="../glossary.html#term-loader">loader</a>. If the module is not found in

1480

1481

module came from, <a class="reference internal" href="../reference/import.html#__loader__" title="__loader__"><code class="xref py py-attr docutils literal">__loader__</code></a> set to self and <a class="reference internal" href="../reference/import.html#__package__" title="__package__"><code class="xref py py-attr docutils literal">__package__</code></a>

1482

is set based on what <a class="reference internal" href="#importlib.abc.InspectLoader.is_package" title="importlib.abc.InspectLoader.is_package"><code class="xref py py-meth docutils literal">importlib.abc.InspectLoader.is_package()</code></a> returns

1483

(if available). These attributes are set unconditionally to support

1484

reloading.

1485

If an exception is raised by the decorated method and a module was added to

1486

1487

initialized module from being in left in <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal">sys.modules</code></a>. If the module

1488

was already in <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-data docutils literal">sys.modules</code></a> then it is left alone.

1489

1490

Changed in version 3.3: <a class="reference internal" href="../reference/import.html#__loader__" title="__loader__"><code class="xref py py-attr docutils literal">__loader__</code></a> and <a class="reference internal" href="../reference/import.html#__package__" title="__package__"><code class="xref py py-attr docutils literal">__package__</code></a> are automatically set

1491

(when possible).

1492

</div>

1493

1494

Changed in version 3.4: Set <a class="reference internal" href="../reference/import.html#__name__" title="__name__"><code class="xref py py-attr docutils literal">__name__</code></a>, <a class="reference internal" href="../reference/import.html#__loader__" title="__loader__"><code class="xref py py-attr docutils literal">__loader__</code></a> <a class="reference internal" href="../reference/import.html#__package__" title="__package__"><code class="xref py py-attr docutils literal">__package__</code></a>

1495

unconditionally to support reloading.

1496

</div>

1497

1498

Deprecated since version 3.4: The import machinery now directly performs all the functionality

1499

provided by this function.

1500

</div>

1501

</dd></dl>

1502

1503

1504

1505

<code class="descclassname">@</code><code class="descclassname">importlib.util.</code><code class="descname">set_loader</code><a class="headerlink" href="#importlib.util.set_loader" title="Permalink to this definition">¶</a></dt>

1506

1507

to set the <a class="reference internal" href="../reference/import.html#__loader__" title="__loader__"><code class="xref py py-attr docutils literal">__loader__</code></a>

1508

attribute on the returned module. If the attribute is already set the

1509

decorator does nothing. It is assumed that the first positional argument to

1510

the wrapped method (i.e. <code class="docutils literal">self</code>) is what <a class="reference internal" href="../reference/import.html#__loader__" title="__loader__"><code class="xref py py-attr docutils literal">__loader__</code></a> should be set

1511

to.

1512

1513

Changed in version 3.4: Set <code class="docutils literal">__loader__</code> if set to <code class="docutils literal">None</code>, as if the attribute does not

1514

exist.

1515

</div>

1516

1517

Deprecated since version 3.4: The import machinery takes care of this automatically.

1518

</div>

1519

</dd></dl>

1520

1521

1522

1523

<code class="descclassname">@</code><code class="descclassname">importlib.util.</code><code class="descname">set_package</code><a class="headerlink" href="#importlib.util.set_package" title="Permalink to this definition">¶</a></dt>

1524

<dd>A <a class="reference internal" href="../glossary.html#term-decorator">decorator</a> for <a class="reference internal" href="#importlib.abc.Loader.load_module" title="importlib.abc.Loader.load_module"><code class="xref py py-meth docutils literal">importlib.abc.Loader.load_module()</code></a> to set the <a class="reference internal" href="../reference/import.html#__package__" title="__package__"><code class="xref py py-attr docutils literal">__package__</code></a> attribute on the returned module. If <a class="reference internal" href="../reference/import.html#__package__" title="__package__"><code class="xref py py-attr docutils literal">__package__</code></a>

1525

is set and has a value other than <code class="docutils literal">None</code> it will not be changed.

1526

1527

Deprecated since version 3.4: The import machinery takes care of this automatically.

1528

</div>

1529

</dd></dl>

1530

1531

1532

1533

<code class="descclassname">importlib.util.</code><code class="descname">spec_from_loader</code>(name, loader, *, origin=None, is_package=None)<a class="headerlink" href="#importlib.util.spec_from_loader" title="Permalink to this definition">¶</a></dt>

1534

<dd>A factory function for creating a <code class="xref py py-class docutils literal">ModuleSpec</code> instance based

1535

on a loader. The parameters have the same meaning as they do for

1536

ModuleSpec. The function uses available <a class="reference internal" href="../glossary.html#term-loader">loader</a> APIs, such as

1537

<code class="xref py py-meth docutils literal">InspectLoader.is_package()</code>, to fill in any missing

1538

information on the spec.

1539

1540

New in version 3.4.

1541

</div>

1542

</dd></dl>

1543

1544

1545

1546

<code class="descclassname">importlib.util.</code><code class="descname">spec_from_file_location</code>(name, location, *, loader=None, submodule_search_locations=None)<a class="headerlink" href="#importlib.util.spec_from_file_location" title="Permalink to this definition">¶</a></dt>

1547

<dd>A factory function for creating a <code class="xref py py-class docutils literal">ModuleSpec</code> instance based

1548

on the path to a file. Missing information will be filled in on the

1549

spec by making use of loader APIs and by the implication that the

1550

module will be file-based.

1551

1552

New in version 3.4.

1553

</div>

1554

</dd></dl>

1555

1556

1557

1558

class <code class="descclassname">importlib.util.</code><code class="descname">LazyLoader</code>(loader)<a class="headerlink" href="#importlib.util.LazyLoader" title="Permalink to this definition">¶</a></dt>

1559

<dd>A class which postpones the execution of the loader of a module until the

1560

module has an attribute accessed.

1561

This class only works with loaders that define

1562

1563

is used for the module is required. For those same reasons, the loader’s

1564

<a class="reference internal" href="#importlib.abc.Loader.create_module" title="importlib.abc.Loader.create_module"><code class="xref py py-meth docutils literal">create_module()</code></a> method will be ignored (i.e., the

1565

loader’s method should only return <code class="docutils literal">None</code>; this excludes

1566

<code class="xref py py-class docutils literal">BuiltinImporter</code> and <code class="xref py py-class docutils literal">ExtensionFileLoader</code>). Finally,

1567

modules which substitute the object placed into <a class="reference internal" href="sys.html#sys.modules" title="sys.modules"><code class="xref py py-attr docutils literal">sys.modules</code></a> will

1568

not work as there is no way to properly replace the module references

1569

throughout the interpreter safely; <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised if such a

1570

substitution is detected.

1571

1572

Note

1573

For projects where startup time is critical, this class allows for

1574

potentially minimizing the cost of loading a module if it is never used.

1575

For projects where startup time is not essential then use of this class is

1576

heavily discouraged due to error messages created during loading being

1577

postponed and thus occurring out of context.

1578

</div>

1579

1580

New in version 3.5.

1581

</div>

1582

1583

1584

classmethod <code class="descname">factory</code>(loader)<a class="headerlink" href="#importlib.util.LazyLoader.factory" title="Permalink to this definition">¶</a></dt>

1585

<dd>A static method which returns a callable that creates a lazy loader. This

1586

is meant to be used in situations where the loader is passed by class

1587

instead of by instance.

1588

<div class="highlight-python3"><div class="highlight"><pre>suffixes = importlib.machinery.SOURCE_SUFFIXES

1589

loader = importlib.machinery.SourceFileLoader

1590

lazy_loader = importlib.util.LazyLoader.factory(loader)

1591

finder = importlib.machinery.FileFinder(path, (lazy_loader, suffixes))

1592

</pre></div>

1593

</div>

1594

</dd></dl>

1595

1596

</dd></dl>

1597

1598

</div>

1599

</div>

1600

1601

1602

</div>

1603

</div>

1604

</div>

1605

1606

1607

<h3><a href="../contents.html">Table Of Contents</a></h3>

1608

<ul>

1609

<li><a class="reference internal" href="#">31.5. <code class="docutils literal">importlib</code> – The implementation of <code class="docutils literal">import</code></a><ul>

1610

<li><a class="reference internal" href="#introduction">31.5.1. Introduction</a></li>

1611

<li><a class="reference internal" href="#functions">31.5.2. Functions</a></li>

1612

<li><a class="reference internal" href="#module-importlib.abc">31.5.3. <code class="docutils literal">importlib.abc</code> – Abstract base classes related to import</a></li>

1613

<li><a class="reference internal" href="#module-importlib.machinery">31.5.4. <code class="docutils literal">importlib.machinery</code> – Importers and path hooks</a></li>

1614

<li><a class="reference internal" href="#module-importlib.util">31.5.5. <code class="docutils literal">importlib.util</code> – Utility code for importers</a></li>

1615

</ul>

1616

</li>

1617

</ul>

1618

1619

<h4>Previous topic</h4>

1620

<a href="runpy.html"

1621

title="previous chapter">31.4. <code class="docutils literal">runpy</code> — Locating and executing Python modules</a>

1622

<h4>Next topic</h4>

1623

<a href="language.html"

1624

title="next chapter">32. Python Language Services</a>

1625

1626

1627

1628

<li><a href="../bugs.html">Report a Bug</a></li>

1629

<li><a href="../_sources/library/importlib.txt"

1630

rel="nofollow">Show Source</a></li>

1631

</ul>

1632

</div>

1633

</div>

1634

</div>

1635

1636

</div>

1637

1638

<h3>Navigation</h3>

1639

<ul>

1640

1641

<a href="../genindex.html" title="General Index"

1642

>index</a></li>

1643

1644

<a href="../py-modindex.html" title="Python Module Index"

1645

>modules</a> |</li>

1646

1647

<a href="language.html" title="32. Python Language Services"

1648

>next</a> |</li>

1649

1650

<a href="runpy.html" title="31.4. runpy — Locating and executing Python modules"

1651

>previous</a> |</li>

1652

<li><img src="../_static/py.png" alt=""

1653

style="vertical-align: middle; margin-top: -1px"/></li>

1654

<li><a href="https://www.python.org/">Python</a> »</li>

1655

<li>

1656

3.5.2

1657

<a href="../index.html">Documentation </a> »

1658

</li>

1659

1660

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

1661

<li class="nav-item nav-item-2"><a href="modules.html" >31. Importing Modules</a> »</li>

1662

1663

1664

1665

1666

1667

1668

1669

1670

1671

</form>

1672

</div>

1673

1674

1675

</li>

1676

1677

</ul>

1678

</div>

1679

1680

1681

1682

The Python Software Foundation is a non-profit corporation.

1683

<a href="https://www.python.org/psf/donations/">Please donate.</a>

1684

1685

Last updated on Oct 19, 2016.

1686

<a href="../bugs.html">Found a bug</a>?

1687

1688

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

1689

</div>

1690

1691

</body>

1692

</html>

b'\\ No newline at end of file'

Older »