~dkuhlman/python-training-materials/Materials

<h1>31.5. <a class="reference internal" href="#module-pkgutil" title="pkgutil: Utilities for the import system."><code class="xref py py-mod docutils literal">pkgutil</code></a> — Package extension utility<a class="headerlink" href="#module-pkgutil" title="Permalink to this headline">¶</a></h1>

New in version 2.3.

</div>

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

This module provides utilities for the import system, in particular package

support.

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

<dd>Extend the search path for the modules which comprise a package. Intended

use is to place the following code in a package’s <code class="file docutils literal">__init__.py</code>:

<div class="highlight-python"><div class="highlight"><pre>from pkgutil import extend_path

__path__ = extend_path(__path__, __name__)

</pre></div>

</div>

This will add to the package’s <code class="docutils literal">__path__</code> all subdirectories of directories

on <code class="docutils literal">sys.path</code> named after the package. This is useful if one wants to

distribute different parts of a single logical package as multiple

directories.

It also looks for <code class="file docutils literal">*.pkg</code> files beginning where <code class="docutils literal">*</code> matches the

100

name argument. This feature is similar to <code class="file docutils literal">*.pth</code> files (see the

101

<a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal">site</code></a> module for more information), except that it doesn’t special-case

102

lines starting with <code class="docutils literal">import</code>. A <code class="file docutils literal">*.pkg</code> file is trusted at face

103

value: apart from checking for duplicates, all entries found in a

104

<code class="file docutils literal">*.pkg</code> file are added to the path, regardless of whether they exist

105

on the filesystem. (This is a feature.)

106

If the input path is not a list (as is the case for frozen packages) it is

107

returned unchanged. The input path is not modified; an extended copy is

108

returned. Items are only appended to the copy at the end.

109

It is assumed that <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a> is a sequence. Items of <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a>

110

that are not (Unicode or 8-bit) strings referring to existing directories are

111

ignored. Unicode items 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> that cause errors when used as

112

filenames may cause this function to raise an exception (in line with

113

<a class="reference internal" href="os.path.html#os.path.isdir" title="os.path.isdir"><code class="xref py py-func docutils literal">os.path.isdir()</code></a> behavior).

114

</dd></dl>

115

116

117

118

class <code class="descclassname">pkgutil.</code><code class="descname">ImpImporter</code>(dirname=None)<a class="headerlink" href="#pkgutil.ImpImporter" title="Permalink to this definition">¶</a></dt>

119

<dd><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> Importer that wraps Python’s “classic” import algorithm.

120

If dirname is a string, a <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> importer is created that searches that

121

directory. If dirname is <code class="docutils literal">None</code>, a <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> importer is created that

122

searches the current <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a>, plus any modules that are frozen or

123

built-in.

124

Note that <a class="reference internal" href="#pkgutil.ImpImporter" title="pkgutil.ImpImporter"><code class="xref py py-class docutils literal">ImpImporter</code></a> does not currently support being used by

125

placement 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>.

126

</dd></dl>

127

128

129

130

class <code class="descclassname">pkgutil.</code><code class="descname">ImpLoader</code>(fullname, file, filename, etc)<a class="headerlink" href="#pkgutil.ImpLoader" title="Permalink to this definition">¶</a></dt>

131

<dd><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> Loader that wraps Python’s “classic” import algorithm.

132

</dd></dl>

133

134

135

136

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

137

<dd>Find a <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> “loader” object for fullname.

138

If fullname contains dots, path must be the containing package’s

139

<code class="docutils literal">__path__</code>. Returns <code class="docutils literal">None</code> if the module cannot be found or imported.

140

This function uses <a class="reference internal" href="#pkgutil.iter_importers" title="pkgutil.iter_importers"><code class="xref py py-func docutils literal">iter_importers()</code></a>, and is thus subject to the same

141

limitations regarding platform-specific special import locations such as the

142

Windows registry.

143

</dd></dl>

144

145

146

147

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

148

<dd>Retrieve a <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> importer for the given path_item.

149

The returned importer is cached 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> if it was

150

newly created by a path hook.

151

If there is no importer, a wrapper around the basic import machinery is

152

returned. This wrapper is never inserted into the importer cache (<code class="docutils literal">None</code>

153

is inserted instead).

154

The cache (or part of it) can be cleared manually if a rescan of

155

<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 necessary.

156

</dd></dl>

157

158

159

160

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

161

<dd>Get a <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> “loader” object for module_or_name.

162

If the module or package is accessible via the normal import mechanism, a

163

wrapper around the relevant part of that machinery is returned. Returns

164

<code class="docutils literal">None</code> if the module cannot be found or imported. If the named module is

165

not already imported, its containing package (if any) is imported, in order

166

to establish the package <code class="docutils literal">__path__</code>.

167

This function uses <a class="reference internal" href="#pkgutil.iter_importers" title="pkgutil.iter_importers"><code class="xref py py-func docutils literal">iter_importers()</code></a>, and is thus subject to the same

168

limitations regarding platform-specific special import locations such as the

169

Windows registry.

170

</dd></dl>

171

172

173

174

<code class="descclassname">pkgutil.</code><code class="descname">iter_importers</code>(fullname='')<a class="headerlink" href="#pkgutil.iter_importers" title="Permalink to this definition">¶</a></dt>

175

<dd>Yield <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> importers for the given module name.

176

If fullname contains a ‘.’, the importers will be for the package containing

177

fullname, otherwise they will be importers for <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>,

178

<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 Python’s “classic” import machinery, in that order. If

179

the named module is in a package, that package is imported as a side effect

180

of invoking this function.

181

Non-<a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> mechanisms (e.g. the Windows registry) used by the standard

182

import machinery to find files in alternative locations are partially

183

supported, but are searched after <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a>. Normally, these

184

locations are searched before <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a>, preventing <a class="reference internal" href="sys.html#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a>

185

entries from shadowing them.

186

For this to cause a visible difference in behaviour, there must be a module

187

or package name that is accessible via both <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 one of the

188

non-<a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> file system mechanisms. In this case, the emulation will find

189

the former version, while the builtin import mechanism will find the latter.

190

Items of the following types can be affected by this discrepancy:

191

<code class="docutils literal">imp.C_EXTENSION</code>, <code class="docutils literal">imp.PY_SOURCE</code>, <code class="docutils literal">imp.PY_COMPILED</code>,

192

<code class="docutils literal">imp.PKG_DIRECTORY</code>.

193

</dd></dl>

194

195

196

197

<code class="descclassname">pkgutil.</code><code class="descname">iter_modules</code>(path=None, prefix='')<a class="headerlink" href="#pkgutil.iter_modules" title="Permalink to this definition">¶</a></dt>

198

<dd>Yields <code class="docutils literal">(module_loader, name, ispkg)</code> for all submodules on path, or, if

199

path is <code class="docutils literal">None</code>, all top-level modules on <code class="docutils literal">sys.path</code>.

200

path should be either <code class="docutils literal">None</code> or a list of paths to look for modules in.

201

prefix is a string to output on the front of every module name on output.

202

</dd></dl>

203

204

205

206

<code class="descclassname">pkgutil.</code><code class="descname">walk_packages</code>(path=None, prefix='', onerror=None)<a class="headerlink" href="#pkgutil.walk_packages" title="Permalink to this definition">¶</a></dt>

207

<dd>Yields <code class="docutils literal">(module_loader, name, ispkg)</code> for all modules recursively on

208

path, or, if path is <code class="docutils literal">None</code>, all accessible modules.

209

path should be either <code class="docutils literal">None</code> or a list of paths to look for modules in.

210

prefix is a string to output on the front of every module name on output.

211

Note that this function must import all packages (not all modules!) on

212

the given path, in order to access the <code class="docutils literal">__path__</code> attribute to find

213

submodules.

214

onerror is a function which gets called with one argument (the name of the

215

package which was being imported) if any exception occurs while trying to

216

import a package. If no onerror function is supplied, <a class="reference internal" href="exceptions.html#exceptions.ImportError" title="exceptions.ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a>s

217

are caught and ignored, while all other exceptions are propagated,

218

terminating the search.

219

Examples:

220

<div class="highlight-python"><div class="highlight"><pre># list all modules python can access

221

walk_packages()

222

223

# list all submodules of ctypes

224

walk_packages(ctypes.__path__, ctypes.__name__ + '.')

225

</pre></div>

226

</div>

227

</dd></dl>

228

229

230

231

<code class="descclassname">pkgutil.</code><code class="descname">get_data</code>(package, resource)<a class="headerlink" href="#pkgutil.get_data" title="Permalink to this definition">¶</a></dt>

232

<dd>Get a resource from a package.

233

This is a wrapper for the <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> loader <a class="reference internal" href="#pkgutil.get_data" title="pkgutil.get_data"><code class="xref py py-func docutils literal">get_data()</code></a> API. The

234

package argument should be the name of a package, in standard module format

235

(<code class="docutils literal">foo.bar</code>). The resource argument should be in the form of a relative

236

filename, using <code class="docutils literal">/</code> as the path separator. The parent directory name

237

<code class="docutils literal">..</code> is not allowed, and nor is a rooted name (starting with a <code class="docutils literal">/</code>).

238

The function returns a binary string that is the contents of the specified

239

resource.

240

For packages located in the filesystem, which have already been imported,

241

this is the rough equivalent of:

242

<div class="highlight-python"><div class="highlight"><pre>d = os.path.dirname(sys.modules[package].__file__)

243

data = open(os.path.join(d, resource), 'rb').read()

244

</pre></div>

245

</div>

246

If the package cannot be located or loaded, or it uses a <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0302">PEP 302</a> loader

247

which does not support <a class="reference internal" href="#pkgutil.get_data" title="pkgutil.get_data"><code class="xref py py-func docutils literal">get_data()</code></a>, then <code class="docutils literal">None</code> is returned.

248

249

New in version 2.6.

250

</div>

251

</dd></dl>

252

253

</div>

254

255

256

</div>

257

</div>

258

</div>

259

260

261

<h4>Previous topic</h4>

262

<a href="zipimport.html"

263

title="previous chapter">31.4. <code class="docutils literal">zipimport</code> — Import modules from Zip archives</a>

264

<h4>Next topic</h4>

265

<a href="modulefinder.html"

266

title="next chapter">31.6. <code class="docutils literal">modulefinder</code> — Find modules used by a script</a>

267

268

269

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

270

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

271

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

272

</ul>

273

274

275

<h3>Quick search</h3>

276

277

278

279

280

281

</form>

282

283

Enter search terms or a module, class or function name.

284

285

</div>

286

287

</div>

288

</div>

289

290

</div>

291

292

<h3>Navigation</h3>

293

<ul>

294

295

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

296

>index</a></li>

297

298

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

299

>modules</a> |</li>

300

301

<a href="modulefinder.html" title="31.6. modulefinder — Find modules used by a script"

302

>next</a> |</li>

303

304

<a href="zipimport.html" title="31.4. zipimport — Import modules from Zip archives"

305

>previous</a> |</li>

306

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

307

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

308

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

309

<li>

310

2.7.12

311

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

312

</li>

313

314

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

315

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

316

</ul>

317

</div>

318

319

320

321

The Python Software Foundation is a non-profit corporation.

322

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

323

324

Last updated on Sep 20, 2016.

325

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

326

327

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

328

</div>

329

330

</body>

331

</html>

b'\\ No newline at end of file'

Older »