~dkuhlman/python-training-materials/Materials

<h2>10.1. <a class="reference internal" href="#module-distutils.core" title="distutils.core: The core Distutils functionality"><code class="xref py py-mod docutils literal">distutils.core</code></a> — Core Distutils functionality<a class="headerlink" href="#module-distutils.core" title="Permalink to this headline">¶</a></h2>

The <a class="reference internal" href="#module-distutils.core" title="distutils.core: The core Distutils functionality"><code class="xref py py-mod docutils literal">distutils.core</code></a> module is the only module that needs to be installed

to use the Distutils. It provides the <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal">setup()</code></a> (which is called from the

setup script). Indirectly provides the <code class="xref py py-class docutils literal">distutils.dist.Distribution</code> and

<a class="reference internal" href="#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal">distutils.cmd.Command</code></a> class.

<code class="descclassname">distutils.core.</code><code class="descname">setup</code>(arguments)<a class="headerlink" href="#distutils.core.setup" title="Permalink to this definition">¶</a></dt>

<dd>The basic do-everything function that does most everything you could ever ask

for from a Distutils method.

The setup function takes a large number of arguments. These are laid out in the

following table.

</colgroup>

<tr class="row-odd"><th class="head">argument name</th>

<th class="head">value</th>

100

101

</tr>

102

</thead>

103

104

105

<td>The name of the package</td>

106

<td>a string</td>

107

</tr>

108

<tr class="row-odd"><td>version</td>

109

<td>The version number of the

110

package; see

111

<a class="reference internal" href="#module-distutils.version" title="distutils.version: implements classes that represent module version numbers."><code class="xref py py-mod docutils literal">distutils.version</code></a></td>

112

<td>a string</td>

113

</tr>

114

<tr class="row-even"><td>description</td>

115

<td>A single line describing the

116

package</td>

117

<td>a string</td>

118

</tr>

119

<tr class="row-odd"><td>long_description</td>

120

<td>Longer description of the

121

package</td>

122

<td>a string</td>

123

</tr>

124

<tr class="row-even"><td>author</td>

125

<td>The name of the package author</td>

126

<td>a string</td>

127

</tr>

128

<tr class="row-odd"><td>author_email</td>

129

<td>The email address of the

130

package author</td>

131

<td>a string</td>

132

</tr>

133

<tr class="row-even"><td>maintainer</td>

134

<td>The name of the current

135

maintainer, if different from

136

the author. Note that if

137

the maintainer is provided,

138

distutils will use it as the

139

author in <code class="file docutils literal">PKG-INFO</code></td>

140

<td>a string</td>

141

</tr>

142

<tr class="row-odd"><td>maintainer_email</td>

143

<td>The email address of the

144

current maintainer, if

145

different from the author</td>

146

<td>a string</td>

147

</tr>

148

149

<td>A URL for the package

150

(homepage)</td>

151

<td>a string</td>

152

</tr>

153

<tr class="row-odd"><td>download_url</td>

154

<td>A URL to download the package</td>

155

<td>a string</td>

156

</tr>

157

<tr class="row-even"><td>packages</td>

158

<td>A list of Python packages that

159

distutils will manipulate</td>

160

<td>a list of strings</td>

161

</tr>

162

<tr class="row-odd"><td>py_modules</td>

163

<td>A list of Python modules that

164

distutils will manipulate</td>

165

<td>a list of strings</td>

166

</tr>

167

<tr class="row-even"><td>scripts</td>

168

<td>A list of standalone script

169

files to be built and

170

installed</td>

171

<td>a list of strings</td>

172

</tr>

173

<tr class="row-odd"><td>ext_modules</td>

174

<td>A list of Python extensions to

175

be built</td>

176

<td>a list of instances of

177

<a class="reference internal" href="#distutils.core.Extension" title="distutils.core.Extension"><code class="xref py py-class docutils literal">distutils.core.Extension</code></a></td>

178

</tr>

179

<tr class="row-even"><td>classifiers</td>

180

<td>A list of categories for the

181

package</td>

182

<td>a list of strings; valid classifiers are listed on <a class="reference external" href="https://pypi.python.org/pypi?:action=list_classifiers">PyPI</a>.</td>

183

</tr>

184

<tr class="row-odd"><td>distclass</td>

185

<td>the <a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal">Distribution</code></a>

186

class to use</td>

187

<td>a subclass of

188

<a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal">distutils.core.Distribution</code></a></td>

189

</tr>

190

<tr class="row-even"><td>script_name</td>

191

<td>The name of the setup.py

192

script - defaults to

193

194

<td>a string</td>

195

</tr>

196

<tr class="row-odd"><td>script_args</td>

197

<td>Arguments to supply to the

198

setup script</td>

199

<td>a list of strings</td>

200

</tr>

201

<tr class="row-even"><td>options</td>

202

<td>default options for the setup

203

script</td>

204

<td>a dictionary</td>

205

</tr>

206

<tr class="row-odd"><td>license</td>

207

<td>The license for the package</td>

208

<td>a string</td>

209

</tr>

210

<tr class="row-even"><td>keywords</td>

211

<td>Descriptive meta-data, see

212

213

<td>a list of strings or a comma-separated string</td>

214

</tr>

215

<tr class="row-odd"><td>platforms</td>

216

217

<td>a list of strings or a comma-separated string</td>

218

</tr>

219

<tr class="row-even"><td>cmdclass</td>

220

<td>A mapping of command names to

221

<a class="reference internal" href="#distutils.core.Command" title="distutils.core.Command"><code class="xref py py-class docutils literal">Command</code></a> subclasses</td>

222

<td>a dictionary</td>

223

</tr>

224

<tr class="row-odd"><td>data_files</td>

225

<td>A list of data files to

226

install</td>

227

228

</tr>

229

<tr class="row-even"><td>package_dir</td>

230

<td>A mapping of package to

231

directory names</td>

232

<td>a dictionary</td>

233

</tr>

234

</tbody>

235

</table>

236

</dd></dl>

237

238

239

240

<code class="descclassname">distutils.core.</code><code class="descname">run_setup</code>(script_name[, script_args=None, stop_after='run'])<a class="headerlink" href="#distutils.core.run_setup" title="Permalink to this definition">¶</a></dt>

241

<dd>Run a setup script in a somewhat controlled environment, and return the

242

<code class="xref py py-class docutils literal">distutils.dist.Distribution</code> instance that drives things. This is

243

useful if you need to find out the distribution meta-data (passed as keyword

244

args from script to <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal">setup()</code></a>), or the contents of the config files or

245

command-line.

246

script_name is a file that will be read and run with <a class="reference internal" href="../library/functions.html#exec" title="exec"><code class="xref py py-func docutils literal">exec()</code></a>. <code class="docutils literal">sys.argv[0]</code>

247

will be replaced with script for the duration of the call. script_args is a

248

list of strings; if supplied, <code class="docutils literal">sys.argv[1:]</code> will be replaced by script_args

249

for the duration of the call.

250

stop_after tells <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal">setup()</code></a> when to stop processing; possible values:

251

252

253

254

255

</colgroup>

256

257

<tr class="row-odd"><th class="head">value</th>

258

<th class="head">description</th>

259

</tr>

260

</thead>

261

262

263

<td>Stop after the <a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal">Distribution</code></a>

264

instance has been created and populated

265

with the keyword arguments to <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal">setup()</code></a></td>

266

</tr>

267

<tr class="row-odd"><td>config</td>

268

<td>Stop after config files have been parsed

269

(and their data stored in the

270

271

</tr>

272

<tr class="row-even"><td>commandline</td>

273

<td>Stop after the command-line

274

(<code class="docutils literal">sys.argv[1:]</code> or script_args) have

275

been parsed (and the data stored in the

276

277

</tr>

278

279

<td>Stop after all commands have been run (the

280

same as if <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal">setup()</code></a> had been called

281

in the usual way). This is the default

282

value.</td>

283

</tr>

284

</tbody>

285

</table>

286

</dd></dl>

287

288

In addition, the <a class="reference internal" href="#module-distutils.core" title="distutils.core: The core Distutils functionality"><code class="xref py py-mod docutils literal">distutils.core</code></a> module exposed a number of classes that

289

live elsewhere.

290

291

<li><code class="xref py py-class docutils literal">Extension</code> from <a class="reference internal" href="#module-distutils.extension" title="distutils.extension: Provides the Extension class, used to describe C/C++ extension modules in setup scripts"><code class="xref py py-mod docutils literal">distutils.extension</code></a></li>

292

<li><a class="reference internal" href="#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal">Command</code></a> from <a class="reference internal" href="#module-distutils.cmd" title="distutils.cmd: This module provides the abstract base class Command. This class is subclassed by the modules in the distutils.command subpackage."><code class="xref py py-mod docutils literal">distutils.cmd</code></a></li>

293

<li><code class="xref py py-class docutils literal">Distribution</code> from <a class="reference internal" href="#module-distutils.dist" title="distutils.dist: Provides the Distribution class, which represents the module distribution being built/installed/distributed"><code class="xref py py-mod docutils literal">distutils.dist</code></a></li>

294

</ul>

295

A short description of each of these follows, but see the relevant module for

296

the full reference.

297

298

299

class <code class="descclassname">distutils.core.</code><code class="descname">Extension</code><a class="headerlink" href="#distutils.core.Extension" title="Permalink to this definition">¶</a></dt>

300

<dd>The Extension class describes a single C or C++extension module in a setup

301

script. It accepts the following keyword arguments in its constructor:

302

303

304

305

306

307

</colgroup>

308

309

<tr class="row-odd"><th class="head">argument name</th>

310

<th class="head">value</th>

311

312

</tr>

313

</thead>

314

315

316

<td>the full name of the

317

extension, including any

318

packages — ie. not a

319

filename or pathname, but

320

Python dotted name</td>

321

<td>a string</td>

322

</tr>

323

<tr class="row-odd"><td>sources</td>

324

<td>list of source filenames,

325

relative to the distribution

326

root (where the setup script

327

lives), in Unix form (slash-

328

separated) for portability.

329

Source files may be C, C++,

330

SWIG (.i), platform-specific

331

resource files, or whatever

332

else is recognized by the

333

build_ext command

334

as source for a Python

335

extension.</td>

336

<td>a list of strings</td>

337

</tr>

338

<tr class="row-even"><td>include_dirs</td>

339

<td>list of directories to search

340

for C/C++ header files (in

341

Unix form for portability)</td>

342

<td>a list of strings</td>

343

</tr>

344

<tr class="row-odd"><td>define_macros</td>

345

<td>list of macros to define; each

346

macro is defined using a

347

2-tuple <code class="docutils literal">(name, value)</code>,

348

where value is

349

either the string to define it

350

to or <code class="docutils literal">None</code> to define it

351

without a particular value

352

(equivalent of <code class="docutils literal">#define FOO</code>

353

in source or <code class="xref std std-option docutils literal">-DFOO</code>

354

on Unix C compiler command

355

line)</td>

356

<td>a list of tuples</td>

357

</tr>

358

<tr class="row-even"><td>undef_macros</td>

359

<td>list of macros to undefine

360

explicitly</td>

361

<td>a list of strings</td>

362

</tr>

363

<tr class="row-odd"><td>library_dirs</td>

364

<td>list of directories to search

365

for C/C++ libraries at link

366

time</td>

367

<td>a list of strings</td>

368

</tr>

369

<tr class="row-even"><td>libraries</td>

370

<td>list of library names (not

371

filenames or paths) to link

372

against</td>

373

<td>a list of strings</td>

374

</tr>

375

<tr class="row-odd"><td>runtime_library_dirs</td>

376

<td>list of directories to search

377

for C/C++ libraries at run

378

time (for shared extensions,

379

this is when the extension is

380

loaded)</td>

381

<td>a list of strings</td>

382

</tr>

383

<tr class="row-even"><td>extra_objects</td>

384

<td>list of extra files to link

385

with (eg. object files not

386

implied by ‘sources’, static

387

library that must be

388

explicitly specified, binary

389

resource files, etc.)</td>

390

<td>a list of strings</td>

391

</tr>

392

<tr class="row-odd"><td>extra_compile_args</td>

393

<td>any extra platform- and

394

compiler-specific information

395

to use when compiling the

396

source files in ‘sources’. For

397

platforms and compilers where

398

a command line makes sense,

399

this is typically a list of

400

command-line arguments, but

401

for other platforms it could

402

be anything.</td>

403

<td>a list of strings</td>

404

</tr>

405

<tr class="row-even"><td>extra_link_args</td>

406

<td>any extra platform- and

407

compiler-specific information

408

to use when linking object

409

files together to create the

410

extension (or to create a new

411

static Python interpreter).

412

Similar interpretation as for

413

‘extra_compile_args’.</td>

414

<td>a list of strings</td>

415

</tr>

416

<tr class="row-odd"><td>export_symbols</td>

417

<td>list of symbols to be exported

418

from a shared extension. Not

419

used on all platforms, and not

420

generally necessary for Python

421

extensions, which typically

422

export exactly one symbol:

423

<code class="docutils literal">init</code> + extension_name.</td>

424

<td>a list of strings</td>

425

</tr>

426

<tr class="row-even"><td>depends</td>

427

<td>list of files that the

428

extension depends on</td>

429

<td>a list of strings</td>

430

</tr>

431

<tr class="row-odd"><td>language</td>

432

<td>extension language (i.e.

433

<code class="docutils literal">'c'</code>, <code class="docutils literal">'c++'</code>,

434

<code class="docutils literal">'objc'</code>). Will be detected

435

from the source extensions if

436

not provided.</td>

437

<td>a string</td>

438

</tr>

439

<tr class="row-even"><td>optional</td>

440

<td>specifies that a build failure

441

in the extension should not

442

abort the build process, but

443

simply skip the extension.</td>

444

<td>a boolean</td>

445

</tr>

446

</tbody>

447

</table>

448

</dd></dl>

449

450

451

452

class <code class="descclassname">distutils.core.</code><code class="descname">Distribution</code><a class="headerlink" href="#distutils.core.Distribution" title="Permalink to this definition">¶</a></dt>

453

<dd>A <a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal">Distribution</code></a> describes how to build, install and package up a Python

454

software package.

455

See the <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal">setup()</code></a> function for a list of keyword arguments accepted by the

456

Distribution constructor. <a class="reference internal" href="#distutils.core.setup" title="distutils.core.setup"><code class="xref py py-func docutils literal">setup()</code></a> creates a Distribution instance.

457

</dd></dl>

458

459

460

461

class <code class="descclassname">distutils.core.</code><code class="descname">Command</code><a class="headerlink" href="#distutils.core.Command" title="Permalink to this definition">¶</a></dt>

462

<dd>A <a class="reference internal" href="#distutils.core.Command" title="distutils.core.Command"><code class="xref py py-class docutils literal">Command</code></a> class (or rather, an instance of one of its subclasses)

463

implement a single distutils command.

464

</dd></dl>

465

466

</div>

467

468

<h2>10.2. <a class="reference internal" href="#module-distutils.ccompiler" title="distutils.ccompiler: Abstract CCompiler class"><code class="xref py py-mod docutils literal">distutils.ccompiler</code></a> — CCompiler base class<a class="headerlink" href="#module-distutils.ccompiler" title="Permalink to this headline">¶</a></h2>

469

This module provides the abstract base class for the <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal">CCompiler</code></a>

470

classes. A <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal">CCompiler</code></a> instance can be used for all the compile and

471

link steps needed to build a single project. Methods are provided to set

472

options for the compiler — macro definitions, include directories, link path,

473

libraries and the like.

474

This module provides the following functions.

475

476

477

<code class="descclassname">distutils.ccompiler.</code><code class="descname">gen_lib_options</code>(compiler, library_dirs, runtime_library_dirs, libraries)<a class="headerlink" href="#distutils.ccompiler.gen_lib_options" title="Permalink to this definition">¶</a></dt>

478

<dd>Generate linker options for searching library directories and linking with

479

specific libraries. libraries and library_dirs are, respectively, lists of

480

library names (not filenames!) and search directories. Returns a list of

481

command-line options suitable for use with some compiler (depending on the two

482

format strings passed in).

483

</dd></dl>

484

485

486

487

<code class="descclassname">distutils.ccompiler.</code><code class="descname">gen_preprocess_options</code>(macros, include_dirs)<a class="headerlink" href="#distutils.ccompiler.gen_preprocess_options" title="Permalink to this definition">¶</a></dt>

488

<dd>Generate C pre-processor options (<code class="xref std std-option docutils literal">-D</code>, <code class="xref std std-option docutils literal">-U</code>, <a class="reference internal" href="../using/cmdline.html#cmdoption-I"><code class="xref std std-option docutils literal">-I</code></a>) as

489

used by at least two types of compilers: the typical Unix compiler and Visual

490

C++. macros is the usual thing, a list of 1- or 2-tuples, where <code class="docutils literal">(name,)</code>

491

means undefine (<code class="xref std std-option docutils literal">-U</code>) macro name, and <code class="docutils literal">(name, value)</code> means define

492

(<code class="xref std std-option docutils literal">-D</code>) macro name to value. include_dirs is just a list of

493

directory names to be added to the header file search path (<a class="reference internal" href="../using/cmdline.html#cmdoption-I"><code class="xref std std-option docutils literal">-I</code></a>).

494

Returns a list of command-line options suitable for either Unix compilers or

495

Visual C++.

496

</dd></dl>

497

498

499

500

<code class="descclassname">distutils.ccompiler.</code><code class="descname">get_default_compiler</code>(osname, platform)<a class="headerlink" href="#distutils.ccompiler.get_default_compiler" title="Permalink to this definition">¶</a></dt>

501

<dd>Determine the default compiler to use for the given platform.

502

osname should be one of the standard Python OS names (i.e. the ones returned

503

by <code class="docutils literal">os.name</code>) and platform the common value returned by <code class="docutils literal">sys.platform</code> for

504

the platform in question.

505

The default values are <code class="docutils literal">os.name</code> and <code class="docutils literal">sys.platform</code> in case the parameters

506

are not given.

507

</dd></dl>

508

509

510

511

<code class="descclassname">distutils.ccompiler.</code><code class="descname">new_compiler</code>(plat=None, compiler=None, verbose=0, dry_run=0, force=0)<a class="headerlink" href="#distutils.ccompiler.new_compiler" title="Permalink to this definition">¶</a></dt>

512

<dd>Factory function to generate an instance of some CCompiler subclass for the

513

supplied platform/compiler combination. plat defaults to <code class="docutils literal">os.name</code> (eg.

514

<code class="docutils literal">'posix'</code>, <code class="docutils literal">'nt'</code>), and compiler defaults to the default compiler for

515

that platform. Currently only <code class="docutils literal">'posix'</code> and <code class="docutils literal">'nt'</code> are supported, and the

516

default compilers are “traditional Unix interface” (<code class="xref py py-class docutils literal">UnixCCompiler</code>

517

class) and Visual C++ (<code class="xref py py-class docutils literal">MSVCCompiler</code> class). Note that it’s perfectly

518

possible to ask for a Unix compiler object under Windows, and a Microsoft

519

compiler object under Unix—if you supply a value for compiler, plat is

520

ignored.

521

</dd></dl>

522

523

524

525

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

526

<dd>Print list of available compilers (used by the <code class="xref std std-option docutils literal">--help-compiler</code> options

527

to build, build_ext, build_clib).

528

</dd></dl>

529

530

531

532

class <code class="descclassname">distutils.ccompiler.</code><code class="descname">CCompiler</code>([verbose=0, dry_run=0, force=0])<a class="headerlink" href="#distutils.ccompiler.CCompiler" title="Permalink to this definition">¶</a></dt>

533

<dd>The abstract base class <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal">CCompiler</code></a> defines the interface that must be

534

implemented by real compiler classes. The class also has some utility methods

535

used by several compiler classes.

536

The basic idea behind a compiler abstraction class is that each instance can be

537

used for all the compile/link steps in building a single project. Thus,

538

attributes common to all of those compile and link steps — include

539

directories, macros to define, libraries to link against, etc. — are

540

attributes of the compiler instance. To allow for variability in how individual

541

files are treated, most of those attributes may be varied on a per-compilation

542

or per-link basis.

543

The constructor for each subclass creates an instance of the Compiler object.

544

Flags are verbose (show verbose output), dry_run (don’t actually execute the

545

steps) and force (rebuild everything, regardless of dependencies). All of

546

these flags default to <code class="docutils literal">0</code> (off). Note that you probably don’t want to

547

instantiate <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal">CCompiler</code></a> or one of its subclasses directly - use the

548

<code class="xref py py-func docutils literal">distutils.CCompiler.new_compiler()</code> factory function instead.

549

The following methods allow you to manually alter compiler options for the

550

instance of the Compiler class.

551

552

553

<code class="descname">add_include_dir</code>(dir)<a class="headerlink" href="#distutils.ccompiler.CCompiler.add_include_dir" title="Permalink to this definition">¶</a></dt>

554

<dd>Add dir to the list of directories that will be searched for header files.

555

The compiler is instructed to search directories in the order in which they are

556

supplied by successive calls to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_include_dir" title="distutils.ccompiler.CCompiler.add_include_dir"><code class="xref py py-meth docutils literal">add_include_dir()</code></a>.

557

</dd></dl>

558

559

560

561

<code class="descname">set_include_dirs</code>(dirs)<a class="headerlink" href="#distutils.ccompiler.CCompiler.set_include_dirs" title="Permalink to this definition">¶</a></dt>

562

<dd>Set the list of directories that will be searched to dirs (a list of strings).

563

Overrides any preceding calls to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_include_dir" title="distutils.ccompiler.CCompiler.add_include_dir"><code class="xref py py-meth docutils literal">add_include_dir()</code></a>; subsequent calls to

564

<a class="reference internal" href="#distutils.ccompiler.CCompiler.add_include_dir" title="distutils.ccompiler.CCompiler.add_include_dir"><code class="xref py py-meth docutils literal">add_include_dir()</code></a> add to the list passed to <a class="reference internal" href="#distutils.ccompiler.CCompiler.set_include_dirs" title="distutils.ccompiler.CCompiler.set_include_dirs"><code class="xref py py-meth docutils literal">set_include_dirs()</code></a>.

565

This does not affect any list of standard include directories that the compiler

566

may search by default.

567

</dd></dl>

568

569

570

571

<code class="descname">add_library</code>(libname)<a class="headerlink" href="#distutils.ccompiler.CCompiler.add_library" title="Permalink to this definition">¶</a></dt>

572

<dd>Add libname to the list of libraries that will be included in all links driven

573

by this compiler object. Note that libname should *not* be the name of a

574

file containing a library, but the name of the library itself: the actual

575

filename will be inferred by the linker, the compiler, or the compiler class

576

(depending on the platform).

577

The linker will be instructed to link against libraries in the order they were

578

supplied to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_library" title="distutils.ccompiler.CCompiler.add_library"><code class="xref py py-meth docutils literal">add_library()</code></a> and/or <a class="reference internal" href="#distutils.ccompiler.CCompiler.set_libraries" title="distutils.ccompiler.CCompiler.set_libraries"><code class="xref py py-meth docutils literal">set_libraries()</code></a>. It is perfectly

579

valid to duplicate library names; the linker will be instructed to link against

580

libraries as many times as they are mentioned.

581

</dd></dl>

582

583

584

585

<code class="descname">set_libraries</code>(libnames)<a class="headerlink" href="#distutils.ccompiler.CCompiler.set_libraries" title="Permalink to this definition">¶</a></dt>

586

<dd>Set the list of libraries to be included in all links driven by this compiler

587

object to libnames (a list of strings). This does not affect any standard

588

system libraries that the linker may include by default.

589

</dd></dl>

590

591

592

593

<code class="descname">add_library_dir</code>(dir)<a class="headerlink" href="#distutils.ccompiler.CCompiler.add_library_dir" title="Permalink to this definition">¶</a></dt>

594

<dd>Add dir to the list of directories that will be searched for libraries

595

specified to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_library" title="distutils.ccompiler.CCompiler.add_library"><code class="xref py py-meth docutils literal">add_library()</code></a> and <a class="reference internal" href="#distutils.ccompiler.CCompiler.set_libraries" title="distutils.ccompiler.CCompiler.set_libraries"><code class="xref py py-meth docutils literal">set_libraries()</code></a>. The linker will be

596

instructed to search for libraries in the order they are supplied to

597

<a class="reference internal" href="#distutils.ccompiler.CCompiler.add_library_dir" title="distutils.ccompiler.CCompiler.add_library_dir"><code class="xref py py-meth docutils literal">add_library_dir()</code></a> and/or <a class="reference internal" href="#distutils.ccompiler.CCompiler.set_library_dirs" title="distutils.ccompiler.CCompiler.set_library_dirs"><code class="xref py py-meth docutils literal">set_library_dirs()</code></a>.

598

</dd></dl>

599

600

601

602

<code class="descname">set_library_dirs</code>(dirs)<a class="headerlink" href="#distutils.ccompiler.CCompiler.set_library_dirs" title="Permalink to this definition">¶</a></dt>

603

<dd>Set the list of library search directories to dirs (a list of strings). This

604

does not affect any standard library search path that the linker may search by

605

default.

606

</dd></dl>

607

608

609

610

<code class="descname">add_runtime_library_dir</code>(dir)<a class="headerlink" href="#distutils.ccompiler.CCompiler.add_runtime_library_dir" title="Permalink to this definition">¶</a></dt>

611

<dd>Add dir to the list of directories that will be searched for shared libraries

612

at runtime.

613

</dd></dl>

614

615

616

617

<code class="descname">set_runtime_library_dirs</code>(dirs)<a class="headerlink" href="#distutils.ccompiler.CCompiler.set_runtime_library_dirs" title="Permalink to this definition">¶</a></dt>

618

<dd>Set the list of directories to search for shared libraries at runtime to dirs

619

(a list of strings). This does not affect any standard search path that the

620

runtime linker may search by default.

621

</dd></dl>

622

623

624

625

<code class="descname">define_macro</code>(name[, value=None])<a class="headerlink" href="#distutils.ccompiler.CCompiler.define_macro" title="Permalink to this definition">¶</a></dt>

626

<dd>Define a preprocessor macro for all compilations driven by this compiler object.

627

The optional parameter value should be a string; if it is not supplied, then

628

the macro will be defined without an explicit value and the exact outcome

629

depends on the compiler used.

630

</dd></dl>

631

632

633

634

<code class="descname">undefine_macro</code>(name)<a class="headerlink" href="#distutils.ccompiler.CCompiler.undefine_macro" title="Permalink to this definition">¶</a></dt>

635

<dd>Undefine a preprocessor macro for all compilations driven by this compiler

636

object. If the same macro is defined by <a class="reference internal" href="#distutils.ccompiler.CCompiler.define_macro" title="distutils.ccompiler.CCompiler.define_macro"><code class="xref py py-meth docutils literal">define_macro()</code></a> and

637

undefined by <a class="reference internal" href="#distutils.ccompiler.CCompiler.undefine_macro" title="distutils.ccompiler.CCompiler.undefine_macro"><code class="xref py py-meth docutils literal">undefine_macro()</code></a> the last call takes precedence

638

(including multiple redefinitions or undefinitions). If the macro is

639

redefined/undefined on a per-compilation basis (ie. in the call to

640

<a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-meth docutils literal">compile()</code></a>), then that takes precedence.

641

</dd></dl>

642

643

644

645

<code class="descname">add_link_object</code>(object)<a class="headerlink" href="#distutils.ccompiler.CCompiler.add_link_object" title="Permalink to this definition">¶</a></dt>

646

<dd>Add object to the list of object files (or analogues, such as explicitly named

647

library files or the output of “resource compilers”) to be included in every

648

link driven by this compiler object.

649

</dd></dl>

650

651

652

653

<code class="descname">set_link_objects</code>(objects)<a class="headerlink" href="#distutils.ccompiler.CCompiler.set_link_objects" title="Permalink to this definition">¶</a></dt>

654

<dd>Set the list of object files (or analogues) to be included in every link to

655

objects. This does not affect any standard object files that the linker may

656

include by default (such as system libraries).

657

</dd></dl>

658

659

The following methods implement methods for autodetection of compiler options,

660

providing some functionality similar to GNU autoconf.

661

662

663

<code class="descname">detect_language</code>(sources)<a class="headerlink" href="#distutils.ccompiler.CCompiler.detect_language" title="Permalink to this definition">¶</a></dt>

664

<dd>Detect the language of a given file, or list of files. Uses the instance

665

attributes <code class="xref py py-attr docutils literal">language_map</code> (a dictionary), and <code class="xref py py-attr docutils literal">language_order</code> (a

666

list) to do the job.

667

</dd></dl>

668

669

670

671

<code class="descname">find_library_file</code>(dirs, lib[, debug=0])<a class="headerlink" href="#distutils.ccompiler.CCompiler.find_library_file" title="Permalink to this definition">¶</a></dt>

672

<dd>Search the specified list of directories for a static or shared library file

673

lib and return the full path to that file. If debug is true, look for a

674

debugging version (if that makes sense on the current platform). Return

675

<code class="docutils literal">None</code> if lib wasn’t found in any of the specified directories.

676

</dd></dl>

677

678

679

680

<code class="descname">has_function</code>(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])<a class="headerlink" href="#distutils.ccompiler.CCompiler.has_function" title="Permalink to this definition">¶</a></dt>

681

<dd>Return a boolean indicating whether funcname is supported on the current

682

platform. The optional arguments can be used to augment the compilation

683

environment by providing additional include files and paths and libraries and

684

paths.

685

</dd></dl>

686

687

688

689

<code class="descname">library_dir_option</code>(dir)<a class="headerlink" href="#distutils.ccompiler.CCompiler.library_dir_option" title="Permalink to this definition">¶</a></dt>

690

<dd>Return the compiler option to add dir to the list of directories searched for

691

libraries.

692

</dd></dl>

693

694

695

696

<code class="descname">library_option</code>(lib)<a class="headerlink" href="#distutils.ccompiler.CCompiler.library_option" title="Permalink to this definition">¶</a></dt>

697

<dd>Return the compiler option to add lib to the list of libraries linked into the

698

shared library or executable.

699

</dd></dl>

700

701

702

703

<code class="descname">runtime_library_dir_option</code>(dir)<a class="headerlink" href="#distutils.ccompiler.CCompiler.runtime_library_dir_option" title="Permalink to this definition">¶</a></dt>

704

<dd>Return the compiler option to add dir to the list of directories searched for

705

runtime libraries.

706

</dd></dl>

707

708

709

710

<code class="descname">set_executables</code>(**args)<a class="headerlink" href="#distutils.ccompiler.CCompiler.set_executables" title="Permalink to this definition">¶</a></dt>

711

<dd>Define the executables (and options for them) that will be run to perform the

712

various stages of compilation. The exact set of executables that may be

713

specified here depends on the compiler class (via the ‘executables’ class

714

attribute), but most will have:

715

716

717

718

719

</colgroup>

720

721

<tr class="row-odd"><th class="head">attribute</th>

722

<th class="head">description</th>

723

</tr>

724

</thead>

725

726

<tr class="row-even"><td>compiler</td>

727

<td>the C/C++ compiler</td>

728

</tr>

729

<tr class="row-odd"><td>linker_so</td>

730

<td>linker used to create shared objects and

731

libraries</td>

732

</tr>

733

<tr class="row-even"><td>linker_exe</td>

734

<td>linker used to create binary executables</td>

735

</tr>

736

<tr class="row-odd"><td>archiver</td>

737

<td>static library creator</td>

738

</tr>

739

</tbody>

740

</table>

741

On platforms with a command-line (Unix, DOS/Windows), each of these is a string

742

that will be split into executable name and (optional) list of arguments.

743

(Splitting the string is done similarly to how Unix shells operate: words are

744

delimited by spaces, but quotes and backslashes can override this. See

745

<a class="reference internal" href="#distutils.util.split_quoted" title="distutils.util.split_quoted"><code class="xref py py-func docutils literal">distutils.util.split_quoted()</code></a>.)

746

</dd></dl>

747

748

The following methods invoke stages in the build process.

749

750

751

<code class="descname">compile</code>(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])<a class="headerlink" href="#distutils.ccompiler.CCompiler.compile" title="Permalink to this definition">¶</a></dt>

752

<dd>Compile one or more source files. Generates object files (e.g. transforms a

753

<code class="file docutils literal">.c</code> file to a <code class="file docutils literal">.o</code> file.)

754

sources must be a list of filenames, most likely C/C++ files, but in reality

755

anything that can be handled by a particular compiler and compiler class (eg.

756

<code class="xref py py-class docutils literal">MSVCCompiler</code> can handle resource files in sources). Return a list of

757

object filenames, one per source filename in sources. Depending on the

758

implementation, not all source files will necessarily be compiled, but all

759

corresponding object filenames will be returned.

760

If output_dir is given, object files will be put under it, while retaining

761

their original path component. That is, <code class="file docutils literal">foo/bar.c</code> normally compiles to

762

<code class="file docutils literal">foo/bar.o</code> (for a Unix implementation); if output_dir is build, then

763

it would compile to <code class="file docutils literal">build/foo/bar.o</code>.

764

macros, if given, must be a list of macro definitions. A macro definition is

765

either a <code class="docutils literal">(name, value)</code> 2-tuple or a <code class="docutils literal">(name,)</code> 1-tuple. The former defines

766

a macro; if the value is <code class="docutils literal">None</code>, the macro is defined without an explicit

767

value. The 1-tuple case undefines a macro. Later

768

definitions/redefinitions/undefinitions take precedence.

769

include_dirs, if given, must be a list of strings, the directories to add to

770

the default include file search path for this compilation only.

771

debug is a boolean; if true, the compiler will be instructed to output debug

772

symbols in (or alongside) the object file(s).

773

extra_preargs and extra_postargs are implementation-dependent. On platforms

774

that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most

775

likely lists of strings: extra command-line arguments to prepend/append to the

776

compiler command line. On other platforms, consult the implementation class

777

documentation. In any event, they are intended as an escape hatch for those

778

occasions when the abstract compiler framework doesn’t cut the mustard.

779

depends, if given, is a list of filenames that all targets depend on. If a

780

source file is older than any file in depends, then the source file will be

781

recompiled. This supports dependency tracking, but only at a coarse

782

granularity.

783

Raises <code class="xref py py-exc docutils literal">CompileError</code> on failure.

784

</dd></dl>

785

786

787

788

<code class="descname">create_static_lib</code>(objects, output_libname[, output_dir=None, debug=0, target_lang=None])<a class="headerlink" href="#distutils.ccompiler.CCompiler.create_static_lib" title="Permalink to this definition">¶</a></dt>

789

<dd>Link a bunch of stuff together to create a static library file. The “bunch of

790

stuff” consists of the list of object files supplied as objects, the extra

791

object files supplied to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_link_object" title="distutils.ccompiler.CCompiler.add_link_object"><code class="xref py py-meth docutils literal">add_link_object()</code></a> and/or

792

<a class="reference internal" href="#distutils.ccompiler.CCompiler.set_link_objects" title="distutils.ccompiler.CCompiler.set_link_objects"><code class="xref py py-meth docutils literal">set_link_objects()</code></a>, the libraries supplied to <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_library" title="distutils.ccompiler.CCompiler.add_library"><code class="xref py py-meth docutils literal">add_library()</code></a> and/or

793

<a class="reference internal" href="#distutils.ccompiler.CCompiler.set_libraries" title="distutils.ccompiler.CCompiler.set_libraries"><code class="xref py py-meth docutils literal">set_libraries()</code></a>, and the libraries supplied as libraries (if any).

794

output_libname should be a library name, not a filename; the filename will be

795

inferred from the library name. output_dir is the directory where the library

796

file will be put.

797

debug is a boolean; if true, debugging information will be included in the

798

library (note that on most platforms, it is the compile step where this matters:

799

the debug flag is included here just for consistency).

800

target_lang is the target language for which the given objects are being

801

compiled. This allows specific linkage time treatment of certain languages.

802

Raises <code class="xref py py-exc docutils literal">LibError</code> on failure.

803

</dd></dl>

804

805

806

807

<code class="descname">link</code>(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])<a class="headerlink" href="#distutils.ccompiler.CCompiler.link" title="Permalink to this definition">¶</a></dt>

808

<dd>Link a bunch of stuff together to create an executable or shared library file.

809

The “bunch of stuff” consists of the list of object files supplied as objects.

810

output_filename should be a filename. If output_dir is supplied,

811

output_filename is relative to it (i.e. output_filename can provide

812

directory components if needed).

813

libraries is a list of libraries to link against. These are library names,

814

not filenames, since they’re translated into filenames in a platform-specific

815

way (eg. foo becomes <code class="file docutils literal">libfoo.a</code> on Unix and <code class="file docutils literal">foo.lib</code> on

816

DOS/Windows). However, they can include a directory component, which means the

817

linker will look in that specific directory rather than searching all the normal

818

locations.

819

library_dirs, if supplied, should be a list of directories to search for

820

libraries that were specified as bare library names (ie. no directory

821

component). These are on top of the system default and those supplied to

822

823

is a list of directories that will be embedded into the shared library and used

824

to search for other shared libraries that *it* depends on at run-time. (This

825

may only be relevant on Unix.)

826

export_symbols is a list of symbols that the shared library will export.

827

(This appears to be relevant only on Windows.)

828

debug is as for <a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-meth docutils literal">compile()</code></a> and <a class="reference internal" href="#distutils.ccompiler.CCompiler.create_static_lib" title="distutils.ccompiler.CCompiler.create_static_lib"><code class="xref py py-meth docutils literal">create_static_lib()</code></a>, with the

829

slight distinction that it actually matters on most platforms (as opposed to

830

<a class="reference internal" href="#distutils.ccompiler.CCompiler.create_static_lib" title="distutils.ccompiler.CCompiler.create_static_lib"><code class="xref py py-meth docutils literal">create_static_lib()</code></a>, which includes a debug flag mostly for form’s

831

sake).

832

extra_preargs and extra_postargs are as for <a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-meth docutils literal">compile()</code></a> (except of

833

course that they supply command-line arguments for the particular linker being

834

used).

835

target_lang is the target language for which the given objects are being

836

compiled. This allows specific linkage time treatment of certain languages.

837

Raises <code class="xref py py-exc docutils literal">LinkError</code> on failure.

838

</dd></dl>

839

840

841

842

<code class="descname">link_executable</code>(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])<a class="headerlink" href="#distutils.ccompiler.CCompiler.link_executable" title="Permalink to this definition">¶</a></dt>

843

<dd>Link an executable. output_progname is the name of the file executable, while

844

objects are a list of object filenames to link in. Other arguments are as for

845

the <a class="reference internal" href="#distutils.ccompiler.CCompiler.link" title="distutils.ccompiler.CCompiler.link"><code class="xref py py-meth docutils literal">link()</code></a> method.

846

</dd></dl>

847

848

849

850

<code class="descname">link_shared_lib</code>(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])<a class="headerlink" href="#distutils.ccompiler.CCompiler.link_shared_lib" title="Permalink to this definition">¶</a></dt>

851

<dd>Link a shared library. output_libname is the name of the output library,

852

while objects is a list of object filenames to link in. Other arguments are

853

as for the <a class="reference internal" href="#distutils.ccompiler.CCompiler.link" title="distutils.ccompiler.CCompiler.link"><code class="xref py py-meth docutils literal">link()</code></a> method.

854

</dd></dl>

855

856

857

858

<code class="descname">link_shared_object</code>(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])<a class="headerlink" href="#distutils.ccompiler.CCompiler.link_shared_object" title="Permalink to this definition">¶</a></dt>

859

<dd>Link a shared object. output_filename is the name of the shared object that

860

will be created, while objects is a list of object filenames to link in.

861

Other arguments are as for the <a class="reference internal" href="#distutils.ccompiler.CCompiler.link" title="distutils.ccompiler.CCompiler.link"><code class="xref py py-meth docutils literal">link()</code></a> method.

862

</dd></dl>

863

864

865

866

<code class="descname">preprocess</code>(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])<a class="headerlink" href="#distutils.ccompiler.CCompiler.preprocess" title="Permalink to this definition">¶</a></dt>

867

<dd>Preprocess a single C/C++ source file, named in source. Output will be written

868

to file named output_file, or stdout if output_file not supplied.

869

macros is a list of macro definitions as for <a class="reference internal" href="../library/functions.html#compile" title="compile"><code class="xref py py-meth docutils literal">compile()</code></a>, which will

870

augment the macros set with <a class="reference internal" href="#distutils.ccompiler.CCompiler.define_macro" title="distutils.ccompiler.CCompiler.define_macro"><code class="xref py py-meth docutils literal">define_macro()</code></a> and <a class="reference internal" href="#distutils.ccompiler.CCompiler.undefine_macro" title="distutils.ccompiler.CCompiler.undefine_macro"><code class="xref py py-meth docutils literal">undefine_macro()</code></a>.

871

include_dirs is a list of directory names that will be added to the default

872

list, in the same way as <a class="reference internal" href="#distutils.ccompiler.CCompiler.add_include_dir" title="distutils.ccompiler.CCompiler.add_include_dir"><code class="xref py py-meth docutils literal">add_include_dir()</code></a>.

873

Raises <code class="xref py py-exc docutils literal">PreprocessError</code> on failure.

874

</dd></dl>

875

876

The following utility methods are defined by the <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal">CCompiler</code></a> class, for

877

use by the various concrete subclasses.

878

879

880

<code class="descname">executable_filename</code>(basename[, strip_dir=0, output_dir=''])<a class="headerlink" href="#distutils.ccompiler.CCompiler.executable_filename" title="Permalink to this definition">¶</a></dt>

881

<dd>Returns the filename of the executable for the given basename. Typically for

882

non-Windows platforms this is the same as the basename, while Windows will get

883

a <code class="file docutils literal">.exe</code> added.

884

</dd></dl>

885

886

887

888

<code class="descname">library_filename</code>(libname[, lib_type='static', strip_dir=0, output_dir=''])<a class="headerlink" href="#distutils.ccompiler.CCompiler.library_filename" title="Permalink to this definition">¶</a></dt>

889

<dd>Returns the filename for the given library name on the current platform. On Unix

890

a library with lib_type of <code class="docutils literal">'static'</code> will typically be of the form

891

<code class="file docutils literal">liblibname.a</code>, while a lib_type of <code class="docutils literal">'dynamic'</code> will be of the form

892

<code class="file docutils literal">liblibname.so</code>.

893

</dd></dl>

894

895

896

897

<code class="descname">object_filenames</code>(source_filenames[, strip_dir=0, output_dir=''])<a class="headerlink" href="#distutils.ccompiler.CCompiler.object_filenames" title="Permalink to this definition">¶</a></dt>

898

<dd>Returns the name of the object files for the given source files.

899

source_filenames should be a list of filenames.

900

</dd></dl>

901

902

903

904

<code class="descname">shared_object_filename</code>(basename[, strip_dir=0, output_dir=''])<a class="headerlink" href="#distutils.ccompiler.CCompiler.shared_object_filename" title="Permalink to this definition">¶</a></dt>

905

<dd>Returns the name of a shared object file for the given file name basename.

906

</dd></dl>

907

908

909

910

<code class="descname">execute</code>(func, args[, msg=None, level=1])<a class="headerlink" href="#distutils.ccompiler.CCompiler.execute" title="Permalink to this definition">¶</a></dt>

911

<dd>Invokes <a class="reference internal" href="#distutils.util.execute" title="distutils.util.execute"><code class="xref py py-func docutils literal">distutils.util.execute()</code></a>. This method invokes a Python function

912

func with the given arguments args, after logging and taking into account

913

the dry_run flag.

914

</dd></dl>

915

916

917

918

<code class="descname">spawn</code>(cmd)<a class="headerlink" href="#distutils.ccompiler.CCompiler.spawn" title="Permalink to this definition">¶</a></dt>

919

<dd>Invokes <code class="xref py py-func docutils literal">distutils.util.spawn()</code>. This invokes an external process to run

920

the given command.

921

</dd></dl>

922

923

924

925

<code class="descname">mkpath</code>(name[, mode=511])<a class="headerlink" href="#distutils.ccompiler.CCompiler.mkpath" title="Permalink to this definition">¶</a></dt>

926

<dd>Invokes <a class="reference internal" href="#distutils.dir_util.mkpath" title="distutils.dir_util.mkpath"><code class="xref py py-func docutils literal">distutils.dir_util.mkpath()</code></a>. This creates a directory and any

927

missing ancestor directories.

928

</dd></dl>

929

930

931

932

933

<dd>Invokes <a class="reference internal" href="#distutils.file_util.move_file" title="distutils.file_util.move_file"><code class="xref py py-meth docutils literal">distutils.file_util.move_file()</code></a>. Renames src to dst.

934

</dd></dl>

935

936

937

938

<code class="descname">announce</code>(msg[, level=1])<a class="headerlink" href="#distutils.ccompiler.CCompiler.announce" title="Permalink to this definition">¶</a></dt>

939

<dd>Write a message using <code class="xref py py-func docutils literal">distutils.log.debug()</code>.

940

</dd></dl>

941

942

943

944

945

<dd>Write a warning message msg to standard error.

946

</dd></dl>

947

948

949

950

<code class="descname">debug_print</code>(msg)<a class="headerlink" href="#distutils.ccompiler.CCompiler.debug_print" title="Permalink to this definition">¶</a></dt>

951

<dd>If the debug flag is set on this <a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal">CCompiler</code></a> instance, print msg to

952

standard output, otherwise do nothing.

953

</dd></dl>

954

955

</dd></dl>

956

957

</div>

958

959

<h2>10.3. <a class="reference internal" href="#module-distutils.unixccompiler" title="distutils.unixccompiler: UNIX C Compiler"><code class="xref py py-mod docutils literal">distutils.unixccompiler</code></a> — Unix C Compiler<a class="headerlink" href="#module-distutils.unixccompiler" title="Permalink to this headline">¶</a></h2>

960

This module provides the <code class="xref py py-class docutils literal">UnixCCompiler</code> class, a subclass of

961

<code class="xref py py-class docutils literal">CCompiler</code> that handles the typical Unix-style command-line C compiler:

962

963

<li>macros defined with <code class="xref std std-option docutils literal">-Dname[=value]</code></li>

964

<li>macros undefined with <code class="xref std std-option docutils literal">-Uname</code></li>

965

<li>include search directories specified with <code class="xref std std-option docutils literal">-Idir</code></li>

966

<li>libraries specified with <code class="xref std std-option docutils literal">-llib</code></li>

967

<li>library search directories specified with <code class="xref std std-option docutils literal">-Ldir</code></li>

968

<li>compile handled by cc (or similar) executable with <a class="reference internal" href="../using/cmdline.html#cmdoption-c"><code class="xref std std-option docutils literal">-c</code></a>

969

option: compiles <code class="file docutils literal">.c</code> to <code class="file docutils literal">.o</code></li>

970

<li>link static library handled by ar command (possibly with

971

ranlib)</li>

972

<li>link shared library handled by cc <code class="xref std std-option docutils literal">-shared</code></li>

973

</ul>

974

</div>

975

976

<h2>10.4. <a class="reference internal" href="#module-distutils.msvccompiler" title="distutils.msvccompiler: Microsoft Compiler"><code class="xref py py-mod docutils literal">distutils.msvccompiler</code></a> — Microsoft Compiler<a class="headerlink" href="#module-distutils.msvccompiler" title="Permalink to this headline">¶</a></h2>

977

This module provides <code class="xref py py-class docutils literal">MSVCCompiler</code>, an implementation of the abstract

978

<code class="xref py py-class docutils literal">CCompiler</code> class for Microsoft Visual Studio. Typically, extension

979

modules need to be compiled with the same compiler that was used to compile

980

Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python

981

2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium

982

binaries are created using the Platform SDK.

983

<code class="xref py py-class docutils literal">MSVCCompiler</code> will normally choose the right compiler, linker etc. on

984

its own. To override this choice, the environment variables DISTUTILS_USE_SDK

985

and MSSdk must be both set. MSSdk indicates that the current environment has

986

been setup by the SDK’s <code class="docutils literal">SetEnv.Cmd</code> script, or that the environment variables

987

had been registered when the SDK was installed; DISTUTILS_USE_SDK indicates

988

that the distutils user has made an explicit choice to override the compiler

989

selection by <code class="xref py py-class docutils literal">MSVCCompiler</code>.

990

</div>

991

992

<h2>10.5. <a class="reference internal" href="#module-distutils.bcppcompiler" title="distutils.bcppcompiler"><code class="xref py py-mod docutils literal">distutils.bcppcompiler</code></a> — Borland Compiler<a class="headerlink" href="#module-distutils.bcppcompiler" title="Permalink to this headline">¶</a></h2>

993

This module provides <code class="xref py py-class docutils literal">BorlandCCompiler</code>, an subclass of the abstract

994

<code class="xref py py-class docutils literal">CCompiler</code> class for the Borland C++ compiler.

995

</div>

996

997

<h2>10.6. <code class="xref py py-mod docutils literal">distutils.cygwincompiler</code> — Cygwin Compiler<a class="headerlink" href="#module-distutils.cygwinccompiler" title="Permalink to this headline">¶</a></h2>

998

This module provides the <code class="xref py py-class docutils literal">CygwinCCompiler</code> class, a subclass of

999

<code class="xref py py-class docutils literal">UnixCCompiler</code> that handles the Cygwin port of the GNU C compiler to

1000

Windows. It also contains the Mingw32CCompiler class which handles the mingw32

1001

port of GCC (same as cygwin in no-cygwin mode).

1002

</div>

1003

1004

<h2>10.7. <a class="reference internal" href="#module-distutils.archive_util" title="distutils.archive_util: Utility functions for creating archive files (tarballs, zip files, ...)"><code class="xref py py-mod docutils literal">distutils.archive_util</code></a> — Archiving utilities<a class="headerlink" href="#module-distutils.archive_util" title="Permalink to this headline">¶</a></h2>

1005

This module provides a few functions for creating archive files, such as

1006

tarballs or zipfiles.

1007

1008

1009

<code class="descclassname">distutils.archive_util.</code><code class="descname">make_archive</code>(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])<a class="headerlink" href="#distutils.archive_util.make_archive" title="Permalink to this definition">¶</a></dt>

1010

<dd>Create an archive file (eg. <code class="docutils literal">zip</code> or <code class="docutils literal">tar</code>). base_name is the name of

1011

the file to create, minus any format-specific extension; format is the

1012

archive format: one of <code class="docutils literal">zip</code>, <code class="docutils literal">tar</code>, <code class="docutils literal">gztar</code>, <code class="docutils literal">bztar</code>, <code class="docutils literal">xztar</code>, or

1013

<code class="docutils literal">ztar</code>. root_dir is a directory that will be the root directory of the

1014

archive; ie. we typically <code class="docutils literal">chdir</code> into root_dir before creating the

1015

archive. base_dir is the directory where we start archiving from; ie.

1016

base_dir will be the common prefix of all files and directories in the

1017

archive. root_dir and base_dir both default to the current directory.

1018

Returns the name of the archive file.

1019

</dd></dl>

1020

1021

1022

1023

<code class="descclassname">distutils.archive_util.</code><code class="descname">make_tarball</code>(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])<a class="headerlink" href="#distutils.archive_util.make_tarball" title="Permalink to this definition">¶</a></dt>

1024

<dd>‘Create an (optional compressed) archive as a tar file from all files in and

1025

under base_dir. compress must be <code class="docutils literal">'gzip'</code> (the default),

1026

<code class="docutils literal">'bzip2'</code>, <code class="docutils literal">'xz'</code>, <code class="docutils literal">'compress'</code>, or <code class="docutils literal">None</code>. For the <code class="docutils literal">'compress'</code>

1027

method the compression utility named by compress must be on the

1028

default program search path, so this is probably Unix-specific. The output

1029

tar file will be named <code class="file docutils literal">base_dir.tar</code>, possibly plus the appropriate

1030

compression extension (<code class="docutils literal">.gz</code>, <code class="docutils literal">.bz2</code>, <code class="docutils literal">.xz</code> or <code class="docutils literal">.Z</code>). Return the

1031

output filename.

1032

</dd></dl>

1033

1034

1035

1036

<code class="descclassname">distutils.archive_util.</code><code class="descname">make_zipfile</code>(base_name, base_dir[, verbose=0, dry_run=0])<a class="headerlink" href="#distutils.archive_util.make_zipfile" title="Permalink to this definition">¶</a></dt>

1037

<dd>Create a zip file from all files in and under base_dir. The output zip file

1038

will be named base_name + <code class="file docutils literal">.zip</code>. Uses either the <a class="reference internal" href="../library/zipfile.html#module-zipfile" title="zipfile: Read and write ZIP-format archive files."><code class="xref py py-mod docutils literal">zipfile</code></a> Python

1039

module (if available) or the InfoZIP <code class="file docutils literal">zip</code> utility (if installed and

1040

found on the default search path). If neither tool is available, raises

1041

<code class="xref py py-exc docutils literal">DistutilsExecError</code>. Returns the name of the output zip file.

1042

</dd></dl>

1043

1044

</div>

1045

1046

<h2>10.8. <a class="reference internal" href="#module-distutils.dep_util" title="distutils.dep_util: Utility functions for simple dependency checking"><code class="xref py py-mod docutils literal">distutils.dep_util</code></a> — Dependency checking<a class="headerlink" href="#module-distutils.dep_util" title="Permalink to this headline">¶</a></h2>

1047

This module provides functions for performing simple, timestamp-based

1048

dependency of files and groups of files; also, functions based entirely on such

1049

timestamp dependency analysis.

1050

1051

1052

<code class="descclassname">distutils.dep_util.</code><code class="descname">newer</code>(source, target)<a class="headerlink" href="#distutils.dep_util.newer" title="Permalink to this definition">¶</a></dt>

1053

<dd>Return true if source exists and is more recently modified than target, or

1054

if source exists and target doesn’t. Return false if both exist and target

1055

is the same age or newer than source. Raise <code class="xref py py-exc docutils literal">DistutilsFileError</code> if

1056

source does not exist.

1057

</dd></dl>

1058

1059

1060

1061

<code class="descclassname">distutils.dep_util.</code><code class="descname">newer_pairwise</code>(sources, targets)<a class="headerlink" href="#distutils.dep_util.newer_pairwise" title="Permalink to this definition">¶</a></dt>

1062

<dd>Walk two filename lists in parallel, testing if each source is newer than its

1063

corresponding target. Return a pair of lists (sources, targets) where

1064

source is newer than target, according to the semantics of <a class="reference internal" href="#distutils.dep_util.newer" title="distutils.dep_util.newer"><code class="xref py py-func docutils literal">newer()</code></a>.

1065

</dd></dl>

1066

1067

1068

1069

<code class="descclassname">distutils.dep_util.</code><code class="descname">newer_group</code>(sources, target[, missing='error'])<a class="headerlink" href="#distutils.dep_util.newer_group" title="Permalink to this definition">¶</a></dt>

1070

<dd>Return true if target is out-of-date with respect to any file listed in

1071

sources In other words, if target exists and is newer than every file in

1072

sources, return false; otherwise return true. missing controls what we do

1073

when a source file is missing; the default (<code class="docutils literal">'error'</code>) is to blow up with an

1074

<a class="reference internal" href="../library/exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> from inside <a class="reference internal" href="../library/os.html#os.stat" title="os.stat"><code class="xref py py-func docutils literal">os.stat()</code></a>; if it is <code class="docutils literal">'ignore'</code>, we silently

1075

drop any missing source files; if it is <code class="docutils literal">'newer'</code>, any missing source files

1076

make us assume that target is out-of-date (this is handy in “dry-run” mode:

1077

it’ll make you pretend to carry out commands that wouldn’t work because inputs

1078

are missing, but that doesn’t matter because you’re not actually going to run

1079

the commands).

1080

</dd></dl>

1081

1082

</div>

1083

1084

<h2>10.9. <a class="reference internal" href="#module-distutils.dir_util" title="distutils.dir_util: Utility functions for operating on directories and directory trees"><code class="xref py py-mod docutils literal">distutils.dir_util</code></a> — Directory tree operations<a class="headerlink" href="#module-distutils.dir_util" title="Permalink to this headline">¶</a></h2>

1085

This module provides functions for operating on directories and trees of

1086

directories.

1087

1088

1089

<code class="descclassname">distutils.dir_util.</code><code class="descname">mkpath</code>(name[, mode=0o777, verbose=0, dry_run=0])<a class="headerlink" href="#distutils.dir_util.mkpath" title="Permalink to this definition">¶</a></dt>

1090

<dd>Create a directory and any missing ancestor directories. If the directory

1091

already exists (or if name is the empty string, which means the current

1092

directory, which of course exists), then do nothing. Raise

1093

<code class="xref py py-exc docutils literal">DistutilsFileError</code> if unable to create some directory along the way (eg.

1094

some sub-path exists, but is a file rather than a directory). If verbose is

1095

true, print a one-line summary of each mkdir to stdout. Return the list of

1096

directories actually created.

1097

</dd></dl>

1098

1099

1100

1101

<code class="descclassname">distutils.dir_util.</code><code class="descname">create_tree</code>(base_dir, files[, mode=0o777, verbose=0, dry_run=0])<a class="headerlink" href="#distutils.dir_util.create_tree" title="Permalink to this definition">¶</a></dt>

1102

<dd>Create all the empty directories under base_dir needed to put files there.

1103

base_dir is just the name of a directory which doesn’t necessarily exist

1104

yet; files is a list of filenames to be interpreted relative to base_dir.

1105

base_dir + the directory portion of every file in files will be created if

1106

it doesn’t already exist. mode, verbose and dry_run flags are as for

1107

<a class="reference internal" href="#distutils.dir_util.mkpath" title="distutils.dir_util.mkpath"><code class="xref py py-func docutils literal">mkpath()</code></a>.

1108

</dd></dl>

1109

1110

1111

1112

<code class="descclassname">distutils.dir_util.</code><code class="descname">copy_tree</code>(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])<a class="headerlink" href="#distutils.dir_util.copy_tree" title="Permalink to this definition">¶</a></dt>

1113

<dd>Copy an entire directory tree src to a new location dst. Both src and

1114

dst must be directory names. If src is not a directory, raise

1115

<code class="xref py py-exc docutils literal">DistutilsFileError</code>. If dst does not exist, it is created with

1116

<a class="reference internal" href="#distutils.dir_util.mkpath" title="distutils.dir_util.mkpath"><code class="xref py py-func docutils literal">mkpath()</code></a>. The end result of the copy is that every file in src is

1117

copied to dst, and directories under src are recursively copied to dst.

1118

Return the list of files that were copied or might have been copied, using their

1119

output name. The return value is unaffected by update or dry_run: it is

1120

simply the list of all files under src, with the names changed to be under

1121

dst.

1122

preserve_mode and preserve_times are the same as for

1123

<a class="reference internal" href="#distutils.file_util.copy_file" title="distutils.file_util.copy_file"><code class="xref py py-func docutils literal">distutils.file_util.copy_file()</code></a>; note that they only apply to

1124

regular files, not to

1125

directories. If preserve_symlinks is true, symlinks will be copied as

1126

symlinks (on platforms that support them!); otherwise (the default), the

1127

destination of the symlink will be copied. update and verbose are the same

1128

as for <code class="xref py py-func docutils literal">copy_file()</code>.

1129

Files in src that begin with <code class="file docutils literal">.nfs</code> are skipped (more information on

1130

these files is available in answer D2 of the <a class="reference external" href="http://nfs.sourceforge.net/#section_d">NFS FAQ page</a>).

1131

1132

Changed in version 3.3.1: NFS files are ignored.

1133

</div>

1134

</dd></dl>

1135

1136

1137

1138

<code class="descclassname">distutils.dir_util.</code><code class="descname">remove_tree</code>(directory[, verbose=0, dry_run=0])<a class="headerlink" href="#distutils.dir_util.remove_tree" title="Permalink to this definition">¶</a></dt>

1139

<dd>Recursively remove directory and all files and directories underneath it. Any

1140

errors are ignored (apart from being reported to <code class="docutils literal">sys.stdout</code> if verbose is

1141

true).

1142

</dd></dl>

1143

1144

</div>

1145

1146

<h2>10.10. <a class="reference internal" href="#module-distutils.file_util" title="distutils.file_util: Utility functions for operating on single files"><code class="xref py py-mod docutils literal">distutils.file_util</code></a> — Single file operations<a class="headerlink" href="#module-distutils.file_util" title="Permalink to this headline">¶</a></h2>

1147

This module contains some utility functions for operating on individual files.

1148

1149

1150

<code class="descclassname">distutils.file_util.</code><code class="descname">copy_file</code>(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])<a class="headerlink" href="#distutils.file_util.copy_file" title="Permalink to this definition">¶</a></dt>

1151

<dd>Copy file src to dst. If dst is a directory, then src is copied there

1152

with the same name; otherwise, it must be a filename. (If the file exists, it

1153

will be ruthlessly clobbered.) If preserve_mode is true (the default), the

1154

file’s mode (type and permission bits, or whatever is analogous on the

1155

current platform) is copied. If preserve_times is true (the default), the

1156

last-modified and last-access times are copied as well. If update is true,

1157

src will only be copied if dst does not exist, or if dst does exist but

1158

is older than src.

1159

link allows you to make hard links (using <a class="reference internal" href="../library/os.html#os.link" title="os.link"><code class="xref py py-func docutils literal">os.link()</code></a>) or symbolic links

1160

(using <a class="reference internal" href="../library/os.html#os.symlink" title="os.symlink"><code class="xref py py-func docutils literal">os.symlink()</code></a>) instead of copying: set it to <code class="docutils literal">'hard'</code> or

1161

<code class="docutils literal">'sym'</code>; if it is <code class="docutils literal">None</code> (the default), files are copied. Don’t set link

1162

on systems that don’t support it: <a class="reference internal" href="#distutils.file_util.copy_file" title="distutils.file_util.copy_file"><code class="xref py py-func docutils literal">copy_file()</code></a> doesn’t check if hard or

1163

symbolic linking is available. It uses <code class="xref py py-func docutils literal">_copy_file_contents()</code> to copy file

1164

contents.

1165

Return a tuple <code class="docutils literal">(dest_name, copied)</code>: dest_name is the actual name of the

1166

output file, and copied is true if the file was copied (or would have been

1167

copied, if dry_run true).

1168

</dd></dl>

1169

1170

1171

1172

<code class="descclassname">distutils.file_util.</code><code class="descname">move_file</code>(src, dst[, verbose, dry_run])<a class="headerlink" href="#distutils.file_util.move_file" title="Permalink to this definition">¶</a></dt>

1173

<dd>Move file src to dst. If dst is a directory, the file will be moved into

1174

it with the same name; otherwise, src is just renamed to dst. Returns the

1175

new full name of the file.

1176

1177

Warning

1178

Handles cross-device moves on Unix using <a class="reference internal" href="#distutils.file_util.copy_file" title="distutils.file_util.copy_file"><code class="xref py py-func docutils literal">copy_file()</code></a>. What about

1179

other systems?

1180

</div>

1181

</dd></dl>

1182

1183

1184

1185

<code class="descclassname">distutils.file_util.</code><code class="descname">write_file</code>(filename, contents)<a class="headerlink" href="#distutils.file_util.write_file" title="Permalink to this definition">¶</a></dt>

1186

<dd>Create a file called filename and write contents (a sequence of strings

1187

without line terminators) to it.

1188

</dd></dl>

1189

1190

</div>

1191

1192

<h2>10.11. <a class="reference internal" href="#module-distutils.util" title="distutils.util: Miscellaneous other utility functions"><code class="xref py py-mod docutils literal">distutils.util</code></a> — Miscellaneous other utility functions<a class="headerlink" href="#module-distutils.util" title="Permalink to this headline">¶</a></h2>

1193

This module contains other assorted bits and pieces that don’t fit into any

1194

other utility module.

1195

1196

1197

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

1198

<dd>Return a string that identifies the current platform. This is used mainly to

1199

distinguish platform-specific build directories and platform-specific built

1200

distributions. Typically includes the OS name and version and the architecture

1201

(as supplied by ‘os.uname()’), although the exact information included depends

1202

on the OS; eg. for IRIX the architecture isn’t particularly important (IRIX only

1203

runs on SGI hardware), but for Linux the kernel version isn’t particularly

1204

important.

1205

Examples of returned values:

1206

1207

<li><code class="docutils literal">linux-i586</code></li>

1208

<li><code class="docutils literal">linux-alpha</code></li>

1209

<li><code class="docutils literal">solaris-2.6-sun4u</code></li>

1210

1211

1212

</ul>

1213

For non-POSIX platforms, currently just returns <code class="docutils literal">sys.platform</code>.

1214

For Mac OS X systems the OS version reflects the minimal version on which

1215

binaries will run (that is, the value of <code class="docutils literal">MACOSX_DEPLOYMENT_TARGET</code>

1216

during the build of Python), not the OS version of the current system.

1217

For universal binary builds on Mac OS X the architecture value reflects

1218

the universal binary status instead of the architecture of the current

1219

processor. For 32-bit universal binaries the architecture is <code class="docutils literal">fat</code>,

1220

for 64-bit universal binaries the architecture is <code class="docutils literal">fat64</code>, and

1221

for 4-way universal binaries the architecture is <code class="docutils literal">universal</code>. Starting

1222

from Python 2.7 and Python 3.2 the architecture <code class="docutils literal">fat3</code> is used for

1223

a 3-way universal build (ppc, i386, x86_64) and <code class="docutils literal">intel</code> is used for

1224

a universal build with the i386 and x86_64 architectures

1225

Examples of returned values on Mac OS X:

1226

1227

<li><code class="docutils literal">macosx-10.3-ppc</code></li>

1228

<li><code class="docutils literal">macosx-10.3-fat</code></li>

1229

<li><code class="docutils literal">macosx-10.5-universal</code></li>

1230

<li><code class="docutils literal">macosx-10.6-intel</code></li>

1231

</ul>

1232

</dd></dl>

1233

1234

1235

1236

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

1237

<dd>Return ‘pathname’ as a name that will work on the native filesystem, i.e. split

1238

it on ‘/’ and put it back together again using the current directory separator.

1239

Needed because filenames in the setup script are always supplied in Unix style,

1240

and have to be converted to the local convention before we can actually use them

1241

in the filesystem. Raises <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> on non-Unix-ish systems if

1242

pathname either starts or ends with a slash.

1243

</dd></dl>

1244

1245

1246

1247

<code class="descclassname">distutils.util.</code><code class="descname">change_root</code>(new_root, pathname)<a class="headerlink" href="#distutils.util.change_root" title="Permalink to this definition">¶</a></dt>

1248

<dd>Return pathname with new_root prepended. If pathname is relative, this is

1249

equivalent to <code class="docutils literal">os.path.join(new_root,pathname)</code> Otherwise, it requires making

1250

pathname relative and then joining the two, which is tricky on DOS/Windows.

1251

</dd></dl>

1252

1253

1254

1255

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

1256

<dd>Ensure that ‘os.environ’ has all the environment variables we guarantee that

1257

users can use in config files, command-line options, etc. Currently this

1258

includes:

1259

1260

<li><code class="xref std std-envvar docutils literal">HOME</code> - user’s home directory (Unix only)</li>

1261

<li><code class="xref std std-envvar docutils literal">PLAT</code> - description of the current platform, including hardware and

1262

OS (see <a class="reference internal" href="#distutils.util.get_platform" title="distutils.util.get_platform"><code class="xref py py-func docutils literal">get_platform()</code></a>)</li>

1263

</ul>

1264

</dd></dl>

1265

1266

1267

1268

<code class="descclassname">distutils.util.</code><code class="descname">subst_vars</code>(s, local_vars)<a class="headerlink" href="#distutils.util.subst_vars" title="Permalink to this definition">¶</a></dt>

1269

<dd>Perform shell/Perl-style variable substitution on s. Every occurrence of

1270

<code class="docutils literal">$</code> followed by a name is considered a variable, and variable is substituted

1271

by the value found in the local_vars dictionary, or in <code class="docutils literal">os.environ</code> if it’s

1272

not in local_vars. os.environ is first checked/augmented to guarantee that

1273

it contains certain values: see <a class="reference internal" href="#distutils.util.check_environ" title="distutils.util.check_environ"><code class="xref py py-func docutils literal">check_environ()</code></a>. Raise <a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a>

1274

for any variables not found in either local_vars or <code class="docutils literal">os.environ</code>.

1275

Note that this is not a fully-fledged string interpolation function. A valid

1276

<code class="docutils literal">$variable</code> can consist only of upper and lower case letters, numbers and an

1277

underscore. No { } or ( ) style quoting is available.

1278

</dd></dl>

1279

1280

1281

1282

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

1283

<dd>Split a string up according to Unix shell-like rules for quotes and backslashes.

1284

In short: words are delimited by spaces, as long as those spaces are not escaped

1285

by a backslash, or inside a quoted string. Single and double quotes are

1286

equivalent, and the quote characters can be backslash-escaped. The backslash is

1287

stripped from any two-character escape sequence, leaving only the escaped

1288

character. The quote characters are stripped from any quoted string. Returns a

1289

list of words.

1290

</dd></dl>

1291

1292

1293

1294

<code class="descclassname">distutils.util.</code><code class="descname">execute</code>(func, args[, msg=None, verbose=0, dry_run=0])<a class="headerlink" href="#distutils.util.execute" title="Permalink to this definition">¶</a></dt>

1295

<dd>Perform some action that affects the outside world (for instance, writing to the

1296

filesystem). Such actions are special because they are disabled by the

1297

dry_run flag. This method takes care of all that bureaucracy for you; all

1298

you have to do is supply the function to call and an argument tuple for it (to

1299

embody the “external action” being performed), and an optional message to print.

1300

</dd></dl>

1301

1302

1303

1304

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

1305

<dd>Convert a string representation of truth to true (1) or false (0).

1306

True values are <code class="docutils literal">y</code>, <code class="docutils literal">yes</code>, <code class="docutils literal">t</code>, <code class="docutils literal">true</code>, <code class="docutils literal">on</code> and <code class="docutils literal">1</code>; false values

1307

are <code class="docutils literal">n</code>, <code class="docutils literal">no</code>, <code class="docutils literal">f</code>, <code class="docutils literal">false</code>, <code class="docutils literal">off</code> and <code class="docutils literal">0</code>. Raises

1308

<a class="reference internal" href="../library/exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> if val is anything else.

1309

</dd></dl>

1310

1311

1312

1313

<code class="descclassname">distutils.util.</code><code class="descname">byte_compile</code>(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])<a class="headerlink" href="#distutils.util.byte_compile" title="Permalink to this definition">¶</a></dt>

1314

<dd>Byte-compile a collection of Python source files to <code class="file docutils literal">.pyc</code> files in a

1315

<code class="file docutils literal">__pycache__</code> subdirectory (see <a class="pep reference external" href="https://www.python.org/dev/peps/pep-3147">PEP 3147</a> and <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0488">PEP 488</a>).

1316

py_files is a list of files to compile; any files that don’t end in

1317

<code class="file docutils literal">.py</code> are silently skipped. optimize must be one of the following:

1318

1319

<li><code class="docutils literal">0</code> - don’t optimize</li>

1320

<li><code class="docutils literal">1</code> - normal optimization (like <code class="docutils literal">python -O</code>)</li>

1321

<li><code class="docutils literal">2</code> - extra optimization (like <code class="docutils literal">python -OO</code>)</li>

1322

</ul>

1323

If force is true, all files are recompiled regardless of timestamps.

1324

The source filename encoded in each <a class="reference internal" href="../glossary.html#term-bytecode">bytecode</a> file defaults to the filenames

1325

listed in py_files; you can modify these with prefix and basedir.

1326

prefix is a string that will be stripped off of each source filename, and

1327

base_dir is a directory name that will be prepended (after prefix is

1328

stripped). You can supply either or both (or neither) of prefix and

1329

base_dir, as you wish.

1330

If dry_run is true, doesn’t actually do anything that would affect the

1331

filesystem.

1332

Byte-compilation is either done directly in this interpreter process with the

1333

standard <a class="reference internal" href="../library/py_compile.html#module-py_compile" title="py_compile: Generate byte-code files from Python source files."><code class="xref py py-mod docutils literal">py_compile</code></a> module, or indirectly by writing a temporary script

1334

and executing it. Normally, you should let <a class="reference internal" href="#distutils.util.byte_compile" title="distutils.util.byte_compile"><code class="xref py py-func docutils literal">byte_compile()</code></a> figure out to

1335

use direct compilation or not (see the source for details). The direct flag

1336

is used by the script generated in indirect mode; unless you know what you’re

1337

doing, leave it set to <code class="docutils literal">None</code>.

1338

1339

Changed in version 3.2.3: Create <code class="docutils literal">.pyc</code> files with an <a class="reference internal" href="../library/imp.html#imp.get_tag" title="imp.get_tag"><code class="xref py py-func docutils literal">import magic tag</code></a> in their name, in a <code class="file docutils literal">__pycache__</code> subdirectory

1340

instead of files without tag in the current directory.

1341

</div>

1342

</dd></dl>

1343

1344

1345

1346

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

1347

<dd>Return a version of header escaped for inclusion in an <a class="rfc reference external" href="https://tools.ietf.org/html/rfc822.html">RFC 822</a> header, by

1348

ensuring there are 8 spaces space after each newline. Note that it does no other

1349

modification of the string.

1350

</dd></dl>

1351

1352

</div>

1353

1354

<h2>10.12. <a class="reference internal" href="#module-distutils.dist" title="distutils.dist: Provides the Distribution class, which represents the module distribution being built/installed/distributed"><code class="xref py py-mod docutils literal">distutils.dist</code></a> — The Distribution class<a class="headerlink" href="#module-distutils.dist" title="Permalink to this headline">¶</a></h2>

1355

This module provides the <a class="reference internal" href="#distutils.core.Distribution" title="distutils.core.Distribution"><code class="xref py py-class docutils literal">Distribution</code></a> class, which

1356

represents the module distribution being built/installed/distributed.

1357

</div>

1358

1359

<h2>10.13. <a class="reference internal" href="#module-distutils.extension" title="distutils.extension: Provides the Extension class, used to describe C/C++ extension modules in setup scripts"><code class="xref py py-mod docutils literal">distutils.extension</code></a> — The Extension class<a class="headerlink" href="#module-distutils.extension" title="Permalink to this headline">¶</a></h2>

1360

This module provides the <code class="xref py py-class docutils literal">Extension</code> class, used to describe C/C++

1361

extension modules in setup scripts.

1362

</div>

1363

1364

<h2>10.14. <a class="reference internal" href="#module-distutils.debug" title="distutils.debug: Provides the debug flag for distutils"><code class="xref py py-mod docutils literal">distutils.debug</code></a> — Distutils debug mode<a class="headerlink" href="#module-distutils.debug" title="Permalink to this headline">¶</a></h2>

1365

This module provides the DEBUG flag.

1366

</div>

1367

1368

<h2>10.15. <a class="reference internal" href="#module-distutils.errors" title="distutils.errors: Provides standard distutils exceptions"><code class="xref py py-mod docutils literal">distutils.errors</code></a> — Distutils exceptions<a class="headerlink" href="#module-distutils.errors" title="Permalink to this headline">¶</a></h2>

1369

Provides exceptions used by the Distutils modules. Note that Distutils modules

1370

may raise standard exceptions; in particular, SystemExit is usually raised for

1371

errors that are obviously the end-user’s fault (eg. bad command-line arguments).

1372

This module is safe to use in <code class="docutils literal">from ... import *</code> mode; it only exports

1373

symbols whose names start with <code class="docutils literal">Distutils</code> and end with <code class="docutils literal">Error</code>.

1374

</div>

1375

1376

<h2>10.16. <a class="reference internal" href="#module-distutils.fancy_getopt" title="distutils.fancy_getopt: Additional getopt functionality"><code class="xref py py-mod docutils literal">distutils.fancy_getopt</code></a> — Wrapper around the standard getopt module<a class="headerlink" href="#module-distutils.fancy_getopt" title="Permalink to this headline">¶</a></h2>

1377

This module provides a wrapper around the standard <a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-mod docutils literal">getopt</code></a> module that

1378

provides the following additional features:

1379

1380

<li>short and long options are tied together</li>

1381

<li>options have help strings, so <a class="reference internal" href="#distutils.fancy_getopt.fancy_getopt" title="distutils.fancy_getopt.fancy_getopt"><code class="xref py py-func docutils literal">fancy_getopt()</code></a> could potentially create a

1382

complete usage summary</li>

1383

<li>options set attributes of a passed-in object</li>

1384

<li>boolean options can have “negative aliases” — eg. if <code class="xref std std-option docutils literal">--quiet</code> is

1385

the “negative alias” of <a class="reference internal" href="../library/tarfile.html#cmdoption--verbose"><code class="xref std std-option docutils literal">--verbose</code></a>, then <code class="xref std std-option docutils literal">--quiet</code> on the

1386

command line sets verbose to false.</li>

1387

</ul>

1388

1389

1390

<code class="descclassname">distutils.fancy_getopt.</code><code class="descname">fancy_getopt</code>(options, negative_opt, object, args)<a class="headerlink" href="#distutils.fancy_getopt.fancy_getopt" title="Permalink to this definition">¶</a></dt>

1391

<dd>Wrapper function. options is a list of <code class="docutils literal">(long_option, short_option,

1392

help_string)</code> 3-tuples as described in the constructor for

1393

<a class="reference internal" href="#distutils.fancy_getopt.FancyGetopt" title="distutils.fancy_getopt.FancyGetopt"><code class="xref py py-class docutils literal">FancyGetopt</code></a>. negative_opt should be a dictionary mapping option names

1394

to option names, both the key and value should be in the options list.

1395

object is an object which will be used to store values (see the <a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-meth docutils literal">getopt()</code></a>

1396

method of the <a class="reference internal" href="#distutils.fancy_getopt.FancyGetopt" title="distutils.fancy_getopt.FancyGetopt"><code class="xref py py-class docutils literal">FancyGetopt</code></a> class). args is the argument list. Will use

1397

<code class="docutils literal">sys.argv[1:]</code> if you pass <code class="docutils literal">None</code> as args.

1398

</dd></dl>

1399

1400

1401

1402

<code class="descclassname">distutils.fancy_getopt.</code><code class="descname">wrap_text</code>(text, width)<a class="headerlink" href="#distutils.fancy_getopt.wrap_text" title="Permalink to this definition">¶</a></dt>

1403

<dd>Wraps text to less than width wide.

1404

</dd></dl>

1405

1406

1407

1408

class <code class="descclassname">distutils.fancy_getopt.</code><code class="descname">FancyGetopt</code>([option_table=None])<a class="headerlink" href="#distutils.fancy_getopt.FancyGetopt" title="Permalink to this definition">¶</a></dt>

1409

<dd>The option_table is a list of 3-tuples: <code class="docutils literal">(long_option, short_option,

1410

help_string)</code>

1411

If an option takes an argument, its long_option should have <code class="docutils literal">'='</code> appended;

1412

short_option should just be a single character, no <code class="docutils literal">':'</code> in any case.

1413

short_option should be <code class="docutils literal">None</code> if a long_option doesn’t have a

1414

corresponding short_option. All option tuples must have long options.

1415

</dd></dl>

1416

1417

The <a class="reference internal" href="#distutils.fancy_getopt.FancyGetopt" title="distutils.fancy_getopt.FancyGetopt"><code class="xref py py-class docutils literal">FancyGetopt</code></a> class provides the following methods:

1418

1419

1420

<code class="descclassname">FancyGetopt.</code><code class="descname">getopt</code>([args=None, object=None])<a class="headerlink" href="#distutils.fancy_getopt.FancyGetopt.getopt" title="Permalink to this definition">¶</a></dt>

1421

<dd>Parse command-line options in args. Store as attributes on object.

1422

If args is <code class="docutils literal">None</code> or not supplied, uses <code class="docutils literal">sys.argv[1:]</code>. If object is

1423

<code class="docutils literal">None</code> or not supplied, creates a new <code class="xref py py-class docutils literal">OptionDummy</code> instance, stores

1424

option values there, and returns a tuple <code class="docutils literal">(args, object)</code>. If object is

1425

supplied, it is modified in place and <a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-func docutils literal">getopt()</code></a> just returns args; in

1426

both cases, the returned args is a modified copy of the passed-in args list,

1427

which is left untouched.

1428

</dd></dl>

1429

1430

1431

1432

<code class="descclassname">FancyGetopt.</code><code class="descname">get_option_order</code>()<a class="headerlink" href="#distutils.fancy_getopt.FancyGetopt.get_option_order" title="Permalink to this definition">¶</a></dt>

1433

<dd>Returns the list of <code class="docutils literal">(option, value)</code> tuples processed by the previous run of

1434

<a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-meth docutils literal">getopt()</code></a> Raises <a class="reference internal" href="../library/exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal">RuntimeError</code></a> if <a class="reference internal" href="../library/getopt.html#module-getopt" title="getopt: Portable parser for command line options; support both short and long option names."><code class="xref py py-meth docutils literal">getopt()</code></a> hasn’t been called

1435

yet.

1436

</dd></dl>

1437

1438

1439

1440

<code class="descclassname">FancyGetopt.</code><code class="descname">generate_help</code>([header=None])<a class="headerlink" href="#distutils.fancy_getopt.FancyGetopt.generate_help" title="Permalink to this definition">¶</a></dt>

1441

<dd>Generate help text (a list of strings, one per suggested line of output) from

1442

the option table for this <a class="reference internal" href="#distutils.fancy_getopt.FancyGetopt" title="distutils.fancy_getopt.FancyGetopt"><code class="xref py py-class docutils literal">FancyGetopt</code></a> object.

1443

If supplied, prints the supplied header at the top of the help.

1444

</dd></dl>

1445

1446

</div>

1447

1448

<h2>10.17. <a class="reference internal" href="#module-distutils.filelist" title="distutils.filelist: The FileList class, used for poking about the file system and building lists of files."><code class="xref py py-mod docutils literal">distutils.filelist</code></a> — The FileList class<a class="headerlink" href="#module-distutils.filelist" title="Permalink to this headline">¶</a></h2>

1449

This module provides the <code class="xref py py-class docutils literal">FileList</code> class, used for poking about the

1450

filesystem and building lists of files.

1451

</div>

1452

1453

<h2>10.18. <a class="reference internal" href="#module-distutils.log" title="distutils.log: A simple logging mechanism, 282-style"><code class="xref py py-mod docutils literal">distutils.log</code></a> — Simple PEP 282-style logging<a class="headerlink" href="#module-distutils.log" title="Permalink to this headline">¶</a></h2>

1454

</div>

1455

1456

<h2>10.19. <a class="reference internal" href="#module-distutils.spawn" title="distutils.spawn: Provides the spawn() function"><code class="xref py py-mod docutils literal">distutils.spawn</code></a> — Spawn a sub-process<a class="headerlink" href="#module-distutils.spawn" title="Permalink to this headline">¶</a></h2>

1457

This module provides the <code class="xref py py-func docutils literal">spawn()</code> function, a front-end to various

1458

platform-specific functions for launching another program in a sub-process.

1459

Also provides <code class="xref py py-func docutils literal">find_executable()</code> to search the path for a given executable

1460

name.

1461

</div>

1462

1463

<h2>10.20. <a class="reference internal" href="#module-distutils.sysconfig" title="distutils.sysconfig: Low-level access to configuration information of the Python interpreter."><code class="xref py py-mod docutils literal">distutils.sysconfig</code></a> — System configuration information<a class="headerlink" href="#module-distutils.sysconfig" title="Permalink to this headline">¶</a></h2>

1464

The <a class="reference internal" href="#module-distutils.sysconfig" title="distutils.sysconfig: Low-level access to configuration information of the Python interpreter."><code class="xref py py-mod docutils literal">distutils.sysconfig</code></a> module provides access to Python’s low-level

1465

configuration information. The specific configuration variables available

1466

depend heavily on the platform and configuration. The specific variables depend

1467

on the build process for the specific version of Python being run; the variables

1468

are those found in the <code class="file docutils literal">Makefile</code> and configuration header that are

1469

installed with Python on Unix systems. The configuration header is called

1470

<code class="file docutils literal">pyconfig.h</code> for Python versions starting with 2.2, and <code class="file docutils literal">config.h</code>

1471

for earlier versions of Python.

1472

Some additional functions are provided which perform some useful manipulations

1473

for other parts of the <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal">distutils</code></a> package.

1474

1475

1476

<code class="descclassname">distutils.sysconfig.</code><code class="descname">PREFIX</code><a class="headerlink" href="#distutils.sysconfig.PREFIX" title="Permalink to this definition">¶</a></dt>

1477

<dd>The result of <code class="docutils literal">os.path.normpath(sys.prefix)</code>.

1478

</dd></dl>

1479

1480

1481

1482

<code class="descclassname">distutils.sysconfig.</code><code class="descname">EXEC_PREFIX</code><a class="headerlink" href="#distutils.sysconfig.EXEC_PREFIX" title="Permalink to this definition">¶</a></dt>

1483

<dd>The result of <code class="docutils literal">os.path.normpath(sys.exec_prefix)</code>.

1484

</dd></dl>

1485

1486

1487

1488

<code class="descclassname">distutils.sysconfig.</code><code class="descname">get_config_var</code>(name)<a class="headerlink" href="#distutils.sysconfig.get_config_var" title="Permalink to this definition">¶</a></dt>

1489

<dd>Return the value of a single variable. This is equivalent to

1490

<code class="docutils literal">get_config_vars().get(name)</code>.

1491

</dd></dl>

1492

1493

1494

1495

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

1496

<dd>Return a set of variable definitions. If there are no arguments, this returns a

1497

dictionary mapping names of configuration variables to values. If arguments are

1498

provided, they should be strings, and the return value will be a sequence giving

1499

the associated values. If a given name does not have a corresponding value,

1500

<code class="docutils literal">None</code> will be included for that variable.

1501

</dd></dl>

1502

1503

1504

1505

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

1506

<dd>Return the full path name of the configuration header. For Unix, this will be

1507

the header generated by the configure script; for other platforms the

1508

header will have been supplied directly by the Python source distribution. The

1509

file is a platform-specific text file.

1510

</dd></dl>

1511

1512

1513

1514

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

1515

<dd>Return the full path name of the <code class="file docutils literal">Makefile</code> used to build Python. For

1516

Unix, this will be a file generated by the configure script; the

1517

meaning for other platforms will vary. The file is a platform-specific text

1518

file, if it exists. This function is only useful on POSIX platforms.

1519

</dd></dl>

1520

1521

1522

1523

<code class="descclassname">distutils.sysconfig.</code><code class="descname">get_python_inc</code>([plat_specific[, prefix]])<a class="headerlink" href="#distutils.sysconfig.get_python_inc" title="Permalink to this definition">¶</a></dt>

1524

<dd>Return the directory for either the general or platform-dependent C include

1525

files. If plat_specific is true, the platform-dependent include directory is

1526

returned; if false or omitted, the platform-independent directory is returned.

1527

If prefix is given, it is used as either the prefix instead of

1528

<a class="reference internal" href="#distutils.sysconfig.PREFIX" title="distutils.sysconfig.PREFIX"><code class="xref py py-const docutils literal">PREFIX</code></a>, or as the exec-prefix instead of <a class="reference internal" href="#distutils.sysconfig.EXEC_PREFIX" title="distutils.sysconfig.EXEC_PREFIX"><code class="xref py py-const docutils literal">EXEC_PREFIX</code></a> if

1529

plat_specific is true.

1530

</dd></dl>

1531

1532

1533

1534

<code class="descclassname">distutils.sysconfig.</code><code class="descname">get_python_lib</code>([plat_specific[, standard_lib[, prefix]]])<a class="headerlink" href="#distutils.sysconfig.get_python_lib" title="Permalink to this definition">¶</a></dt>

1535

<dd>Return the directory for either the general or platform-dependent library

1536

installation. If plat_specific is true, the platform-dependent include

1537

directory is returned; if false or omitted, the platform-independent directory

1538

is returned. If prefix is given, it is used as either the prefix instead of

1539

1540

plat_specific is true. If standard_lib is true, the directory for the

1541

standard library is returned rather than the directory for the installation of

1542

third-party extensions.

1543

</dd></dl>

1544

1545

The following function is only intended for use within the <a class="reference internal" href="../library/distutils.html#module-distutils" title="distutils: Support for building and installing Python modules into an existing Python installation."><code class="xref py py-mod docutils literal">distutils</code></a>

1546

package.

1547

1548

1549

<code class="descclassname">distutils.sysconfig.</code><code class="descname">customize_compiler</code>(compiler)<a class="headerlink" href="#distutils.sysconfig.customize_compiler" title="Permalink to this definition">¶</a></dt>

1550

<dd>Do any platform-specific customization of a

1551

<a class="reference internal" href="#distutils.ccompiler.CCompiler" title="distutils.ccompiler.CCompiler"><code class="xref py py-class docutils literal">distutils.ccompiler.CCompiler</code></a> instance.

1552

This function is only needed on Unix at this time, but should be called

1553

consistently to support forward-compatibility. It inserts the information that

1554

varies across Unix flavors and is stored in Python’s <code class="file docutils literal">Makefile</code>. This

1555

information includes the selected compiler, compiler and linker options, and the

1556

extension used by the linker for shared objects.

1557

</dd></dl>

1558

1559

This function is even more special-purpose, and should only be used from

1560

Python’s own build procedures.

1561

1562

1563

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

1564

<dd>Inform the <a class="reference internal" href="#module-distutils.sysconfig" title="distutils.sysconfig: Low-level access to configuration information of the Python interpreter."><code class="xref py py-mod docutils literal">distutils.sysconfig</code></a> module that it is being used as part of

1565

the build process for Python. This changes a lot of relative locations for

1566

files, allowing them to be located in the build area rather than in an installed

1567

Python.

1568

</dd></dl>

1569

1570

</div>

1571

1572

<h2>10.21. <a class="reference internal" href="#module-distutils.text_file" title="distutils.text_file: provides the TextFile class, a simple interface to text files"><code class="xref py py-mod docutils literal">distutils.text_file</code></a> — The TextFile class<a class="headerlink" href="#module-distutils.text_file" title="Permalink to this headline">¶</a></h2>

1573

This module provides the <a class="reference internal" href="#distutils.text_file.TextFile" title="distutils.text_file.TextFile"><code class="xref py py-class docutils literal">TextFile</code></a> class, which gives an interface to

1574

text files that (optionally) takes care of stripping comments, ignoring blank

1575

lines, and joining lines with backslashes.

1576

1577

1578

class <code class="descclassname">distutils.text_file.</code><code class="descname">TextFile</code>([filename=None, file=None, **options])<a class="headerlink" href="#distutils.text_file.TextFile" title="Permalink to this definition">¶</a></dt>

1579

<dd>This class provides a file-like object that takes care of all the things you

1580

commonly want to do when processing a text file that has some line-by-line

1581

syntax: strip comments (as long as <code class="docutils literal">#</code> is your comment character), skip blank

1582

lines, join adjacent lines by escaping the newline (ie. backslash at end of

1583

line), strip leading and/or trailing whitespace. All of these are optional and

1584

independently controllable.

1585

The class provides a <a class="reference internal" href="#distutils.text_file.TextFile.warn" title="distutils.text_file.TextFile.warn"><code class="xref py py-meth docutils literal">warn()</code></a> method so you can generate warning messages

1586

that report physical line number, even if the logical line in question spans

1587

multiple physical lines. Also provides <a class="reference internal" href="#distutils.text_file.TextFile.unreadline" title="distutils.text_file.TextFile.unreadline"><code class="xref py py-meth docutils literal">unreadline()</code></a> for implementing

1588

line-at-a-time lookahead.

1589

<a class="reference internal" href="#distutils.text_file.TextFile" title="distutils.text_file.TextFile"><code class="xref py py-class docutils literal">TextFile</code></a> instances are create with either filename, file, or both.

1590

<a class="reference internal" href="../library/exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal">RuntimeError</code></a> is raised if both are <code class="docutils literal">None</code>. filename should be a

1591

string, and file a file object (or something that provides <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal">readline()</code></a>

1592

and <a class="reference internal" href="#distutils.text_file.TextFile.close" title="distutils.text_file.TextFile.close"><code class="xref py py-meth docutils literal">close()</code></a> methods). It is recommended that you supply at least

1593

filename, so that <a class="reference internal" href="#distutils.text_file.TextFile" title="distutils.text_file.TextFile"><code class="xref py py-class docutils literal">TextFile</code></a> can include it in warning messages. If

1594

file is not supplied, <a class="reference internal" href="#distutils.text_file.TextFile" title="distutils.text_file.TextFile"><code class="xref py py-class docutils literal">TextFile</code></a> creates its own using the

1595

<a class="reference internal" href="../library/functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a> built-in function.

1596

The options are all boolean, and affect the values returned by <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal">readline()</code></a>

1597

1598

1599

1600

1601

1602

</colgroup>

1603

1604

<tr class="row-odd"><th class="head">option name</th>

1605

<th class="head">description</th>

1606

<th class="head">default</th>

1607

</tr>

1608

</thead>

1609

1610

<tr class="row-even"><td>strip_comments</td>

1611

<td>strip from <code class="docutils literal">'#'</code> to end-of-

1612

line, as well as any

1613

whitespace leading up to the

1614

<code class="docutils literal">'#'</code>—unless it is

1615

escaped by a backslash</td>

1616

1617

</tr>

1618

<tr class="row-odd"><td>lstrip_ws</td>

1619

<td>strip leading whitespace from

1620

each line before returning it</td>

1621

<td>false</td>

1622

</tr>

1623

<tr class="row-even"><td>rstrip_ws</td>

1624

<td>strip trailing whitespace

1625

(including line terminator!)

1626

from each line before

1627

returning it.</td>

1628

1629

</tr>

1630

<tr class="row-odd"><td>skip_blanks</td>

1631

<td>skip lines that are empty

1632

*after* stripping comments

1633

and whitespace. (If both

1634

lstrip_ws and rstrip_ws are

1635

false, then some lines may

1636

consist of solely whitespace:

1637

these will *not* be skipped,

1638

even if skip_blanks is

1639

true.)</td>

1640

1641

</tr>

1642

<tr class="row-even"><td>join_lines</td>

1643

<td>if a backslash is the last

1644

non-newline character on a

1645

line after stripping comments

1646

and whitespace, join the

1647

following line to it to form

1648

one logical line; if N

1649

consecutive lines end with a

1650

backslash, then N+1 physical

1651

lines will be joined to form

1652

one logical line.</td>

1653

<td>false</td>

1654

</tr>

1655

<tr class="row-odd"><td>collapse_join</td>

1656

<td>strip leading whitespace from

1657

lines that are joined to their

1658

predecessor; only matters if

1659

<code class="docutils literal">(join_lines and not

1660

lstrip_ws)</code></td>

1661

<td>false</td>

1662

</tr>

1663

</tbody>

1664

</table>

1665

Note that since rstrip_ws can strip the trailing newline, the semantics of

1666

1667

<a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal">readline()</code></a> method! In particular, <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal">readline()</code></a> returns <code class="docutils literal">None</code> for

1668

end-of-file: an empty string might just be a blank line (or an all-whitespace

1669

line), if rstrip_ws is true but skip_blanks is not.

1670

1671

1672

<code class="descname">open</code>(filename)<a class="headerlink" href="#distutils.text_file.TextFile.open" title="Permalink to this definition">¶</a></dt>

1673

<dd>Open a new file filename. This overrides any file or filename

1674

constructor arguments.

1675

</dd></dl>

1676

1677

1678

1679

<code class="descname">close</code>()<a class="headerlink" href="#distutils.text_file.TextFile.close" title="Permalink to this definition">¶</a></dt>

1680

<dd>Close the current file and forget everything we know about it (including the

1681

filename and the current line number).

1682

</dd></dl>

1683

1684

1685

1686

1687

<dd>Print (to stderr) a warning message tied to the current logical line in the

1688

current file. If the current logical line in the file spans multiple physical

1689

lines, the warning refers to the whole range, such as <code class="docutils literal">"lines 3-5"</code>. If

1690

line is supplied, it overrides the current line number; it may be a list or

1691

tuple to indicate a range of physical lines, or an integer for a single

1692

physical line.

1693

</dd></dl>

1694

1695

1696

1697

<code class="descname">readline</code>()<a class="headerlink" href="#distutils.text_file.TextFile.readline" title="Permalink to this definition">¶</a></dt>

1698

<dd>Read and return a single logical line from the current file (or from an internal

1699

buffer if lines have previously been “unread” with <a class="reference internal" href="#distutils.text_file.TextFile.unreadline" title="distutils.text_file.TextFile.unreadline"><code class="xref py py-meth docutils literal">unreadline()</code></a>). If the

1700

join_lines option is true, this may involve reading multiple physical lines

1701

concatenated into a single string. Updates the current line number, so calling

1702

<a class="reference internal" href="#distutils.text_file.TextFile.warn" title="distutils.text_file.TextFile.warn"><code class="xref py py-meth docutils literal">warn()</code></a> after <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal">readline()</code></a> emits a warning about the physical line(s)

1703

just read. Returns <code class="docutils literal">None</code> on end-of-file, since the empty string can occur

1704

if rstrip_ws is true but strip_blanks is not.

1705

</dd></dl>

1706

1707

1708

1709

<code class="descname">readlines</code>()<a class="headerlink" href="#distutils.text_file.TextFile.readlines" title="Permalink to this definition">¶</a></dt>

1710

<dd>Read and return the list of all logical lines remaining in the current file.

1711

This updates the current line number to the last line of the file.

1712

</dd></dl>

1713

1714

1715

1716

<code class="descname">unreadline</code>(line)<a class="headerlink" href="#distutils.text_file.TextFile.unreadline" title="Permalink to this definition">¶</a></dt>

1717

<dd>Push line (a string) onto an internal buffer that will be checked by future

1718

1719

lookahead. Note that lines that are “unread” with <a class="reference internal" href="#distutils.text_file.TextFile.unreadline" title="distutils.text_file.TextFile.unreadline"><code class="xref py py-meth docutils literal">unreadline()</code></a> are not

1720

subsequently re-cleansed (whitespace stripped, or whatever) when read with

1721

<a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal">readline()</code></a>. If multiple calls are made to <a class="reference internal" href="#distutils.text_file.TextFile.unreadline" title="distutils.text_file.TextFile.unreadline"><code class="xref py py-meth docutils literal">unreadline()</code></a> before a call

1722

to <a class="reference internal" href="../library/readline.html#module-readline" title="readline: GNU readline support for Python. (Unix)"><code class="xref py py-meth docutils literal">readline()</code></a>, the lines will be returned most in most recent first order.

1723

</dd></dl>

1724

1725

</dd></dl>

1726

1727

</div>

1728

1729

<h2>10.22. <a class="reference internal" href="#module-distutils.version" title="distutils.version: implements classes that represent module version numbers."><code class="xref py py-mod docutils literal">distutils.version</code></a> — Version number classes<a class="headerlink" href="#module-distutils.version" title="Permalink to this headline">¶</a></h2>

1730

</div>

1731

1732

<h2>10.23. <a class="reference internal" href="#module-distutils.cmd" title="distutils.cmd: This module provides the abstract base class Command. This class is subclassed by the modules in the distutils.command subpackage."><code class="xref py py-mod docutils literal">distutils.cmd</code></a> — Abstract base class for Distutils commands<a class="headerlink" href="#module-distutils.cmd" title="Permalink to this headline">¶</a></h2>

1733

This module supplies the abstract base class <a class="reference internal" href="#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal">Command</code></a>.

1734

1735

1736

class <code class="descclassname">distutils.cmd.</code><code class="descname">Command</code>(dist)<a class="headerlink" href="#distutils.cmd.Command" title="Permalink to this definition">¶</a></dt>

1737

<dd>Abstract base class for defining command classes, the “worker bees” of the

1738

Distutils. A useful analogy for command classes is to think of them as

1739

subroutines with local variables called options. The options are declared

1740

in <a class="reference internal" href="#distutils.cmd.Command.initialize_options" title="distutils.cmd.Command.initialize_options"><code class="xref py py-meth docutils literal">initialize_options()</code></a> and defined (given their final values) in

1741

<a class="reference internal" href="#distutils.cmd.Command.finalize_options" title="distutils.cmd.Command.finalize_options"><code class="xref py py-meth docutils literal">finalize_options()</code></a>, both of which must be defined by every command

1742

class. The distinction between the two is necessary because option values

1743

might come from the outside world (command line, config file, ...), and any

1744

options dependent on other options must be computed after these outside

1745

influences have been processed — hence <a class="reference internal" href="#distutils.cmd.Command.finalize_options" title="distutils.cmd.Command.finalize_options"><code class="xref py py-meth docutils literal">finalize_options()</code></a>. The body

1746

of the subroutine, where it does all its work based on the values of its

1747

options, is the <a class="reference internal" href="#distutils.cmd.Command.run" title="distutils.cmd.Command.run"><code class="xref py py-meth docutils literal">run()</code></a> method, which must also be implemented by every

1748

command class.

1749

The class constructor takes a single argument dist, a

1750

1751

</dd></dl>

1752

1753

</div>

1754

1755

<h2>10.24. Creating a new Distutils command<a class="headerlink" href="#creating-a-new-distutils-command" title="Permalink to this headline">¶</a></h2>

1756

This section outlines the steps to create a new Distutils command.

1757

A new command lives in a module in the <a class="reference internal" href="#module-distutils.command" title="distutils.command: This subpackage contains one module for each standard Distutils command."><code class="xref py py-mod docutils literal">distutils.command</code></a> package. There

1758

is a sample template in that directory called <code class="file docutils literal">command_template</code>. Copy

1759

this file to a new module with the same name as the new command you’re

1760

implementing. This module should implement a class with the same name as the

1761

module (and the command). So, for instance, to create the command

1762

<code class="docutils literal">peel_banana</code> (so that users can run <code class="docutils literal">setup.py peel_banana</code>), you’d copy

1763

<code class="file docutils literal">command_template</code> to <code class="file docutils literal">distutils/command/peel_banana.py</code>, then edit

1764

it so that it’s implementing the class <code class="xref py py-class docutils literal">peel_banana</code>, a subclass of

1765

1766

Subclasses of <a class="reference internal" href="#distutils.cmd.Command" title="distutils.cmd.Command"><code class="xref py py-class docutils literal">Command</code></a> must define the following methods.

1767

1768

1769

<code class="descclassname">Command.</code><code class="descname">initialize_options</code>()<a class="headerlink" href="#distutils.cmd.Command.initialize_options" title="Permalink to this definition">¶</a></dt>

1770

<dd>Set default values for all the options that this command supports. Note that

1771

these defaults may be overridden by other commands, by the setup script, by

1772

config files, or by the command-line. Thus, this is not the place to code

1773

dependencies between options; generally, <a class="reference internal" href="#distutils.cmd.Command.initialize_options" title="distutils.cmd.Command.initialize_options"><code class="xref py py-meth docutils literal">initialize_options()</code></a>

1774

implementations are just a bunch of <code class="docutils literal">self.foo = None</code> assignments.

1775

</dd></dl>

1776

1777

1778

1779

<code class="descclassname">Command.</code><code class="descname">finalize_options</code>()<a class="headerlink" href="#distutils.cmd.Command.finalize_options" title="Permalink to this definition">¶</a></dt>

1780

<dd>Set final values for all the options that this command supports. This is

1781

always called as late as possible, ie. after any option assignments from the

1782

command-line or from other commands have been done. Thus, this is the place

1783

to code option dependencies: if foo depends on bar, then it is safe to

1784

set foo from bar as long as foo still has the same value it was

1785

assigned in <a class="reference internal" href="#distutils.cmd.Command.initialize_options" title="distutils.cmd.Command.initialize_options"><code class="xref py py-meth docutils literal">initialize_options()</code></a>.

1786

</dd></dl>

1787

1788

1789

1790

<code class="descclassname">Command.</code><code class="descname">run</code>()<a class="headerlink" href="#distutils.cmd.Command.run" title="Permalink to this definition">¶</a></dt>

1791

<dd>A command’s raison d’etre: carry out the action it exists to perform, controlled

1792

by the options initialized in <a class="reference internal" href="#distutils.cmd.Command.initialize_options" title="distutils.cmd.Command.initialize_options"><code class="xref py py-meth docutils literal">initialize_options()</code></a>, customized by other

1793

commands, the setup script, the command-line, and config files, and finalized in

1794

1795

be done by <a class="reference internal" href="#distutils.cmd.Command.run" title="distutils.cmd.Command.run"><code class="xref py py-meth docutils literal">run()</code></a>.

1796

</dd></dl>

1797

1798

1799

1800

<code class="descclassname">Command.</code><code class="descname">sub_commands</code><a class="headerlink" href="#distutils.cmd.Command.sub_commands" title="Permalink to this definition">¶</a></dt>

1801

<dd>sub_commands formalizes the notion of a “family” of commands,

1802

e.g. <code class="docutils literal">install</code> as the parent with sub-commands <code class="docutils literal">install_lib</code>,

1803

<code class="docutils literal">install_headers</code>, etc. The parent of a family of commands defines

1804

sub_commands as a class attribute; it’s a list of 2-tuples <code class="docutils literal">(command_name,

1805

predicate)</code>, with command_name a string and predicate a function, a

1806

string or <code class="docutils literal">None</code>. predicate is a method of the parent command that

1807

determines whether the corresponding command is applicable in the current

1808

situation. (E.g. <code class="docutils literal">install_headers</code> is only applicable if we have any C

1809

header files to install.) If predicate is <code class="docutils literal">None</code>, that command is always

1810

applicable.

1811

sub_commands is usually defined at the end of a class, because

1812

predicates can be methods of the class, so they must already have been

1813

defined. The canonical example is the install command.

1814

</dd></dl>

1815

1816

</div>

1817

1818

<h2>10.25. <a class="reference internal" href="#module-distutils.command" title="distutils.command: This subpackage contains one module for each standard Distutils command."><code class="xref py py-mod docutils literal">distutils.command</code></a> — Individual Distutils commands<a class="headerlink" href="#module-distutils.command" title="Permalink to this headline">¶</a></h2>

1819

</div>

1820

1821

<h2>10.26. <a class="reference internal" href="#module-distutils.command.bdist" title="distutils.command.bdist: Build a binary installer for a package"><code class="xref py py-mod docutils literal">distutils.command.bdist</code></a> — Build a binary installer<a class="headerlink" href="#module-distutils.command.bdist" title="Permalink to this headline">¶</a></h2>

1822

</div>

1823

1824

<h2>10.27. <a class="reference internal" href="#module-distutils.command.bdist_packager" title="distutils.command.bdist_packager: Abstract base class for packagers"><code class="xref py py-mod docutils literal">distutils.command.bdist_packager</code></a> — Abstract base class for packagers<a class="headerlink" href="#module-distutils.command.bdist_packager" title="Permalink to this headline">¶</a></h2>

1825

</div>

1826

1827

<h2>10.28. <a class="reference internal" href="#module-distutils.command.bdist_dumb" title="distutils.command.bdist_dumb: Build a "dumb" installer - a simple archive of files"><code class="xref py py-mod docutils literal">distutils.command.bdist_dumb</code></a> — Build a “dumb” installer<a class="headerlink" href="#module-distutils.command.bdist_dumb" title="Permalink to this headline">¶</a></h2>

1828

</div>

1829

1830

<h2>10.29. <a class="reference internal" href="#module-distutils.command.bdist_msi" title="distutils.command.bdist_msi: Build a binary distribution as a Windows MSI file"><code class="xref py py-mod docutils literal">distutils.command.bdist_msi</code></a> — Build a Microsoft Installer binary package<a class="headerlink" href="#module-distutils.command.bdist_msi" title="Permalink to this headline">¶</a></h2>

1831

1832

1833

class <code class="descclassname">distutils.command.bdist_msi.</code><code class="descname">bdist_msi</code><a class="headerlink" href="#distutils.command.bdist_msi.bdist_msi" title="Permalink to this definition">¶</a></dt>

1834

<dd>Builds a <a class="reference external" href="http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx">Windows Installer</a> (.msi) binary package.

1835

In most cases, the <code class="docutils literal">bdist_msi</code> installer is a better choice than the

1836

<code class="docutils literal">bdist_wininst</code> installer, because it provides better support for

1837

Win64 platforms, allows administrators to perform non-interactive

1838

installations, and allows installation through group policies.

1839

</dd></dl>

1840

1841

</div>

1842

1843

<h2>10.30. <a class="reference internal" href="#module-distutils.command.bdist_rpm" title="distutils.command.bdist_rpm: Build a binary distribution as a Redhat RPM and SRPM"><code class="xref py py-mod docutils literal">distutils.command.bdist_rpm</code></a> — Build a binary distribution as a Redhat RPM and SRPM<a class="headerlink" href="#module-distutils.command.bdist_rpm" title="Permalink to this headline">¶</a></h2>

1844

</div>

1845

1846

<h2>10.31. <a class="reference internal" href="#module-distutils.command.bdist_wininst" title="distutils.command.bdist_wininst: Build a Windows installer"><code class="xref py py-mod docutils literal">distutils.command.bdist_wininst</code></a> — Build a Windows installer<a class="headerlink" href="#module-distutils.command.bdist_wininst" title="Permalink to this headline">¶</a></h2>

1847

</div>

1848

1849

<h2>10.32. <a class="reference internal" href="#module-distutils.command.sdist" title="distutils.command.sdist: Build a source distribution"><code class="xref py py-mod docutils literal">distutils.command.sdist</code></a> — Build a source distribution<a class="headerlink" href="#module-distutils.command.sdist" title="Permalink to this headline">¶</a></h2>

1850

</div>

1851

1852

<h2>10.33. <a class="reference internal" href="#module-distutils.command.build" title="distutils.command.build: Build all files of a package"><code class="xref py py-mod docutils literal">distutils.command.build</code></a> — Build all files of a package<a class="headerlink" href="#module-distutils.command.build" title="Permalink to this headline">¶</a></h2>

1853

</div>

1854

1855

<h2>10.34. <a class="reference internal" href="#module-distutils.command.build_clib" title="distutils.command.build_clib: Build any C libraries in a package"><code class="xref py py-mod docutils literal">distutils.command.build_clib</code></a> — Build any C libraries in a package<a class="headerlink" href="#module-distutils.command.build_clib" title="Permalink to this headline">¶</a></h2>

1856

</div>

1857

1858

<h2>10.35. <a class="reference internal" href="#module-distutils.command.build_ext" title="distutils.command.build_ext: Build any extensions in a package"><code class="xref py py-mod docutils literal">distutils.command.build_ext</code></a> — Build any extensions in a package<a class="headerlink" href="#module-distutils.command.build_ext" title="Permalink to this headline">¶</a></h2>

1859

</div>

1860

1861

<h2>10.36. <a class="reference internal" href="#module-distutils.command.build_py" title="distutils.command.build_py: Build the .py/.pyc files of a package"><code class="xref py py-mod docutils literal">distutils.command.build_py</code></a> — Build the .py/.pyc files of a package<a class="headerlink" href="#module-distutils.command.build_py" title="Permalink to this headline">¶</a></h2>

1862

1863

1864

class <code class="descclassname">distutils.command.build_py.</code><code class="descname">build_py</code><a class="headerlink" href="#distutils.command.build_py.build_py" title="Permalink to this definition">¶</a></dt>

1865

1866

1867

1868

1869

class <code class="descclassname">distutils.command.build_py.</code><code class="descname">build_py_2to3</code><a class="headerlink" href="#distutils.command.build_py.build_py_2to3" title="Permalink to this definition">¶</a></dt>

1870

<dd>Alternative implementation of build_py which also runs the

1871

2to3 conversion library on each .py file that is going to be

1872

installed. To use this in a setup.py file for a distribution

1873

that is designed to run with both Python 2.x and 3.x, add:

1874

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

1875

from distutils.command.build_py import build_py_2to3 as build_py

1876

except ImportError:

1877

from distutils.command.build_py import build_py

1878

</pre></div>

1879

</div>

1880

to your setup.py, and later:

1881

<div class="highlight-python3"><div class="highlight"><pre>cmdclass = {'build_py': build_py}

1882

</pre></div>

1883

</div>

1884

to the invocation of setup().

1885

</dd></dl>

1886

1887

</div>

1888

1889

<h2>10.37. <a class="reference internal" href="#module-distutils.command.build_scripts" title="distutils.command.build_scripts: Build the scripts of a package"><code class="xref py py-mod docutils literal">distutils.command.build_scripts</code></a> — Build the scripts of a package<a class="headerlink" href="#module-distutils.command.build_scripts" title="Permalink to this headline">¶</a></h2>

1890

</div>

1891

1892

<h2>10.38. <a class="reference internal" href="#module-distutils.command.clean" title="distutils.command.clean: Clean a package build area"><code class="xref py py-mod docutils literal">distutils.command.clean</code></a> — Clean a package build area<a class="headerlink" href="#module-distutils.command.clean" title="Permalink to this headline">¶</a></h2>

1893

This command removes the temporary files created by build

1894

and its subcommands, like intermediary compiled object files. With

1895

the <code class="docutils literal">--all</code> option, the complete build directory will be removed.

1896

Extension modules built <a class="reference internal" href="configfile.html#distutils-build-ext-inplace">in place</a>

1897

will not be cleaned, as they are not in the build directory.

1898

</div>

1899

1900

<h2>10.39. <a class="reference internal" href="#module-distutils.command.config" title="distutils.command.config: Perform package configuration"><code class="xref py py-mod docutils literal">distutils.command.config</code></a> — Perform package configuration<a class="headerlink" href="#module-distutils.command.config" title="Permalink to this headline">¶</a></h2>

1901

</div>

1902

1903

<h2>10.40. <a class="reference internal" href="#module-distutils.command.install" title="distutils.command.install: Install a package"><code class="xref py py-mod docutils literal">distutils.command.install</code></a> — Install a package<a class="headerlink" href="#module-distutils.command.install" title="Permalink to this headline">¶</a></h2>

1904

</div>

1905

1906

<h2>10.41. <a class="reference internal" href="#module-distutils.command.install_data" title="distutils.command.install_data: Install data files from a package"><code class="xref py py-mod docutils literal">distutils.command.install_data</code></a> — Install data files from a package<a class="headerlink" href="#module-distutils.command.install_data" title="Permalink to this headline">¶</a></h2>

1907

</div>

1908

1909

<h2>10.42. <a class="reference internal" href="#module-distutils.command.install_headers" title="distutils.command.install_headers: Install C/C++ header files from a package"><code class="xref py py-mod docutils literal">distutils.command.install_headers</code></a> — Install C/C++ header files from a package<a class="headerlink" href="#module-distutils.command.install_headers" title="Permalink to this headline">¶</a></h2>

1910

</div>

1911

1912

<h2>10.43. <a class="reference internal" href="#module-distutils.command.install_lib" title="distutils.command.install_lib: Install library files from a package"><code class="xref py py-mod docutils literal">distutils.command.install_lib</code></a> — Install library files from a package<a class="headerlink" href="#module-distutils.command.install_lib" title="Permalink to this headline">¶</a></h2>

1913

</div>

1914

1915

<h2>10.44. <a class="reference internal" href="#module-distutils.command.install_scripts" title="distutils.command.install_scripts: Install script files from a package"><code class="xref py py-mod docutils literal">distutils.command.install_scripts</code></a> — Install script files from a package<a class="headerlink" href="#module-distutils.command.install_scripts" title="Permalink to this headline">¶</a></h2>

1916

</div>

1917

1918

<h2>10.45. <a class="reference internal" href="#module-distutils.command.register" title="distutils.command.register: Register a module with the Python Package Index"><code class="xref py py-mod docutils literal">distutils.command.register</code></a> — Register a module with the Python Package Index<a class="headerlink" href="#module-distutils.command.register" title="Permalink to this headline">¶</a></h2>

1919

The <code class="docutils literal">register</code> command registers the package with the Python Package Index.

1920

This is described in more detail in <a class="pep reference external" href="https://www.python.org/dev/peps/pep-0301">PEP 301</a>.

1921

</div>

1922

1923

<h2>10.46. <a class="reference internal" href="#module-distutils.command.check" title="distutils.command.check: Check the metadata of a package"><code class="xref py py-mod docutils literal">distutils.command.check</code></a> — Check the meta-data of a package<a class="headerlink" href="#module-distutils.command.check" title="Permalink to this headline">¶</a></h2>

1924

The <code class="docutils literal">check</code> command performs some tests on the meta-data of a package.

1925

For example, it verifies that all required meta-data are provided as

1926

the arguments passed to the <code class="xref py py-func docutils literal">setup()</code> function.

1927

</div>

1928

</div>

1929

1930

1931

</div>

1932

</div>

1933

</div>

1934

1935

1936

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

1937

<ul>

1938

<li><a class="reference internal" href="#">10. API Reference</a><ul>

1939

<li><a class="reference internal" href="#module-distutils.core">10.1. <code class="docutils literal">distutils.core</code> — Core Distutils functionality</a></li>

1940

<li><a class="reference internal" href="#module-distutils.ccompiler">10.2. <code class="docutils literal">distutils.ccompiler</code> — CCompiler base class</a></li>

1941

<li><a class="reference internal" href="#module-distutils.unixccompiler">10.3. <code class="docutils literal">distutils.unixccompiler</code> — Unix C Compiler</a></li>

1942

<li><a class="reference internal" href="#module-distutils.msvccompiler">10.4. <code class="docutils literal">distutils.msvccompiler</code> — Microsoft Compiler</a></li>

1943

<li><a class="reference internal" href="#module-distutils.bcppcompiler">10.5. <code class="docutils literal">distutils.bcppcompiler</code> — Borland Compiler</a></li>

1944

<li><a class="reference internal" href="#module-distutils.cygwinccompiler">10.6. <code class="docutils literal">distutils.cygwincompiler</code> — Cygwin Compiler</a></li>

1945

<li><a class="reference internal" href="#module-distutils.archive_util">10.7. <code class="docutils literal">distutils.archive_util</code> — Archiving utilities</a></li>

1946

<li><a class="reference internal" href="#module-distutils.dep_util">10.8. <code class="docutils literal">distutils.dep_util</code> — Dependency checking</a></li>

1947

<li><a class="reference internal" href="#module-distutils.dir_util">10.9. <code class="docutils literal">distutils.dir_util</code> — Directory tree operations</a></li>

1948

<li><a class="reference internal" href="#module-distutils.file_util">10.10. <code class="docutils literal">distutils.file_util</code> — Single file operations</a></li>

1949

<li><a class="reference internal" href="#module-distutils.util">10.11. <code class="docutils literal">distutils.util</code> — Miscellaneous other utility functions</a></li>

1950

<li><a class="reference internal" href="#module-distutils.dist">10.12. <code class="docutils literal">distutils.dist</code> — The Distribution class</a></li>

1951

<li><a class="reference internal" href="#module-distutils.extension">10.13. <code class="docutils literal">distutils.extension</code> — The Extension class</a></li>

1952

<li><a class="reference internal" href="#module-distutils.debug">10.14. <code class="docutils literal">distutils.debug</code> — Distutils debug mode</a></li>

1953

<li><a class="reference internal" href="#module-distutils.errors">10.15. <code class="docutils literal">distutils.errors</code> — Distutils exceptions</a></li>

1954

<li><a class="reference internal" href="#module-distutils.fancy_getopt">10.16. <code class="docutils literal">distutils.fancy_getopt</code> — Wrapper around the standard getopt module</a></li>

1955

<li><a class="reference internal" href="#module-distutils.filelist">10.17. <code class="docutils literal">distutils.filelist</code> — The FileList class</a></li>

1956

<li><a class="reference internal" href="#module-distutils.log">10.18. <code class="docutils literal">distutils.log</code> — Simple PEP 282-style logging</a></li>

1957

<li><a class="reference internal" href="#module-distutils.spawn">10.19. <code class="docutils literal">distutils.spawn</code> — Spawn a sub-process</a></li>

1958

<li><a class="reference internal" href="#module-distutils.sysconfig">10.20. <code class="docutils literal">distutils.sysconfig</code> — System configuration information</a></li>

1959

<li><a class="reference internal" href="#module-distutils.text_file">10.21. <code class="docutils literal">distutils.text_file</code> — The TextFile class</a></li>

1960

<li><a class="reference internal" href="#module-distutils.version">10.22. <code class="docutils literal">distutils.version</code> — Version number classes</a></li>

1961

<li><a class="reference internal" href="#module-distutils.cmd">10.23. <code class="docutils literal">distutils.cmd</code> — Abstract base class for Distutils commands</a></li>

1962

<li><a class="reference internal" href="#creating-a-new-distutils-command">10.24. Creating a new Distutils command</a></li>

1963

<li><a class="reference internal" href="#module-distutils.command">10.25. <code class="docutils literal">distutils.command</code> — Individual Distutils commands</a></li>

1964

<li><a class="reference internal" href="#module-distutils.command.bdist">10.26. <code class="docutils literal">distutils.command.bdist</code> — Build a binary installer</a></li>

1965

<li><a class="reference internal" href="#module-distutils.command.bdist_packager">10.27. <code class="docutils literal">distutils.command.bdist_packager</code> — Abstract base class for packagers</a></li>

1966

<li><a class="reference internal" href="#module-distutils.command.bdist_dumb">10.28. <code class="docutils literal">distutils.command.bdist_dumb</code> — Build a “dumb” installer</a></li>

1967

<li><a class="reference internal" href="#module-distutils.command.bdist_msi">10.29. <code class="docutils literal">distutils.command.bdist_msi</code> — Build a Microsoft Installer binary package</a></li>

1968

<li><a class="reference internal" href="#module-distutils.command.bdist_rpm">10.30. <code class="docutils literal">distutils.command.bdist_rpm</code> — Build a binary distribution as a Redhat RPM and SRPM</a></li>

1969

<li><a class="reference internal" href="#module-distutils.command.bdist_wininst">10.31. <code class="docutils literal">distutils.command.bdist_wininst</code> — Build a Windows installer</a></li>

1970

<li><a class="reference internal" href="#module-distutils.command.sdist">10.32. <code class="docutils literal">distutils.command.sdist</code> — Build a source distribution</a></li>

1971

<li><a class="reference internal" href="#module-distutils.command.build">10.33. <code class="docutils literal">distutils.command.build</code> — Build all files of a package</a></li>

1972

<li><a class="reference internal" href="#module-distutils.command.build_clib">10.34. <code class="docutils literal">distutils.command.build_clib</code> — Build any C libraries in a package</a></li>

1973

<li><a class="reference internal" href="#module-distutils.command.build_ext">10.35. <code class="docutils literal">distutils.command.build_ext</code> — Build any extensions in a package</a></li>

1974

<li><a class="reference internal" href="#module-distutils.command.build_py">10.36. <code class="docutils literal">distutils.command.build_py</code> — Build the .py/.pyc files of a package</a></li>

1975

<li><a class="reference internal" href="#module-distutils.command.build_scripts">10.37. <code class="docutils literal">distutils.command.build_scripts</code> — Build the scripts of a package</a></li>

1976

<li><a class="reference internal" href="#module-distutils.command.clean">10.38. <code class="docutils literal">distutils.command.clean</code> — Clean a package build area</a></li>

1977

<li><a class="reference internal" href="#module-distutils.command.config">10.39. <code class="docutils literal">distutils.command.config</code> — Perform package configuration</a></li>

1978

<li><a class="reference internal" href="#module-distutils.command.install">10.40. <code class="docutils literal">distutils.command.install</code> — Install a package</a></li>

1979

<li><a class="reference internal" href="#module-distutils.command.install_data">10.41. <code class="docutils literal">distutils.command.install_data</code> — Install data files from a package</a></li>

1980

<li><a class="reference internal" href="#module-distutils.command.install_headers">10.42. <code class="docutils literal">distutils.command.install_headers</code> — Install C/C++ header files from a package</a></li>

1981

<li><a class="reference internal" href="#module-distutils.command.install_lib">10.43. <code class="docutils literal">distutils.command.install_lib</code> — Install library files from a package</a></li>

1982

<li><a class="reference internal" href="#module-distutils.command.install_scripts">10.44. <code class="docutils literal">distutils.command.install_scripts</code> — Install script files from a package</a></li>

1983

<li><a class="reference internal" href="#module-distutils.command.register">10.45. <code class="docutils literal">distutils.command.register</code> — Register a module with the Python Package Index</a></li>

1984

<li><a class="reference internal" href="#module-distutils.command.check">10.46. <code class="docutils literal">distutils.command.check</code> — Check the meta-data of a package</a></li>

1985

</ul>

1986

</li>

1987

</ul>

1988

1989

<h4>Previous topic</h4>

1990

<a href="commandref.html"

1991

title="previous chapter">9. Command Reference</a>

1992

<h4>Next topic</h4>

1993

<a href="../install/index.html"

1994

title="next chapter">Installing Python Modules (Legacy version)</a>

1995

1996

1997

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

1998

<li><a href="../_sources/distutils/apiref.txt"

1999

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

2000

</ul>

2001

2002

2003

<h3>Quick search</h3>

2004

2005

2006

2007

2008

2009

</form>

2010

2011

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

2012

2013

</div>

2014

2015

</div>

2016

</div>

2017

2018

</div>

2019

2020

<h3>Navigation</h3>

2021

<ul>

2022

2023

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

2024

>index</a></li>

2025

2026

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

2027

>modules</a> |</li>

2028

2029

<a href="../install/index.html" title="Installing Python Modules (Legacy version)"

2030

>next</a> |</li>

2031

2032

<a href="commandref.html" title="9. Command Reference"

2033

>previous</a> |</li>

2034

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

2035

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

2036

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

2037

<li>

2038

3.5.1

2039

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

2040

</li>

2041

2042

<li class="nav-item nav-item-1"><a href="index.html" >Distributing Python Modules (Legacy version)</a> »</li>

2043

</ul>

2044

</div>

2045

2046

2047

2048

The Python Software Foundation is a non-profit corporation.

2049

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

2050

2051

Last updated on Jan 22, 2016.

2052

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

2053

2054

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

2055

</div>

2056

2057

</body>

2058

</html>

b'\\ No newline at end of file'

Older »