pythontutorial3/docs/html/modules.html at master · duling2/pythontutorial3

History

602 lines (521 loc) · 57.6 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

<!DOCTYPE html>

<html class="no-js" lang="en" >

<head>

<title>6. 模块 — Python tutorial 3.5.2 documentation</title>

</head>

<a href="index.html" class="fa fa-home"> Python tutorial</a>

</form>

</div>

<li class="toctree-l1"><a class="reference internal" href="interpreter.html">2. 使用 Python 解释器</a><ul>

<li class="toctree-l2"><a class="reference internal" href="interpreter.html#tut-invoking">2.1. 调用 Python 解释器</a></li>

<li class="toctree-l2"><a class="reference internal" href="interpreter.html#tut-interp">2.2. 解释器及其环境</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="introduction.html">3. Python 简介</a><ul>

<li class="toctree-l2"><a class="reference internal" href="introduction.html#tut-calculator">3.1. 将 Python 当做计算器</a></li>

<li class="toctree-l2"><a class="reference internal" href="introduction.html#tut-firststeps">3.2. 编程的第一步</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="controlflow.html">4. 深入 Python 流程控制</a><ul>

<li class="toctree-l2"><a class="reference internal" href="controlflow.html#range">4.3. range() 函数</a></li>

<li class="toctree-l2"><a class="reference internal" href="controlflow.html#break-continue-else">4.4. break 和 continue 语句, 以及循环中的 else 子句</a></li>

<li class="toctree-l2"><a class="reference internal" href="controlflow.html#tut-defining">4.7. 深入 Python 函数定义</a></li>

</ul>

</li>

<li class="toctree-l2"><a class="reference internal" href="datastructures.html#tut-morelists">5.1. 关于列表更多的内容</a></li>

<li class="toctree-l2"><a class="reference internal" href="datastructures.html#tut-tuples">5.3. 元组和序列</a></li>

<li class="toctree-l2"><a class="reference internal" href="datastructures.html#tut-conditions">5.7. 深入条件控制</a></li>

<li class="toctree-l2"><a class="reference internal" href="datastructures.html#tut-comparing">5.8. 比较序列和其它类型</a></li>

</ul>

</li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="inputoutput.html">7. 输入和输出</a><ul>

<li class="toctree-l2"><a class="reference internal" href="inputoutput.html#tut-formatting">7.1. 格式化输出</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="errors.html">8. 错误和异常</a><ul>

<li class="toctree-l2"><a class="reference internal" href="errors.html#tut-userexceptions">8.5. 用户自定义异常</a></li>

<li class="toctree-l2"><a class="reference internal" href="errors.html#tut-cleanup">8.6. 定义清理行为</a></li>

<li class="toctree-l2"><a class="reference internal" href="errors.html#tut-cleanup-with">8.7. 预定义清理行为</a></li>

</ul>

</li>

<li class="toctree-l2"><a class="reference internal" href="classes.html#python">9.2. Python 作用域和命名空间</a></li>

<li class="toctree-l2"><a class="reference internal" href="classes.html#tut-exceptionclasses">9.8. 异常也是类</a></li>

<li class="toctree-l2"><a class="reference internal" href="classes.html#tut-genexps">9.11. 生成器表达式</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="stdlib.html">10. Python 标准库概览</a><ul>

<li class="toctree-l2"><a class="reference internal" href="stdlib.html#tut-os-interface">10.1. 操作系统接口</a></li>

<li class="toctree-l2"><a class="reference internal" href="stdlib.html#tut-file-wildcards">10.2. 文件通配符</a></li>

<li class="toctree-l2"><a class="reference internal" href="stdlib.html#tut-command-line-arguments">10.3. 命令行参数</a></li>

<li class="toctree-l2"><a class="reference internal" href="stdlib.html#tut-stderr">10.4. 错误输出重定向和程序终止</a></li>

<li class="toctree-l2"><a class="reference internal" href="stdlib.html#tut-string-pattern-matching">10.5. 字符串正则匹配</a></li>

<li class="toctree-l2"><a class="reference internal" href="stdlib.html#tut-internet-access">10.7. 互联网访问</a></li>

<li class="toctree-l2"><a class="reference internal" href="stdlib.html#tut-dates-and-times">10.8. 日期和时间</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="stdlib2.html">11. 标准库浏览 – Part II</a><ul>

<li class="toctree-l2"><a class="reference internal" href="stdlib2.html#tut-binary-formats">11.3. 使用二进制数据记录布局</a></li>

<li class="toctree-l2"><a class="reference internal" href="stdlib2.html#tut-decimal-fp">11.8. 十进制浮点数算法</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="venv.html">12. 虚拟环境和包</a><ul>

<li class="toctree-l2"><a class="reference internal" href="venv.html#id4">12.2. 创建虚拟环境</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="interactive.html">14. 交互式输入行编辑历史回溯</a><ul>

<li class="toctree-l2"><a class="reference internal" href="interactive.html#tab">14.1. Tab 补全和历史记录</a></li>

<li class="toctree-l2"><a class="reference internal" href="interactive.html#tut-commentary">14.2. 其它交互式解释器</a></li>

</ul>

</li>

<li class="toctree-l1"><a class="reference internal" href="floatingpoint.html">15. 浮点数算法：争议和限制</a><ul>

</ul>

</li>

</ul>

</li>

</ul>

</div>

</nav>

<a href="index.html">Python tutorial</a>

</nav>

<a href="_sources/modules.txt" rel="nofollow"> View page source</a>

</li>

</ul>

<hr/>

</div>

如果你退出 Python 解释器并重新进入，你做的任何定义（变量和方法）都会丢失。因此，如果你想要编写一些更大的程序，为准备解释器输入使用一个文本编辑器会更好，并以那个文件替代作为输入执行。这就是传说中的 脚本。随着你的程序变得越来越长，你可能想要将它分割成几个更易于维护的文件。你也可能想在不同的程序中使用顺手的函数，而不是把代码在它们之间中拷来拷去。

为了满足这些需要，Python 提供了一个方法可以从文件中获取定义，在脚本或者解释器的一个交互式实例中使用。这样的文件被称为 模块；模块中的定义可以 导入 到另一个模块或 主模块 中（在脚本执行时可以调用的变量集位于最高级，并且处于计算器模式）。

模块是包括 Python 定义和声明的文件。文件名就是模块名加上 <code class="file docutils literal">.py</code> 后缀。模块的模块名（做为一个字符串）可以由全局变量 <code class="docutils literal">__name__</code> 得到。例如，你可以用自己惯用的文件编辑器在当前目录下创建一个叫 fibo.py 的文件，录入如下内容:

<div class="highlight-default"><div class="highlight"><pre># Fibonacci numbers module

def fib(n): # write Fibonacci series up to n

a, b = 0, 1

while b < n:

print(b, end=' ')

a, b = b, a+b

print()

def fib2(n): # return Fibonacci series up to n

result = []

a, b = 0, 1

while b < n:

result.append(b)

return result

</pre></div>

</div>

现在进入 Python 解释器并使用以下命令导入这个模块:

<div class="highlight-default"><div class="highlight"><pre>>>> import fibo

</pre></div>

</div>

这样做不会直接把 <code class="docutils literal">fibo</code> 中的函数导入当前的语义表；它只是引入了模块名 <code class="docutils literal">fibo</code>。你可以通过模块名按如下方式访问这个函数:

<div class="highlight-default"><div class="highlight"><pre>>>> fibo.fib(1000)

1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987

>>> fibo.fib2(100)

[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]

>>> fibo.__name__

'fibo'

</pre></div>

</div>

如果打算频繁使用一个函数，你可以将它赋予一个本地变量:

<div class="highlight-default"><div class="highlight"><pre>>>> fib = fibo.fib

>>> fib(500)

1 1 2 3 5 8 13 21 34 55 89 144 233 377

</pre></div>

</div>

除了包含函数定义外，模块也可以包含可执行语句。这些语句一般用来初始化模块。他们仅在 第一次 被导入的地方执行一次。<a class="footnote-reference" href="#id11" id="id3">[1]</a>

每个模块都有自己私有的符号表，被模块内所有的函数定义作为全局符号表使用。因此，模块的作者可以在模块内部使用全局变量，而无需担心它与某个用户的全局变量意外冲突。从另一个方面讲，如果你确切的知道自己在做什么，你可以使用引用模块函数的表示法访问模块的全局变量，<code class="docutils literal">modname.itemname</code>。

模块可以导入其他的模块。一个（好的）习惯是将所有的 <a class="reference external" href="https://docs.python.org/3/reference/simple_stmts.html#import">import</a> 语句放在模块的开始（或者是脚本），这并非强制。被导入的模块名会放入当前模块的全局符号表中。

<a class="reference external" href="https://docs.python.org/3/reference/simple_stmts.html#import">import</a> 语句的一个变体直接从被导入的模块中导入命名到本模块的语义表中。例如:

<div class="highlight-default"><div class="highlight"><pre>>>> from fibo import fib, fib2

>>> fib(500)

1 1 2 3 5 8 13 21 34 55 89 144 233 377

</pre></div>

</div>

这样不会从局域语义表中导入模块名（如上所示， <code class="docutils literal">fibo</code> 没有定义）。

甚至有种方式可以导入模块中的所有定义:

>>> fib(500)

1 1 2 3 5 8 13 21 34 55 89 144 233 377

</pre></div>

</div>

这样可以导入所有除了以下划线( <code class="docutils literal">_</code> )开头的命名。

需要注意的是在实践中往往不鼓励从一个模块或包中使用 <code class="docutils literal">*</code> 导入所有，因为这样会让代码变得很难读。不过，在交互式会话中这样用很方便省力。

Note

出于性能考虑，每个模块在每个解释器会话中只导入一遍。因此，如果你修改了你的模块，需要重启解释器；或者，如果你就是想交互式的测试这么一个模块，可以用 <a class="reference external" href="https://docs.python.org/3/library/imp.html#imp.reload">imp.reload()</a> 重新加载，例如 <code class="docutils literal">import imp; imp.reload(modulename)</code>。

</div>

<h3>6.1.1. 作为脚本来执行模块<a class="headerlink" href="#tut-modulesasscripts" title="Permalink to this headline">¶</a></h3>

当你使用以下方式运行 Python 模块时，模块中的代码便会被执行:

<div class="highlight-default"><div class="highlight"><pre>python fibo.py <arguments>

</pre></div>

</div>

模块中的代码会被执行，就像导入它一样，不过此时 <code class="docutils literal">__name__</code> 被设置为 <code class="docutils literal">"__main__"</code>。这相当于，如果你在模块后加入如下代码:

<div class="highlight-default"><div class="highlight"><pre>if __name__ == "__main__":

import sys

fib(int(sys.argv[1]))

</pre></div>

</div>

就可以让此文件像作为模块导入时一样作为脚本执行。此代码只有在模块作为 “main” 文件执行时才被调用:

<div class="highlight-default"><div class="highlight"><pre>$ python fibo.py 50

1 1 2 3 5 8 13 21 34

</pre></div>

</div>

如果模块被导入，不会执行这段代码:

<div class="highlight-default"><div class="highlight"><pre>>>> import fibo

>>>

</pre></div>

</div>

这通常用来为模块提供一个便于测试的用户接口（将模块作为脚本执行测试需求）。

</div>

<h3>6.1.2. 模块的搜索路径<a class="headerlink" href="#tut-searchpath" title="Permalink to this headline">¶</a></h3>

导入一个叫 <code class="xref py py-mod docutils literal">spam</code> 的模块时，解释器先在当前目录中搜索名为 <code class="file docutils literal">spam.py</code> 的文件。如果没有找到的话，接着会到 <a class="reference external" href="https://docs.python.org/3/library/sys.html#sys.path">sys.path</a> 变量中给出的目录列表中查找。 <a class="reference external" href="https://docs.python.org/3/library/sys.html#sys.path">sys.path</a> 变量的初始值来自如下：

<ul>

<li>输入脚本的目录（当前目录）。

</li>

<li>环境变量 <a class="reference external" href="https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH">PYTHONPATH</a> 表示的目录列表中搜索

(这和 shell 变量 <code class="xref std std-envvar docutils literal">PATH</code> 具有一样的语法，即一系列目录名的列表)。

</li>

<li>Python 默认安装路径中搜索。

Note

在支持符号连接的文件系统中，输入的脚本所在的目录是符号连接指向的目录。换句话说也就是包含符号链接的目录不会被加到目录搜索路径中。

</div>

</li>

</ul>

实际上，解释器由 <a class="reference external" href="https://docs.python.org/3/library/sys.html#sys.path">sys.path</a> 变量指定的路径目录搜索模块，该变量初始化时默认包含了输入脚本（或者当前目录）， <a class="reference external" href="https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH">PYTHONPATH</a> 和安装目录。这样就允许 Python 程序了解如何修改或替换模块搜索目录。需要注意的是由于这些目录中包含有搜索路径中运行的脚本，所以这些脚本不应该和标准模块重名，否则在导入模块时 Python 会尝试把这些脚本当作模块来加载。这通常会引发错误。请参见 <a class="reference internal" href="#tut-standardmodules">标准模块</a> 以了解更多的信息。

</div>

<h3>6.1.3. “编译的” Python 文件<a class="headerlink" href="#python" title="Permalink to this headline">¶</a></h3>

为了加快加载模块的速度，Python 会在 <code class="docutils literal">__pycache__</code> 目录下以 <code class="file docutils literal">module.version.pyc</code> 名字缓存每个模块编译后的版本，这里的版本编制了编译后文件的格式。它通常会包含 Python 的版本号。例如，在 CPython 3.3 版中，spam.py 编译后的版本将缓存为 <code class="docutils literal">__pycache__/spam.cpython-33.pyc</code>。这种命名约定允许由不同发布和不同版本的 Python 编译的模块同时存在。

Python 会检查源文件与编译版的修改日期以确定它是否过期并需要重新编译。这是完全自动化的过程。同时，编译后的模块是跨平台的，所以同一个库可以在不同架构的系统之间共享。

Python 不检查在两个不同环境中的缓存。首先，它会永远重新编译而且不会存储直接从命令行加载的模块。其次，如果没有源模块它不会检查缓存。若要支持没有源文件（只有编译版）的发布，编译后的模块必须在源目录下，并且必须没有源文件的模块。

部分高级技巧:

<ul>

<li>为了减少一个编译模块的大小，你可以在 Python 命令行中使用 <a class="reference external" href="https://docs.python.org/3/using/cmdline.html#cmdoption-O">-O</a> 或者 <a class="reference external" href="https://docs.python.org/3/using/cmdline.html#cmdoption-OO">-OO</a>。<a class="reference external" href="https://docs.python.org/3/using/cmdline.html#cmdoption-O">-O</a> 参数删除了断言语句，<a class="reference external" href="https://docs.python.org/3/using/cmdline.html#cmdoption-OO">-OO</a> 参数删除了断言语句和 __doc__ 字符串。

因为某些程序依赖于这些变量的可用性，你应该只在确定无误的场合使用这一选项。“优化的” 模块有一个 .pyo 后缀而不是 .pyc 后缀。未来的版本可能会改变优化的效果。

</li>

<li>来自 <code class="file docutils literal">.pyc</code> 文件或 <code class="file docutils literal">.pyo</code> 文件中的程序不会比来自 <code class="file docutils literal">.py</code> 文件的运行更快；<code class="file docutils literal">.pyc</code> 或 <code class="file docutils literal">.pyo</code> 文件只是在它们加载的时候更快一些。

</li>

<li><a class="reference external" href="https://docs.python.org/3/library/compileall.html#module-compileall">compileall</a> 模块可以为指定目录中的所有模块创建 <code class="file docutils literal">.pyc</code> 文件（或者使用 <a class="reference external" href="https://docs.python.org/3/using/cmdline.html#cmdoption-O">-O</a> 参数创建 <code class="file docutils literal">.pyo</code> 文件）。

</li>

<li>在 PEP 3147 中有很多关这一部分内容的细节，并且包含了一个决策流程。

</li>

</ul>

</div>

Python 带有一个标准模块库，并发布有独立的文档，名为 Python 库参考手册（此后称其为“库参考手册”）。有一些模块内置于解释器之中，这些操作的访问接口不是语言内核的一部分，但是已经内置于解释器了。这既是为了提高效率，也是为了给系统调用等操作系统原生访问提供接口。这类模块集合是一个依赖于底层平台的配置选项。例如，<a class="reference external" href="https://docs.python.org/3/library/winreg.html#module-winreg">winreg</a> 模块只提供在 Windows 系统上才有。有一个具体的模块值得注意： <a class="reference external" href="https://docs.python.org/3/library/sys.html#module-sys">sys</a> ，这个模块内置于所有的 Python 解释器。变量 <code class="docutils literal">sys.ps1</code> 和 <code class="docutils literal">sys.ps2</code> 定义了主提示符和辅助提示符字符串:

<div class="highlight-default"><div class="highlight"><pre>>>> import sys

>>> sys.ps1

'>>> '

>>> sys.ps2

'... '

>>> sys.ps1 = 'C> '

C> print('Yuck!')

Yuck!

C>

</pre></div>

</div>

这两个变量只在解释器的交互模式下有意义。

变量 <code class="docutils literal">sys.path</code> 是解释器模块搜索路径的字符串列表。它由环境变量 <a class="reference external" href="https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH">PYTHONPATH</a> 初始化，如果没有设定 <a class="reference external" href="https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH">PYTHONPATH</a> ，就由内置的默认值初始化。你可以用标准的字符串操作修改它:

<div class="highlight-default"><div class="highlight"><pre>>>> import sys

>>> sys.path.append('/ufs/guido/lib/python')

</pre></div>

</div>

内置函数 <a class="reference external" href="https://docs.python.org/3/library/functions.html#dir">dir()</a> 用于按模块名搜索模块定义，它返回一个字符串类型的存储列表:

<div class="highlight-default"><div class="highlight"><pre>>>> import fibo, sys

>>> dir(fibo)

['__name__', 'fib', 'fib2']

>>> dir(sys)

['__displayhook__', '__doc__', '__excepthook__', '__loader__', '__name__',

'__package__', '__stderr__', '__stdin__', '__stdout__',

'_clear_type_cache', '_current_frames', '_debugmallocstats', '_getframe',

'_home', '_mercurial', '_xoptions', 'abiflags', 'api_version', 'argv',

'base_exec_prefix', 'base_prefix', 'builtin_module_names', 'byteorder',

'call_tracing', 'callstats', 'copyright', 'displayhook',

'dont_write_bytecode', 'exc_info', 'excepthook', 'exec_prefix',

'executable', 'exit', 'flags', 'float_info', 'float_repr_style',

'getcheckinterval', 'getdefaultencoding', 'getdlopenflags',

'getfilesystemencoding', 'getobjects', 'getprofile', 'getrecursionlimit',

'getrefcount', 'getsizeof', 'getswitchinterval', 'gettotalrefcount',

'gettrace', 'hash_info', 'hexversion', 'implementation', 'int_info',

'intern', 'maxsize', 'maxunicode', 'meta_path', 'modules', 'path',

'path_hooks', 'path_importer_cache', 'platform', 'prefix', 'ps1',

'setcheckinterval', 'setdlopenflags', 'setprofile', 'setrecursionlimit',

'setswitchinterval', 'settrace', 'stderr', 'stdin', 'stdout',

'thread_info', 'version', 'version_info', 'warnoptions']

</pre></div>

</div>

无参数调用时，<a class="reference external" href="https://docs.python.org/3/library/functions.html#dir">dir()</a> 函数返回当前定义的命名:

<div class="highlight-default"><div class="highlight"><pre>>>> a = [1, 2, 3, 4, 5]

>>> import fibo

>>> fib = fibo.fib

>>> dir()

['__builtins__', '__doc__', '__file__', '__name__', 'a', 'fib', 'fibo', 'sys']

</pre></div>

</div>

注意该列表列出了所有类型的名称：变量，模块，函数，等等。

<a class="reference external" href="https://docs.python.org/3/library/functions.html#dir">dir()</a> 不会列出内置函数和变量名。如果你想列出这些内容，它们在标准模块 <a class="reference external" href="https://docs.python.org/3/library/builtins.html#module-builtins">builtins</a> 中定义:

<div class="highlight-default"><div class="highlight"><pre>>>> import builtins

>>> dir(builtins)

['ArithmeticError', 'AssertionError', 'AttributeError', 'BaseException',

'BlockingIOError', 'BrokenPipeError', 'BufferError', 'BytesWarning',

'ChildProcessError', 'ConnectionAbortedError', 'ConnectionError',

'ConnectionRefusedError', 'ConnectionResetError', 'DeprecationWarning',

'EOFError', 'Ellipsis', 'EnvironmentError', 'Exception', 'False',

'FileExistsError', 'FileNotFoundError', 'FloatingPointError',

'FutureWarning', 'GeneratorExit', 'IOError', 'ImportError',

'ImportWarning', 'IndentationError', 'IndexError', 'InterruptedError',

'IsADirectoryError', 'KeyError', 'KeyboardInterrupt', 'LookupError',

'MemoryError', 'NameError', 'None', 'NotADirectoryError', 'NotImplemented',

'NotImplementedError', 'OSError', 'OverflowError',

'PendingDeprecationWarning', 'PermissionError', 'ProcessLookupError',

'ReferenceError', 'ResourceWarning', 'RuntimeError', 'RuntimeWarning',

'StopIteration', 'SyntaxError', 'SyntaxWarning', 'SystemError',

'SystemExit', 'TabError', 'TimeoutError', 'True', 'TypeError',

'UnboundLocalError', 'UnicodeDecodeError', 'UnicodeEncodeError',

'UnicodeError', 'UnicodeTranslateError', 'UnicodeWarning', 'UserWarning',

'ValueError', 'Warning', 'ZeroDivisionError', '_', '__build_class__',

'__debug__', '__doc__', '__import__', '__name__', '__package__', 'abs',

'all', 'any', 'ascii', 'bin', 'bool', 'bytearray', 'bytes', 'callable',

'chr', 'classmethod', 'compile', 'complex', 'copyright', 'credits',

'delattr', 'dict', 'dir', 'divmod', 'enumerate', 'eval', 'exec', 'exit',

'filter', 'float', 'format', 'frozenset', 'getattr', 'globals', 'hasattr',

'hash', 'help', 'hex', 'id', 'input', 'int', 'isinstance', 'issubclass',

'iter', 'len', 'license', 'list', 'locals', 'map', 'max', 'memoryview',

'min', 'next', 'object', 'oct', 'open', 'ord', 'pow', 'print', 'property',

'quit', 'range', 'repr', 'reversed', 'round', 'set', 'setattr', 'slice',

'sorted', 'staticmethod', 'str', 'sum', 'super', 'tuple', 'type', 'vars',

'zip']

</pre></div>

</div>

包通常是使用用“圆点模块名”的结构化模块命名空间。例如，名为 <code class="xref py py-mod docutils literal">A.B</code> 的模块表示了名为 <code class="docutils literal">A</code> 的包中名为 <code class="docutils literal">B</code> 的子模块。正如同用模块来保存不同的模块架构可以避免全局变量之间的相互冲突，使用圆点模块名保存像 NumPy 或 Python Imaging Library 之类的不同类库架构可以避免模块之间的命名冲突。

假设你现在想要设计一个模块集（一个“包”）来统一处理声音文件和声音数据。存在几种不同的声音格式（通常由它们的扩展名来标识，例如：<code class="file docutils literal">.wav</code>，

<code class="file docutils literal">.aiff</code>，<code class="file docutils literal">.au</code> ），于是，为了在不同类型的文件格式之间转换，你需要维护一个不断增长的包集合。可能你还想要对声音数据做很多不同的操作（例如混音，添加回声，应用平衡功能，创建一个人造效果），所以你要加入一个无限流模块来执行这些操作。你的包可能会是这个样子（通过分级的文件体系来进行分组）:

<div class="highlight-text"><div class="highlight"><pre>sound/ Top-level package

__init__.py Initialize the sound package

formats/ Subpackage for file format conversions

__init__.py

wavread.py

wavwrite.py

aiffread.py

aiffwrite.py

auread.py

auwrite.py

...

effects/ Subpackage for sound effects

__init__.py

echo.py

surround.py

reverse.py

...

filters/ Subpackage for filters

__init__.py

equalizer.py

vocoder.py

karaoke.py

...

</pre></div>

</div>

当导入这个包时，Python 通过 <code class="docutils literal">sys.path</code> 搜索路径查找包含这个包的子目录。

为了让 Python 将目录当做内容包，目录中必须包含 <code class="file docutils literal">__init__.py</code> 文件。这是为了避免一个含有烂俗名字的目录无意中隐藏了稍后在模块搜索路径中出现的有效模块，比如 string。最简单的情况下，只需要一个空的 <code class="file docutils literal">__init__.py</code> 文件即可。当然它也可以执行包的初始化代码，或者定义稍后介绍的 <code class="docutils literal">__all__</code> 变量。

用户可以每次只导入包里的特定模块，例如:

<div class="highlight-default"><div class="highlight"><pre>import sound.effects.echo

</pre></div>

</div>

这样就导入了 <code class="xref py py-mod docutils literal">sound.effects.echo</code> 子模块。它必需通过完整的名称来引用:

<div class="highlight-default"><div class="highlight"><pre>sound.effects.echo.echofilter(input, output, delay=0.7, atten=4)

</pre></div>

</div>

导入包时有一个可以选择的方式:

<div class="highlight-default"><div class="highlight"><pre>from sound.effects import echo

</pre></div>

</div>

这样就加载了 <code class="xref py py-mod docutils literal">echo</code> 子模块，并且使得它在没有包前缀的情况下也可以使用，所以它可以如下方式调用:

<div class="highlight-default"><div class="highlight"><pre>echo.echofilter(input, output, delay=0.7, atten=4)

</pre></div>

</div>

还有另一种变体用于直接导入函数或变量:

<div class="highlight-default"><div class="highlight"><pre>from sound.effects.echo import echofilter

</pre></div>

</div>

这样就又一次加载了 <code class="xref py py-mod docutils literal">echo</code> 子模块，但这样就可以直接调用它的 <code class="xref py py-func docutils literal">echofilter()</code> 函数:

<div class="highlight-default"><div class="highlight"><pre>echofilter(input, output, delay=0.7, atten=4)

</pre></div>

</div>

需要注意的是使用 <code class="docutils literal">from package import item</code> 方式导入包时，这个子项（item）既可以是包中的一个子模块（或一个子包），也可以是包中定义的其它命名，像函数、类或变量。<code class="docutils literal">import</code> 语句首先核对是否包中有这个子项，如果没有，它假定这是一个模块，并尝试加载它。如果没有找到它，会引发一个 <a class="reference external" href="https://docs.python.org/3/library/exceptions.html#ImportError">ImportError</a> 异常。

相反，使用类似 <code class="docutils literal">import item.subitem.subsubitem</code> 这样的语法时，这些子项必须是包，最后的子项可以是包或模块，但不能是前面子项中定义的类、函数或变量。

那么当用户写下 <code class="docutils literal">from sound.Effects import *</code> 时会发生什么事？理想中，总是希望在文件系统中找出包中所有的子模块，然后导入它们。这可能会花掉委有长时间，并且出现期待之外的边界效应，导出了希望只能显式导入的包。

对于包的作者来说唯一的解决方案就是给提供一个明确的包索引。<a class="reference external" href="https://docs.python.org/3/reference/simple_stmts.html#import">import</a> 语句按如下条件进行转换：执行 <code class="docutils literal">from package import *</code> 时，如果包中的 <code class="file docutils literal">__init__.py</code> 代码定义了一个名为 <code class="docutils literal">__all__</code> 的列表，就会按照列表中给出的模块名进行导入。新版本的包发布时作者可以任意更新这个列表。如果包作者不想 import * 的时候导入他们的包中所有模块，那么也可能会决定不支持它（ import * ）。例如， <code class="file docutils literal">sound/effects/__init__.py</code> 这个文件可能包括如下代码:

<div class="highlight-default"><div class="highlight"><pre>__all__ = ["echo", "surround", "reverse"]

</pre></div>

</div>

这意味着 <code class="docutils literal">from Sound.Effects import *</code> 语句会从 <code class="xref py py-mod docutils literal">sound</code> 包中导入以上三个已命名的子模块。

如果没有定义 <code class="docutils literal">__all__</code> ， <code class="docutils literal">from Sound.Effects import *</code> 语句 不会 从 <code class="xref py py-mod docutils literal">sound.effects</code> 包中导入所有的子模块。无论包中定义多少命名，只能确定的是导入了 <code class="xref py py-mod docutils literal">sound.effects</code> 包（可能会运行 <code class="file docutils literal">__init__.py</code> 中的初始化代码）以及包中定义的所有命名会随之导入。这样就从 <code class="file docutils literal">__init__.py</code> 中导入了每一个命名（以及明确导入的子模块）。同样也包括了前述的 <a class="reference external" href="https://docs.python.org/3/reference/simple_stmts.html#import">import</a> 语句从包中明确导入的子模块，考虑以下代码:

<div class="highlight-default"><div class="highlight"><pre>import sound.effects.echo

import sound.effects.surround

from sound.effects import *

</pre></div>

</div>

在这个例子中，<code class="xref py py-mod docutils literal">echo</code> 和 <code class="xref py py-mod docutils literal">surround</code> 模块导入了当前的命名空间，这是因为执行 <code class="docutils literal">from...import</code> 语句时它们已经定义在 <code class="xref py py-mod docutils literal">sound.effects</code> 包中了（定义了 <code class="docutils literal">__all__</code> 时也会同样工作）。

尽管某些模块设计为使用 <code class="docutils literal">import *</code> 时它只导出符全某种模式的命名，仍然不建议在生产代码中使用这种写法。

记住，<code class="docutils literal">from Package import specific_submodule</code> 没有错误！事实上，除非导入的模块需要使用其它包中的同名子模块，否则这是推荐的写法。

</div>

如果包中使用了子包结构（就像示例中的 <code class="xref py py-mod docutils literal">sound</code> 包），可以按绝对位置从相邻的包中引入子模块。例如，如果 <code class="xref py py-mod docutils literal">sound.filters.vocoder</code> 包需要使用 <code class="xref py py-mod docutils literal">sound.effects</code> 包中的 <code class="xref py py-mod docutils literal">echo</code> 模块，它可以 <code class="docutils literal">from Sound.Effects import echo</code>。

你可以用这样的形式 <code class="docutils literal">from module import name</code> 来写显式的相对位置导入。那些显式相对导入用点号标明关联导入当前和上级包。以 <code class="xref py py-mod docutils literal">surround</code> 模块为例，你可以这样用:

<div class="highlight-default"><div class="highlight"><pre>from . import echo

from .. import formats

from ..filters import equalizer

</pre></div>

</div>

需要注意的是显式或隐式相对位置导入都基于当前模块的命名。因为主模块的名字总是 <code class="docutils literal">"__main__"</code>，Python 应用程序的主模块应该总是用绝对导入。

</div>

<h3>6.4.3. 多重目录中的包<a class="headerlink" href="#id10" title="Permalink to this headline">¶</a></h3>

包支持一个更为特殊的特性， <a class="reference external" href="https://docs.python.org/3/reference/import.html#__path__">__path__</a>。在包的 <code class="file docutils literal">__init__.py</code> 文件代码执行之前，该变量初始化一个目录名列表。该变量可以修改，它作用于包中的子包和模块的搜索功能。

这个功能可以用于扩展包中的模块集，不过它不常用。

Footnotes

<tr><td class="label"><a class="fn-backref" href="#id3">[1]</a></td><td>事实上函数定义既是“声明”又是“可执行体”；执行体由函数在模块全局语义表中的命名导入。</td></tr>

</tbody>

</table>

</div>

<a href="datastructures.html" class="btn btn-neutral" title="5. 数据结构"> Previous</a>

</div>

<hr/>

</div>

Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.

</footer>

</div>

</section>

</div>

var DOCUMENTATION_OPTIONS = {

URL_ROOT:'./',

VERSION:'3.5.2',

COLLAPSE_INDEX:false,

FILE_SUFFIX:'.html',

HAS_SOURCE: true

};

</script>

jQuery(function () {

SphinxRtdTheme.StickyNav.enable();

});

</script>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

modules.html

Latest commit

History

modules.html

File metadata and controls