~dkuhlman/python-training-materials/Materials

<h1>28.1. <a class="reference internal" href="#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal">sys</code></a> — System-specific parameters and functions<a class="headerlink" href="#module-sys" title="Permalink to this headline">¶</a></h1>

This module provides access to some variables used or maintained by the

interpreter and to functions that interact strongly with the interpreter. It is

always available.

<dd>The list of command line arguments passed to a Python script. <code class="docutils literal">argv[0]</code> is the

script name (it is operating system dependent whether this is a full pathname or

not). If the command was executed using the <a class="reference internal" href="../using/cmdline.html#cmdoption-c"><code class="xref std std-option docutils literal">-c</code></a> command line option to

the interpreter, <code class="docutils literal">argv[0]</code> is set to the string <code class="docutils literal">'-c'</code>. If no script name

was passed to the Python interpreter, <code class="docutils literal">argv[0]</code> is the empty string.

To loop over the standard input, or the list of files given on the

command line, see the <a class="reference internal" href="fileinput.html#module-fileinput" title="fileinput: Loop over standard input or a list of files."><code class="xref py py-mod docutils literal">fileinput</code></a> module.

</dd></dl>

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

<dd>An indicator of the native byte order. This will have the value <code class="docutils literal">'big'</code> on

big-endian (most-significant byte first) platforms, and <code class="docutils literal">'little'</code> on

little-endian (least-significant byte first) platforms.

100

101

New in version 2.0.

102

</div>

103

</dd></dl>

104

105

106

107

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

108

<dd>A tuple of strings giving the names of all modules that are compiled into this

109

Python interpreter. (This information is not available in any other way —

110

<code class="docutils literal">modules.keys()</code> only lists the imported modules.)

111

</dd></dl>

112

113

114

115

<code class="descclassname">sys.</code><code class="descname">call_tracing</code>(func, args)<a class="headerlink" href="#sys.call_tracing" title="Permalink to this definition">¶</a></dt>

116

<dd>Call <code class="docutils literal">func(*args)</code>, while tracing is enabled. The tracing state is saved,

117

and restored afterwards. This is intended to be called from a debugger from

118

a checkpoint, to recursively debug some other code.

119

</dd></dl>

120

121

122

123

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

124

<dd>A string containing the copyright pertaining to the Python interpreter.

125

</dd></dl>

126

127

128

129

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

130

<dd>Clear the internal type cache. The type cache is used to speed up attribute

131

and method lookups. Use the function only to drop unnecessary references

132

during reference leak debugging.

133

This function should be used for internal and specialized purposes only.

134

135

New in version 2.6.

136

</div>

137

</dd></dl>

138

139

140

141

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

142

<dd>Return a dictionary mapping each thread’s identifier to the topmost stack frame

143

currently active in that thread at the time the function is called. Note that

144

functions in the <a class="reference internal" href="traceback.html#module-traceback" title="traceback: Print or retrieve a stack traceback."><code class="xref py py-mod docutils literal">traceback</code></a> module can build the call stack given such a

145

frame.

146

This is most useful for debugging deadlock: this function does not require the

147

deadlocked threads’ cooperation, and such threads’ call stacks are frozen for as

148

long as they remain deadlocked. The frame returned for a non-deadlocked thread

149

may bear no relationship to that thread’s current activity by the time calling

150

code examines the frame.

151

This function should be used for internal and specialized purposes only.

152

153

New in version 2.5.

154

</div>

155

</dd></dl>

156

157

158

159

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

160

<dd>Integer specifying the handle of the Python DLL. Availability: Windows.

161

</dd></dl>

162

163

164

165

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

166

<dd>If value is not <code class="docutils literal">None</code>, this function prints it to <code class="docutils literal">sys.stdout</code>, and saves

167

it in <code class="docutils literal">__builtin__._</code>.

168

<code class="docutils literal">sys.displayhook</code> is called on the result of evaluating an <a class="reference internal" href="../glossary.html#term-expression">expression</a>

169

entered in an interactive Python session. The display of these values can be

170

customized by assigning another one-argument function to <code class="docutils literal">sys.displayhook</code>.

171

</dd></dl>

172

173

174

175

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

176

<dd>If this is true, Python won’t try to write <code class="docutils literal">.pyc</code> or <code class="docutils literal">.pyo</code> files on the

177

import of source modules. This value is initially set to <code class="docutils literal">True</code> or

178

<code class="docutils literal">False</code> depending on the <a class="reference internal" href="../using/cmdline.html#cmdoption-B"><code class="xref std std-option docutils literal">-B</code></a> command line option and the

179

<a class="reference internal" href="../using/cmdline.html#envvar-PYTHONDONTWRITEBYTECODE"><code class="xref std std-envvar docutils literal">PYTHONDONTWRITEBYTECODE</code></a> environment variable, but you can set it

180

yourself to control bytecode file generation.

181

182

New in version 2.6.

183

</div>

184

</dd></dl>

185

186

187

188

<code class="descclassname">sys.</code><code class="descname">excepthook</code>(type, value, traceback)<a class="headerlink" href="#sys.excepthook" title="Permalink to this definition">¶</a></dt>

189

<dd>This function prints out a given traceback and exception to <code class="docutils literal">sys.stderr</code>.

190

When an exception is raised and uncaught, the interpreter calls

191

<code class="docutils literal">sys.excepthook</code> with three arguments, the exception class, exception

192

instance, and a traceback object. In an interactive session this happens just

193

before control is returned to the prompt; in a Python program this happens just

194

before the program exits. The handling of such top-level exceptions can be

195

customized by assigning another three-argument function to <code class="docutils literal">sys.excepthook</code>.

196

</dd></dl>

197

198

199

200

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

201

202

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

203

<dd>These objects contain the original values of <code class="docutils literal">displayhook</code> and <code class="docutils literal">excepthook</code>

204

at the start of the program. They are saved so that <code class="docutils literal">displayhook</code> and

205

<code class="docutils literal">excepthook</code> can be restored in case they happen to get replaced with broken

206

objects.

207

</dd></dl>

208

209

210

211

212

<dd>This function returns a tuple of three values that give information about the

213

exception that is currently being handled. The information returned is specific

214

both to the current thread and to the current stack frame. If the current stack

215

frame is not handling an exception, the information is taken from the calling

216

stack frame, or its caller, and so on until a stack frame is found that is

217

handling an exception. Here, “handling an exception” is defined as “executing

218

or having executed an except clause.” For any stack frame, only information

219

about the most recently handled exception is accessible.

220

If no exception is being handled anywhere on the stack, a tuple containing three

221

<code class="docutils literal">None</code> values is returned. Otherwise, the values returned are <code class="docutils literal">(type, value,

222

traceback)</code>. Their meaning is: type gets the exception type of the exception

223

being handled (a class object); value gets the exception parameter (its

224

associated value or the second argument to <a class="reference internal" href="../reference/simple_stmts.html#raise"><code class="xref std std-keyword docutils literal">raise</code></a>, which is

225

always a class instance if the exception type is a class object); traceback

226

gets a traceback object (see the Reference Manual) which encapsulates the call

227

stack at the point where the exception originally occurred.

228

If <a class="reference internal" href="#sys.exc_clear" title="sys.exc_clear"><code class="xref py py-func docutils literal">exc_clear()</code></a> is called, this function will return three <code class="docutils literal">None</code> values

229

until either another exception is raised in the current thread or the execution

230

stack returns to a frame where another exception is being handled.

231

232

Warning

233

Assigning the traceback return value to a local variable in a function that is

234

handling an exception will cause a circular reference. This will prevent

235

anything referenced by a local variable in the same function or by the traceback

236

from being garbage collected. Since most functions don’t need access to the

237

traceback, the best solution is to use something like <code class="docutils literal">exctype, value =

238

sys.exc_info()[:2]</code> to extract only the exception type and value. If you do

239

need the traceback, make sure to delete it after use (best done with a

240

<a class="reference internal" href="../reference/compound_stmts.html#try"><code class="xref std std-keyword docutils literal">try</code></a> ... <a class="reference internal" href="../reference/compound_stmts.html#finally"><code class="xref std std-keyword docutils literal">finally</code></a> statement) or to call <a class="reference internal" href="#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal">exc_info()</code></a> in

241

a function that does not itself handle an exception.

242

</div>

243

244

Note

245

Beginning with Python 2.2, such cycles are automatically reclaimed when garbage

246

collection is enabled and they become unreachable, but it remains more efficient

247

to avoid creating cycles.

248

</div>

249

</dd></dl>

250

251

252

253

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

254

<dd>This function clears all information relating to the current or last exception

255

that occurred in the current thread. After calling this function,

256

<a class="reference internal" href="#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal">exc_info()</code></a> will return three <code class="docutils literal">None</code> values until another exception is

257

raised in the current thread or the execution stack returns to a frame where

258

another exception is being handled.

259

This function is only needed in only a few obscure situations. These include

260

logging and error handling systems that report information on the last or

261

current exception. This function can also be used to try to free resources and

262

trigger object finalization, though no guarantee is made as to what objects will

263

be freed, if any.

264

265

New in version 2.3.

266

</div>

267

</dd></dl>

268

269

270

271

272

273

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

274

275

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

276

277

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

278

</div>

279

Since they are global variables, they are not specific to the current thread, so

280

their use is not safe in a multi-threaded program. When no exception is being

281

handled, <code class="docutils literal">exc_type</code> is set to <code class="docutils literal">None</code> and the other two are undefined.

282

</dd></dl>

283

284

285

286

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

287

<dd>A string giving the site-specific directory prefix where the platform-dependent

288

Python files are installed; by default, this is also <code class="docutils literal">'/usr/local'</code>. This can

289

be set at build time with the <code class="docutils literal">--exec-prefix</code> argument to the

290

configure script. Specifically, all configuration files (e.g. the

291

<code class="file docutils literal">pyconfig.h</code> header file) are installed in the directory

292

<code class="file docutils literal">exec_prefix/lib/pythonX.Y/config</code>, and shared library modules are

293

installed in <code class="file docutils literal">exec_prefix/lib/pythonX.Y/lib-dynload</code>, where X.Y

294

is the version number of Python, for example <code class="docutils literal">2.7</code>.

295

</dd></dl>

296

297

298

299

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

300

<dd>A string giving the absolute path of the executable binary for the Python

301

interpreter, on systems where this makes sense. If Python is unable to retrieve

302

the real path to its executable, <a class="reference internal" href="#sys.executable" title="sys.executable"><code class="xref py py-data docutils literal">sys.executable</code></a> will be an empty string

303

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

304

</dd></dl>

305

306

307

308

309

<dd>Exit from Python. This is implemented by raising the <a class="reference internal" href="exceptions.html#exceptions.SystemExit" title="exceptions.SystemExit"><code class="xref py py-exc docutils literal">SystemExit</code></a>

310

exception, so cleanup actions specified by finally clauses of <a class="reference internal" href="../reference/compound_stmts.html#try"><code class="xref std std-keyword docutils literal">try</code></a>

311

statements are honored, and it is possible to intercept the exit attempt at

312

an outer level.

313

The optional argument arg can be an integer giving the exit status

314

(defaulting to zero), or another type of object. If it is an integer, zero

315

is considered “successful termination” and any nonzero value is considered

316

“abnormal termination” by shells and the like. Most systems require it to be

317

in the range 0–127, and produce undefined results otherwise. Some systems

318

have a convention for assigning specific meanings to specific exit codes, but

319

these are generally underdeveloped; Unix programs generally use 2 for command

320

line syntax errors and 1 for all other kind of errors. If another type of

321

object is passed, <code class="docutils literal">None</code> is equivalent to passing zero, and any other

322

object is printed to <a class="reference internal" href="#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal">stderr</code></a> and results in an exit code of 1. In

323

particular, <code class="docutils literal">sys.exit("some error message")</code> is a quick way to exit a

324

program when an error occurs.

325

Since <a class="reference internal" href="constants.html#exit" title="exit"><code class="xref py py-func docutils literal">exit()</code></a> ultimately “only” raises an exception, it will only exit

326

the process when called from the main thread, and the exception is not

327

intercepted.

328

</dd></dl>

329

330

331

332

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

333

<dd>This value is not actually defined by the module, but can be set by the user (or

334

by a program) to specify a clean-up action at program exit. When set, it should

335

be a parameterless function. This function will be called when the interpreter

336

exits. Only one function may be installed in this way; to allow multiple

337

functions which will be called at termination, use the <a class="reference internal" href="atexit.html#module-atexit" title="atexit: Register and execute cleanup functions."><code class="xref py py-mod docutils literal">atexit</code></a> module.

338

339

Note

340

The exit function is not called when the program is killed by a signal, when a

341

Python fatal internal error is detected, or when <code class="docutils literal">os._exit()</code> is called.

342

</div>

343

344

Deprecated since version 2.4: Use <a class="reference internal" href="atexit.html#module-atexit" title="atexit: Register and execute cleanup functions."><code class="xref py py-mod docutils literal">atexit</code></a> instead.

345

</div>

346

</dd></dl>

347

348

349

350

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

351

<dd>The struct sequence flags exposes the status of command line flags. The

352

attributes are read only.

353

354

355

356

357

</colgroup>

358

359

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

360

361

</tr>

362

</thead>

363

364

<tr class="row-even"><td><code class="xref py py-const docutils literal">debug</code></td>

365

366

</tr>

367

<tr class="row-odd"><td><code class="xref py py-const docutils literal">py3k_warning</code></td>

368

369

</tr>

370

<tr class="row-even"><td><code class="xref py py-const docutils literal">division_warning</code></td>

371

372

</tr>

373

<tr class="row-odd"><td><code class="xref py py-const docutils literal">division_new</code></td>

374

375

</tr>

376

<tr class="row-even"><td><a class="reference internal" href="inspect.html#module-inspect" title="inspect: Extract information and source code from live objects."><code class="xref py py-const docutils literal">inspect</code></a></td>

377

378

</tr>

379

<tr class="row-odd"><td><code class="xref py py-const docutils literal">interactive</code></td>

380

381

</tr>

382

<tr class="row-even"><td><code class="xref py py-const docutils literal">optimize</code></td>

383

384

</tr>

385

<tr class="row-odd"><td><a class="reference internal" href="#sys.dont_write_bytecode" title="sys.dont_write_bytecode"><code class="xref py py-const docutils literal">dont_write_bytecode</code></a></td>

386

387

</tr>

388

389

390

</tr>

391

392

393

</tr>

394

<tr class="row-even"><td><code class="xref py py-const docutils literal">ignore_environment</code></td>

395

396

</tr>

397

<tr class="row-odd"><td><code class="xref py py-const docutils literal">tabcheck</code></td>

398

399

</tr>

400

<tr class="row-even"><td><code class="xref py py-const docutils literal">verbose</code></td>

401

402

</tr>

403

<tr class="row-odd"><td><a class="reference internal" href="functions.html#unicode" title="unicode"><code class="xref py py-const docutils literal">unicode</code></a></td>

404

405

</tr>

406

<tr class="row-even"><td><code class="xref py py-const docutils literal">bytes_warning</code></td>

407

408

</tr>

409

<tr class="row-odd"><td><code class="xref py py-const docutils literal">hash_randomization</code></td>

410

411

</tr>

412

</tbody>

413

</table>

414

415

New in version 2.6.

416

</div>

417

418

New in version 2.7.3: The <code class="docutils literal">hash_randomization</code> attribute.

419

</div>

420

</dd></dl>

421

422

423

424

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

425

<dd>A structseq holding information about the float type. It contains low level

426

information about the precision and internal representation. The values

427

correspond to the various floating-point constants defined in the standard

428

header file <code class="file docutils literal">float.h</code> for the ‘C’ programming language; see section

429

5.2.4.2.2 of the 1999 ISO/IEC C standard <a class="reference internal" href="#c99" id="id1">[C99]</a>, ‘Characteristics of

430

floating types’, for details.

431

432

433

434

435

436

</colgroup>

437

438

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

439

<th class="head">float.h macro</th>

440

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

441

</tr>

442

</thead>

443

444

<tr class="row-even"><td><code class="xref py py-const docutils literal">epsilon</code></td>

445

<td>DBL_EPSILON</td>

446

<td>difference between 1 and the least value greater

447

than 1 that is representable as a float</td>

448

</tr>

449

450

451

<td>maximum number of decimal digits that can be

452

faithfully represented in a float; see below</td>

453

</tr>

454

455

456

<td>float precision: the number of base-<code class="docutils literal">radix</code>

457

digits in the significand of a float</td>

458

</tr>

459

460

461

<td>maximum representable finite float</td>

462

</tr>

463

464

465

<td>maximum integer e such that <code class="docutils literal">radix**(e-1)</code> is

466

a representable finite float</td>

467

</tr>

468

469

470

<td>maximum integer e such that <code class="docutils literal">10**e</code> is in the

471

range of representable finite floats</td>

472

</tr>

473

474

475

<td>minimum positive normalized float</td>

476

</tr>

477

478

479

<td>minimum integer e such that <code class="docutils literal">radix**(e-1)</code> is

480

a normalized float</td>

481

</tr>

482

483

484

<td>minimum integer e such that <code class="docutils literal">10**e</code> is a

485

normalized float</td>

486

</tr>

487

<tr class="row-odd"><td><code class="xref py py-const docutils literal">radix</code></td>

488

<td>FLT_RADIX</td>

489

<td>radix of exponent representation</td>

490

</tr>

491

<tr class="row-even"><td><code class="xref py py-const docutils literal">rounds</code></td>

492

<td>FLT_ROUNDS</td>

493

<td>integer constant representing the rounding mode

494

used for arithmetic operations. This reflects

495

the value of the system FLT_ROUNDS macro at

496

interpreter startup time. See section 5.2.4.2.2

497

of the C99 standard for an explanation of the

498

possible values and their meanings.</td>

499

</tr>

500

</tbody>

501

</table>

502

The attribute <code class="xref py py-attr docutils literal">sys.float_info.dig</code> needs further explanation. If

503

<code class="docutils literal">s</code> is any string representing a decimal number with at most

504

<code class="xref py py-attr docutils literal">sys.float_info.dig</code> significant digits, then converting <code class="docutils literal">s</code> to a

505

float and back again will recover a string representing the same decimal

506

value:

507

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

508

>>> sys.float_info.dig

509

15

510

>>> s = '3.14159265358979' # decimal string with 15 significant digits

511

>>> format(float(s), '.15g') # convert to float and back -> same value

512

'3.14159265358979'

513

</pre></div>

514

</div>

515

But for strings with more than <code class="xref py py-attr docutils literal">sys.float_info.dig</code> significant digits,

516

this isn’t always true:

517

<div class="highlight-python"><div class="highlight"><pre>>>> s = '9876543211234567' # 16 significant digits is too many!

518

>>> format(float(s), '.16g') # conversion changes value

519

'9876543211234568'

520

</pre></div>

521

</div>

522

523

New in version 2.6.

524

</div>

525

</dd></dl>

526

527

528

529

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

530

<dd>A string indicating how the <a class="reference internal" href="functions.html#repr" title="repr"><code class="xref py py-func docutils literal">repr()</code></a> function behaves for

531

floats. If the string has value <code class="docutils literal">'short'</code> then for a finite

532

float <code class="docutils literal">x</code>, <code class="docutils literal">repr(x)</code> aims to produce a short string with the

533

property that <code class="docutils literal">float(repr(x)) == x</code>. This is the usual behaviour

534

in Python 2.7 and later. Otherwise, <code class="docutils literal">float_repr_style</code> has value

535

<code class="docutils literal">'legacy'</code> and <code class="docutils literal">repr(x)</code> behaves in the same way as it did in

536

versions of Python prior to 2.7.

537

538

New in version 2.7.

539

</div>

540

</dd></dl>

541

542

543

544

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

545

<dd>Return the interpreter’s “check interval”; see <a class="reference internal" href="#sys.setcheckinterval" title="sys.setcheckinterval"><code class="xref py py-func docutils literal">setcheckinterval()</code></a>.

546

547

New in version 2.3.

548

</div>

549

</dd></dl>

550

551

552

553

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

554

<dd>Return the name of the current default string encoding used by the Unicode

555

implementation.

556

557

New in version 2.0.

558

</div>

559

</dd></dl>

560

561

562

563

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

564

<dd>Return the current value of the flags that are used for <code class="xref c c-func docutils literal">dlopen()</code> calls.

565

The flag constants are defined in the <a class="reference internal" href="dl.html#module-dl" title="dl: Call C functions in shared objects. (deprecated) (Unix)"><code class="xref py py-mod docutils literal">dl</code></a> and <code class="xref py py-mod docutils literal">DLFCN</code> modules.

566

Availability: Unix.

567

568

New in version 2.2.

569

</div>

570

</dd></dl>

571

572

573

574

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

575

<dd>Return the name of the encoding used to convert Unicode filenames into system

576

file names, or <code class="docutils literal">None</code> if the system default encoding is used. The result value

577

depends on the operating system:

578

579

<li>On Mac OS X, the encoding is <code class="docutils literal">'utf-8'</code>.</li>

580

<li>On Unix, the encoding is the user’s preference according to the result of

581

nl_langinfo(CODESET), or <code class="docutils literal">None</code> if the <code class="docutils literal">nl_langinfo(CODESET)</code>

582

failed.</li>

583

<li>On Windows NT+, file names are Unicode natively, so no conversion is

584

performed. <a class="reference internal" href="#sys.getfilesystemencoding" title="sys.getfilesystemencoding"><code class="xref py py-func docutils literal">getfilesystemencoding()</code></a> still returns <code class="docutils literal">'mbcs'</code>, as

585

this is the encoding that applications should use when they explicitly

586

want to convert Unicode strings to byte strings that are equivalent when

587

used as file names.</li>

588

<li>On Windows 9x, the encoding is <code class="docutils literal">'mbcs'</code>.</li>

589

</ul>

590

591

New in version 2.3.

592

</div>

593

</dd></dl>

594

595

596

597

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

598

<dd>Return the reference count of the object. The count returned is generally one

599

higher than you might expect, because it includes the (temporary) reference as

600

an argument to <a class="reference internal" href="#sys.getrefcount" title="sys.getrefcount"><code class="xref py py-func docutils literal">getrefcount()</code></a>.

601

</dd></dl>

602

603

604

605

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

606

<dd>Return the current value of the recursion limit, the maximum depth of the Python

607

interpreter stack. This limit prevents infinite recursion from causing an

608

overflow of the C stack and crashing Python. It can be set by

609

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

610

</dd></dl>

611

612

613

614

<code class="descclassname">sys.</code><code class="descname">getsizeof</code>(object[, default])<a class="headerlink" href="#sys.getsizeof" title="Permalink to this definition">¶</a></dt>

615

<dd>Return the size of an object in bytes. The object can be any type of

616

object. All built-in objects will return correct results, but this

617

does not have to hold true for third-party extensions as it is implementation

618

specific.

619

If given, default will be returned if the object does not provide means to

620

retrieve the size. Otherwise a <a class="reference internal" href="exceptions.html#exceptions.TypeError" title="exceptions.TypeError"><code class="xref py py-exc docutils literal">TypeError</code></a> will be raised.

621

<a class="reference internal" href="#sys.getsizeof" title="sys.getsizeof"><code class="xref py py-func docutils literal">getsizeof()</code></a> calls the object’s <code class="docutils literal">__sizeof__</code> method and adds an

622

additional garbage collector overhead if the object is managed by the garbage

623

collector.

624

625

New in version 2.6.

626

</div>

627

</dd></dl>

628

629

630

631

<code class="descclassname">sys.</code><code class="descname">_getframe</code>([depth])<a class="headerlink" href="#sys._getframe" title="Permalink to this definition">¶</a></dt>

632

<dd>Return a frame object from the call stack. If optional integer depth is

633

given, return the frame object that many calls below the top of the stack. If

634

that is deeper than the call stack, <a class="reference internal" href="exceptions.html#exceptions.ValueError" title="exceptions.ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> is raised. The default

635

for depth is zero, returning the frame at the top of the call stack.

636

637

CPython implementation detail: This function should be used for internal and specialized purposes only.

638

It is not guaranteed to exist in all implementations of Python.

639

</div>

640

</dd></dl>

641

642

643

644

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

645

<dd>Get the profiler function as set by <a class="reference internal" href="#sys.setprofile" title="sys.setprofile"><code class="xref py py-func docutils literal">setprofile()</code></a>.

646

647

New in version 2.6.

648

</div>

649

</dd></dl>

650

651

652

653

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

654

<dd>Get the trace function as set by <a class="reference internal" href="#sys.settrace" title="sys.settrace"><code class="xref py py-func docutils literal">settrace()</code></a>.

655

656

CPython implementation detail: The <a class="reference internal" href="#sys.gettrace" title="sys.gettrace"><code class="xref py py-func docutils literal">gettrace()</code></a> function is intended only for implementing debuggers,

657

profilers, coverage tools and the like. Its behavior is part of the

658

implementation platform, rather than part of the language definition, and

659

thus may not be available in all Python implementations.

660

</div>

661

662

New in version 2.6.

663

</div>

664

</dd></dl>

665

666

667

668

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

669

<dd>Return a named tuple describing the Windows version

670

currently running. The named elements are major, minor,

671

build, platform, service_pack, service_pack_minor,

672

service_pack_major, suite_mask, and product_type.

673

service_pack contains a string while all other values are

674

integers. The components can also be accessed by name, so

675

<code class="docutils literal">sys.getwindowsversion()[0]</code> is equivalent to

676

<code class="docutils literal">sys.getwindowsversion().major</code>. For compatibility with prior

677

versions, only the first 5 elements are retrievable by indexing.

678

platform may be one of the following values:

679

680

681

682

683

</colgroup>

684

685

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

686

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

687

</tr>

688

</thead>

689

690

<tr class="row-even"><td><code class="xref py py-const docutils literal">0 (VER_PLATFORM_WIN32s)</code></td>

691

<td>Win32s on Windows 3.1</td>

692

</tr>

693

<tr class="row-odd"><td><code class="xref py py-const docutils literal">1 (VER_PLATFORM_WIN32_WINDOWS)</code></td>

694

<td>Windows 95/98/ME</td>

695

</tr>

696

<tr class="row-even"><td><code class="xref py py-const docutils literal">2 (VER_PLATFORM_WIN32_NT)</code></td>

697

<td>Windows NT/2000/XP/x64</td>

698

</tr>

699

<tr class="row-odd"><td><code class="xref py py-const docutils literal">3 (VER_PLATFORM_WIN32_CE)</code></td>

700

<td>Windows CE</td>

701

</tr>

702

</tbody>

703

</table>

704

product_type may be one of the following values:

705

706

707

708

709

</colgroup>

710

711

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

712

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

713

</tr>

714

</thead>

715

716

<tr class="row-even"><td><code class="xref py py-const docutils literal">1 (VER_NT_WORKSTATION)</code></td>

717

<td>The system is a workstation.</td>

718

</tr>

719

<tr class="row-odd"><td><code class="xref py py-const docutils literal">2 (VER_NT_DOMAIN_CONTROLLER)</code></td>

720

<td>The system is a domain

721

controller.</td>

722

</tr>

723

<tr class="row-even"><td><code class="xref py py-const docutils literal">3 (VER_NT_SERVER)</code></td>

724

<td>The system is a server, but not

725

a domain controller.</td>

726

</tr>

727

</tbody>

728

</table>

729

This function wraps the Win32 <code class="xref c c-func docutils literal">GetVersionEx()</code> function; see the

730

Microsoft documentation on <code class="xref c c-func docutils literal">OSVERSIONINFOEX()</code> for more information

731

about these fields.

732

Availability: Windows.

733

734

New in version 2.3.

735

</div>

736

737

Changed in version 2.7: Changed to a named tuple and added service_pack_minor,

738

service_pack_major, suite_mask, and product_type.

739

</div>

740

</dd></dl>

741

742

743

744

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

745

<dd>The version number encoded as a single integer. This is guaranteed to increase

746

with each version, including proper support for non-production releases. For

747

example, to test that the Python interpreter is at least version 1.5.2, use:

748

<div class="highlight-python"><div class="highlight"><pre>if sys.hexversion >= 0x010502F0:

749

# use some advanced feature

750

...

751

else:

752

# use an alternative implementation or warn the user

753

...

754

</pre></div>

755

</div>

756

This is called <code class="docutils literal">hexversion</code> since it only really looks meaningful when viewed

757

as the result of passing it to the built-in <a class="reference internal" href="functions.html#hex" title="hex"><code class="xref py py-func docutils literal">hex()</code></a> function. The

758

<code class="docutils literal">version_info</code> value may be used for a more human-friendly encoding of the

759

same information.

760

The <code class="docutils literal">hexversion</code> is a 32-bit number with the following layout:

761

762

763

764

765

</colgroup>

766

767

<tr class="row-odd"><th class="head">Bits (big endian order)</th>

768

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

769

</tr>

770

</thead>

771

772

773

<td><code class="docutils literal">PY_MAJOR_VERSION</code> (the <code class="docutils literal">2</code> in

774

775

</tr>

776

777

<td><code class="docutils literal">PY_MINOR_VERSION</code> (the <code class="docutils literal">1</code> in

778

779

</tr>

780

781

<td><code class="docutils literal">PY_MICRO_VERSION</code> (the <code class="docutils literal">0</code> in

782

783

</tr>

784

785

<td><code class="docutils literal">PY_RELEASE_LEVEL</code> (<code class="docutils literal">0xA</code> for alpha,

786

<code class="docutils literal">0xB</code> for beta, <code class="docutils literal">0xC</code> for release

787

candidate and <code class="docutils literal">0xF</code> for final)</td>

788

</tr>

789

790

<td><code class="docutils literal">PY_RELEASE_SERIAL</code> (the <code class="docutils literal">3</code> in

791

<code class="docutils literal">2.1.0a3</code>, zero for final releases)</td>

792

</tr>

793

</tbody>

794

</table>

795

Thus <code class="docutils literal">2.1.0a3</code> is hexversion <code class="docutils literal">0x020100a3</code>.

796

797

New in version 1.5.2.

798

</div>

799

</dd></dl>

800

801

802

803

804

<dd>A struct sequence that holds information about Python’s

805

internal representation of integers. The attributes are read only.

806

807

808

809

810

</colgroup>

811

812

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

813

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

814

</tr>

815

</thead>

816

817

<tr class="row-even"><td><code class="xref py py-const docutils literal">bits_per_digit</code></td>

818

<td>number of bits held in each digit. Python

819

integers are stored internally in base

820

<code class="docutils literal">2**long_info.bits_per_digit</code></td>

821

</tr>

822

<tr class="row-odd"><td><code class="xref py py-const docutils literal">sizeof_digit</code></td>

823

<td>size in bytes of the C type used to

824

represent a digit</td>

825

</tr>

826

</tbody>

827

</table>

828

829

New in version 2.7.

830

</div>

831

</dd></dl>

832

833

834

835

836

837

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

838

839

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

840

<dd>These three variables are not always defined; they are set when an exception is

841

not handled and the interpreter prints an error message and a stack traceback.

842

Their intended use is to allow an interactive user to import a debugger module

843

and engage in post-mortem debugging without having to re-execute the command

844

that caused the error. (Typical use is <code class="docutils literal">import pdb; pdb.pm()</code> to enter the

845

post-mortem debugger; see chapter <a class="reference internal" href="pdb.html#debugger">pdb — The Python Debugger</a> for

846

more information.)

847

The meaning of the variables is the same as that of the return values from

848

<a class="reference internal" href="#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal">exc_info()</code></a> above. (Since there is only one interactive thread,

849

thread-safety is not a concern for these variables, unlike for <code class="docutils literal">exc_type</code>

850

etc.)

851

</dd></dl>

852

853

854

855

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

856

<dd>The largest positive integer supported by Python’s regular integer type. This

857

is at least 2**31-1. The largest negative integer is <code class="docutils literal">-maxint-1</code> — the

858

asymmetry results from the use of 2’s complement binary arithmetic.

859

</dd></dl>

860

861

862

863

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

864

<dd>The largest positive integer supported by the platform’s Py_ssize_t type,

865

and thus the maximum size lists, strings, dicts, and many other containers

866

can have.

867

</dd></dl>

868

869

870

871

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

872

<dd>An integer giving the largest supported code point for a Unicode character. The

873

value of this depends on the configuration option that specifies whether Unicode

874

characters are stored as UCS-2 or UCS-4.

875

</dd></dl>

876

877

878

879

880

<dd>A list of <a class="reference internal" href="../glossary.html#term-finder">finder</a> objects that have their <code class="xref py py-meth docutils literal">find_module()</code>

881

methods called to see if one of the objects can find the module to be

882

imported. The <code class="xref py py-meth docutils literal">find_module()</code> method is called at least with the

883

absolute name of the module being imported. If the module to be imported is

884

contained in package then the parent package’s <code class="xref py py-attr docutils literal">__path__</code> attribute

885

is passed in as a second argument. The method returns <code class="docutils literal">None</code> if

886

the module cannot be found, else returns a <a class="reference internal" href="../glossary.html#term-loader">loader</a>.

887

<a class="reference internal" href="#sys.meta_path" title="sys.meta_path"><code class="xref py py-data docutils literal">sys.meta_path</code></a> is searched before any implicit default finders or

888

<a class="reference internal" href="#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a>.

889

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

890

</dd></dl>

891

892

893

894

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

895

<dd>This is a dictionary that maps module names to modules which have already been

896

loaded. This can be manipulated to force reloading of modules and other tricks.

897

Note that removing a module from this dictionary is not the same as calling

898

<a class="reference internal" href="functions.html#reload" title="reload"><code class="xref py py-func docutils literal">reload()</code></a> on the corresponding module object.

899

</dd></dl>

900

901

902

903

904

<dd>A list of strings that specifies the search path for modules. Initialized from

905

the environment variable <a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal">PYTHONPATH</code></a>, plus an installation-dependent

906

default.

907

As initialized upon program startup, the first item of this list, <code class="docutils literal">path[0]</code>,

908

is the directory containing the script that was used to invoke the Python

909

interpreter. If the script directory is not available (e.g. if the interpreter

910

is invoked interactively or if the script is read from standard input),

911

<code class="docutils literal">path[0]</code> is the empty string, which directs Python to search modules in the

912

current directory first. Notice that the script directory is inserted before

913

the entries inserted as a result of <a class="reference internal" href="../using/cmdline.html#envvar-PYTHONPATH"><code class="xref std std-envvar docutils literal">PYTHONPATH</code></a>.

914

A program is free to modify this list for its own purposes.

915

916

Changed in version 2.3: Unicode strings are no longer ignored.

917

</div>

918

919

See also

920

Module <a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal">site</code></a> This describes how to use .pth files to extend

921

<a class="reference internal" href="#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a>.

922

</div>

923

</dd></dl>

924

925

926

927

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

928

<dd>A list of callables that take a path argument to try to create a

929

<a class="reference internal" href="../glossary.html#term-finder">finder</a> for the path. If a finder can be created, it is to be

930

returned by the callable, else raise <a class="reference internal" href="exceptions.html#exceptions.ImportError" title="exceptions.ImportError"><code class="xref py py-exc docutils literal">ImportError</code></a>.

931

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

932

</dd></dl>

933

934

935

936

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

937

<dd>A dictionary acting as a cache for <a class="reference internal" href="../glossary.html#term-finder">finder</a> objects. The keys are

938

paths that have been passed to <a class="reference internal" href="#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal">sys.path_hooks</code></a> and the values are

939

the finders that are found. If a path is a valid file system path but no

940

explicit finder is found on <a class="reference internal" href="#sys.path_hooks" title="sys.path_hooks"><code class="xref py py-data docutils literal">sys.path_hooks</code></a> then <code class="docutils literal">None</code> is

941

stored to represent the implicit default finder should be used. If the path

942

is not an existing path then <a class="reference internal" href="imp.html#imp.NullImporter" title="imp.NullImporter"><code class="xref py py-class docutils literal">imp.NullImporter</code></a> is set.

943

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

944

</dd></dl>

945

946

947

948

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

949

<dd>This string contains a platform identifier that can be used to append

950

platform-specific components to <a class="reference internal" href="#sys.path" title="sys.path"><code class="xref py py-data docutils literal">sys.path</code></a>, for instance.

951

For most Unix systems, this is the lowercased OS name as returned by <code class="docutils literal">uname

952

-s</code> with the first part of the version as returned by <code class="docutils literal">uname -r</code> appended,

953

e.g. <code class="docutils literal">'sunos5'</code>, at the time when Python was built. Unless you want to

954

test for a specific system version, it is therefore recommended to use the

955

following idiom:

956

<div class="highlight-python"><div class="highlight"><pre>if sys.platform.startswith('freebsd'):

957

# FreeBSD-specific code here...

958

elif sys.platform.startswith('linux'):

959

# Linux-specific code here...

960

</pre></div>

961

</div>

962

963

Changed in version 2.7.3: Since lots of code check for <code class="docutils literal">sys.platform == 'linux2'</code>, and there is

964

no essential change between Linux 2.x and 3.x, <code class="docutils literal">sys.platform</code> is always

965

set to <code class="docutils literal">'linux2'</code>, even on Linux 3.x. In Python 3.3 and later, the

966

value will always be set to <code class="docutils literal">'linux'</code>, so it is recommended to always

967

use the <code class="docutils literal">startswith</code> idiom presented above.

968

</div>

969

For other systems, the values are:

970

971

972

973

974

</colgroup>

975

976

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

977

<th class="head"><a class="reference internal" href="platform.html#module-platform" title="platform: Retrieves as much platform identifying data as possible."><code class="xref py py-data docutils literal">platform</code></a> value</th>

978

</tr>

979

</thead>

980

981

<tr class="row-even"><td>Linux (2.x and 3.x)</td>

982

<td><code class="docutils literal">'linux2'</code></td>

983

</tr>

984

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

985

986

</tr>

987

<tr class="row-even"><td>Windows/Cygwin</td>

988

<td><code class="docutils literal">'cygwin'</code></td>

989

</tr>

990

991

<td><code class="docutils literal">'darwin'</code></td>

992

</tr>

993

994

995

</tr>

996

997

998

</tr>

999

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

1000

<td><code class="docutils literal">'riscos'</code></td>

1001

</tr>

1002

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

1003

<td><code class="docutils literal">'atheos'</code></td>

1004

</tr>

1005

</tbody>

1006

</table>

1007

1008

See also

1009

<a class="reference internal" href="os.html#os.name" title="os.name"><code class="xref py py-attr docutils literal">os.name</code></a> has a coarser granularity. <a class="reference internal" href="os.html#os.uname" title="os.uname"><code class="xref py py-func docutils literal">os.uname()</code></a> gives

1010

system-dependent version information.

1011

The <a class="reference internal" href="platform.html#module-platform" title="platform: Retrieves as much platform identifying data as possible."><code class="xref py py-mod docutils literal">platform</code></a> module provides detailed checks for the

1012

system’s identity.

1013

</div>

1014

</dd></dl>

1015

1016

1017

1018

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

1019

<dd>A string giving the site-specific directory prefix where the platform

1020

independent Python files are installed; by default, this is the string

1021

<code class="docutils literal">'/usr/local'</code>. This can be set at build time with the <code class="docutils literal">--prefix</code>

1022

argument to the configure script. The main collection of Python

1023

library modules is installed in the directory <code class="file docutils literal">prefix/lib/pythonX.Y</code>

1024

while the platform independent header files (all except <code class="file docutils literal">pyconfig.h</code>) are

1025

stored in <code class="file docutils literal">prefix/include/pythonX.Y</code>, where X.Y is the version

1026

number of Python, for example <code class="docutils literal">2.7</code>.

1027

</dd></dl>

1028

1029

1030

1031

1032

1033

1034

<dd>Strings specifying the primary and secondary prompt of the interpreter. These

1035

are only defined if the interpreter is in interactive mode. Their initial

1036

values in this case are <code class="docutils literal">'>>> '</code> and <code class="docutils literal">'... '</code>. If a non-string object is

1037

assigned to either variable, its <a class="reference internal" href="functions.html#str" title="str"><code class="xref py py-func docutils literal">str()</code></a> is re-evaluated each time the

1038

interpreter prepares to read a new interactive command; this can be used to

1039

implement a dynamic prompt.

1040

</dd></dl>

1041

1042

1043

1044

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

1045

<dd>Bool containing the status of the Python 3 warning flag. It’s <code class="docutils literal">True</code>

1046

when Python is started with the -3 option. (This should be considered

1047

read-only; setting it to a different value doesn’t have an effect on

1048

Python 3 warnings.)

1049

1050

New in version 2.6.

1051

</div>

1052

</dd></dl>

1053

1054

1055

1056

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

1057

<dd>Set the interpreter’s “check interval”. This integer value determines how often

1058

the interpreter checks for periodic things such as thread switches and signal

1059

handlers. The default is <code class="docutils literal">100</code>, meaning the check is performed every 100

1060

Python virtual instructions. Setting it to a larger value may increase

1061

performance for programs using threads. Setting it to a value <code class="docutils literal"><=</code> 0 checks

1062

every virtual instruction, maximizing responsiveness as well as overhead.

1063

</dd></dl>

1064

1065

1066

1067

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

1068

<dd>Set the current default string encoding used by the Unicode implementation. If

1069

name does not match any available encoding, <a class="reference internal" href="exceptions.html#exceptions.LookupError" title="exceptions.LookupError"><code class="xref py py-exc docutils literal">LookupError</code></a> is raised.

1070

This function is only intended to be used by the <a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal">site</code></a> module

1071

implementation and, where needed, by <code class="xref py py-mod docutils literal">sitecustomize</code>. Once used by the

1072

<a class="reference internal" href="site.html#module-site" title="site: Module responsible for site-specific configuration."><code class="xref py py-mod docutils literal">site</code></a> module, it is removed from the <a class="reference internal" href="#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal">sys</code></a> module’s namespace.

1073

1074

New in version 2.0.

1075

</div>

1076

</dd></dl>

1077

1078

1079

1080

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

1081

<dd>Set the flags used by the interpreter for <code class="xref c c-func docutils literal">dlopen()</code> calls, such as when

1082

the interpreter loads extension modules. Among other things, this will enable a

1083

lazy resolving of symbols when importing a module, if called as

1084

<code class="docutils literal">sys.setdlopenflags(0)</code>. To share symbols across extension modules, call as

1085

<code class="docutils literal">sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL)</code>. Symbolic names for the

1086

flag modules can be either found in the <a class="reference internal" href="dl.html#module-dl" title="dl: Call C functions in shared objects. (deprecated) (Unix)"><code class="xref py py-mod docutils literal">dl</code></a> module, or in the <code class="xref py py-mod docutils literal">DLFCN</code>

1087

module. If <code class="xref py py-mod docutils literal">DLFCN</code> is not available, it can be generated from

1088

<code class="file docutils literal">/usr/include/dlfcn.h</code> using the h2py script. Availability:

1089

Unix.

1090

1091

New in version 2.2.

1092

</div>

1093

</dd></dl>

1094

1095

1096

1097

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

1098

<dd>Set the system’s profile function, which allows you to implement a Python source

1099

code profiler in Python. See chapter <a class="reference internal" href="profile.html#profile">The Python Profilers</a> for more information on the

1100

Python profiler. The system’s profile function is called similarly to the

1101

system’s trace function (see <a class="reference internal" href="#sys.settrace" title="sys.settrace"><code class="xref py py-func docutils literal">settrace()</code></a>), but it isn’t called for each

1102

executed line of code (only on call and return, but the return event is reported

1103

even when an exception has been set). The function is thread-specific, but

1104

there is no way for the profiler to know about context switches between threads,

1105

so it does not make sense to use this in the presence of multiple threads. Also,

1106

its return value is not used, so it can simply return <code class="docutils literal">None</code>.

1107

</dd></dl>

1108

1109

1110

1111

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

1112

<dd>Set the maximum depth of the Python interpreter stack to limit. This limit

1113

prevents infinite recursion from causing an overflow of the C stack and crashing

1114

Python.

1115

The highest possible limit is platform-dependent. A user may need to set the

1116

limit higher when she has a program that requires deep recursion and a platform

1117

that supports a higher limit. This should be done with care, because a too-high

1118

limit can lead to a crash.

1119

</dd></dl>

1120

1121

1122

1123

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

1124

<dd>Set the system’s trace function, which allows you to implement a Python

1125

source code debugger in Python. The function is thread-specific; for a

1126

debugger to support multiple threads, it must be registered using

1127

<a class="reference internal" href="#sys.settrace" title="sys.settrace"><code class="xref py py-func docutils literal">settrace()</code></a> for each thread being debugged.

1128

Trace functions should have three arguments: frame, event, and

1129

arg. frame is the current stack frame. event is a string: <code class="docutils literal">'call'</code>,

1130

<code class="docutils literal">'line'</code>, <code class="docutils literal">'return'</code>, <code class="docutils literal">'exception'</code>, <code class="docutils literal">'c_call'</code>, <code class="docutils literal">'c_return'</code>, or

1131

<code class="docutils literal">'c_exception'</code>. arg depends on the event type.

1132

The trace function is invoked (with event set to <code class="docutils literal">'call'</code>) whenever a new

1133

local scope is entered; it should return a reference to a local trace

1134

function to be used that scope, or <code class="docutils literal">None</code> if the scope shouldn’t be traced.

1135

The local trace function should return a reference to itself (or to another

1136

function for further tracing in that scope), or <code class="docutils literal">None</code> to turn off tracing

1137

in that scope.

1138

The events have the following meaning:

1139

1140

1141

<dd>A function is called (or some other code block entered). The

1142

global trace function is called; arg is <code class="docutils literal">None</code>; the return value

1143

specifies the local trace function.</dd>

1144

1145

<dd>The interpreter is about to execute a new line of code or re-execute the

1146

condition of a loop. The local trace function is called; arg is

1147

<code class="docutils literal">None</code>; the return value specifies the new local trace function. See

1148

<code class="file docutils literal">Objects/lnotab_notes.txt</code> for a detailed explanation of how this

1149

works.</dd>

1150

<dt><code class="docutils literal">'return'</code></dt>

1151

<dd>A function (or other code block) is about to return. The local trace

1152

function is called; arg is the value that will be returned, or <code class="docutils literal">None</code>

1153

if the event is caused by an exception being raised. The trace function’s

1154

return value is ignored.</dd>

1155

<dt><code class="docutils literal">'exception'</code></dt>

1156

<dd>An exception has occurred. The local trace function is called; arg is a

1157

tuple <code class="docutils literal">(exception, value, traceback)</code>; the return value specifies the

1158

new local trace function.</dd>

1159

1160

<dd>A C function is about to be called. This may be an extension function or

1161

a built-in. arg is the C function object.</dd>

1162

<dt><code class="docutils literal">'c_return'</code></dt>

1163

<dd>A C function has returned. arg is the C function object.</dd>

1164

<dt><code class="docutils literal">'c_exception'</code></dt>

1165

<dd>A C function has raised an exception. arg is the C function object.</dd>

1166

</dl>

1167

Note that as an exception is propagated down the chain of callers, an

1168

<code class="docutils literal">'exception'</code> event is generated at each level.

1169

For more information on code and frame objects, refer to <a class="reference internal" href="../reference/datamodel.html#types">The standard type hierarchy</a>.

1170

1171

CPython implementation detail: The <a class="reference internal" href="#sys.settrace" title="sys.settrace"><code class="xref py py-func docutils literal">settrace()</code></a> function is intended only for implementing debuggers,

1172

profilers, coverage tools and the like. Its behavior is part of the

1173

implementation platform, rather than part of the language definition, and

1174

thus may not be available in all Python implementations.

1175

</div>

1176

</dd></dl>

1177

1178

1179

1180

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

1181

<dd>Activate dumping of VM measurements using the Pentium timestamp counter, if

1182

on_flag is true. Deactivate these dumps if on_flag is off. The function is

1183

available only if Python was compiled with <code class="docutils literal">--with-tsc</code>. To understand

1184

the output of this dump, read <code class="file docutils literal">Python/ceval.c</code> in the Python sources.

1185

1186

New in version 2.4.

1187

</div>

1188

1189

CPython implementation detail: This function is intimately bound to CPython implementation details and

1190

thus not likely to be implemented elsewhere.

1191

</div>

1192

</dd></dl>

1193

1194

1195

1196

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

1197

1198

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

1199

1200

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

1201

<dd>File objects corresponding to the interpreter’s standard input, output and error

1202

streams. <code class="docutils literal">stdin</code> is used for all interpreter input except for scripts but

1203

including calls to <a class="reference internal" href="functions.html#input" title="input"><code class="xref py py-func docutils literal">input()</code></a> and <a class="reference internal" href="functions.html#raw_input" title="raw_input"><code class="xref py py-func docutils literal">raw_input()</code></a>. <code class="docutils literal">stdout</code> is used for

1204

the output of <a class="reference internal" href="../reference/simple_stmts.html#print"><code class="xref std std-keyword docutils literal">print</code></a> and <a class="reference internal" href="../glossary.html#term-expression">expression</a> statements and for the

1205

prompts of <a class="reference internal" href="functions.html#input" title="input"><code class="xref py py-func docutils literal">input()</code></a> and <a class="reference internal" href="functions.html#raw_input" title="raw_input"><code class="xref py py-func docutils literal">raw_input()</code></a>. The interpreter’s own prompts

1206

and (almost all of) its error messages go to <code class="docutils literal">stderr</code>. <code class="docutils literal">stdout</code> and

1207

<code class="docutils literal">stderr</code> needn’t be built-in file objects: any object is acceptable as long

1208

as it has a <code class="xref py py-meth docutils literal">write()</code> method that takes a string argument. (Changing these

1209

objects doesn’t affect the standard I/O streams of processes executed by

1210

<a class="reference internal" href="os.html#os.popen" title="os.popen"><code class="xref py py-func docutils literal">os.popen()</code></a>, <a class="reference internal" href="os.html#os.system" title="os.system"><code class="xref py py-func docutils literal">os.system()</code></a> or the <code class="xref py py-func docutils literal">exec*()</code> family of functions in

1211

the <a class="reference internal" href="os.html#module-os" title="os: Miscellaneous operating system interfaces."><code class="xref py py-mod docutils literal">os</code></a> module.)

1212

</dd></dl>

1213

1214

1215

1216

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

1217

1218

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

1219

1220

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

1221

<dd>These objects contain the original values of <code class="docutils literal">stdin</code>, <code class="docutils literal">stderr</code> and

1222

<code class="docutils literal">stdout</code> at the start of the program. They are used during finalization,

1223

and could be useful to print to the actual standard stream no matter if the

1224

<code class="docutils literal">sys.std*</code> object has been redirected.

1225

It can also be used to restore the actual files to known working file objects

1226

in case they have been overwritten with a broken object. However, the

1227

preferred way to do this is to explicitly save the previous stream before

1228

replacing it, and restore the saved object.

1229

</dd></dl>

1230

1231

1232

1233

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

1234

<dd>A triple (repo, branch, version) representing the Subversion information of the

1235

Python interpreter. repo is the name of the repository, <code class="docutils literal">'CPython'</code>.

1236

branch is a string of one of the forms <code class="docutils literal">'trunk'</code>, <code class="docutils literal">'branches/name'</code> or

1237

<code class="docutils literal">'tags/name'</code>. version is the output of <code class="docutils literal">svnversion</code>, if the interpreter

1238

was built from a Subversion checkout; it contains the revision number (range)

1239

and possibly a trailing ‘M’ if there were local modifications. If the tree was

1240

exported (or svnversion was not available), it is the revision of

1241

<code class="docutils literal">Include/patchlevel.h</code> if the branch is a tag. Otherwise, it is <code class="docutils literal">None</code>.

1242

1243

New in version 2.5.

1244

</div>

1245

1246

Note

1247

Python is now <a class="reference external" href="https://docs.python.org/devguide/">developed</a> using

1248

Mercurial. In recent Python 2.7 bugfix releases, <a class="reference internal" href="#sys.subversion" title="sys.subversion"><code class="xref py py-data docutils literal">subversion</code></a>

1249

therefore contains placeholder information. It is removed in Python

1250

3.3.

1251

</div>

1252

</dd></dl>

1253

1254

1255

1256

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

1257

<dd>When this variable is set to an integer value, it determines the maximum number

1258

of levels of traceback information printed when an unhandled exception occurs.

1259

The default is <code class="docutils literal">1000</code>. When set to <code class="docutils literal">0</code> or less, all traceback information

1260

is suppressed and only the exception type and value are printed.

1261

</dd></dl>

1262

1263

1264

1265

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

1266

<dd>A string containing the version number of the Python interpreter plus additional

1267

information on the build number and compiler used. This string is displayed

1268

when the interactive interpreter is started. Do not extract version information

1269

out of it, rather, use <a class="reference internal" href="#sys.version_info" title="sys.version_info"><code class="xref py py-data docutils literal">version_info</code></a> and the functions provided by the

1270

<a class="reference internal" href="platform.html#module-platform" title="platform: Retrieves as much platform identifying data as possible."><code class="xref py py-mod docutils literal">platform</code></a> module.

1271

</dd></dl>

1272

1273

1274

1275

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

1276

<dd>The C API version for this interpreter. Programmers may find this useful when

1277

debugging version conflicts between Python and extension modules.

1278

1279

New in version 2.3.

1280

</div>

1281

</dd></dl>

1282

1283

1284

1285

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

1286

<dd>A tuple containing the five components of the version number: major, minor,

1287

micro, releaselevel, and serial. All values except releaselevel are

1288

integers; the release level is <code class="docutils literal">'alpha'</code>, <code class="docutils literal">'beta'</code>, <code class="docutils literal">'candidate'</code>, or

1289

<code class="docutils literal">'final'</code>. The <code class="docutils literal">version_info</code> value corresponding to the Python version 2.0

1290

is <code class="docutils literal">(2, 0, 0, 'final', 0)</code>. The components can also be accessed by name,

1291

so <code class="docutils literal">sys.version_info[0]</code> is equivalent to <code class="docutils literal">sys.version_info.major</code>

1292

and so on.

1293

1294

New in version 2.0.

1295

</div>

1296

1297

Changed in version 2.7: Added named component attributes

1298

</div>

1299

</dd></dl>

1300

1301

1302

1303

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

1304

<dd>This is an implementation detail of the warnings framework; do not modify this

1305

value. Refer to the <a class="reference internal" href="warnings.html#module-warnings" title="warnings: Issue warning messages and control their disposition."><code class="xref py py-mod docutils literal">warnings</code></a> module for more information on the warnings

1306

framework.

1307

</dd></dl>

1308

1309

1310

1311

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

1312

<dd>The version number used to form registry keys on Windows platforms. This is

1313

stored as string resource 1000 in the Python DLL. The value is normally the

1314

first three characters of <a class="reference internal" href="#sys.version" title="sys.version"><code class="xref py py-const docutils literal">version</code></a>. It is provided in the <a class="reference internal" href="#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal">sys</code></a>

1315

module for informational purposes; modifying this value has no effect on the

1316

registry keys used by Python. Availability: Windows.

1317

</dd></dl>

1318

1319

Citations

1320

1321

1322

1323

<tr><td class="label"><a class="fn-backref" href="#id1">[C99]</a></td><td>ISO/IEC 9899:1999. “Programming languages – C.” A public draft of this standard is available at <a class="reference external" href="http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf">http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1256.pdf</a>.</td></tr>

1324

</tbody>

1325

</table>

1326

</div>

1327

1328

1329

</div>

1330

</div>

1331

</div>

1332

1333

1334

<h4>Previous topic</h4>

1335

<a href="python.html"

1336

title="previous chapter">28. Python Runtime Services</a>

1337

<h4>Next topic</h4>

1338

<a href="sysconfig.html"

1339

title="next chapter">28.2. <code class="docutils literal">sysconfig</code> — Provide access to Python’s configuration information</a>

1340

1341

1342

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

1343

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

1344

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

1345

</ul>

1346

1347

1348

<h3>Quick search</h3>

1349

1350

1351

1352

1353

1354

</form>

1355

1356

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

1357

1358

</div>

1359

1360

</div>

1361

</div>

1362

1363

</div>

1364

1365

<h3>Navigation</h3>

1366

<ul>

1367

1368

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

1369

>index</a></li>

1370

1371

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

1372

>modules</a> |</li>

1373

1374

<a href="sysconfig.html" title="28.2. sysconfig — Provide access to Python’s configuration information"

1375

>next</a> |</li>

1376

1377

<a href="python.html" title="28. Python Runtime Services"

1378

>previous</a> |</li>

1379

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

1380

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

1381

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

1382

<li>

1383

2.7.12

1384

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

1385

</li>

1386

1387

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

1388

<li class="nav-item nav-item-2"><a href="python.html" >28. Python Runtime Services</a> »</li>

1389

</ul>

1390

</div>

1391

1392

1393

1394

The Python Software Foundation is a non-profit corporation.

1395

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

1396

1397

Last updated on Nov 26, 2016.

1398

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

1399

1400

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

1401

</div>

1402

1403

</body>

1404

</html>

b'\\ No newline at end of file'

Older »