~ubuntu-branches/ubuntu/natty/bluefish/natty-proposed : revision 8

1

<?xml version="1.0" ?>

2

3

4

5

<description>The Python interpreter has a number of functions built into it that

6

are always available. They are listed here in alphabetical order.

7

</description>

8

9

<description>This function is invoked by the importimport

10

statement. It mainly exists so that you can replace it with another

11

function that has a compatible interface, in order to change the

12

semantics of the import statement. For examples of why

13

and how you would do this, see the standard library modules

14

ihooksihooks and

15

rexecrexec. See also the built-in

16

module impimp, which defines some useful

17

operations out of which you can build your own

18

__import__() function.

19

For example, the statement import spam results in the

20

following call: __import__('spam', globals(),

21

locals(), []); the statement from spam.ham import eggs

22

results in __import__('spam.ham', globals(), locals(),

23

['eggs']). Note that even though locals() and

24

['eggs'] are passed in as arguments, the

25

__import__() function does not set the local variable

26

named eggs; this is done by subsequent code that is generated

27

for the import statement. (In fact, the standard implementation

28

does not use its locals argument at all, and uses its

29

globals only to determine the package context of the

30

import statement.)

31

When the name variable is of the form package.module,

32

normally, the top-level package (the name up till the first dot) is

33

returned, not the module named by name. However, when

34

a non-empty fromlist argument is given, the module named by

35

name is returned. This is done for compatibility with the

36

bytecode generated for the different kinds of import statement; when

37

using import spam.ham.eggs, the top-level package spam

38

must be placed in the importing namespace, but when using from

39

spam.ham import eggs, the spam.ham subpackage must be used

40

to find the eggs variable. As a workaround for this

41

behavior, use getattr() to extract the desired

42

components. For example, you could define the following helper:

43

def my_import(name):

44

mod = __import__(name)

45

components = name.split('.')

46

for comp in components[1:]:

47

mod = getattr(mod, comp)

48

return mod

49

</description>

50

51

52

53

54

<description>Return the absolute value of a number. The argument may be a plain

55

or long integer or a floating point number. If the argument is a

56

complex number, its magnitude is returned.</description>

57

58

59

60

61

<description>This abstract type is the superclass for str and unicode.

62

It cannot be called or instantiated, but it can be used to test whether

63

an object is an instance of str or unicode.

64

isinstance(obj, basestring) is equivalent to

65

isinstance(obj, (str, unicode)).

66

New in version 2.3</description>

67

68

</element>

69

70

71

<description>Convert a value to a Boolean, using the standard truth testing

72

procedure. If x is false or omitted, this returns

73

False; otherwise it returns True.

74

bool is also a class, which is a subclass of int.

75

Class bool cannot be subclassed further. Its only instances

76

are False and True.

77

New in version 2.2.1

78

Changed in version 2.3: If no argument is given, this function returns False</description>

79

80

81

82

83

<description>Return true if the object argument appears callable, false if

84

not. If this returns true, it is still possible that a call fails,

85

but if it is false, calling object will never succeed. Note

86

that classes are callable (calling a class returns a new instance);

87

class instances are callable if they have a __call__()

88

method.</description>

89

90

91

92

93

<description>Return a string of one character whose ASCII code is the integer

94

i. For example, chr(97) returns the string 'a'.

95

This is the inverse of ord(). The argument must be in

96

the range [0..255], inclusive; ValueError will be raised

97

if i is outside that range.</description>

98

99

100

101

102

<description>Return a class method for function.

103

A class method receives the class as implicit first argument,

104

just like an instance method receives the instance.

105

To declare a class method, use this idiom:

106

class C:

107

def f(cls, arg1, arg2, ...): ...

108

f = classmethod(f)

109

It can be called either on the class (such as C.f()) or on an

110

instance (such as C().f()). The instance is ignored except for

111

its class.

112

If a class method is called for a derived class, the derived class

113

object is passed as the implied first argument.

114

Class methods are different than or Java static methods.

115

If you want those, see staticmethod() in this section.

116

New in version 2.2</description>

117

118

119

120

121

<description>Compare the two objects x and y and return an integer

122

according to the outcome. The return value is negative if x

123

< y, zero if x == y and strictly positive if

124

x > y.</description>

125

126

127

128

129

<description>Compile the string into a code object. Code objects can be

130

executed by an exec statement or evaluated by a call to

131

eval(). The filename argument should

132

give the file from which the code was read; pass some recognizable value

133

if it wasn't read from a file ('<string>' is commonly used).

134

The kind argument specifies what kind of code must be

135

compiled; it can be 'exec' if string consists of a

136

sequence of statements, 'eval' if it consists of a single

137

expression, or 'single' if it consists of a single

138

interactive statement (in the latter case, expression statements

139

that evaluate to something else than None will printed).

140

When compiling multi-line statements, two caveats apply: line

141

endings must be represented by a single newline character

142

('\n'), and the input must be terminated by at least one

143

newline character. If line endings are represented by

144

'\r\n', use the string replace() method to

145

change them into '\n'.

146

The optional arguments flags and dont_inherit

147

(which are new in Python 2.2) control which future statements (see

148

236) affect the compilation of string. If neither is

149

present (or both are zero) the code is compiled with those future

150

statements that are in effect in the code that is calling compile.

151

If the flags argument is given and dont_inherit is not

152

(or is zero) then the future statements specified by the flags

153

argument are used in addition to those that would be used anyway.

154

If dont_inherit is a non-zero integer then the flags

155

argument is it -- the future statements in effect around the call to

156

compile are ignored.

157

Future statemants are specified by bits which can be bitwise or-ed

158

together to specify multiple statements. The bitfield required to

159

specify a given feature can be found as the compiler_flag

160

attribute on the _Feature instance in the

161

__future__ module.</description>

162

163

164

165

166

<description>Create a complex number with the value real + imag*j or

167

convert a string or number to a complex number. If the first

168

parameter is a string, it will be interpreted as a complex number

169

and the function must be called without a second parameter. The

170

second parameter can never be a string.

171

Each argument may be any numeric type (including complex).

172

If imag is omitted, it defaults to zero and the function

173

serves as a numeric conversion function like int(),

174

long() and float(). If both arguments

175

are omitted, returns 0j.</description>

176

177

178

179

180

<description>This is a relative of setattr(). The arguments are an

181

object and a string. The string must be the name

182

of one of the object's attributes. The function deletes

183

the named attribute, provided the object allows it. For example,

184

delattr(x, 'foobar') is equivalent to

185

del x.foobar.</description>

186

187

188

189

190

<description>Return a new dictionary initialized from an optional positional

191

argument or from a set of keyword arguments.

192

If no arguments are given, return a new empty dictionary.

193

If the positional argument is a mapping object, return a dictionary

194

mapping the same keys to the same values as does the mapping object.

195

Otherwise the positional argument must be a sequence, a container that

196

supports iteration, or an iterator object. The elements of the argument

197

must each also be of one of those kinds, and each must in turn contain

198

exactly two objects. The first is used as a key in the new dictionary,

199

and the second as the key's value. If a given key is seen more than

200

once, the last value associated with it is retained in the new

201

dictionary.

202

If keyword arguments are given, the keywords themselves with their

203

associated values are added as items to the dictionary. If a key

204

is specified both in the positional argument and as a keyword argument,

205

the value associated with the keyword is retained in the dictionary.

206

For example, these all return a dictionary equal to

207

{"one": 2, "two": 3}:

208

dict({'one': 2, 'two': 3})

209

dict({'one': 2, 'two': 3}.items())

210

dict({'one': 2, 'two': 3}.iteritems())

211

dict(zip(('one', 'two'), (2, 3)))

212

dict([['two', 3], ['one', 2]])

213

dict(one=2, two=3)

214

dict([(['one', 'two'][i-2], i) for i in (2, 3)])

215

New in version 2.2

216

Changed in version 2.3: Support for building a dictionary from keyword

217

arguments added</description>

218

219

220

221

222

<description>Without arguments, return the list of names in the current local

223

symbol table. With an argument, attempts to return a list of valid

224

attributes for that object. This information is gleaned from the

225

object's __dict__ attribute, if defined, and from the class

226

or type object. The list is not necessarily complete.

227

If the object is a module object, the list contains the names of the

228

module's attributes.

229

If the object is a type or class object,

230

the list contains the names of its attributes,

231

and recursively of the attributes of its bases.

232

Otherwise, the list contains the object's attributes' names,

233

the names of its class's attributes,

234

and recursively of the attributes of its class's base classes.

235

The resulting list is sorted alphabetically.

236

For example:

237

>>> import struct

238

>>> dir()

239

['__builtins__', '__doc__', '__name__', 'struct']

240

>>> dir(struct)

241

['__doc__', '__name__', 'calcsize', 'error', 'pack', 'unpack']

242

Because dir() is supplied primarily as a convenience

243

for use at an interactive prompt,

244

it tries to supply an interesting set of names more than it tries to

245

supply a rigorously or consistently defined set of names,

246

and its detailed behavior may change across releases.</description>

247

248

249

250

251

<description>Take two (non complex) numbers as arguments and return a pair of numbers

252

consisting of their quotient and remainder when using long division. With

253

mixed operand types, the rules for binary arithmetic operators apply. For

254

plain and long integers, the result is the same as

255

(a / b, a % b).

256

For floating point numbers the result is (q, a %

257

b), where q is usually math.floor(a /

258

b) but may be 1 less than that. In any case q *

259

b + a % b is very close to a, if

260

a % b is non-zero it has the same sign as

261

b, and 0 <= abs(a % b) < abs(b).

262

Changed in version 2.3: Using divmod() with complex numbers is

263

deprecated</description>

264

265

266

267

268

<description>Return an enumerate object. iterable must be a sequence, an

269

iterator, or some other object which supports iteration. The

270

next() method of the iterator returned by

271

enumerate() returns a tuple containing a count (from

272

zero) and the corresponding value obtained from iterating over

273

iterable. enumerate() is useful for obtaining an

274

indexed series: (0, seq[0]), (1, seq[1]), (2,

275

seq[2]), ....

276

New in version 2.3</description>

277

278

279

280

281

<description>The arguments are a string and two optional dictionaries. The

282

expression argument is parsed and evaluated as a Python

283

expression (technically speaking, a condition list) using the

284

globals and locals dictionaries as global and local name

285

space. If the globals dictionary is present and lacks

286

'__builtins__', the current globals are copied into globals before

287

expression is parsed. This means that expression

288

normally has full access to the standard

289

__builtin__ module and restricted environments

290

are propagated. If the locals dictionary is omitted it defaults to

291

the globals dictionary. If both dictionaries are omitted, the

292

expression is executed in the environment where eval is

293

called. The return value is the result of the evaluated expression.

294

Syntax errors are reported as exceptions. Example:

295

>>> x = 1

296

>>> print eval('x+1')

297

2

298

This function can also be used to execute arbitrary code objects

299

(such as those created by compile()). In this case pass

300

a code object instead of a string. The code object must have been

301

compiled passing 'eval' as the kind argument.

302

Hints: dynamic execution of statements is supported by the

303

exec statement. Execution of statements from a file is

304

supported by the execfile() function. The

305

globals() and locals() functions returns the

306

current global and local dictionary, respectively, which may be

307

useful to pass around for use by eval() or

308

execfile().</description>

309

310

311

312

313

<description>This function is similar to the

314

exec statement, but parses a file instead of a string. It

315

is different from the import statement in that it does not

316

use the module administration --- it reads the file unconditionally

317

and does not create a new module.It is used relatively

318

rarely so does not warrant being made into a statement.

319

The arguments are a file name and two optional dictionaries. The

320

file is parsed and evaluated as a sequence of Python statements

321

(similarly to a module) using the globals and locals

322

dictionaries as global and local namespace. If the locals

323

dictionary is omitted it defaults to the globals dictionary.

324

If both dictionaries are omitted, the expression is executed in the

325

environment where execfile() is called. The return value is

326

None.

327

The default locals act as described for function

328

locals() below: modifications to the default locals

329

dictionary should not be attempted. Pass an explicit locals

330

dictionary if you need to see effects of the code on locals after

331

function execfile() returns. execfile() cannot

332

be used reliably to modify a function's locals.</description>

333

334

335

336

337

<description>Return a new file object (described earlier under Built-in Types).

338

The first two arguments are the same as for stdio's

339

fopen(): filename is the file name to be opened,

340

mode indicates how the file is to be opened: 'r' for

341

reading, 'w' for writing (truncating an existing file), and

342

'a' opens it for appending (which on some systems means that all writes append to the end of the file,

343

regardless of the current seek position).

344

Modes 'r+', 'w+' and 'a+' open the file for

345

updating (note that 'w+' truncates the file). Append

346

'b' to the mode to open the file in binary mode, on systems

347

that differentiate between binary and text files (else it is

348

ignored). If the file cannot be opened, IOError is

349

raised.

350

In addition to the standard fopen() values mode

351

may be 'U' or 'rU'. If Python is built with universal

352

newline support (the default) the file is opened as a text file, but

353

lines may be terminated by any of '\n', the Unix end-of-line

354

convention,

355

'\r', the Macintosh convention or '\r\n', the Windows

356

convention. All of these external representations are seen as

357

'\n'

358

by the Python program. If Python is built without universal newline support

359

mode 'U' is the same as normal text mode. Note that

360

file objects so opened also have an attribute called

361

newlines which has a value of None (if no newlines

362

have yet been seen), '\n', '\r', '\r\n', or a tuple containing all the newline types seen.

363

If mode is omitted, it defaults to 'r'. When opening a

364

binary file, you should append 'b' to the mode value

365

for improved portability. (It's useful even on systems which don't

366

treat binary and text files differently, where it serves as

367

documentation.)

368

</description>

369

370

371

372

373

<description>Construct a list from those elements of list for which

374

function returns true. list may be either a sequence, a

375

container which supports iteration, or an iterator, If list

376

is a string or a tuple, the result also has that type; otherwise it

377

is always a list. If function is None, the identity

378

function is assumed, that is, all elements of list that are false

379

(zero or empty) are removed.

380

Note that filter(function, list) is equivalent to

381

[item for item in list if function(item)] if function is

382

not None and [item for item in list if item] if

383

function is None.</description>

384

385

386

387

388

<description>Convert a string or a number to floating point. If the argument is a

389

string, it must contain a possibly signed decimal or floating point

390

number, possibly embedded in whitespace; this behaves identical to

391

string.atof(x). Otherwise, the argument may be a plain

392

or long integer or a floating point number, and a floating point

393

number with the same value (within Python's floating point

394

precision) is returned. If no argument is given, returns 0.0.

395

When passing in a string, values for NaN</description>

396

397

398

399

400

<description>Return a frozenset object whose elements are taken from iterable.

401

Frozensets are sets that have no update methods but can be hashed and

402

used as members of other sets or as dictionary keys. The elements of

403

a frozenset must be immutable themselves. To represent sets of sets,

404

the inner sets should also be frozenset objects. If

405

iterable is not specified, returns a new empty set,

406

frozenset([]).

407

New in version 2.4</description>

408

409

410

411

412

<description>Return the value of the named attributed of object. name

413

must be a string. If the string is the name of one of the object's

414

attributes, the result is the value of that attribute. For example,

415

getattr(x, 'foobar') is equivalent to x.foobar. If the

416

named attribute does not exist, default is returned if provided,

417

otherwise AttributeError is raised.</description>

418

419

420

421

422

<description>Return a dictionary representing the current global symbol table.

423

This is always the dictionary of the current module (inside a

424

function or method, this is the module where it is defined, not the

425

module from which it is called).</description>

426

427

</element>

428

429

430

<description>The arguments are an object and a string. The result is 1 if the

431

string is the name of one of the object's attributes, 0 if not.

432

(This is implemented by calling getattr(object,

433

name) and seeing whether it raises an exception or not.)</description>

434

435

436

437

438

<description>Return the hash value of the object (if it has one). Hash values

439

are integers. They are used to quickly compare dictionary

440

keys during a dictionary lookup. Numeric values that compare equal

441

have the same hash value (even if they are of different types, as is

442

the case for 1 and 1.0).</description>

443

444

445

446

447

<description>Invoke the built-in help system. (This function is intended for

448

interactive use.) If no argument is given, the interactive help

449

system starts on the interpreter console. If the argument is a

450

string, then the string is looked up as the name of a module,

451

function, class, method, keyword, or documentation topic, and a

452

help page is printed on the console. If the argument is any other

453

kind of object, a help page on the object is generated.

454

New in version 2.2</description>

455

456

457

458

459

<description>Convert an integer number (of any size) to a hexadecimal string.

460

The result is a valid Python expression. Note: this always yields

461

an unsigned literal. For example, on a 32-bit machine,

462

hex(-1) yields '0xffffffff'. When evaluated on a

463

machine with the same word size, this literal is evaluated as -1; at

464

a different word size, it may turn up as a large positive number or

465

raise an OverflowError exception.</description>

466

467

468

469

470

<description>Return the `identity' of an object. This is an integer (or long

471

integer) which is guaranteed to be unique and constant for this

472

object during its lifetime. Two objects whose lifetimes are

473

disjunct may have the same id() value. (Implementation

474

note: this is the address of the object.)</description>

475

476

477

478

479

<description>Equivalent to eval(raw_input(prompt)).

480

This function is not safe from user errors! It

481

expects a valid Python expression as input; if the input is not

482

syntactically valid, a SyntaxError will be raised.

483

Other exceptions may be raised if there is an error during

484

evaluation. (On the other hand, sometimes this is exactly what you

485

need when writing a quick script for expert use.)

486

If the readline module was loaded, then

487

input() will use it to provide elaborate line editing and

488

history features.

489

Consider using the raw_input() function for general input

490

from users.</description>

491

492

493

494

495

<description>Convert a string or number to a plain integer. If the argument is a

496

string, it must contain a possibly signed decimal number

497

representable as a Python integer, possibly embedded in whitespace.

498

The radix parameter gives the base for the

499

conversion and may be any integer in the range [2, 36], or zero. If

500

radix is zero, the proper radix is guessed based on the

501

contents of string; the interpretation is the same as for integer

502

literals. If radix is specified and x is not a string,

503

TypeError is raised.

504

Otherwise, the argument may be a plain or

505

long integer or a floating point number. Conversion of floating

506

point numbers to integers truncates (towards zero).

507

If the argument is outside the integer range a long object will

508

be returned instead. If no arguments are given, returns 0.</description>

509

510

511

512

513

<description>Return true if the object argument is an instance of the

514

classinfo argument, or of a (direct or indirect) subclass

515

thereof. Also return true if classinfo is a type object and

516

object is an object of that type. If object is not a

517

class instance or an object of the given type, the function always

518

returns false. If classinfo is neither a class object nor a

519

type object, it may be a tuple of class or type objects, or may

520

recursively contain other such tuples (other sequence types are not

521

accepted). If classinfo is not a class, type, or tuple of

522

classes, types, and such tuples, a TypeError exception

523

is raised.

524

Changed in version 2.2: Support for a tuple of type information was added</description>

525

526

527

528

529

<description>Return true if class is a subclass (direct or indirect) of

530

classinfo. A class is considered a subclass of itself.

531

classinfo may be a tuple of class objects, in which case every

532

entry in classinfo will be checked. In any other case, a

533

TypeError exception is raised.

534

Changed in version 2.3: Support for a tuple of type information was added</description>

535

536

537

538

539

<description>Return an iterator object. The first argument is interpreted very

540

differently depending on the presence of the second argument.

541

Without a second argument, o must be a collection object which

542

supports the iteration protocol (the __iter__() method), or

543

it must support the sequence protocol (the __getitem__()

544

method with integer arguments starting at 0). If it does not

545

support either of those protocols, TypeError is raised.

546

If the second argument, sentinel, is given, then o must

547

be a callable object. The iterator created in this case will call

548

o with no arguments for each call to its next()

549

method; if the value returned is equal to sentinel,

550

StopIteration will be raised, otherwise the value will

551

be returned.

552

New in version 2.2</description>

553

554

555

556

557

<description>Return the length (the number of items) of an object. The argument

558

may be a sequence (string, tuple or list) or a mapping (dictionary).</description>

559

560

561

562

563

<description>Return a list whose items are the same and in the same order as

564

sequence's items. sequence may be either a sequence, a

565

container that supports iteration, or an iterator object. If

566

sequence is already a list, a copy is made and returned,

567

similar to sequence[:]. For instance,

568

list('abc') returns ['a', 'b', 'c'] and list(

569

(1, 2, 3) ) returns [1, 2, 3]. If no argument is given,

570

returns a new empty list, [].</description>

571

572

573

574

575

<description>Update and return a dictionary representing the current local symbol table.

576

The contents of this dictionary should not be modified;

577

changes may not affect the values of local variables used by the

578

interpreter.</description>

579

580

</element>

581

582

583

<description>Convert a string or number to a long integer. If the argument is a

584

string, it must contain a possibly signed number of

585

arbitrary size, possibly embedded in whitespace;

586

this behaves identical to string.atol(x). The

587

radix argument is interpreted in the same way as for

588

int(), and may only be given when x is a string.

589

Otherwise, the argument may be a plain or

590

long integer or a floating point number, and a long integer with

591

the same value is returned. Conversion of floating

592

point numbers to integers truncates (towards zero). If no arguments

593

are given, returns 0L.</description>

594

595

596

597

598

<description>Apply function to every item of list and return a list

599

of the results. If additional list arguments are passed,

600

function must take that many arguments and is applied to the

601

items of all lists in parallel; if a list is shorter than another it

602

is assumed to be extended with None items. If function

603

is None, the identity function is assumed; if there are

604

multiple list arguments, map() returns a list consisting

605

of tuples containing the corresponding items from all lists (a kind

606

of transpose operation). The list arguments may be any kind

607

of sequence; the result is always a list.</description>

608

609

610

611

612

<description>With a single argument s, return the largest item of a

613

non-empty sequence (such as a string, tuple or list). With more

614

than one argument, return the largest of the arguments.</description>

615

616

617

618

619

<description>With a single argument s, return the smallest item of a

620

non-empty sequence (such as a string, tuple or list). With more

621

than one argument, return the smallest of the arguments.</description>

622

623

624

625

626

<description>Return a new featureless object. object() is a base for all new style classes. It has the methods that are common

627

to all instances of new style classes.

628

New in version 2.2

629

Changed in version 2.3: This function does not accept any arguments.

630

Formerly, it accepted arguments but ignored them</description>

631

632

</element>

633

634

635

<description>Convert an integer number (of any size) to an octal string. The

636

result is a valid Python expression. Note: this always yields an

637

unsigned literal. For example, on a 32-bit machine, oct(-1)

638

yields '037777777777'. When evaluated on a machine with the

639

same word size, this literal is evaluated as -1; at a different word

640

size, it may turn up as a large positive number or raise an

641

OverflowError exception.</description>

642

643

644

645

646

<description>An alias for the file() function above.</description>

647

648

649

650

651

<description>Return the ASCII value of a string of one character or a Unicode

652

character. E.g., ord('a') returns the integer 97,

653

ord(u'\u2020') returns 8224. This is the inverse of

654

chr() for strings and of unichr() for Unicode

655

characters.</description>

656

657

658

659

660

<description>Return x to the power y; if z is present, return

661

x to the power y, modulo z (computed more

662

efficiently than pow(x, y) % z). The

663

arguments must have numeric types. With mixed operand types, the

664

coercion rules for binary arithmetic operators apply. For int and

665

long int operands, the result has the same type as the operands

666

(after coercion) unless the second argument is negative; in that

667

case, all arguments are converted to float and a float result is

668

delivered. For example, 10**2 returns 100, but

669

10**-2 returns 0.01. (This last feature was added in

670

Python 2.2. In Python 2.1 and before, if both arguments were of integer

671

types and the second argument was negative, an exception was raised.)

672

If the second argument is negative, the third argument must be omitted.

673

If z is present, x and y must be of integer types,

674

and y must be non-negative. (This restriction was added in

675

Python 2.2. In Python 2.1 and before, floating 3-argument pow()

676

returned platform-dependent results depending on floating-point

677

rounding accidents.)</description>

678

679

680

681

682

<description>Return a property attribute for new-style classes (classes that

683

derive from object).

684

fget is a function for getting an attribute value, likewise

685

fset is a function for setting, and fdel a function

686

for del'ing, an attribute. Typical use is to define a managed attribute x:

687

class C(object):

688

def getx(self): return self.__x

689

def setx(self, value): self.__x = value

690

def delx(self): del self.__x

691

x = property(getx, setx, delx, "I'm the 'x' property.")

692

New in version 2.2</description>

693

694

695

696

697

<description>This is a versatile function to create lists containing arithmetic

698

progressions. It is most often used in for loops. The

699

arguments must be plain integers. If the step argument is

700

omitted, it defaults to 1. If the start argument is

701

omitted, it defaults to 0. The full form returns a list of

702

plain integers [start, start + step,

703

start + 2 * step, ...]. If step is positive,

704

the last element is the largest start + i *

705

step less than stop; if step is negative, the last

706

element is the largest start + i * step

707

greater than stop. step must not be zero (or else

708

ValueError is raised). Example:

709

>>> range(10)

710

[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

711

>>> range(1, 11)

712

[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

713

>>> range(0, 30, 5)

714

[0, 5, 10, 15, 20, 25]

715

>>> range(0, 10, 3)

716

[0, 3, 6, 9]

717

>>> range(0, -10, -1)

718

[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]

719

>>> range(0)

720

[]

721

>>> range(1, 0)

722

[]

723

</description>

724

725

726

727

728

<description>If the prompt argument is present, it is written to standard output

729

without a trailing newline. The function then reads a line from input,

730

converts it to a string (stripping a trailing newline), and returns that.

731

When is read, EOFError is raised. Example:

732

>>> s = raw_input('--> ')

733

--> Monty Python's Flying Circus

734

>>> s

735

"Monty Python's Flying Circus"

736

If the readline module was loaded, then

737

raw_input() will use it to provide elaborate

738

line editing and history features.</description>

739

740

741

742

743

<description>Apply function of two arguments cumulatively to the items of

744

sequence, from left to right, so as to reduce the sequence to

745

a single value. For example, reduce(lambda x, y: x+y, [1, 2,

746

3, 4, 5]) calculates ((((1+2)+3)+4)+5). The left argument,

747

x, is the accumulated value and the right argument, y,

748

is the update value from the sequence. If the optional

749

initializer is present, it is placed before the items of the

750

sequence in the calculation, and serves as a default when the

751

sequence is empty. If initializer is not given and

752

sequence contains only one item, the first item is returned.</description>

753

754

755

756

757

<description>Re-parse and re-initialize an already imported module. The

758

argument must be a module object, so it must have been successfully

759

imported before. This is useful if you have edited the module

760

source file using an external editor and want to try out the new

761

version without leaving the Python interpreter. The return value is

762

the module object (the same as the module argument).

763

There are a number of caveats:

764

If a module is syntactically correct but its initialization fails,

765

the first import statement for it does not bind its name

766

locally, but does store a (partially initialized) module object in

767

sys.modules. To reload the module you must first

768

import it again (this will bind the name to the partially

769

initialized module object) before you can reload() it.

770

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

771

global variables) is retained. Redefinitions of names will override

772

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

773

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

774

old version, the old definition remains. This feature can be used

775

to the module's advantage if it maintains a global table or cache of

776

objects --- with a try statement it can test for the

777

table's presence and skip its initialization if desired.

778

It is legal though generally not very useful to reload built-in or

779

dynamically loaded modules, except for sys,

780

__main__ and __builtin__. In

781

many cases, however, extension modules are not designed to be

782

initialized more than once, and may fail in arbitrary ways when

783

reloaded.

784

If a module imports objects from another module using from

785

import , calling reload() for

786

the other module does not redefine the objects imported from it ---

787

one way around this is to re-execute the from statement,

788

another is to use import and qualified names

789

(module.name) instead.

790

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

791

that defines the class does not affect the method definitions of the

792

instances --- they continue to use the old class definition. The

793

same is true for derived classes.</description>

794

795

796

797

798

<description>Return a string containing a printable representation of an object.

799

This is the same value yielded by conversions (reverse quotes).

800

It is sometimes useful to be able to access this operation as an

801

ordinary function. For many types, this function makes an attempt

802

to return a string that would yield an object with the same value

803

when passed to eval().</description>

804

805

806

807

808

<description>Return a reverse iterator. seq must be an object which

809

supports the sequence protocol (the __len__() method and the

810

__getitem__() method with integer arguments starting at

811

0).

812

New in version 2.4</description>

813

814

815

816

817

<description>Return the floating point value x rounded to n digits

818

after the decimal point. If n is omitted, it defaults to zero.

819

The result is a floating point number. Values are rounded to the

820

closest multiple of 10 to the power minus n; if two multiples

821

are equally close, rounding is done away from 0 (so. for example,

822

round(0.5) is 1.0 and round(-0.5) is -1.0).</description>

823

824

825

826

827

<description>Return a set whose elements are taken from iterable. The elements

828

must be immutable. To represent sets of sets, the inner sets should

829

be frozenset objects. If iterable is not specified,

830

returns a new empty set, set([]).

831

New in version 2.4</description>

832

833

834

835

836

<description>This is the counterpart of getattr(). The arguments are an

837

object, a string and an arbitrary value. The string may name an

838

existing attribute or a new attribute. The function assigns the

839

value to the attribute, provided the object allows it. For example,

840

setattr(x, 'foobar', 123) is equivalent to

841

x.foobar = 123.</description>

842

843

844

845

846

<description>Return a slice object representing the set of indices specified by

847

range(start, stop, step). The start

848

and step arguments default to None. Slice objects have

849

read-only data attributes start, stop and

850

step which merely return the argument values (or their

851

default). They have no other explicit functionality; however they

852

are used by Numerical Python</description>

853

854

855

856

857

<description>Return a new sorted list from the items in iterable.

858

The optional arguments cmp, key, and reverse

859

have the same meaning as those for the list.sort() method.

860

New in version 2.4</description>

861

862

863

864

865

<description>Return a static method for function.

866

A static method does not receive an implicit first argument.

867

To declare a static method, use this idiom:

868

class C:

869

def f(arg1, arg2, ...): ...

870

f = staticmethod(f)

871

It can be called either on the class (such as C.f()) or on an

872

instance (such as C().f()). The instance is ignored except

873

for its class.

874

Static methods in Python are similar to those found in Java or Cpp.

875

For a more advanced concept, see classmethod() in this

876

section.

877

New in version 2.2</description>

878

879

880

881

882

<description>Return a string containing a nicely printable representation of an

883

object. For strings, this returns the string itself. The

884

difference with repr(object) is that

885

str(object) does not always attempt to return a string

886

that is acceptable to eval(); its goal is to return a

887

printable string. If no argument is given, returns the empty

888

string, ''.</description>

889

890

891

892

893

<description>Sums start and the items of a sequence, from left to

894

right, and returns the total. start defaults to 0.

895

The sequence's items are normally numbers, and are not allowed

896

to be strings. The fast, correct way to concatenate sequence of

897

strings is by calling ''.join(sequence).

898

Note that sum(range(n), m) is equivalent to

899

reduce(operator.add, range(n), m)

900

New in version 2.3</description>

901

902

903

904

905

<description>Return the superclass of type. If the second argument is omitted

906

the super object returned is unbound. If the second argument is an

907

object, isinstance(obj, type) must be true. If

908

the second argument is a type, issubclass(type2,

909

type) must be true.

910

super() only works for new-style classes.

911

A typical use for calling a cooperative superclass method is:

912

class C(B):

913

def meth(self, arg):

914

super(C, self).meth(arg)

915

New in version 2.2</description>

916

917

918

919

920

<description>Return a tuple whose items are the same and in the same order as

921

sequence's items. sequence may be a sequence, a

922

container that supports iteration, or an iterator object.

923

If sequence is already a tuple, it

924

is returned unchanged. For instance, tuple('abc') returns

925

('a', 'b', 'c') and tuple([1, 2, 3]) returns

926

(1, 2, 3). If no argument is given, returns a new empty

927

tuple, ().</description>

928

929

930

931

932

<description>Return the type of an object. The return value is a

933

typetype object. The standard module

934

typestypes defines names for all built-in

935

types that don't already have built-in names.

936

For instance:

937

>>> import types

938

>>> x = 'abc'

939

>>> if type(x) is str: print "It's a string"

940

...

941

It's a string

942

>>> def f(): pass

943

...

944

>>> if type(f) is types.FunctionType: print "It's a function"

945

...

946

It's a function

947

The isinstance() built-in function is recommended for

948

testing the type of an object.</description>

949

950

951

952

953

<description>Return the Unicode string of one character whose Unicode code is the

954

integer i. For example, unichr(97) returns the string

955

u'a'. This is the inverse of ord() for Unicode

956

strings. The argument must be in the range [0..65535], inclusive.

957

ValueError is raised otherwise.

958

New in version 2.0</description>

959

960

961

962

963

<description>Return the Unicode string version of object using one of the

964

following modes:

965

If encoding and/or errors are given, unicode()

966

will decode the object which can either be an 8-bit string or a

967

character buffer using the codec for encoding. The

968

encoding parameter is a string giving the name of an encoding;

969

if the encoding is not known, LookupError is raised.

970

Error handling is done according to errors; this specifies the

971

treatment of characters which are invalid in the input encoding. If

972

errors is 'strict' (the default), a

973

ValueError is raised on errors, while a value of

974

'ignore' causes errors to be silently ignored, and a value of

975

'replace' causes the official Unicode replacement character,

976

U+FFFD, to be used to replace input characters which cannot

977

be decoded. See also the codecs module.

978

If no optional parameters are given, unicode() will mimic the

979

behaviour of str() except that it returns Unicode strings

980

instead of 8-bit strings. More precisely, if object is a

981

Unicode string or subclass it will return that Unicode string without

982

any additional decoding applied.

983

For objects which provide a __unicode__() method, it will

984

call this method without arguments to create a Unicode string. For

985

all other objects, the 8-bit string version or representation is

986

requested and then converted to a Unicode string using the codec for

987

the default encoding in 'strict' mode.

988

New in version 2.0

989

Changed in version 2.2: Support for __unicode__() added</description>

990

991

992

993

994

<description>Without arguments, return a dictionary corresponding to the current

995

local symbol table. With a module, class or class instance object

996

as argument (or anything else that has a __dict__

997

attribute), returns a dictionary corresponding to the object's

998

symbol table. The returned dictionary should not be modified: the

999

effects on the corresponding symbol table are undefined.

1000

In the current implementation, local variable bindings cannot

1001

normally be affected this way, but variables retrieved from

1002

other scopes (such as modules) can be. This may change.</description>

1003

1004

1005

1006

1007

<description>This function is very similar to range(), but returns an

1008

``xrange object'' instead of a list. This is an opaque sequence

1009

type which yields the same values as the corresponding list, without

1010

actually storing them all simultaneously. The advantage of

1011

xrange() over range() is minimal (since

1012

xrange() still has to create the values when asked for

1013

them) except when a very large range is used on a memory-starved

1014

machine or when all of the range's elements are never used (such as

1015

when the loop is usually terminated with break).</description>

1016

1017

1018

1019

1020

<description>This function returns a list of tuples, where the i-th tuple contains

1021

the i-th element from each of the argument sequences.

1022

The returned list is truncated in length to the length of

1023

the shortest argument sequence. When there are multiple argument

1024

sequences which are all of the same length, zip() is

1025

similar to map() with an initial argument of None.

1026

With a single sequence argument, it returns a list of 1-tuples.

1027

With no arguments, it returns an empty list.

1028

New in version 2.0

1029

Changed in version 2.4: Formerly, zip() required at least one argument

1030

and zip() raised a TypeError instead of returning

1031

an empty list.</description>

1032

1033

1034

1035

1036

<description>The function argument must be a callable object (a

1037

user-defined or built-in function or method, or a class object) and

1038

the args argument must be a sequence. The function is

1039

called with args as the argument list; the number of arguments

1040

is the length of the tuple.

1041

If the optional keywords argument is present, it must be a

1042

dictionary whose keys are strings. It specifies keyword arguments

1043

to be added to the end of the argument list.

1044

Calling apply() is different from just calling

1045

function(args), since in that case there is always

1046

exactly one argument. The use of apply() is equivalent

1047

to function(*args, **keywords).

1048

Use of apply() is not necessary since the ``extended call

1049

syntax,'' as used in the last example, is completely equivalent.

1050

2.3{Use the extended call syntax instead, as described

1051

above.}</description>

1052

1053

1054

1055

1056

<description>The object argument must be an object that supports the buffer

1057

call interface (such as strings, arrays, and buffers). A new buffer

1058

object will be created which references the object argument.

1059

The buffer object will be a slice from the beginning of object

1060

(or from the specified offset). The slice will extend to the

1061

end of object (or will have a length given by the size

1062

argument).</description>

1063

1064

1065

1066

1067

<description>Return a tuple consisting of the two numeric arguments converted to

1068

a common type, using the same rules as used by arithmetic

1069

operations.</description>

1070

1071

1072

1073

1074

<description>Enter string in the table of ``interned'' strings and return

1075

the interned string -- which is string itself or a copy.

1076

Interning strings is useful to gain a little performance on

1077

dictionary lookup -- if the keys in a dictionary are interned, and

1078

the lookup key is interned, the key comparisons (after hashing) can

1079

be done by a pointer compare instead of a string compare. Normally,

1080

the names used in Python programs are automatically interned, and

1081

the dictionaries used to hold module, class or instance attributes

1082

have interned keys. Changed in version 2.3: Interned strings are not

1083

immortal (like they used to be in Python 2.2 and before);

1084

you must keep a reference to the return value of intern()

1085

around to benefit from it</description>

1086

1087

1088

1089

</group>

1090

1091

<description>The following sections describe the standard types that are built into

1092

the interpreter. Historically, Python's built-in types have differed

1093

from user-defined types because it was not possible to use the built-in

1094

types as the basis for object-oriented inheritance. With the 2.2

1095

release this situation has started to change, although the intended

1096

unification of user-defined and built-in types is as yet far from

1097

complete.

1098

The principal built-in types are numerics, sequences, mappings, files

1099

classes, instances and exceptions.

1100

Some operations are supported by several object types; in particular,

1101

all objects can be compared, tested for truth value, and converted to

1102

a string (with the `...` notation). The latter

1103

conversion is implicitly used when an object is written by the

1104

printprint statement.

1105

(Information on print statement{../ref/print.html}

1106

and other language statements can be found in the

1107

Python Reference Manual and the

1108

Python Tutorial.)

1109

</description>

1110

1111

<description>Any object can be tested for truth value, for use in an if or

1112

while condition or as operand of the Boolean operations below.

1113

The following values are considered false:

1114

if

1115

while

1116

</description>

1117

</group>

1118

1119

<description>These are the Boolean operations, ordered by ascending priority:

1120

{c|l|c}{code}{Operation}{Result}{Notes}

1121

x or y

1122

{if x is false, then y, else x}{(1)}

1123

x and y

1124

{if x is false, then x, else y}{(1)}

1125

not x

1126

{if x is false, then True, else False}{(2)}

1127

and

1128

or

1129

not

1130

Notes:

1131

[(1)]

1132

These only evaluate their second argument if needed for their outcome.

1133

[(2)]

1134

not has a lower priority than non-Boolean operators, so

1135

not a == b is interpreted as not (a ==

1136

b), and a == not b is a syntax error.

1137

</description>

1138

</group>

1139

1140

<description>Comparison operations are supported by all objects. They all have the

1141

same priority (which is higher than that of the Boolean operations).

1142

Comparisons can be chained arbitrarily; for example, x <

1143

y <= z is equivalent to x < y and

1144

y <= z, except that y is evaluated only once (but

1145

in both cases z is not evaluated at all when x <

1146

y is found to be false).

1147

This table summarizes the comparison operations:

1148

{c|l|c}{code}{Operation}{Meaning}{Notes}

1149

<{strictly less than}{}

1150

<={less than or equal}{}

1151

>{strictly greater than}{}

1152

>={greater than or equal}{}

1153

=={equal}{}

1154

!={not equal}{(1)}

1155

<>{not equal}{(1)}

1156

is{object identity}{}

1157

is not{negated object identity}{}

1158

== % XXX *All* others have funny characters < ! >

1159

is

1160

is not

1161

Notes:

1162

[(1)]

1163

<> and != are alternate spellings for the same operator.

1164

!= is the preferred spelling; <> is obsolescent.

1165

Objects of different types, except different numeric types and different string types, never

1166

compare equal; such objects are ordered consistently but arbitrarily

1167

(so that sorting a heterogeneous array yields a consistent result).

1168

Furthermore, some types (for example, file objects) support only a

1169

degenerate notion of comparison where any two objects of that type are

1170

unequal. Again, such objects are ordered arbitrarily but

1171

consistently. The <, <=, > and >=

1172

operators will raise a TypeError exception when any operand

1173

is a complex number. Instances of a class normally compare as non-equal unless the class

1174

(instance method){__cmp__()}

1175

defines the __cmp__() method. Refer to the

1176

Python Reference Manual for

1177

information on the use of this method to effect object comparisons.

1178

Implementation note: Objects of different types except

1179

numbers are ordered by their type names; objects of the same types

1180

that don't support proper comparison are ordered by their address.

1181

Two more operations with the same syntactic priority,

1182

inin and not innot in, are supported

1183

only by sequence types (below).

1184

</description>

1185

</group>

1186

1187

<description>There are four distinct numeric types: plain integers,

1188

long integers, floating point numbers, and complex numbers.

1189

In addition, Booleans are a subtype of plain integers.

1190

Plain integers (also just called integers)

1191

are implemented using long in C, which gives them at least 32

1192

bits of precision. Long integers have unlimited precision. Floating

1193

point numbers are implemented using double in C. All bets on

1194

their precision are off unless you happen to know the machine you are

1195

working with.

1196

numeric

1197

Boolean

1198

integer

1199

long integer

1200

floating point

1201

complex number

1202

Complex numbers have a real and imaginary part, which are each

1203

implemented using double in C. To extract these parts from

1204

a complex number z, use z.real and z.imag.

1205

Numbers are created by numeric literals or as the result of built-in

1206

functions and operators. Unadorned integer literals (including hex

1207

and octal numbers) yield plain integers unless the value they denote

1208

is too large to be represented as a plain integer, in which case

1209

they yield a long integer. Integer literals with an

1210

L or l suffix yield long integers

1211

(L is preferred because 1l looks too much like

1212

eleven!). Numeric literals containing a decimal point or an exponent

1213

sign yield floating point numbers. Appending j or

1214

J to a numeric literal yields a complex number with a

1215

zero real part. A complex numeric literal is the sum of a real and

1216

an imaginary part.

1217

long{integer}{literals}

1218

Python fully supports mixed arithmetic: when a binary arithmetic

1219

operator has operands of different numeric types, the operand with the

1220

``narrower'' type is widened to that of the other, where plain

1221

integer is narrower than long integer is narrower than floating point is

1222

narrower than complex.

1223

Comparisons between numbers of mixed type use the same rule.

1224

As a consequence, the list [1, 2] is considered equal

1225

to [1.0, 2.0], and similarly for tuples.

1226

The constructors int(), long(), float(),

1227

and complex() can be used

1228

to produce numbers of a specific type.

1229

</description>

1230

</group>

1231

1232

<description>New in version 2.2

1233

</description>

1234

1235

<description>Return an iterator object. The object is required to support the

1236

iterator protocol described below. If a container supports

1237

different types of iteration, additional methods can be provided to

1238

specifically request iterators for those iteration types. (An

1239

example of an object supporting multiple forms of iteration would be

1240

a tree structure which supports both breadth-first and depth-first

1241

traversal.) This method corresponds to the tp_iter slot of

1242

the type structure for Python objects in the Python/C API.</description>

1243

1244

</element>

1245

1246

1247

<description>Return the iterator object itself. This is required to allow both

1248

containers and iterators to be used with the for and

1249

in statements. This method corresponds to the

1250

tp_iter slot of the type structure for Python objects in

1251

the Python/C API.</description>

1252

1253

</element>

1254

1255

1256

<description>Return the next item from the container. If there are no further

1257

items, raise the StopIteration exception. This method

1258

corresponds to the tp_iternext slot of the type structure

1259

for Python objects in the Python/C API.</description>

1260

1261

</element>

1262

1263

</group>

1264

1265

<description>There are six sequence types: strings, Unicode strings, lists,

1266

tuples, buffers, and xrange objects.

1267

String literals are written in single or double quotes:

1268

'xyzzy', "frobozz". See chapter 2 of the

1269

Python Reference Manual for more about

1270

string literals. Unicode strings are much like strings, but are

1271

specified in the syntax using a preceeding u character:

1272

u'abc', u"def". Lists are constructed with square brackets,

1273

separating items with commas: [a, b, c]. Tuples are

1274

constructed by the comma operator (not within square brackets), with

1275

or without enclosing parentheses, but an empty tuple must have the

1276

enclosing parentheses, such as a, b, c or (). A single

1277

item tuple must have a trailing comma, such as (d,).

1278

sequence

1279

string

1280

Unicode

1281

tuple

1282

list

1283

Buffer objects are not directly supported by Python syntax, but can be

1284

created by calling the builtin function

1285

buffer().buffer They don't support

1286

concatenation or repetition.

1287

buffer

1288

Xrange objects are similar to buffers in that there is no specific

1289

syntax to create them, but they are created using the xrange()

1290

function.xrange They don't support slicing,

1291

concatenation or repetition, and using in, not in,

1292

min() or max() on them is inefficient.

1293

xrange

1294

Most sequence types support the following operations. The in and

1295

not in operations have the same priorities as the comparison

1296

operations. The + and * operations have the same

1297

priority as the corresponding numeric operations.They must

1298

have since the parser can't tell the type of the operands.

1299

This table lists the sequence operations sorted in ascending priority

1300

(operations in the same box have the same priority). In the table,

1301

s and t are sequences of the same type; n, i

1302

and j are integers:

1303

{c|l|c}{code}{Operation}{Result}{Notes}

1304

x in s{1 if an item of s is equal to x, else 0}{(1)}

1305

x not in s{0 if an item of s is

1306

equal to x, else 1}{(1)}

1307

s + t{the concatenation of s and t}{}

1308

s * n, n * s{n shallow copies of s concatenated}{(2)}

1309

s[i]{i'th item of s, origin 0}{(3)}

1310

s[i:j]{slice of s from i to j}{(3), (4)}

1311

s[i:j:k]{slice of s from i to j with step k}{(3), (5)}

1312

len(s){length of s}{}

1313

min(s){smallest item of s}{}

1314

max(s){largest item of s}{}

1315

operations on{sequence}{types}

1316

len

1317

min

1318

max

1319

in

1320

not in

1321

Notes:

1322

[(1)] When s is a string or Unicode string object the

1323

in and not in operations act like a substring test. In

1324

Python versions before 2.3, x had to be a string of length 1.

1325

In Python 2.3 and beyond, x may be a string of any length.

1326

[(2)] Values of n less than 0 are treated as

1327

0 (which yields an empty sequence of the same type as

1328

s). Note also that the copies are shallow; nested structures

1329

are not copied. This often haunts new Python programmers; consider:

1330

>>> lists = [[]] * 3

1331

>>> lists

1332

[[], [], []]

1333

>>> lists[0].append(3)

1334

>>> lists

1335

[[3], [3], [3]]

1336

What has happened is that lists is a list containing three

1337

copies of the list [[]] (a one-element list containing an

1338

empty list), but the contained list is shared by each copy. You can

1339

create a list of different lists this way:

1340

>>> lists = [[] for i in range(3)]

1341

>>> lists[0].append(3)

1342

>>> lists[1].append(5)

1343

>>> lists[2].append(7)

1344

>>> lists

1345

[[3], [5], [7]]

1346

[(3)] If i or j is negative, the index is relative to

1347

the end of the string: len(s) + i or

1348

len(s) + j is substituted. But note that -0 is

1349

still 0.

1350

[(4)] The slice of s from i to j is defined as

1351

the sequence of items with index k such that i <=

1352

k < j. If i or j is greater than

1353

len(s), use len(s). If i is omitted,

1354

use 0. If j is omitted, use len(s). If

1355

i is greater than or equal to j, the slice is empty.

1356

[(5)] The slice of s from i to j with step

1357

k is defined as the sequence of items with index x = i + n*k such that 0

1358

<= n < abs(i-j). If i or j

1359

is greater than len(s), use len(s). If

1360

i or j are omitted then they become ``end'' values

1361

(which end depends on the sign of k). Note, k cannot

1362

be zero.

1363

String Methods These are the string methods which both 8-bit strings and Unicode

1364

objects support:

1365

</description>

1366

1367

<description>Return a copy of the string with only its first character capitalized.</description>

1368

1369

</element>

1370

1371

1372

<description>Return centered in a string of length width. Padding is done

1373

using the specified fillchar (default is a space).

1374

Changed in version 2.4: Support for the fillchar argument</description>

1375

1376

1377

1378

1379

<description>Return the number of occurrences of substring sub in string

1380

S[start:end]. Optional arguments start and

1381

end are interpreted as in slice notation.</description>

1382

1383

1384

1385

1386

<description>Decodes the string using the codec registered for encoding.

1387

encoding defaults to the default string encoding. errors

1388

may be given to set a different error handling scheme. The default is

1389

'strict', meaning that encoding errors raise

1390

ValueError. Other possible values are 'ignore' and

1391

'replace'.

1392

New in version 2.2</description>

1393

1394

1395

1396

1397

<description>Return an encoded version of the string. Default encoding is the current

1398

default string encoding. errors may be given to set a different

1399

error handling scheme. The default for errors is

1400

'strict', meaning that encoding errors raise a

1401

ValueError. Other possible values are 'ignore' and

1402

'replace'.

1403

New in version 2.0</description>

1404

1405

1406

1407

1408

<description>Return True if the string ends with the specified suffix,

1409

otherwise return False. With optional start, test beginning at

1410

that position. With optional end, stop comparing at that position.</description>

1411

1412

1413

1414

1415

<description>Return a copy of the string where all tab characters are expanded

1416

using spaces. If tabsize is not given, a tab size of 8

1417

characters is assumed.</description>

1418

1419

1420

1421

1422

<description>Return the lowest index in the string where substring sub is

1423

found, such that sub is contained in the range [start,

1424

end). Optional arguments start and end are

1425

interpreted as in slice notation. Return -1 if sub is

1426

not found.</description>

1427

1428

1429

1430

1431

<description>Like find(), but raise ValueError when the

1432

substring is not found.</description>

1433

1434

1435

1436

1437

<description>Return true if all characters in the string are alphanumeric and there

1438

is at least one character, false otherwise.</description>

1439

1440

</element>

1441

1442

1443

<description>Return true if all characters in the string are alphabetic and there

1444

is at least one character, false otherwise.</description>

1445

1446

</element>

1447

1448

1449

<description>Return true if all characters in the string are digits and there

1450

is at least one character, false otherwise.</description>

1451

1452

</element>

1453

1454

1455

<description>Return true if all cased characters in the string are lowercase and

1456

there is at least one cased character, false otherwise.</description>

1457

1458

</element>

1459

1460

1461

<description>Return true if there are only whitespace characters in the string and

1462

there is at least one character, false otherwise.</description>

1463

1464

</element>

1465

1466

1467

<description>Return true if the string is a titlecased string and there is at least one

1468

character, for example uppercase characters may only follow uncased

1469

characters and lowercase characters only cased ones. Return false

1470

otherwise.</description>

1471

1472

</element>

1473

1474

1475

<description>Return true if all cased characters in the string are uppercase and

1476

there is at least one cased character, false otherwise.</description>

1477

1478

</element>

1479

1480

1481

<description>Return a string which is the concatenation of the strings in the

1482

sequence seq. The separator between elements is the string

1483

providing this method.</description>

1484

1485

1486

1487

1488

<description>Return the string left justified in a string of length width.

1489

Padding is done using the specified fillchar (default is a

1490

space). The original string is returned if

1491

width is less than len(s).

1492

Changed in version 2.4: Support for the fillchar argument</description>

1493

1494

1495

1496

1497

<description>Return a copy of the string converted to lowercase.</description>

1498

1499

</element>

1500

1501

1502

<description>Return a copy of the string with leading characters removed. If

1503

chars is omitted or None, whitespace characters are

1504

removed. If given and not None, chars must be a string;

1505

the characters in the string will be stripped from the beginning of

1506

the string this method is called on.

1507

Changed in version 2.2.2: Support for the chars argument</description>

1508

1509

1510

1511

1512

<description>Return a copy of the string with all occurrences of substring

1513

old replaced by new. If the optional argument

1514

count is given, only the first count occurrences are

1515

replaced.</description>

1516

1517

1518

1519

1520

<description>Return the highest index in the string where substring sub is

1521

found, such that sub is contained within s[start,end]. Optional

1522

arguments start and end are interpreted as in slice

1523

notation. Return -1 on failure.</description>

1524

1525

1526

1527

1528

<description>Like rfind() but raises ValueError when the

1529

substring sub is not found.</description>

1530

1531

1532

1533

1534

<description>Return the string right justified in a string of length width.

1535

Padding is done using the specified fillchar (default is a space).

1536

The original string is returned if

1537

width is less than len(s).

1538

Changed in version 2.4: Support for the fillchar argument</description>

1539

1540

1541

1542

1543

<description>Return a list of the words in the string, using sep as the

1544

delimiter string. If maxsplit is given, at most maxsplit

1545

splits are done, the rightmost ones. If sep is not specified

1546

or None, any whitespace string is a separator.

1547

New in version 2.4</description>

1548

1549

1550

1551

1552

<description>Return a copy of the string with trailing characters removed. If

1553

chars is omitted or None, whitespace characters are

1554

removed. If given and not None, chars must be a string;

1555

the characters in the string will be stripped from the end of the

1556

string this method is called on.

1557

Changed in version 2.2.2: Support for the chars argument</description>

1558

1559

1560

1561

1562

<description>Return a list of the words in the string, using sep as the

1563

delimiter string. If maxsplit is given, at most maxsplit

1564

splits are done. If sep is not specified or None, any

1565

whitespace string is a separator.</description>

1566

1567

1568

1569

1570

<description>Return a list of the lines in the string, breaking at line

1571

boundaries. Line breaks are not included in the resulting list unless

1572

keepends is given and true.</description>

1573

1574

1575

1576

1577

<description>Return True if string starts with the prefix, otherwise

1578

return False. With optional start, test string beginning at

1579

that position. With optional end, stop comparing string at that

1580

position.</description>

1581

1582

1583

1584

1585

<description>Return a copy of the string with leading and trailing characters

1586

removed. If chars is omitted or None, whitespace

1587

characters are removed. If given and not None, chars

1588

must be a string; the characters in the string will be stripped from

1589

the both ends of the string this method is called on.

1590

Changed in version 2.2.2: Support for the chars argument</description>

1591

1592

1593

1594

1595

<description>Return a copy of the string with uppercase characters converted to

1596

lowercase and vice versa.</description>

1597

1598

</element>

1599

1600

1601

<description>Return a titlecased version of the string: words start with uppercase

1602

characters, all remaining cased characters are lowercase.</description>

1603

1604

</element>

1605

1606

1607

<description>Return a copy of the string where all characters occurring in the

1608

optional argument deletechars are removed, and the remaining

1609

characters have been mapped through the given translation table, which

1610

must be a string of length 256.

1611

For Unicode objects, the translate() method does not

1612

accept the optional deletechars argument. Instead, it

1613

returns a copy of the s where all characters have been mapped

1614

through the given translation table which must be a mapping of

1615

Unicode ordinals to Unicode ordinals, Unicode strings or None.

1616

Unmapped characters are left untouched. Characters mapped to None

1617

are deleted. Note, a more flexible approach is to create a custom

1618

character mapping codec using the codecs module (see

1619

encodings.cp1251 for an example).</description>

1620

1621

1622

1623

1624

<description>Return a copy of the string converted to uppercase.</description>

1625

1626

</element>

1627

1628

1629

<description>Return the numeric string left filled with zeros in a string

1630

of length width. The original string is returned if

1631

width is less than len(s).

1632

New in version 2.2.2</description>

1633

1634

1635

1636

</group>

1637

1638

<description>set

1639

A set object is an unordered collection of immutable values.

1640

Common uses include membership testing, removing duplicates from a sequence,

1641

and computing mathematical operations such as intersection, union, difference,

1642

and symmetric difference.

1643

New in version 2.4 Like other collections, sets support x in set,

1644

len(set), and for x in set. Being an

1645

unordered collection, sets do not record element position or order of

1646

insertion. Accordingly, sets do not support indexing, slicing, or

1647

other sequence-like behavior. There are currently two builtin set types, set and frozenset.

1648

The set type is mutable --- the contents can be changed using methods

1649

like add() and remove(). Since it is mutable, it has no

1650

hash value and cannot be used as either a dictionary key or as an element of

1651

another set. The frozenset type is immutable and hashable --- its

1652

contents cannot be altered after is created; however, it can be used as

1653

a dictionary key or as an element of another set.

1654

Instances of set and frozenset provide the following operations:

1655

{c|c|l}{code}{Operation}{Equivalent}{Result}

1656

len(s){}{cardinality of set s}

1657

x in s{}

1658

{test x for membership in s}

1659

x not in s{}

1660

{test x for non-membership in s}

1661

s.issubset(t){s <= t}

1662

{test whether every element in s is in t}

1663

s.issuperset(t){s >= t}

1664

{test whether every element in t is in s}

1665

s.union(t){s | t}

1666

{new set with elements from both s and t}

1667

s.intersection(t){s t}

1668

{new set with elements common to s and t}

1669

s.difference(t){s - t}

1670

{new set with elements in s but not in t}

1671

s.symmetric_difference(t){s t}

1672

{new set with elements in either s or t but not both}

1673

s.copy(){}

1674

{new set with a shallow copy of s}

1675

Note, the non-operator versions of union(), intersection(),

1676

difference(), and symmetric_difference(),

1677

issubset(), and issuperset() methods will accept any

1678

iterable as an argument. In contrast, their operator based counterparts

1679

require their arguments to be sets. This precludes error-prone constructions

1680

like set('abc') ' in favor of the more readable

1681

set('abc').intersection('cbs').

1682

Both set and frozenset support set to set comparisons.

1683

Two sets are equal if and only if every element of each set is contained in

1684

the other (each is a subset of the other).

1685

A set is less than another set if and only if the first set is a proper

1686

subset of the second set (is a subset, but is not equal).

1687

A set is greater than another set if and only if the first set is a proper

1688

superset of the second set (is a superset, but is not equal).

1689

The subset and equality comparisons do not generalize to a complete

1690

ordering function. For example, any two disjoint sets are not equal and

1691

are not subsets of each other, so all of the following return

1692

False: a<b, a==b, or

1693

a>b.

1694

Accordingly, sets do not implement the __cmp__ method.

1695

Since sets only define partial ordering (subset relationships), the output

1696

of the list.sort() method is undefined for lists of sets.

1697

For convenience in implementing sets of sets, the __contains__(),

1698

remove(), and discard() methods automatically match

1699

instances of the set class their frozenset counterparts

1700

inside a set. For example, set('abc') in set([frozenset('abc')])

1701

returns True.

1702

The following table lists operations available for set

1703

that do not apply to immutable instances of frozenset:

1704

{c|c|l}{code}{Operation}{Equivalent}{Result}

1705

s.update(t)

1706

{s |= t}

1707

{return set s with elements added from t}

1708

s.intersection_update(t)

1709

{s t}

1710

{return set s keeping only elements also found in t}

1711

s.difference_update(t)

1712

{s -= t}

1713

{return set s after removing elements found in t}

1714

s.symmetric_difference_update(t)

1715

{s = t}

1716

{return set s with elements from s or t

1717

but not both}

1718

s.add(x){}

1719

{add element x to set s}

1720

s.remove(x){}

1721

{remove x from set s; raises KeyError if not present}

1722

s.discard(x){}

1723

{removes x from set s if present}

1724

s.pop(){}

1725

{remove and return an arbitrary element from s; raises

1726

KeyError if empty}

1727

s.clear(){}

1728

{remove all elements from set s}

1729

Note, the non-operator versions of the update(),

1730

intersection_update(), difference_update(), and

1731

symmetric_difference_update() methods will accept any iterable

1732

as an argument.

1733

</description>

1734

</group>

1735

1736

<description>mapping

1737

dictionary

1738

A mapping object maps immutable values to

1739

arbitrary objects. Mappings are mutable objects. There is currently

1740

only one standard mapping type, the dictionary. A dictionary's keys are

1741

almost arbitrary values. Only values containing lists, dictionaries

1742

or other mutable types (that are compared by value rather than by

1743

object identity) may not be used as keys.

1744

Numeric types used for keys obey the normal rules for numeric

1745

comparison: if two numbers compare equal (such as 1 and

1746

1.0) then they can be used interchangeably to index the same

1747

dictionary entry.

1748

Dictionaries are created by placing a comma-separated list of

1749

key: value pairs within braces, for example:

1750

{'jack': 4098, 'sjoerd': 4127} or

1751

{4098: 'jack', 4127: 'sjoerd'}.

1752

The following operations are defined on mappings (where a and

1753

b are mappings, k is a key, and v and x are

1754

arbitrary objects):

1755

operations on{mapping}{types}

1756

operations on{dictionary}{type}

1757

del

1758

len

1759

(dictionary method){

1760

clear()

1761

copy()

1762

has_key()

1763

fromkeys() items()

1764

keys()

1765

update()

1766

values()

1767

get()

1768

setdefault()

1769

pop()

1770

popitem()

1771

iteritems()

1772

iterkeys()

1773

itervalues()}

1774

{c|l|c}{code}{Operation}{Result}{Notes}

1775

len(a){the number of items in a}{}

1776

a[k]{the item of a with key k}{(1)}

1777

a[k] = v

1778

{set a[k] to v}

1779

{}

1780

del a[k]

1781

{remove a[k] from a}

1782

{(1)}

1783

a.clear(){remove all items from a}{}

1784

a.copy(){a (shallow) copy of a}{}

1785

a.has_key(k)

1786

{True if a has a key k, else False}

1787

{}

1788

k in a

1789

{Equivalent to a.has_key(k)}

1790

{(2)}

1791

k not in a

1792

{Equivalent to not a.has_key(k)}

1793

{(2)}

1794

a.items()

1795

{a copy of a's list of (key, value) pairs}

1796

{(3)}

1797

a.keys(){a copy of a's list of keys}{(3)}

1798

a.update(b)

1799

{for k in b.keys(): a[k] = b[k]}

1800

{}

1801

a.fromkeys(seq, value)

1802

{Creates a new dictionary with keys from seq and values set to value}

1803

{(7)} a.values(){a copy of a's list of values}{(3)}

1804

a.get(k, x)

1805

{a[k] if k in a,

1806

else x}

1807

{(4)}

1808

a.setdefault(k, x)

1809

{a[k] if k in a,

1810

else x (also setting it)}

1811

{(5)}

1812

a.pop(k, x)

1813

{a[k] if k in a,

1814

else x (and remove k)}

1815

{(8)}

1816

a.popitem()

1817

{remove and return an arbitrary (key, value) pair}

1818

{(6)}

1819

a.iteritems()

1820

{return an iterator over (key, value) pairs}

1821

{(2), (3)}

1822

a.iterkeys()

1823

{return an iterator over the mapping's keys}

1824

{(2), (3)}

1825

a.itervalues()

1826

{return an iterator over the mapping's values}

1827

{(2), (3)}

1828

Notes:

1829

[(1)] Raises a KeyError exception if k is not

1830

in the map.

1831

[(2)] New in version 2.2

1832

[(3)] Keys and values are listed in random order. If

1833

items(), keys(), values(),

1834

iteritems(), iterkeys(), and itervalues()

1835

are called with no intervening modifications to the dictionary, the

1836

lists will directly correspond. This allows the creation of

1837

(value, key) pairs using zip():

1838

pairs = zip(a.values(), a.keys()). The same

1839

relationship holds for the iterkeys() and

1840

itervalues() methods: pairs = zip(a.itervalues(),

1841

a.iterkeys()) provides the same value for pairs.

1842

Another way to create the same list is pairs = [(v, k) for (k,

1843

v) in a.iteritems()].

1844

[(4)] Never raises an exception if k is not in the map,

1845

instead it returns x. x is optional; when x is not

1846

provided and k is not in the map, None is returned.

1847

[(5)] setdefault() is like get(), except

1848

that if k is missing, x is both returned and inserted into

1849

the dictionary as the value of k.

1850

[(6)] popitem() is useful to destructively iterate

1851

over a dictionary, as often used in set algorithms.

1852

[(7)] fromkeys() is a class method that returns a

1853

new dictionary. value defaults to None. New in version 2.3

1854

[(8)] pop() raises a KeyError when no default

1855

value is given and the key is not found. New in version 2.3

1856

</description>

1857

</group>

1858

1859

<description>File objectsfile are implemented using C's stdio

1860

package and can be created with the built-in constructor

1861

file()file described in section

1862

built-in-funcs, ``Built-in Functions.''file()

1863

is new in Python 2.2. The older built-in open() is an

1864

alias for file().

1865

File objects are also returned

1866

by some other built-in functions and methods, such as

1867

os.popen() and os.fdopen() and the

1868

makefile() method of socket objects.

1869

os

1870

socket

1871

When a file operation fails for an I/O-related reason, the exception

1872

IOError is raised. This includes situations where the

1873

operation is not defined for some reason, like seek() on a tty

1874

device or writing a file opened for reading.

1875

Files have the following methods:

1876

</description>

1877

1878

<description>Close the file. A closed file cannot be read or written any more.

1879

Any operation which requires that the file be open will raise a

1880

ValueError after the file has been closed. Calling

1881

close() more than once is allowed.</description>

1882

1883

</element>

1884

1885

1886

<description>Flush the internal buffer, like stdio's

1887

fflush(). This may be a no-op on some file-like

1888

objects.</description>

1889

1890

</element>

1891

1892

1893

1894

1895

</element>

1896

1897

1898

<description>Return True if the file is connected to a tty(-like) device, else

1899

False. If a file-like object is not associated

1900

with a real file, this method should not be implemented.</description>

1901

1902

</element>

1903

1904

1905

<description>A file object is its own iterator, for example iter(f) returns

1906

f (unless f is closed). When a file is used as an

1907

iterator, typically in a for loop (for example,

1908

for line in f: print line), the next() method is

1909

called repeatedly. This method returns the next input line, or raises

1910

StopIteration when is hit. In order to make a

1911

for loop the most efficient way of looping over the lines of

1912

a file (a very common operation), the next() method uses a

1913

hidden read-ahead buffer. As a consequence of using a read-ahead

1914

buffer, combining next() with other file methods (like

1915

readline()) does not work right. However, using

1916

seek() to reposition the file to an absolute position will

1917

flush the read-ahead buffer.

1918

New in version 2.3</description>

1919

1920

</element>

1921

1922

1923

<description>Read at most size bytes from the file (less if the read hits

1924

before obtaining size bytes). If the size

1925

argument is negative or omitted, read all data until is

1926

reached. The bytes are returned as a string object. An empty

1927

string is returned when is encountered immediately. (For

1928

certain files, like ttys, it makes sense to continue reading after

1929

an is hit.) Note that this method may call the underlying

1930

C function fread() more than once in an effort to

1931

acquire as close to size bytes as possible. Also note that

1932

when in non-blocking mode, less data than what was requested may

1933

be returned, even if no size parameter was given.</description>

1934

1935

1936

1937

1938

<description>Read one entire line from the file. A trailing newline character is

1939

kept in the string

1940

The advantage of leaving the newline on is that

1941

returning an empty string is then an unambiguous indication. It is also possible (in cases where it might

1942

matter, for example, if you

1943

want to make an exact copy of a file while scanning its lines)

1944

to tell whether the last line of a file ended in a newline

1945

or not (yes this happens!).

1946

(but may be absent when a file ends with an

1947

incomplete line). If the size argument is present and

1948

non-negative, it is a maximum byte count (including the trailing

1949

newline) and an incomplete line may be returned.

1950

An empty string is returned only when is encountered

1951

immediately. Unlike stdio's fgets(), the

1952

returned string contains null characters ('\0') if they

1953

occurred in the input.</description>

1954

1955

1956

1957

1958

<description>Read until using readline() and return a list containing

1959

the lines thus read. If the optional sizehint argument is

1960

present, instead of reading up to , whole lines totalling

1961

approximately sizehint bytes (possibly after rounding up to an

1962

internal buffer size) are read. Objects implementing a file-like

1963

interface may choose to ignore sizehint if it cannot be

1964

implemented, or cannot be implemented efficiently.</description>

1965

1966

1967

1968

1969

<description>This method returns the same thing as iter(f).

1970

New in version 2.1

1971

2.3{Use for line in file instead.}</description>

1972

1973

</element>

1974

1975

1976

<description>Set the file's current position, like stdio's fseek().

1977

The whence argument is optional and defaults to 0

1978

(absolute file positioning); other values are 1 (seek

1979

relative to the current position) and 2 (seek relative to the

1980

file's end). There is no return value. Note that if the file is

1981

opened for appending (mode 'a' or 'a+'), any

1982

seek() operations will be undone at the next write. If the

1983

file is only opened for writing in append mode (mode 'a'),

1984

this method is essentially a no-op, but it remains useful for files

1985

opened in append mode with reading enabled (mode 'a+'). If the

1986

file is opened in text mode (mode 't'), only offsets returned

1987

by tell() are legal. Use of other offsets causes undefined

1988

behavior.

1989

Note that not all file objects are seekable.</description>

1990

1991

1992

1993

1994

<description>Return the file's current position, like stdio's

1995

ftell().</description>

1996

1997

</element>

1998

1999

2000

<description>Truncate the file's size. If the optional size argument is

2001

present, the file is truncated to (at most) that size. The size

2002

defaults to the current position. The current file position is

2003

not changed. Note that if a specified size exceeds the file's

2004

current size, the result is platform-dependent: possibilities

2005

include that file may remain unchanged, increase to the specified

2006

size as if zero-filled, or increase to the specified size with

2007

undefined new content.

2008

Availability: Windows, many variants.</description>

2009

2010

2011

2012

2013

<description>Write a string to the file. There is no return value. Due to

2014

buffering, the string may not actually show up in the file until

2015

the flush() or close() method is called.</description>

2016

2017

2018

2019

2020

<description>Write a sequence of strings to the file. The sequence can be any

2021

iterable object producing strings, typically a list of strings.

2022

There is no return value.

2023

(The name is intended to match readlines();

2024

writelines() does not add line separators.)</description>

2025

2026

2027

2028

</group>

2029

2030

<description>The interpreter supports several other kinds of objects.

2031

Most of these support only one or two operations.

2032

Modules The only special operation on a module is attribute access:

2033

m.name, where m is a module and name

2034

accesses a name defined in m's symbol table. Module attributes

2035

can be assigned to. (Note that the import statement is not,

2036

strictly speaking, an operation on a module object; import

2037

foo does not require a module object named foo to exist,

2038

rather it requires an (external) definition for a module named

2039

foo somewhere.)

2040

A special member of every module is __dict__.

2041

This is the dictionary containing the module's symbol table.

2042

Modifying this dictionary will actually change the module's symbol

2043

table, but direct assignment to the __dict__ attribute is not

2044

possible (you can write m.__dict__['a'] = 1, which

2045

defines m.a to be 1, but you can't write

2046

m.__dict__ = {}).

2047

Modules built into the interpreter are written like this:

2048

<module 'sys' (built-in)>. If loaded from a file, they are

2049

written as <module 'os' from

2050

'/usr/local/lib/python/os.pyc'>.

2051

Classes and Class Instances Classes and Instances

2052

See chapters 3 and 7 of the Python

2053

Reference Manual for these.

2054

Functions Function objects are created by function definitions. The only

2055

operation on a function object is to call it:

2056

func(argument-list).

2057

There are really two flavors of function objects: built-in functions

2058

and user-defined functions. Both support the same operation (to call

2059

the function), but the implementation is different, hence the

2060

different object types.

2061

The implementation adds two special read-only attributes:

2062

f.func_code is a function's code

2063

objectcode (see below) and f.func_globals is

2064

the dictionary used as the function's global namespace (this is the

2065

same as m.__dict__ where m is the module in which

2066

the function f was defined).

2067

Function objects also support getting and setting arbitrary

2068

attributes, which can be used, for example, to attach metadata to

2069

functions. Regular attribute dot-notation is used to get and set such

2070

attributes. Note that the current implementation only supports

2071

function attributes on user-defined functions. Function attributes on

2072

built-in functions may be supported in the future.

2073

Functions have another special attribute f.__dict__

2074

(a.k.a. f.func_dict) which contains the namespace used to

2075

support function attributes. __dict__ and func_dict can

2076

be accessed directly or set to a dictionary object. A function's

2077

dictionary cannot be deleted.

2078

Methods method

2079

Methods are functions that are called using the attribute notation.

2080

There are two flavors: built-in methods (such as append() on

2081

lists) and class instance methods. Built-in methods are described

2082

with the types that support them.

2083

The implementation adds two special read-only attributes to class

2084

instance methods: m.im_self is the object on which the

2085

method operates, and m.im_func is the function

2086

implementing the method. Calling m(arg-1,

2087

arg-2, ..., arg-n) is completely equivalent to

2088

calling m.im_func(m.im_self, arg-1,

2089

arg-2, ..., arg-n).

2090

Class instance methods are either bound or unbound,

2091

referring to whether the method was accessed through an instance or a

2092

class, respectively. When a method is unbound, its im_self

2093

attribute will be None and if called, an explicit self

2094

object must be passed as the first argument. In this case,

2095

self must be an instance of the unbound method's class (or a

2096

subclass of that class), otherwise a TypeError is raised.

2097

Like function objects, methods objects support getting

2098

arbitrary attributes. However, since method attributes are actually

2099

stored on the underlying function object (meth.im_func),

2100

setting method attributes on either bound or unbound methods is

2101

disallowed. Attempting to set a method attribute results in a

2102

TypeError being raised. In order to set a method attribute,

2103

you need to explicitly set it on the underlying function object:

2104

class C:

2105

def method(self):

2106

pass

2107

c = C()

2108

c.method.im_func.whoami = 'my name is c'

2109

See the Python Reference Manual for more

2110

information.

2111

Code Objects code

2112

Code objects are used by the implementation to represent

2113

``pseudo-compiled'' executable Python code such as a function body.

2114

They differ from function objects because they don't contain a

2115

reference to their global execution environment. Code objects are

2116

returned by the built-in compile() function and can be

2117

extracted from function objects through their func_code

2118

attribute.

2119

compile

2120

(function object attribute){func_code}

2121

A code object can be executed or evaluated by passing it (instead of a

2122

source string) to the exec statement or the built-in

2123

eval() function.

2124

exec

2125

eval

2126

See the Python Reference Manual for more

2127

information.

2128

Type Objects Type objects represent the various object types. An object's type is

2129

accessed by the built-in function type(). There are no special

2130

operations on types. The standard module types defines names

2131

for all standard built-in types.

2132

type

2133

types

2134

Types are written like this: <type 'int'>.

2135

The Null Object This object is returned by functions that don't explicitly return a

2136

value. It supports no special operations. There is exactly one null

2137

object, named None (a built-in name).

2138

It is written as None.

2139

The Ellipsis Object This object is used by extended slice notation (see the

2140

Python Reference Manual). It supports no

2141

special operations. There is exactly one ellipsis object, named

2142

Ellipsis (a built-in name).

2143

It is written as Ellipsis.

2144

Boolean Values

2145

Boolean values are the two constant objects False and

2146

True. They are used to represent truth values (although other

2147

values can also be considered false or true). In numeric contexts

2148

(for example when used as the argument to an arithmetic operator),

2149

they behave like the integers 0 and 1, respectively. The built-in

2150

function bool() can be used to cast any value to a Boolean,

2151

if the value can be interpreted as a truth value (see section Truth

2152

Value Testing above).

2153

They are written as False and True, respectively.

2154

</description>

2155

</group>

2156

2157

</group>

2158

</group>

2159

2160

</group>

2161

</group>

2162

2163

2164

<description>Access system-specific parameters and functions.

2165

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

2166

interpreter and to functions that interact strongly with the interpreter.

2167

It is always available.

2168

{argv}

2169

The list of command line arguments passed to a Python script.

2170

argv[0] is the script name (it is operating system dependent

2171

whether this is a full pathname or not). If the command was

2172

executed using the -c command line option to the

2173

interpreter, argv[0] is set to the string '-c'. If no

2174

script name was passed to the Python interpreter, argv has

2175

zero length.

2176

{byteorder}

2177

An indicator of the native byte order. This will have the value

2178

'big' on big-endian (most-signigicant byte first) platforms,

2179

and 'little' on little-endian (least-significant byte first)

2180

platforms.

2181

New in version 2.0

2182

{builtin_module_names}

2183

A tuple of strings giving the names of all modules that are compiled

2184

into this Python interpreter. (This information is not available in

2185

any other way --- modules.keys() only lists the imported

2186

modules.)

2187

{copyright}

2188

A string containing the copyright pertaining to the Python

2189

interpreter.

2190

{dllhandle}

2191

Integer specifying the handle of the Python DLL.

2192

Availability: Windows.

2193

</description>

2194

2195

<description>If value is not None, this function prints it to

2196

sys.stdout, and saves it in __builtin__._.

2197

sys.displayhook is called on the result of evaluating an

2198

expression entered in an interactive Python session. The display of

2199

these values can be customized by assigning another one-argument

2200

function to sys.displayhook.</description>

2201

2202

2203

2204

2205

<description>This function prints out a given traceback and exception to

2206

sys.stderr.

2207

When an exception is raised and uncaught, the interpreter calls

2208

sys.excepthook with three arguments, the exception class,

2209

exception instance, and a traceback object. In an interactive

2210

session this happens just before control is returned to the prompt;

2211

in a Python program this happens just before the program exits. The

2212

handling of such top-level exceptions can be customized by assigning

2213

another three-argument function to sys.excepthook.</description>

2214

2215

2216

2217

2218

<description>This function returns a tuple of three values that give information

2219

about the exception that is currently being handled. The

2220

information returned is specific both to the current thread and to

2221

the current stack frame. If the current stack frame is not handling

2222

an exception, the information is taken from the calling stack frame,

2223

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

2224

handling an exception. Here, ``handling an exception'' is defined

2225

as ``executing or having executed an except clause.'' For any stack

2226

frame, only information about the most recently handled exception is

2227

accessible.

2228

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

2229

containing three None values is returned. Otherwise, the

2230

values returned are (type, value,

2231

traceback). Their meaning is: type gets the exception

2232

type of the exception being handled (a class object);

2233

value gets the exception parameter (its associated value

2234

or the second argument to raise, which is always a class

2235

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

2236

gets a traceback object (see the Reference Manual) which

2237

encapsulates the call stack at the point where the exception

2238

originally occurred. traceback

2239

If exc_clear() is called, this function will return three

2240

None values until either another exception is raised in the

2241

current thread or the execution stack returns to a frame where

2242

another exception is being handled.

2243

Assigning the traceback return value to a

2244

local variable in a function that is handling an exception will

2245

cause a circular reference. This will prevent anything referenced

2246

by a local variable in the same function or by the traceback from

2247

being garbage collected. Since most functions don't need access to

2248

the traceback, the best solution is to use something like

2249

exctype, value = sys.exc_info()[:2] to extract only the

2250

exception type and value. If you do need the traceback, make sure

2251

to delete it after use (best done with a try

2252

... finally statement) or to call exc_info() in

2253

a function that does not itself handle an exception. Beginning

2254

with Python 2.2, such cycles are automatically reclaimed when garbage

2255

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

2256

efficient to avoid creating cycles.</description>

2257

2258

</element>

2259

2260

2261

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

2262

exception that occured in the current thread. After calling this

2263

function, exc_info() will return three None values until

2264

another exception is raised in the current thread or the execution stack

2265

returns to a frame where another exception is being handled.

2266

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

2267

include logging and error handling systems that report information on the

2268

last or current exception. This function can also be used to try to free

2269

resources and trigger object finalization, though no guarantee is made as

2270

to what objects will be freed, if any.

2271

New in version 2.3</description>

2272

2273

</element>

2274

2275

2276

<description>Exit from Python. This is implemented by raising the

2277

SystemExit exception, so cleanup actions specified by

2278

finally clauses of try statements are honored, and it is

2279

possible to intercept the exit attempt at an outer level. The

2280

optional argument arg can be an integer giving the exit status

2281

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

2282

integer, zero is considered ``successful termination'' and any

2283

nonzero value is considered ``abnormal termination'' by shells and

2284

the like. Most systems require it to be in the range 0-127, and

2285

produce undefined results otherwise. Some systems have a convention

2286

for assigning specific meanings to specific exit codes, but these

2287

are generally underdeveloped; programs generally use 2 for

2288

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

2289

another type of object is passed, None is equivalent to

2290

passing zero, and any other object is printed to sys.stderr

2291

and results in an exit code of 1. In particular,

2292

sys.exit("some error message") is a quick way to exit a

2293

program when an error occurs.</description>

2294

2295

2296

2297

2298

<description>Return the interpreter's ``check interval'';

2299

see setcheckinterval().

2300

New in version 2.3</description>

2301

2302

</element>

2303

2304

2305

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

2306

Unicode implementation.

2307

New in version 2.0</description>

2308

2309

</element>

2310

2311

2312

<description>Return the current value of the flags that are used for

2313

dlopen() calls. The flag constants are defined in the

2314

dl and DLFCN modules.

2315

Availability: .

2316

New in version 2.2</description>

2317

2318

</element>

2319

2320

2321

<description>Return the name of the encoding used to convert Unicode filenames

2322

into system file names, or None if the system default encoding

2323

is used. The result value depends on the operating system:

2324

On Windows 9x, the encoding is ``mbcs''.

2325

On Mac OS X, the encoding is ``utf-8''.

2326

On Unix, the encoding is the user's preference according to the result of nl_langinfo(CODESET), or None if

2327

the nl_langinfo(CODESET) failed.

2328

On Windows NT+, file names are Unicode natively, so no conversion

2329

is performed.

2330

New in version 2.3</description>

2331

2332

</element>

2333

2334

2335

<description>Return the reference count of the object. The count returned

2336

is generally one higher than you might expect, because it includes

2337

the (temporary) reference as an argument to

2338

getrefcount().</description>

2339

2340

2341

2342

2343

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

2344

of the Python interpreter stack. This limit prevents infinite

2345

recursion from causing an overflow of the C stack and crashing

2346

Python. It can be set by setrecursionlimit().</description>

2347

2348

</element>

2349

2350

2351

<description>Return a frame object from the call stack. If optional integer

2352

depth is given, return the frame object that many calls below

2353

the top of the stack. If that is deeper than the call stack,

2354

ValueError is raised. The default for depth is

2355

zero, returning the frame at the top of the call stack.

2356

This function should be used for internal and specialized purposes

2357

only.</description>

2358

2359

2360

2361

2362

<description>Return a tuple containing five components, describing the Windows version currently running. The elements are major, minor, build, platform, and text. text contains

2363

a string while all other values are integers.

2364

platform may be one of the following values:

2365

{}{ 0.7in 0.65in}

2366

[0 (VER_PLATFORM_WIN32s)]

2367

Win32s on Windows 3.1.

2368

[1 (VER_PLATFORM_WIN32_WINDOWS)] Windows 95/98/ME

2369

[2 (VER_PLATFORM_WIN32_NT)] Windows NT/2000/XP

2370

[3 (VER_PLATFORM_WIN32_CE)] Windows CE.

2371

This function wraps the Win32 GetVersionEx() function;

2372

see the Microsoft Documentation for more information about these

2373

fields.

2374

Availability: Windows.

2375

New in version 2.3</description>

2376

2377

</element>

2378

2379

2380

<description>Set the interpreter's ``check interval''. This integer value

2381

determines how often the interpreter checks for periodic things such

2382

as thread switches and signal handlers. The default is 100,

2383

meaning the check is performed every 100 Python virtual instructions.

2384

Setting it to a larger value may increase performance for programs

2385

using threads. Setting it to a value <= 0 checks every

2386

virtual instruction, maximizing responsiveness as well as overhead.</description>

2387

2388

2389

2390

2391

<description>Set the current default string encoding used by the Unicode

2392

implementation. If name does not match any available

2393

encoding, LookupError is raised. This function is only

2394

intended to be used by the site module implementation

2395

and, where needed, by sitecustomize. Once used by the

2396

site module, it is removed from the sys

2397

module's namespace.

2398

% Note that site is not imported if

2399

% the -S option is passed to the interpreter, in which

2400

% case this function will remain available.

2401

New in version 2.0</description>

2402

2403

2404

2405

2406

<description>Set the flags used by the interpreter for dlopen()

2407

calls, such as when the interpreter loads extension modules. Among

2408

other things, this will enable a lazy resolving of symbols when

2409

importing a module, if called as sys.setdlopenflags(0). To

2410

share symbols across extension modules, call as

2411

sys.setdlopenflags(dl.RTLD_NOW | dl.RTLD_GLOBAL). Symbolic

2412

names for the flag modules can be either found in the dl

2413

module, or in the DLFCN module. If DLFCN is not

2414

available, it can be generated from /usr/include/dlfcn.h

2415

using the h2py script.

2416

Availability: .

2417

New in version 2.2</description>

2418

2419

2420

2421

2422

<description>Set the system's profile function,</description>

2423

2424

2425

2426

2427

<description>Set the maximum depth of the Python interpreter stack to

2428

limit. This limit prevents infinite recursion from causing an

2429

overflow of the C stack and crashing Python.

2430

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

2431

to set the limit higher when she has a program that requires deep

2432

recursion and a platform that supports a higher limit. This should

2433

be done with care, because a too-high limit can lead to a crash.</description>

2434

2435

2436

2437

2438

<description>Set the system's trace function,</description>

2439

2440

2441

2442

</group>

2443

2444

<description>Interface to the cycle-detecting garbage collector.

2445

The gc module is only available if the interpreter was built

2446

with the optional cyclic garbage detector (enabled by default). If

2447

this was not enabled, an ImportError is raised by attempts

2448

to import this module.

2449

This module provides an interface to the optional garbage collector. It

2450

provides the ability to disable the collector, tune the collection

2451

frequency, and set debugging options. It also provides access to

2452

unreachable objects that the collector found but cannot free. Since the

2453

collector supplements the reference counting already used in Python, you

2454

can disable the collector if you are sure your program does not create

2455

reference cycles. Automatic collection can be disabled by calling

2456

gc.disable(). To debug a leaking program call

2457

gc.set_debug(gc.DEBUG_LEAK).

2458

The gc module provides the following functions:

2459

</description>

2460

2461

<description>Enable automatic garbage collection.</description>

2462

2463

</element>

2464

2465

2466

<description>Disable automatic garbage collection.</description>

2467

2468

</element>

2469

2470

2471

<description>Returns true if automatic collection is enabled.</description>

2472

2473

</element>

2474

2475

2476

<description>Run a full collection. All generations are examined and the

2477

number of unreachable objects found is returned.</description>

2478

2479

</element>

2480

2481

2482

<description>Set the garbage collection debugging flags.

2483

Debugging information will be written to sys.stderr. See below

2484

for a list of debugging flags which can be combined using bit

2485

operations to control debugging.</description>

2486

2487

2488

2489

2490

<description>Return the debugging flags currently set.</description>

2491

2492

</element>

2493

2494

2495

<description>Returns a list of all objects tracked by the collector, excluding the

2496

list returned.

2497

New in version 2.2</description>

2498

2499

</element>

2500

2501

2502

<description>Set the garbage collection thresholds (the collection frequency).

2503

Setting threshold0 to zero disables collection.

2504

The GC classifies objects into three generations depending on how many

2505

collection sweeps they have survived. New objects are placed in the

2506

youngest generation (generation 0). If an object survives a

2507

collection it is moved into the next older generation. Since

2508

generation 2 is the oldest generation, objects in that

2509

generation remain there after a collection. In order to decide when

2510

to run, the collector keeps track of the number object allocations and

2511

deallocations since the last collection. When the number of

2512

allocations minus the number of deallocations exceeds

2513

threshold0, collection starts. Initially only generation

2514

0 is examined. If generation 0 has been examined more

2515

than threshold1 times since generation 1 has been

2516

examined, then generation 1 is examined as well. Similarly,

2517

threshold2 controls the number of collections of generation

2518

1 before collecting generation 2.</description>

2519

2520

2521

2522

2523

<description>Return the current collection thresholds as a tuple of

2524

(threshold0, threshold1, threshold2).</description>

2525

2526

</element>

2527

2528

2529

<description>Return the list of objects that directly refer to any of objs. This

2530

function will only locate those containers which support garbage

2531

collection; extension types which do refer to other objects but do not

2532

support garbage collection will not be found.

2533

Note that objects which have already been dereferenced, but which live

2534

in cycles and have not yet been collected by the garbage collector can

2535

be listed among the resulting referrers. To get only currently live

2536

objects, call collect() before calling

2537

get_referrers().

2538

Care must be taken when using objects returned by

2539

get_referrers() because some of them could still be under

2540

construction and hence in a temporarily invalid state. Avoid using

2541

get_referrers() for any purpose other than debugging.

2542

New in version 2.2</description>

2543

2544

2545

2546

2547

<description>Return a list of objects directly referred to by any of the arguments.

2548

The referents returned are those objects visited by the arguments'

2549

C-level tp_traverse methods (if any), and may not be all

2550

objects actually directly reachable. tp_traverse methods

2551

are supported only by objects that support garbage collection, and are

2552

only required to visit objects that may be involved in a cycle. So,

2553

for example, if an integer is directly reachable from an argument, that

2554

integer object may or may not appear in the result list.

2555

New in version 2.3</description>

2556

2557

2558

2559

</group>

2560

2561

<description>Support for weak references and weak dictionaries.

2562

New in version 2.1

2563

The weakref module allows the Python programmer to create

2564

weak references to objects.

2565

In the following, the term referent means the

2566

object which is referred to by a weak reference.

2567

A weak reference to an object is not enough to keep the object alive:

2568

when the only remaining references to a referent are weak references,

2569

garbage collection is free to destroy the referent and reuse its memory

2570

for something else. A primary use for weak references is to implement

2571

caches or mappings holding large objects, where it's desired that a

2572

large object not be kept alive solely because it appears in a cache or

2573

mapping. For example, if you have a number of large binary image objects,

2574

you may wish to associate a name with each. If you used a Python

2575

dictionary to map names to images, or images to names, the image objects

2576

would remain alive just because they appeared as values or keys in the

2577

dictionaries. The WeakKeyDictionary and

2578

WeakValueDictionary classes supplied by the weakref

2579

module are an alternative, using weak references to construct mappings

2580

that don't keep objects alive solely because they appear in the mapping

2581

objects. If, for example, an image object is a value in a

2582

WeakValueDictionary, then when the last remaining

2583

references to that image object are the weak references held by weak

2584

mappings, garbage collection can reclaim the object, and its corresponding

2585

entries in weak mappings are simply deleted.

2586

WeakKeyDictionary and WeakValueDictionary use weak

2587

references in their implementation, setting up callback functions on

2588

the weak references that notify the weak dictionaries when a key or value

2589

has been reclaimed by garbage collection. Most programs should find that

2590

using one of these weak dictionary types is all they need -- it's

2591

not usually necessary to create your own weak references directly. The

2592

low-level machinery used by the weak dictionary implementations is exposed

2593

by the weakref module for the benefit of advanced uses.

2594

Not all objects can be weakly referenced; those objects which can

2595

include class instances, functions written in Python (but not in C),

2596

and methods (both bound and unbound). Extension types can easily

2597

be made to support weak references; see section weakref-extension,

2598

``Weak References in Extension Types,'' for more information.

2599

</description>

2600

2601

<description>Return a weak reference to object. The original object can be

2602

retrieved by calling the reference object if the referent is still

2603

alive; if the referent is no longer alive, calling the reference

2604

object will cause None to be returned. If callback is

2605

provided, it will be called when the object is about to be

2606

finalized; the weak reference object will be passed as the only

2607

parameter to the callback; the referent will no longer be available.

2608

It is allowable for many weak references to be constructed for the

2609

same object. Callbacks registered for each weak reference will be

2610

called from the most recently registered callback to the oldest

2611

registered callback.

2612

Exceptions raised by the callback will be noted on the standard

2613

error output, but cannot be propagated; they are handled in exactly

2614

the same way as exceptions raised from an object's

2615

__del__() method.

2616

Weak references are hashable if the object is hashable. They

2617

will maintain their hash value even after the object was

2618

deleted. If hash() is called the first time only after

2619

the object was deleted, the call will raise

2620

TypeError.

2621

Weak references support tests for equality, but not ordering. If

2622

the referents are still alive, two references have the same

2623

equality relationship as their referents (regardless of the

2624

callback). If either referent has been deleted, the

2625

references are equal only if the reference objects are the same

2626

object.</description>

2627

2628

2629

2630

2631

<description>Return a proxy to object which uses a weak reference. This

2632

supports use of the proxy in most contexts instead of requiring the

2633

explicit dereferencing used with weak reference objects. The

2634

returned object will have a type of either ProxyType or

2635

CallableProxyType, depending on whether object is

2636

callable. Proxy objects are not hashable regardless of the

2637

referent; this avoids a number of problems related to their

2638

fundamentally mutable nature, and prevent their use as dictionary

2639

keys. callback is the same as the parameter of the same name

2640

to the ref() function.</description>

2641

2642

2643

2644

2645

<description>Return the number of weak references and proxies which refer to

2646

object.</description>

2647

2648

2649

2650

2651

<description>Return a list of all weak reference and proxy objects which refer to

2652

object.</description>

2653

2654

2655

2656

2657

<description>Mapping class that references keys weakly. Entries in the

2658

dictionary will be discarded when there is no longer a strong

2659

reference to the key. This can be used to associate additional data

2660

with an object owned by other parts of an application without adding

2661

attributes to those objects. This can be especially useful with

2662

objects that override attribute accesses.

2663

Caution: Because a WeakKeyDictionary is built on top

2664

of a Python dictionary, it must not change size when iterating

2665

over it. This can be difficult to ensure for a

2666

WeakKeyDictionary because actions performed by the

2667

program during iteration may cause items in the dictionary

2668

to vanish "by magic" (as a side effect of garbage collection).</description>

2669

2670

2671

2672

2673

<description>Mapping class that references values weakly. Entries in the

2674

dictionary will be discarded when no strong reference to the value

2675

exists any more.

2676

Caution: Because a WeakValueDictionary is built on top

2677

of a Python dictionary, it must not change size when iterating

2678

over it. This can be difficult to ensure for a

2679

WeakValueDictionary because actions performed by the

2680

program during iteration may cause items in the dictionary

2681

to vanish "by magic" (as a side effect of garbage collection).</description>

2682

2683

2684

2685

2686

<description>Weak reference objects have no attributes or methods, but do allow the

2687

referent to be obtained, if it still exists, by calling it:

2688

>>> import weakref

2689

>>> class Object:

2690

... pass

2691

...

2692

>>> o = Object()

2693

>>> r = weakref.ref(o)

2694

>>> o2 = r()

2695

>>> o is o2

2696

True

2697

If the referent no longer exists, calling the reference object returns

2698

None:

2699

>>> del o, o2

2700

>>> print r()

2701

None

2702

Testing that a weak reference object is still live should be done

2703

using the expression ref() is not None. Normally,

2704

application code that needs to use a reference object should follow

2705

this pattern:

2706

# r is a weak reference object

2707

o = r()

2708

if o is None:

2709

# referent has been garbage collected

2710

print "Object has been allocated; can't frobnicate."

2711

else:

2712

print "Object is still live!"

2713

o.do_something_useful()

2714

Using a separate test for ``liveness'' creates race conditions in

2715

threaded applications; another thread can cause a weak reference to

2716

become invalidated before the weak reference is called; the

2717

idiom shown above is safe in threaded applications as well as

2718

single-threaded applications.

2719

</description>

2720

</group>

2721

2722

<description>This simple example shows how an application can use objects IDs to

2723

retrieve objects that it has seen before. The IDs of the objects can

2724

then be used in other data structures without forcing the objects to

2725

remain alive, but the objects can still be retrieved by ID if they

2726

do.

2727

% Example contributed by Tim Peters <tim_one@msn.com>.

2728

import weakref

2729

_id2obj_dict = weakref.WeakValueDictionary()

2730

def remember(obj):

2731

oid = id(obj)

2732

_id2obj_dict[oid] = obj

2733

return oid

2734

def id2obj(oid):

2735

return _id2obj_dict[oid]

2736

</description>

2737

</group>

2738

2739

</group>

2740

</group>

2741

2742

<description>Unix

2743

Provide control for floating point exception handling.

2744

Most computers carry out floating point operations</description>

2745

2746

<description>Turn on the generation of SIGFPE,

2747

and set up an appropriate signal handler.</description>

2748

2749

</element>

2750

2751

2752

<description>Reset default handling of floating point exceptions.</description>

2753

2754

</element>

2755

2756

2757

<description>The following example demonstrates how to start up and test operation of

2758

the fpectl module.

2759

>>> import fpectl

2760

>>> import fpetest

2761

>>> fpectl.turnon_sigfpe()

2762

>>> fpetest.test()

2763

overflow PASS

2764

FloatingPointError: Overflow

2765

div by 0 PASS

2766

FloatingPointError: Division by zero

2767

[ more output from test elided ]

2768

>>> import math

2769

>>> math.exp(1000)

2770

Traceback (most recent call last):

2771

File "<stdin>", line 1, in ?

2772

FloatingPointError: in math_1

2773

</description>

2774

</group>

2775

2776

</group>

2777

</group>

2778

2779

<description>Register and execute cleanup functions.

2780

New in version 2.0

2781

The atexit module defines a single function to register

2782

cleanup functions. Functions thus registered are automatically

2783

executed upon normal interpreter termination.

2784

Note: the functions registered via this module are not called when the program is killed by a

2785

signal, when a Python fatal internal error is detected, or when

2786

os._exit() is called.

2787

This is an alternate interface to the functionality provided by the

2788

sys.exitfunc variable.

2789

(in sys){exitfunc}

2790

Note: This module is unlikely to work correctly when used with other code

2791

that sets sys.exitfunc. In particular, other core Python modules are

2792

free to use atexit without the programmer's knowledge. Authors who

2793

use sys.exitfunc should convert their code to use

2794

atexit instead. The simplest way to convert code that sets

2795

sys.exitfunc is to import atexit and register the function

2796

that had been bound to sys.exitfunc.

2797

</description>

2798

2799

<description>Register func as a function to be executed at termination. Any

2800

optional arguments that are to be passed to func must be passed

2801

as arguments to register().

2802

At normal program termination (for instance, if

2803

sys.exit() is called or the main module's execution

2804

completes), all functions registered are called in last in, first out

2805

order. The assumption is that lower level modules will normally be

2806

imported before higher level modules and thus must be cleaned up

2807

later.</description>

2808

2809

2810

2811

2812

</group>

2813

</group>

2814

2815

</group>

2816

2817

<description>Class wrapper for dictionary objects.

2818

This module is available for backward compatibility only. If

2819

you are writing code that does not need to work with versions of

2820

Python earlier than Python 2.2, please consider subclassing directly

2821

from the built-in dict type.

2822

This module defines a class that acts as a wrapper around

2823

dictionary objects. It is a useful base class for

2824

your own dictionary-like classes, which can inherit from

2825

them and override existing methods or add new ones. In this way one

2826

can add new behaviors to dictionaries.

2827

The module also defines a mixin defining all dictionary methods for

2828

classes that already have a minimum mapping interface. This greatly

2829

simplifies writing classes that need to be substitutable for

2830

dictionaries (such as the shelve module).

2831

The UserDict module defines the UserDict class

2832

and DictMixin:

2833

</description>

2834

2835

<description>Class that simulates a dictionary. The instance's

2836

contents are kept in a regular dictionary, which is accessible via the

2837

data attribute of UserDict instances. If

2838

initialdata is provided, data is initialized with its

2839

contents; note that a reference to initialdata will not be kept, allowing it be used for other purposes.</description>

2840

2841

2842

2843

2844

<description>Mixin defining all dictionary methods for classes that already have

2845

a minimum dictionary interface including __getitem__(),

2846

__setitem__(), __delitem__(), and keys().

2847

This mixin should be used as a superclass. Adding each of the

2848

above methods adds progressively more functionality. For instance,

2849

defining all but __delitem__ will preclude only pop

2850

and popitem from the full interface.

2851

In addition to the four base methods, progessively more efficiency

2852

comes with defining __contains__(), __iter__(), and

2853

iteritems().

2854

Since the mixin has no knowledge of the subclass constructor, it

2855

does not define __init__() or copy().</description>

2856

2857

</element>

2858

2859

2860

<description>Class that simulates a list. The instance's

2861

contents are kept in a regular list, which is accessible via the

2862

data attribute of UserList instances. The instance's

2863

contents are initially set to a copy of list, defaulting to the

2864

empty list []. list can be either a regular Python list,

2865

or an instance of UserList (or a subclass).</description>

2866

2867

2868

2869

2870

<description>Class that simulates a string or a Unicode string

2871

object. The instance's content is kept in a regular string or Unicode

2872

string object, which is accessible via the data attribute of

2873

UserString instances. The instance's contents are initially

2874

set to a copy of sequence. sequence can be either a

2875

regular Python string or Unicode string, an instance of

2876

UserString (or a subclass) or an arbitrary sequence which can

2877

be converted into a string using the built-in str() function.</description>

2878

2879

2880

2881

2882

<description>This class is derived from the UserString above and redefines

2883

strings to be mutable. Mutable strings can't be used as

2884

dictionary keys, because dictionaries require immutable objects as

2885

keys. The main intention of this class is to serve as an educational

2886

example for inheritance and necessity to remove (override) the

2887

__hash__() method in order to trap attempts to use a

2888

mutable object as dictionary key, which would be otherwise very

2889

error prone and hard to track down.</description>

2890

2891

2892

2893

</group>

2894

2895

<description>All Python's standard operators as built-in functions.

2896

The operator module exports a set of functions implemented in C

2897

corresponding to the intrinsic operators of Python. For example,

2898

operator.add(x, y) is equivalent to the expression x+y. The

2899

function names are those used for special class methods; variants without

2900

leading and trailing __ are also provided for convenience.

2901

The functions fall into categories that perform object comparisons,

2902

logical operations, mathematical operations, sequence operations, and

2903

abstract type tests.

2904

The object comparison functions are useful for all objects, and are

2905

named after the rich comparison operators they support:

2906

</description>

2907

2908

<description>le{a, b}

2909

eq{a, b}

2910

ne{a, b}

2911

ge{a, b}

2912

gt{a, b}

2913

__lt__{a, b}

2914

__le__{a, b}

2915

__eq__{a, b}

2916

__ne__{a, b}

2917

__ge__{a, b}

2918

__gt__{a, b}

2919

Perform ``rich comparisons'' between a and b. Specifically,

2920

lt(a, b) is equivalent to a < b,

2921

le(a, b) is equivalent to a <= b,

2922

eq(a, b) is equivalent to a == b,

2923

ne(a, b) is equivalent to a != b,

2924

gt(a, b) is equivalent to a > b

2925

and

2926

ge(a, b) is equivalent to a >= b.

2927

Note that unlike the built-in cmp(), these functions can

2928

return any value, which may or may not be interpretable as a Boolean

2929

value. See the Python Reference Manual

2930

for more informations about rich comparisons.

2931

New in version 2.2</description>

2932

2933

2934

2935

2936

<description>__not__{o}

2937

Return the outcome of not o. (Note that there is no

2938

__not__() method for object instances; only the interpreter

2939

core defines this operation. The result is affected by the

2940

__nonzero__() and __len__() methods.)</description>

2941

2942

2943

2944

2945

<description>Return True if o is true, and False

2946

otherwise. This is equivalent to using the bool

2947

constructor.</description>

2948

2949

2950

2951

2952

<description>Return a is b. Tests object identity.

2953

New in version 2.3</description>

2954

2955

2956

2957

2958

<description>Return a is not b. Tests object identity.

2959

New in version 2.3</description>

2960

2961

2962

2963

2964

<description>__abs__{o}

2965

Return the absolute value of o.</description>

2966

2967

2968

2969

2970

<description>__add__{a, b}

2971

Return a + b, for a and b numbers.</description>

2972

2973

2974

2975

2976

<description>__and__{a, b}

2977

Return the bitwise and of a and b.</description>

2978

2979

2980

2981

2982

<description>__div__{a, b}

2983

Return a / b when __future__.division is not

2984

in effect. This is also known as ``classic'' division.</description>

2985

2986

2987

2988

2989

<description>__floordiv__{a, b}

2990

Return a // b.

2991

New in version 2.2</description>

2992

2993

2994

2995

2996

<description>invert{o}

2997

__inv__{o}

2998

__invert__{o}

2999

Return the bitwise inverse of the number o. This is equivalent

3000

to o. The names invert() and

3001

__invert__() were added in Python 2.0.</description>

3002

3003

3004

3005

3006

<description>__lshift__{a, b}

3007

Return a shifted left by b.</description>

3008

3009

3010

3011

3012

<description>__mod__{a, b}

3013

Return a % b.</description>

3014

3015

3016

3017

3018

<description>__mul__{a, b}

3019

Return a * b, for a and b numbers.</description>

3020

3021

3022

3023

3024

<description>__neg__{o}

3025

Return o negated.</description>

3026

3027

3028

3029

3030

<description>__or__{a, b}

3031

Return the bitwise or of a and b.</description>

3032

3033

3034

3035

3036

<description>__pos__{o}

3037

Return o positive.</description>

3038

3039

3040

3041

3042

<description>__pow__{a, b}

3043

Return a ** b, for a and b numbers.

3044

New in version 2.3</description>

3045

3046

3047

3048

3049

<description>__rshift__{a, b}

3050

Return a shifted right by b.</description>

3051

3052

3053

3054

3055

<description>__sub__{a, b}

3056

Return a - b.</description>

3057

3058

3059

3060

3061

<description>__truediv__{a, b}

3062

Return a / b when __future__.division is in

3063

effect. This is also known as division.

3064

New in version 2.2</description>

3065

3066

3067

3068

3069

<description>__xor__{a, b}

3070

Return the bitwise exclusive or of a and b.</description>

3071

3072

3073

3074

3075

<description>__concat__{a, b}

3076

Return a + b for a and b sequences.</description>

3077

3078

3079

3080

3081

<description>__contains__{a, b}

3082

Return the outcome of the test b in a.

3083

Note the reversed operands. The name __contains__() was

3084

added in Python 2.0.</description>

3085

3086

3087

3088

3089

<description>Return the number of occurrences of b in a.</description>

3090

3091

3092

3093

3094

<description>__delitem__{a, b}

3095

Remove the value of a at index b.</description>

3096

3097

3098

3099

3100

<description>__delslice__{a, b, c}

3101

Delete the slice of a from index b to index c-1.</description>

3102

3103

3104

3105

3106

<description>__getitem__{a, b}

3107

Return the value of a at index b.</description>

3108

3109

3110

3111

3112

<description>__getslice__{a, b, c}

3113

Return the slice of a from index b to index c-1.</description>

3114

3115

3116

3117

3118

<description>Return the index of the first of occurrence of b in a.</description>

3119

3120

3121

3122

3123

<description>__repeat__{a, b}

3124

Return a * b where a is a sequence and

3125

b is an integer.</description>

3126

3127

3128

3129

3130

<description>2.0{Use contains() instead.}

3131

Alias for contains().</description>

3132

3133

3134

3135

3136

<description>__setitem__{a, b, c}

3137

Set the value of a at index b to c.</description>

3138

3139

3140

3141

3142

<description>__setslice__{a, b, c, v}

3143

Set the slice of a from index b to index c-1 to the

3144

sequence v.</description>

3145

3146

3147

3148

3149

<description>2.0{Use the callable() built-in function instead.}

3150

Returns true if the object o can be called like a function,

3151

otherwise it returns false. True is returned for functions, bound and

3152

unbound methods, class objects, and instance objects which support the

3153

__call__() method.</description>

3154

3155

3156

3157

3158

<description>Returns true if the object o supports the mapping interface.

3159

This is true for dictionaries and all instance objects.

3160

There is no reliable way to test if an instance

3161

supports the complete mapping protocol since the interface itself is

3162

ill-defined. This makes this test less useful than it otherwise might

3163

be.</description>

3164

3165

3166

3167

3168

<description>Returns true if the object o represents a number. This is true

3169

for all numeric types implemented in C, and for all instance objects.

3170

There is no reliable way to test if an instance

3171

supports the complete numeric interface since the interface itself is

3172

ill-defined. This makes this test less useful than it otherwise might

3173

be.</description>

3174

3175

3176

3177

3178

<description>Returns true if the object o supports the sequence protocol.

3179

This returns true for all objects which define sequence methods in C,

3180

and for all instance objects. There is no reliable

3181

way to test if an instance supports the complete sequence interface

3182

since the interface itself is ill-defined. This makes this test less

3183

useful than it otherwise might be.</description>

3184

3185

3186

3187

3188

<description>Return a callable object that fetches attr from its operand.

3189

After, f=attrgetter('name'), the call f(b) returns

3190

b.name.

3191

New in version 2.4</description>

3192

3193

3194

3195

3196

<description>Return a callable object that fetches item from its operand.

3197

After, f=itemgetter(2), the call f(b) returns

3198

b[2].

3199

New in version 2.4</description>

3200

3201

3202

3203

3204

</group>

3205

</group>

3206

3207

<description>Extract information and source code from live objects.

3208

New in version 2.1

3209

The inspect module provides several useful functions

3210

to help get information about live objects such as modules,

3211

classes, methods, functions, tracebacks, frame objects, and

3212

code objects. For example, it can help you examine the

3213

contents of a class, retrieve the source code of a method,

3214

extract and format the argument list for a function, or

3215

get all the information you need to display a detailed traceback.

3216

There are four main kinds of services provided by this module:

3217

type checking, getting source code, inspecting classes

3218

and functions, and examining the interpreter stack.

3219

</description>

3220

3221

<description>The getmembers() function retrieves the members

3222

of an object such as a class or module.

3223

The eleven functions whose names begin with ``is'' are mainly

3224

provided as convenient choices for the second argument to

3225

getmembers(). They also help you determine when

3226

you can expect to find the following special attributes:

3227

{c|l|l|c}{}{Type}{Attribute}{Description}{Notes}

3228

module{__doc__}{documentation string}{}

3229

{__file__}{filename (missing for built-in modules)}{}

3230

class{__doc__}{documentation string}{}

3231

{__module__}{name of module in which this class was defined}{}

3232

method{__doc__}{documentation string}{}

3233

{__name__}{name with which this method was defined}{}

3234

{im_class}{class object that asked for this method}{(1)}

3235

{im_func}{function object containing implementation of method}{}

3236

{im_self}{instance to which this method is bound, or None}{}

3237

function{__doc__}{documentation string}{}

3238

{__name__}{name with which this function was defined}{}

3239

{func_code}{code object containing compiled function bytecode}{}

3240

{func_defaults}{tuple of any default values for arguments}{}

3241

{func_doc}{(same as __doc__)}{}

3242

{func_globals}{global namespace in which this function was defined}{}

3243

{func_name}{(same as __name__)}{}

3244

traceback{tb_frame}{frame object at this level}{}

3245

{tb_lasti}{index of last attempted instruction in bytecode}{}

3246

{tb_lineno}{current line number in Python source code}{}

3247

{tb_next}{next inner traceback object (called by this level)}{}

3248

frame{f_back}{next outer frame object (this frame's caller)}{}

3249

{f_builtins}{built-in namespace seen by this frame}{}

3250

{f_code}{code object being executed in this frame}{}

3251

{f_exc_traceback}{traceback if raised in this frame, or None}{}

3252

{f_exc_type}{exception type if raised in this frame, or None}{}

3253

{f_exc_value}{exception value if raised in this frame, or None}{}

3254

{f_globals}{global namespace seen by this frame}{}

3255

{f_lasti}{index of last attempted instruction in bytecode}{}

3256

{f_lineno}{current line number in Python source code}{}

3257

{f_locals}{local namespace seen by this frame}{}

3258

{f_restricted}{0 or 1 if frame is in restricted execution mode}{}

3259

{f_trace}{tracing function for this frame, or None}{}

3260

code{co_argcount}{number of arguments (not including * or ** args)}{}

3261

{co_code}{string of raw compiled bytecode}{}

3262

{co_consts}{tuple of constants used in the bytecode}{}

3263

{co_filename}{name of file in which this code object was created}{}

3264

{co_firstlineno}{number of first line in Python source code}{}

3265

{co_flags}{bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg}{}

3266

{co_lnotab}{encoded mapping of line numbers to bytecode indices}{}

3267

{co_name}{name with which this code object was defined}{}

3268

{co_names}{tuple of names of local variables}{}

3269

{co_nlocals}{number of local variables}{}

3270

{co_stacksize}{virtual machine stack space required}{}

3271

{co_varnames}{tuple of names of arguments and local variables}{}

3272

builtin{__doc__}{documentation string}{}

3273

{__name__}{original name of this function or method}{}

3274

{__self__}{instance to which a method is bound, or None}{}

3275

Note:

3276

[(1)]

3277

Changed in version 2.2: im_class used to refer to the class that

3278

defined the method

3279

</description>

3280

3281

<description>Return all the members of an object in a list of (name, value) pairs

3282

sorted by name. If the optional predicate argument is supplied,

3283

only members for which the predicate returns a true value are included.</description>

3284

3285

3286

3287

3288

<description>Return a tuple of values that describe how Python will interpret the

3289

file identified by path if it is a module, or None if

3290

it would not be identified as a module. The return tuple is

3291

(name, suffix, mode, mtype), where

3292

name is the name of the module without the name of any

3293

enclosing package, suffix is the trailing part of the file

3294

name (which may not be a dot-delimited extension), mode is the

3295

open() mode that would be used ('r' or

3296

'rb'), and mtype is an integer giving the type of the

3297

module. mtype will have a value which can be compared to the

3298

constants defined in the imp module; see the

3299

documentation for that module for more information on module types.</description>

3300

3301

3302

3303

3304

<description>Return the name of the module named by the file path, without

3305

including the names of enclosing packages. This uses the same

3306

algortihm as the interpreter uses when searching for modules. If

3307

the name cannot be matched according to the interpreter's rules,

3308

None is returned.</description>

3309

3310

3311

3312

3313

<description>Return true if the object is a module.</description>

3314

3315

3316

3317

3318

<description>Return true if the object is a class.</description>

3319

3320

3321

3322

3323

<description>Return true if the object is a method.</description>

3324

3325

3326

3327

3328

<description>Return true if the object is a Python function or unnamed (lambda) function.</description>

3329

3330

3331

3332

3333

<description>Return true if the object is a traceback.</description>

3334

3335

3336

3337

3338

<description>Return true if the object is a frame.</description>

3339

3340

3341

3342

3343

<description>Return true if the object is a code.</description>

3344

3345

3346

3347

3348

<description>Return true if the object is a built-in function.</description>

3349

3350

3351

3352

3353

<description>Return true if the object is a user-defined or built-in function or method.</description>

3354

3355

3356

3357

3358

<description>Return true if the object is a method descriptor, but not if ismethod() or isclass() or isfunction() are true.

3359

This is new as of Python 2.2, and, for example, is true of int.__add__.

3360

An object passing this test has a __get__ attribute but not a __set__

3361

attribute, but beyond that the set of attributes varies. __name__ is

3362

usually sensible, and __doc__ often is.

3363

Methods implemented via descriptors that also pass one of the other

3364

tests return false from the ismethoddescriptor() test, simply because

3365

the other tests promise more -- you can, e.g., count on having the

3366

im_func attribute (etc) when an object passes ismethod().</description>

3367

3368

3369

3370

3371

<description>Return true if the object is a data descriptor.

3372

Data descriptors have both a __get__ and a __set__ attribute. Examples are

3373

properties (defined in Python) and getsets and members (defined in C).

3374

Typically, data descriptors will also have __name__ and __doc__ attributes (properties, getsets, and members have both of these attributes), but this is not guaranteed.

3375

New in version 2.3</description>

3376

3377

3378

3379

</group>

3380

3381

3382

<description>Get the documentation string for an object.

3383

All tabs are expanded to spaces. To clean up docstrings that are

3384

indented to line up with blocks of code, any whitespace than can be

3385

uniformly removed from the second line onwards is removed.</description>

3386

3387

3388

3389

3390

<description>Return in a single string any lines of comments immediately preceding

3391

the object's source code (for a class, function, or method), or at the

3392

top of the Python source file (if the object is a module).</description>

3393

3394

3395

3396

3397

<description>Return the name of the (text or binary) file in which an object was

3398

defined. This will fail with a TypeError if the object

3399

is a built-in module, class, or function.</description>

3400

3401

3402

3403

3404

<description>Try to guess which module an object was defined in.</description>

3405

3406

3407

3408

3409

<description>Return the name of the Python source file in which an object was

3410

defined. This will fail with a TypeError if the object

3411

is a built-in module, class, or function.</description>

3412

3413

3414

3415

3416

<description>Return a list of source lines and starting line number for an object.

3417

The argument may be a module, class, method, function, traceback, frame,

3418

or code object. The source code is returned as a list of the lines

3419

corresponding to the object and the line number indicates where in the

3420

original source file the first line of code was found. An

3421

IOError is raised if the source code cannot be retrieved.</description>

3422

3423

3424

3425

3426

<description>Return the text of the source code for an object.

3427

The argument may be a module, class, method, function, traceback, frame,

3428

or code object. The source code is returned as a single string. An

3429

IOError is raised if the source code cannot be retrieved.</description>

3430

3431

3432

3433

</group>

3434

3435

3436

<description>Arrange the given list of classes into a hierarchy of nested lists.

3437

Where a nested list appears, it contains classes derived from the class

3438

whose entry immediately precedes the list. Each entry is a 2-tuple

3439

containing a class and a tuple of its base classes. If the unique

3440

argument is true, exactly one entry appears in the returned structure

3441

for each class in the given list. Otherwise, classes using multiple

3442

inheritance and their descendants will appear multiple times.</description>

3443

3444

3445

3446

3447

<description>Get the names and default values of a function's arguments.

3448

A tuple of four things is returned: (args,

3449

varargs, varkw, defaults).

3450

args is a list of the argument names (it may contain nested lists).

3451

varargs and varkw are the names of the * and

3452

** arguments or None.

3453

defaults is a tuple of default argument values; if this tuple

3454

has n elements, they correspond to the last n elements

3455

listed in args.</description>

3456

3457

3458

3459

3460

<description>Get information about arguments passed into a particular frame.

3461

A tuple of four things is returned: (args,

3462

varargs, varkw, locals).

3463

args is a list of the argument names (it may contain nested

3464

lists).

3465

varargs and varkw are the names of the * and

3466

** arguments or None.

3467

locals is the locals dictionary of the given frame.</description>

3468

3469

3470

3471

3472

<description>Format a pretty argument spec from the four values returned by

3473

getargspec(). The other four arguments are the

3474

corresponding optional formatting functions that are called to turn

3475

names and values into strings.</description>

3476

3477

3478

3479

3480

<description>Format a pretty argument spec from the four values returned by

3481

getargvalues(). The other four arguments are the

3482

corresponding optional formatting functions that are called to turn

3483

names and values into strings.</description>

3484

3485

3486

3487

3488

<description>Return a tuple of class cls's base classes, including cls, in

3489

method resolution order. No class appears more than once in this tuple.

3490

Note that the method resolution order depends on cls's type. Unless a

3491

very peculiar user-defined metatype is in use, cls will be the first

3492

element of the tuple.</description>

3493

3494

3495

3496

</group>

3497

3498

<description>When the following functions return ``frame records,'' each record

3499

is a tuple of six items: the frame object, the filename,

3500

the line number of the current line, the function name, a list of

3501

lines of context from the source code, and the index of the current

3502

line within that list.

3503

The optional context argument specifies the number of lines of

3504

context to return, which are centered around the current line.

3505

Keeping references to frame objects, as found in

3506

the first element of the frame records these functions return, can

3507

cause your program to create reference cycles. Once a reference cycle

3508

has been created, the lifespan of all objects which can be accessed

3509

from the objects which form the cycle can become much longer even if

3510

Python's optional cycle detector is enabled. If such cycles must be

3511

created, it is important to ensure they are explicitly broken to avoid

3512

the delayed destruction of objects and increased memory consumption

3513

which occurs.

3514

</description>

3515

3516

<description>Get information about a frame or traceback object. A 5-tuple

3517

is returned, the last five elements of the frame's frame record.

3518

The optional second argument specifies the number of lines of context

3519

to return, which are centered around the current line.</description>

3520

3521

3522

3523

3524

<description>Get a list of frame records for a frame and all higher (calling)

3525

frames.</description>

3526

3527

3528

3529

3530

<description>Get a list of frame records for a traceback's frame and all lower

3531

frames.</description>

3532

3533

3534

3535

3536

<description>Return the frame object for the caller's stack frame.</description>

3537

3538

</element>

3539

3540

3541

<description>Return a list of frame records for the stack above the caller's

3542

frame.</description>

3543

3544

3545

3546

3547

<description>Return a list of frame records for the stack below the current

3548

exception.</description>

3549

3550

3551

3552

</group>

3553

</group>

3554

3555

<description>Print or retrieve a stack traceback.

3556

This module provides a standard interface to extract, format and print

3557

stack traces of Python programs. It exactly mimics the behavior of

3558

the Python interpreter when it prints a stack trace. This is useful

3559

when you want to print stack traces under program control, such as in a

3560

``wrapper'' around the interpreter.

3561

The module uses traceback objects --- this is the object type that is

3562

stored in the variables sys.exc_traceback (deprecated) and

3563

sys.last_traceback and returned as the third item from

3564

sys.exc_info().

3565

traceback

3566

The module defines the following functions:

3567

</description>

3568

3569

<description>Print up to limit stack trace entries from traceback. If

3570

limit is omitted or None, all entries are printed.

3571

If file is omitted or None, the output goes to

3572

sys.stderr; otherwise it should be an open file or file-like

3573

object to receive the output.</description>

3574

3575

3576

3577

3578

<description>Print exception information and up to limit stack trace entries

3579

from traceback to file.

3580

This differs from print_tb() in the

3581

following ways: (1) if traceback is not None, it prints a

3582

header Traceback (most recent call last):; (2) it prints the

3583

exception type and value after the stack trace; (3) if

3584

type is SyntaxError and value has the

3585

appropriate format, it prints the line where the syntax error occurred

3586

with a caret indicating the approximate position of the error.</description>

3587

3588

3589

3590

3591

<description>This is a shorthand for print_exception(sys.exc_type,

3592

sys.exc_value, sys.exc_traceback, limit, file). (In

3593

fact, it uses sys.exc_info() to retrieve the same

3594

information in a thread-safe way instead of using the deprecated

3595

variables.)</description>

3596

3597

3598

3599

3600

<description>This is like print_exc(limit) but returns a string

3601

instead of printing to a file.

3602

New in version 2.4</description>

3603

3604

3605

3606

3607

<description>This is a shorthand for print_exception(sys.last_type,

3608

sys.last_value, sys.last_traceback, limit, file).</description>

3609

3610

3611

3612

3613

<description>This function prints a stack trace from its invocation point. The

3614

optional f argument can be used to specify an alternate stack

3615

frame to start. The optional limit and file arguments have the

3616

same meaning as for print_exception().</description>

3617

3618

3619

3620

3621

<description>Return a list of up to limit ``pre-processed'' stack trace

3622

entries extracted from the traceback object traceback. It is

3623

useful for alternate formatting of stack traces. If limit is

3624

omitted or None, all entries are extracted. A

3625

``pre-processed'' stack trace entry is a quadruple (filename,

3626

line number, function name, text) representing

3627

the information that is usually printed for a stack trace. The

3628

text is a string with leading and trailing whitespace

3629

stripped; if the source is not available it is None.</description>

3630

3631

3632

3633

3634

<description>Extract the raw traceback from the current stack frame. The return

3635

value has the same format as for extract_tb(). The

3636

optional f and limit arguments have the same meaning as

3637

for print_stack().</description>

3638

3639

3640

3641

3642

<description>Given a list of tuples as returned by extract_tb() or

3643

extract_stack(), return a list of strings ready for

3644

printing. Each string in the resulting list corresponds to the item

3645

with the same index in the argument list. Each string ends in a

3646

newline; the strings may contain internal newlines as well, for those

3647

items whose source text line is not None.</description>

3648

3649

3650

3651

3652

<description>Format the exception part of a traceback. The arguments are the

3653

exception type and value such as given by sys.last_type and

3654

sys.last_value. The return value is a list of strings, each

3655

ending in a newline. Normally, the list contains a single string;

3656

however, for SyntaxError exceptions, it contains several

3657

lines that (when printed) display detailed information about where the

3658

syntax error occurred. The message indicating which exception

3659

occurred is the always last string in the list.</description>

3660

3661

3662

3663

3664

<description>Format a stack trace and the exception information. The arguments have the same meaning as the corresponding arguments to

3665

print_exception(). The return value is a list of strings,

3666

each ending in a newline and some containing internal newlines. When

3667

these lines are concatenated and printed, exactly the same text is

3668

printed as does print_exception().</description>

3669

3670

3671

3672

3673

<description>A shorthand for format_list(extract_tb(tb, limit)).</description>

3674

3675

3676

3677

3678

<description>A shorthand for format_list(extract_stack(f, limit)).</description>

3679

3680

3681

3682

3683

<description>This function returns the current line number set in the traceback

3684

object. This function was necessary because in versions of Python

3685

prior to 2.3 when the -O flag was passed to Python the

3686

tb.tb_lineno was not updated correctly. This function

3687

has no use in versions past 2.3.</description>

3688

3689

3690

3691

3692

</group>

3693

</group>

3694

3695

<description>This module provides random access to individual lines

3696

from text files.

3697

The linecache module allows one to get any line from any file,

3698

while attempting to optimize internally, using a cache, the common case

3699

where many lines are read from a single file. This is used by the

3700

traceback module to retrieve source lines for inclusion in the formatted traceback.

3701

The linecache module defines the following functions:

3702

</description>

3703

3704

<description>Get line lineno from file named filename. This function

3705

will never throw an exception --- it will return '' on errors

3706

(the terminating newline character will be included for lines that are

3707

found).

3708

If a file named filename is not found, the function will look

3709

for it in the modulemodule{search}{path} search path,

3710

sys.path.</description>

3711

3712

3713

3714

3715

<description>Clear the cache. Use this function if you no longer need lines from

3716

files previously read using getline().</description>

3717

3718

</element>

3719

3720

3721

<description>Check the cache for validity. Use this function if files in the cache may have changed on disk, and you require the updated version.</description>

3722

3723

</element>

3724

3725

</group>

3726

3727

<description>Convert Python objects to streams of bytes and back.

3728

% Substantial improvements by Jim Kerr <jbkerr@sr.hp.com>.

3729

% Rewritten by Barry Warsaw <barry@zope.com>

3730

</description>

3731

3732

<description>The pickle module has an optimized cousin called the

3733

cPickle module. As its name implies, cPickle is

3734

written in C, so it can be up to 1000 times faster than

3735

pickle. However it does not support subclassing of the

3736

Pickler() and Unpickler() classes, because in

3737

cPickle these are functions, not classes. Most applications

3738

have no need for this functionality, and can benefit from the improved

3739

performance of cPickle. Other than that, the interfaces of

3740

the two modules are nearly identical; the common interface is

3741

described in this manual and differences are pointed out where

3742

necessary. In the following discussions, we use the term ``pickle''

3743

to collectively describe the pickle and

3744

cPickle modules.

3745

The data streams the two modules produce are guaranteed to be

3746

interchangeable.

3747

Python has a more primitive serialization module called

3748

marshal, but in general

3749

pickle should always be the preferred way to serialize Python

3750

objects. marshal exists primarily to support Python's

3751

.pyc files.

3752

The pickle module differs from marshal several

3753

significant ways:

3754

The pickle module keeps track of the objects it has

3755

already serialized, so that later references to the same object

3756

won't be serialized again. marshal doesn't do this.

3757

This has implications both for recursive objects and object

3758

sharing. Recursive objects are objects that contain references

3759

to themselves. These are not handled by marshal, and in fact,

3760

attempting to marshal recursive objects will crash your Python

3761

interpreter. Object sharing happens when there are multiple

3762

references to the same object in different places in the object

3763

hierarchy being serialized. pickle stores such objects

3764

only once, and ensures that all other references point to the

3765

master copy. Shared objects remain shared, which can be very

3766

important for mutable objects.

3767

marshal cannot be used to serialize user-defined

3768

classes and their instances. pickle can save and

3769

restore class instances transparently, however the class

3770

definition must be importable and live in the same module as

3771

when the object was stored.

3772

The marshal serialization format is not guaranteed to

3773

be portable across Python versions. Because its primary job in

3774

life is to support .pyc files, the Python implementers

3775

reserve the right to change the serialization format in

3776

non-backwards compatible ways should the need arise. The

3777

pickle serialization format is guaranteed to be

3778

backwards compatible across Python releases.

3779

[warning]

3780

The pickle module is not intended to be secure against

3781

erroneous or maliciously constructed data. Never unpickle data

3782

received from an untrusted or unauthenticated source.

3783

Note that serialization is a more primitive notion than persistence;

3784

although

3785

pickle reads and writes file objects, it does not handle the

3786

issue of naming persistent objects, nor the (even more complicated)

3787

issue of concurrent access to persistent objects. The pickle

3788

module can transform a complex object into a byte stream and it can

3789

transform the byte stream into an object with the same internal

3790

structure. Perhaps the most obvious thing to do with these byte

3791

streams is to write them onto a file, but it is also conceivable to

3792

send them across a network or store them in a database. The module

3793

shelve provides a simple interface

3794

to pickle and unpickle objects on DBM-style database files.

3795

</description>

3796

</group>

3797

3798

<description>The data format used by pickle is Python-specific. This has

3799

the advantage that there are no restrictions imposed by external

3800

standards such as XDR</description>

3801

</group>

3802

3803

<description>To serialize an object hierarchy, you first create a pickler, then you

3804

call the pickler's dump() method. To de-serialize a data

3805

stream, you first create an unpickler, then you call the unpickler's

3806

load() method. The pickle module provides the

3807

following constant:

3808

{HIGHEST_PROTOCOL}

3809

The highest protocol version available. This value can be passed

3810

as a protocol value.

3811

New in version 2.3

3812

The pickle module provides the

3813

following functions to make this process more convenient:

3814

</description>

3815

3816

<description>Write a pickled representation of object to the open file object

3817

file. This is equivalent to

3818

Pickler(file, protocol, bin).dump(object).

3819

If the protocol parameter is ommitted, protocol 0 is used.

3820

If protocol is specified as a negative value

3821

or HIGHEST_PROTOCOL,

3822

the highest protocol version will be used.

3823

Changed in version 2.3: The protocol parameter was added.

3824

The bin parameter is deprecated and only provided

3825

for backwards compatibility. You should use the protocol

3826

parameter instead

3827

If the optional bin argument is true, the binary pickle format

3828

is used; otherwise the (less efficient) text pickle format is used

3829

(for backwards compatibility, this is the default).

3830

file must have a write() method that accepts a single

3831

string argument. It can thus be a file object opened for writing, a

3832

StringIO object, or any other custom

3833

object that meets this interface.</description>

3834

3835

3836

3837

3838

<description>Read a string from the open file object file and interpret it as

3839

a pickle data stream, reconstructing and returning the original object

3840

hierarchy. This is equivalent to Unpickler(file).load().

3841

file must have two methods, a read() method that takes

3842

an integer argument, and a readline() method that requires no

3843

arguments. Both methods should return a string. Thus file can

3844

be a file object opened for reading, a

3845

StringIO object, or any other custom

3846

object that meets this interface.

3847

This function automatically determines whether the data stream was

3848

written in binary mode or not.</description>

3849

3850

3851

3852

3853

<description>Return the pickled representation of the object as a string, instead

3854

of writing it to a file.

3855

If the protocol parameter is ommitted, protocol 0 is used.

3856

If protocol is specified as a negative value

3857

or HIGHEST_PROTOCOL,

3858

the highest protocol version will be used.

3859

Changed in version 2.3: The protocol parameter was added.

3860

The bin parameter is deprecated and only provided

3861

for backwards compatibility. You should use the protocol

3862

parameter instead

3863

If the optional bin argument is

3864

true, the binary pickle format is used; otherwise the (less efficient)

3865

text pickle format is used (this is the default).</description>

3866

3867

3868

3869

3870

<description>Read a pickled object hierarchy from a string. Characters in the

3871

string past the pickled object's representation are ignored.</description>

3872

3873

3874

3875

3876

<description>This takes a file-like object to which it will write a pickle data

3877

stream. If the protocol parameter is ommitted, protocol 0 is used.

3878

If protocol is specified as a negative value,

3879

the highest protocol version will be used.

3880

Changed in version 2.3: The bin parameter is deprecated and only provided

3881

for backwards compatibility. You should use the protocol

3882

parameter instead

3883

Optional bin if true, tells the pickler to use the more

3884

efficient binary pickle format, otherwise the ASCII format is used

3885

(this is the default).

3886

file must have a write() method that accepts a single

3887

string argument. It can thus be an open file object, a

3888

StringIO object, or any other custom

3889

object that meets this interface.</description>

3890

3891

3892

3893

3894

<description>Write a pickled representation of object to the open file object

3895

given in the constructor. Either the binary or ASCII format will

3896

be used, depending on the value of the bin flag passed to the

3897

constructor.</description>

3898

3899

3900

3901

3902

<description>Clears the pickler's ``memo''. The memo is the data structure that

3903

remembers which objects the pickler has already seen, so that shared

3904

or recursive objects pickled by reference and not by value. This

3905

method is useful when re-using picklers.

3906

Prior to Python 2.3, clear_memo() was only available on the

3907

picklers created by cPickle. In the pickle module,

3908

picklers have an instance variable called memo which is a

3909

Python dictionary. So to clear the memo for a pickle module

3910

pickler, you could do the following:

3911

mypickler.memo.clear()

3912

Code that does not need to support older versions of Python should

3913

simply use clear_memo().

3914

</description>

3915

3916

</element>

3917

3918

3919

<description>This takes a file-like object from which it will read a pickle data

3920

stream. This class automatically determines whether the data stream

3921

was written in binary mode or not, so it does not need a flag as in

3922

the Pickler factory.

3923

file must have two methods, a read() method that takes

3924

an integer argument, and a readline() method that requires no

3925

arguments. Both methods should return a string. Thus file can

3926

be a file object opened for reading, a

3927

StringIO object, or any other custom

3928

object that meets this interface.</description>

3929

3930

3931

3932

3933

<description>Read a pickled object representation from the open file object given

3934

in the constructor, and return the reconstituted object hierarchy

3935

specified therein.</description>

3936

3937

</element>

3938

3939

3940

<description>This is just like load() except that it doesn't actually

3941

create any objects. This is useful primarily for finding what's

3942

called ``persistent ids'' that may be referenced in a pickle data

3943

stream. See section~pickle-protocol below for more details.

3944

Note: the noload() method is currently only

3945

available on Unpickler objects created with the

3946

cPickle module. pickle module Unpicklers do

3947

not have the noload() method.</description>

3948

3949

</element>

3950

3951

</group>

3952

3953

<description>The following types can be pickled:

3954

None, True, and False

3955

integers, long integers, floating point numbers, complex numbers

3956

normal and Unicode strings

3957

tuples, lists, and dictionaries containing only picklable objects

3958

functions defined at the top level of a module

3959

built-in functions defined at the top level of a module

3960

classes that are defined at the top level of a module

3961

instances of such classes whose __dict__ or

3962

__setstate__() is picklable (see

3963

section~pickle-protocol for details)

3964

Attempts to pickle unpicklable objects will raise the

3965

PicklingError exception; when this happens, an unspecified

3966

number of bytes may have already been written to the underlying file.

3967

Note that functions (built-in and user-defined) are pickled by ``fully

3968

qualified'' name reference, not by value. This means that only the

3969

function name is pickled, along with the name of module the function

3970

is defined in. Neither the function's code, nor any of its function

3971

attributes are pickled. Thus the defining module must be importable

3972

in the unpickling environment, and the module must contain the named

3973

object, otherwise an exception will be raised.The exception

3974

raised will likely be an ImportError or an

3975

AttributeError but it could be something else.

3976

Similarly, classes are pickled by named reference, so the same

3977

restrictions in the unpickling environment apply. Note that none of

3978

the class's code or data is pickled, so in the following example the

3979

class attribute attr is not restored in the unpickling

3980

environment:

3981

class Foo:

3982

attr = 'a class attr'

3983

picklestring = pickle.dumps(Foo)

3984

These restrictions are why picklable functions and classes must be

3985

defined in the top level of a module.

3986

Similarly, when class instances are pickled, their class's code and

3987

data are not pickled along with them. Only the instance data are

3988

pickled. This is done on purpose, so you can fix bugs in a class or

3989

add methods to the class and still load objects that were created with

3990

an earlier version of the class. If you plan to have long-lived

3991

objects that will see many versions of a class, it may be worthwhile

3992

to put a version number in the objects so that suitable conversions

3993

can be made by the class's __setstate__() method.

3994

</description>

3995

</group>

3996

3997

</group>

3998

3999

<description>By default, unpickling will import any class that it finds in the

4000

pickle data. You can control exactly what gets unpickled and what

4001

gets called by customizing your unpickler. Unfortunately, exactly how

4002

you do this is different depending on whether you're using

4003

pickle or cPickle.A word of caution: the

4004

mechanisms described here use internal attributes and methods, which

4005

are subject to change in future versions of Python. We intend to

4006

someday provide a common interface for controlling this behavior,

4007

which will work in either pickle or cPickle.

4008

In the pickle module, you need to derive a subclass from

4009

Unpickler, overriding the load_global()

4010

method. load_global() should read two lines from the pickle

4011

data stream where the first line will the name of the module

4012

containing the class and the second line will be the name of the

4013

instance's class. It then looks up the class, possibly importing the

4014

module and digging out the attribute, then it appends what it finds to

4015

the unpickler's stack. Later on, this class will be assigned to the

4016

__class__ attribute of an empty class, as a way of magically

4017

creating an instance without calling its class's __init__().

4018

Your job (should you choose to accept it), would be to have

4019

load_global() push onto the unpickler's stack, a known safe

4020

version of any class you deem safe to unpickle. It is up to you to

4021

produce such a class. Or you could raise an error if you want to

4022

disallow all unpickling of instances. If this sounds like a hack,

4023

you're right. Refer to the source code to make this work.

4024

Things are a little cleaner with cPickle, but not by much.

4025

To control what gets unpickled, you can set the unpickler's

4026

find_global attribute to a function or None. If it is

4027

None then any attempts to unpickle instances will raise an

4028

UnpicklingError. If it is a function,

4029

then it should accept a module name and a class name, and return the

4030

corresponding class object. It is responsible for looking up the

4031

class and performing any necessary imports, and it may raise an

4032

error to prevent instances of the class from being unpickled.

4033

The moral of the story is that you should be really careful about the

4034

source of the strings your application unpickles.

4035

</description>

4036

</group>

4037

4038

</group>

4039

</group>

4040

4041

<description>Python object persistence.

4042

A ``shelf'' is a persistent, dictionary-like object. The difference

4043

with ``dbm'' databases is that the values (not the keys!) in a shelf

4044

can be essentially arbitrary Python objects --- anything that the

4045

pickle module can handle. This includes most class

4046

instances, recursive data types, and objects containing lots of shared sub-objects. The keys are ordinary strings.

4047

pickle

4048

</description>

4049

4050

<description>Open a persistent dictionary. The filename specified is the base filename

4051

for the underlying database. As a side-effect, an extension may be added to

4052

the filename and more than one file may be created. By default, the

4053

underlying database file is opened for reading and writing. The optional

4054

{}flag pararameter has the same interpretation as the flag

4055

parameter of anydbm.open. By default, version 0 pickles are used to serialize values. The version of the pickle protocol can be specified with the

4056

protocol parameter. Changed in version 2.3: The protocol

4057

parameter was added. The binary parameter is deprecated

4058

and provided for backwards compatibility only

4059

By default, mutations to persistent-dictionary mutable entries are not

4060

automatically written back. If the optional writeback parameter

4061

is set to {}True, all entries accessed are cached in memory, and

4062

written back at close time; this can make it handier to mutate mutable

4063

entries in the persistent dictionary, but, if many entries are

4064

accessed, it can consume vast amounts of memory for the cache, and it

4065

can make the close operation very slow since all accessed entries are

4066

written back (there is no way to determine which accessed entries are

4067

mutable, nor which ones were actually mutated).</description>

4068

4069

4070

4071

4072

<description>The choice of which database package will be used

4073

(such as dbm, gdbm or bsddb) depends on

4074

which interface is available. Therefore it is not safe to open the database

4075

directly using dbm. The database is also (unfortunately) subject

4076

to the limitations of dbm, if it is used --- this means

4077

that (the pickled representation of) the objects stored in the

4078

database should be fairly small, and in rare cases key collisions may

4079

cause the database to refuse updates.

4080

dbm

4081

gdbm

4082

bsddb

4083

Depending on the implementation, closing a persistent dictionary may

4084

or may not be necessary to flush changes to disk. The __del__

4085

method of the Shelf class calls the close method, so the

4086

programmer generally need not do this explicitly.

4087

The shelve module does not support concurrent read/write

4088

access to shelved objects. (Multiple simultaneous read accesses are

4089

safe.) When a program has a shelf open for writing, no other program

4090

should have it open for reading or writing. file locking can

4091

be used to solve this, but this differs across versions and

4092

requires knowledge about the database implementation used.

4093

</description>

4094

4095

<description>A subclass of UserDict.DictMixin which stores pickled values in the

4096

dict object. By default, version 0 pickles are used to serialize values. The

4097

version of the pickle protocol can be specified with the

4098

protocol parameter. See the pickle documentation for a

4099

discussion of the pickle protocols. Changed in version 2.3: The protocol

4100

parameter was added. The binary parameter is deprecated and

4101

provided for backwards compatibility only

4102

If the writeback parameter is True, the object will hold a

4103

cache of all entries accessed and write them back to the dict at

4104

sync and close times. This allows natural operations on mutable entries,

4105

but can consume much more memory and make sync and close take a long time.</description>

4106

4107

4108

4109

4110

<description>A subclass of Shelf which exposes first,

4111

next, previous, last and

4112

set_location which are available in the bsddb module

4113

but not in other database modules. The dict object passed to

4114

the constructor must support those methods. This is generally

4115

accomplished by calling one of bsddb.hashopen,

4116

bsddb.btopen or bsddb.rnopen. The optional

4117

protocol, writeback, and binary parameters have the

4118

same interpretation as for the Shelf class.</description>

4119

4120

4121

4122

4123

<description>A subclass of Shelf which accepts a filename instead of

4124

a dict-like object. The underlying file will be opened using

4125

{}anydbm.open. By default, the file will be created and

4126

opened for both read and write. The optional flag parameter has

4127

the same interpretation as for the open function. The

4128

optional protocol, writeback, and binary parameters

4129

have the same interpretation as for the Shelf class.</description>

4130

4131

4132

4133

</group>

4134

4135

</group>

4136

</group>

4137

4138

</group>

4139

4140

<description>Convert Python objects to streams of bytes and back

4141

(with different constraints).

4142

This module contains functions that can read and write Python

4143

values in a binary format. The format is specific to Python, but

4144

independent of machine architecture issues (e.g., you can write a

4145

Python value to a file on a PC, transport the file to a Sun, and read

4146

it back there). Details of the format are undocumented on purpose;

4147

it may change between Python versions (although it rarely

4148

does).The name of this module stems from a bit of

4149

terminology used by the designers of Modula-3 (amongst others), who

4150

use the term ``marshalling'' for shipping of data around in a

4151

self-contained form. Strictly speaking, ``to marshal'' means to

4152

convert some data from internal to external form (in an RPC buffer for

4153

instance) and ``unmarshalling'' for the reverse process.

4154

This is not a general ``persistence'' module. For general persistence

4155

and transfer of Python objects through RPC calls, see the modules

4156

pickle and shelve. The marshal module exists

4157

mainly to support reading and writing the ``pseudo-compiled'' code for

4158

Python modules of .pyc files. Therefore, the Python

4159

maintainers reserve the right to modify the marshal format in backward

4160

incompatible ways should the need arise. If you're serializing and

4161

de-serializing Python objects, use the pickle module instead. pickle

4162

shelve

4163

code

4164

[warning]

4165

The marshal module is not intended to be secure against

4166

erroneous or maliciously constructed data. Never unmarshal data

4167

received from an untrusted or unauthenticated source.

4168

Not all Python object types are supported; in general, only objects

4169

whose value is independent from a particular invocation of Python can

4170

be written and read by this module. The following types are supported:

4171

None, integers, long integers, floating point numbers,

4172

strings, Unicode objects, tuples, lists, dictionaries, and code

4173

objects, where it should be understood that tuples, lists and

4174

dictionaries are only supported as long as the values contained

4175

therein are themselves supported; and recursive lists and dictionaries

4176

should not be written (they will cause infinite loops).

4177

Caveat: On machines where C's long int type has more than

4178

32 bits (such as the DEC Alpha), it is possible to create plain Python

4179

integers that are longer than 32 bits.

4180

If such an integer is marshaled and read back in on a machine where

4181

C's long int type has only 32 bits, a Python long integer object

4182

is returned instead. While of a different type, the numeric value is

4183

the same. (This behavior is new in Python 2.2. In earlier versions,

4184

all but the least-significant 32 bits of the value were lost, and a

4185

warning message was printed.)

4186

There are functions that read/write files as well as functions

4187

operating on strings.

4188

The module defines these functions:

4189

</description>

4190

4191

<description>Write the value on the open file. The value must be a supported

4192

type. The file must be an open file object such as

4193

sys.stdout or returned by open() or

4194

posix.popen(). It must be opened in binary mode

4195

('wb' or 'w+b').

4196

If the value has (or contains an object that has) an unsupported type,

4197

a ValueError exception is raised --- but garbage data

4198

will also be written to the file. The object will not be properly

4199

read back by load().</description>

4200

4201

4202

4203

4204

<description>Read one value from the open file and return it. If no valid value

4205

is read, raise EOFError, ValueError or

4206

TypeError. The file must be an open file object opened

4207

in binary mode ('rb' or 'r+b').

4208

If an object containing an unsupported type was

4209

marshalled with dump(), load() will substitute

4210

None for the unmarshallable type.</description>

4211

4212

4213

4214

4215

<description>Return the string that would be written to a file by

4216

dump(value, file). The value must be a supported

4217

type. Raise a ValueError exception if value has (or

4218

contains an object that has) an unsupported type.</description>

4219

4220

4221

4222

4223

<description>Convert the string to a value. If no valid value is found, raise

4224

EOFError, ValueError or

4225

TypeError. Extra characters in the string are ignored.</description>

4226

4227

4228

4229

</group>

4230

4231

<description>Issue warning messages and control their disposition.

4232

</description>

4233

4234

<description>There are a number of built-in exceptions that represent warning

4235

categories. This categorization is useful to be able to filter out

4236

groups of warnings. The following warnings category classes are

4237

currently defined:

4238

{l|l}{exception}{Class}{Description}

4239

Warning{This is the base class of all warning category

4240

classes. It is a subclass of Exception.}

4241

UserWarning{The default category for warn().}

4242

DeprecationWarning{Base category for warnings about

4243

deprecated features.}

4244

SyntaxWarning{Base category for warnings about dubious

4245

syntactic features.}

4246

RuntimeWarning{Base category for warnings about dubious

4247

runtime features.}

4248

FutureWarning{Base category for warnings about constructs

4249

that will change semantically in the future.}

4250

While these are technically built-in exceptions, they are documented

4251

here, because conceptually they belong to the warnings mechanism.

4252

User code can define additional warning categories by subclassing one

4253

of the standard warning categories. A warning category must always be

4254

a subclass of the Warning class.

4255

</description>

4256

</group>

4257

4258

<description>The warnings filter controls whether warnings are ignored, displayed,

4259

or turned into errors (raising an exception).

4260

Conceptually, the warnings filter maintains an ordered list of filter

4261

specifications; any specific warning is matched against each filter

4262

specification in the list in turn until a match is found; the match

4263

determines the disposition of the match. Each entry is a tuple of the

4264

form (action, message, category, module,

4265

lineno), where:

4266

action is one of the following strings:

4267

{l|l}{code}{Value}{Disposition}

4268

"error"{turn matching warnings into exceptions}

4269

"ignore"{never print matching warnings}

4270

"always"{always print matching warnings}

4271

"default"{print the first occurrence of matching

4272

warnings for each location where the warning is issued}

4273

"module"{print the first occurrence of matching

4274

warnings for each module where the warning is issued}

4275

"once"{print only the first occurrence of matching

4276

warnings, regardless of location}

4277

message is a string containing a regular expression that

4278

the warning message must match (the match is compiled to always be case-insensitive) category is a class (a subclass of Warning) of

4279

which the warning category must be a subclass in order to match

4280

module is a string containing a regular expression that the module

4281

name must match (the match is compiled to be case-sensitive)

4282

lineno is an integer that the line number where the

4283

warning occurred must match, or 0 to match all line

4284

numbers

4285

Since the Warning class is derived from the built-in

4286

Exception class, to turn a warning into an error we simply

4287

raise category(message).

4288

The warnings filter is initialized by -W options passed

4289

to the Python interpreter command line. The interpreter saves the

4290

arguments for all -W options without interpretation in

4291

sys.warnoptions; the warnings module parses these when

4292

it is first imported (invalid options are ignored, after printing a

4293

message to sys.stderr).

4294

</description>

4295

</group>

4296

4297

4298

<description>Issue a warning, or maybe ignore it or raise an exception. The

4299

category argument, if given, must be a warning category class

4300

(see above); it defaults to UserWarning. Alternatively

4301

message can be a Warning instance, in which case

4302

category will be ignored and message.__class__ will be used.

4303

In this case the message text will be str(message). This function

4304

raises an exception if the particular warning issued is changed

4305

into an error by the warnings filter see above. The stacklevel

4306

argument can be used by wrapper functions written in Python, like

4307

this:

4308

def deprecation(message):

4309

warnings.warn(message, DeprecationWarning, stacklevel=2)

4310

This makes the warning refer to deprecation()'s caller,

4311

rather than to the source of deprecation() itself (since

4312

the latter would defeat the purpose of the warning message).</description>

4313

4314

4315

4316

4317

<description>This is a low-level interface to the functionality of

4318

warn(), passing in explicitly the message, category,

4319

filename and line number, and optionally the module name and the

4320

registry (which should be the __warningregistry__ dictionary of

4321

the module). The module name defaults to the filename with .py

4322

stripped; if no registry is passed, the warning is never suppressed.

4323

message must be a string and category a subclass of

4324

Warning or message may be a Warning instance,

4325

in which case category will be ignored.</description>

4326

4327

4328

4329

4330

<description>Write a warning to a file. The default implementation calls

4331

formatwarning(message, category, filename,

4332

lineno) and writes the resulting string to file, which

4333

defaults to sys.stderr. You may replace this function with an

4334

alternative implementation by assigning to

4335

warnings.showwarning.</description>

4336

4337

4338

4339

4340

<description>Format a warning the standard way. This returns a string which may

4341

contain embedded newlines and ends in a newline.</description>

4342

4343

4344

4345

4346

<description>Insert an entry into the list of warnings filters. The entry is

4347

inserted at the front by default; if append is true, it is

4348

inserted at the end.

4349

This checks the types of the arguments, compiles the message and

4350

module regular expressions, and inserts them as a tuple in front

4351

of the warnings filter. Entries inserted later override entries

4352

inserted earlier, if both match a particular warning. Omitted

4353

arguments default to a value that matches everything.</description>

4354

4355

4356

4357

4358

<description>Reset the warnings filter. This discards the effect of all previous

4359

calls to filterwarnings(), including that of the

4360

-W command line options.</description>

4361

4362

</element>

4363

4364

</group>

4365

</group>

4366

4367

<description>Base classes for interactive Python interpreters.

4368

The code module provides facilities to implement

4369

read-eval-print loops in Python. Two classes and convenience

4370

functions are included which can be used to build applications which

4371

provide an interactive interpreter prompt.

4372

</description>

4373

4374

<description>This class deals with parsing and interpreter state (the user's

4375

namespace); it does not deal with input buffering or prompting or

4376

input file naming (the filename is always passed in explicitly).

4377

The optional locals argument specifies the dictionary in

4378

which code will be executed; it defaults to a newly created

4379

dictionary with key '__name__' set to '__console__'

4380

and key '__doc__' set to None.</description>

4381

4382

4383

4384

4385

<description>Closely emulate the behavior of the interactive Python interpreter.

4386

This class builds on InteractiveInterpreter and adds

4387

prompting using the familiar sys.ps1 and sys.ps2, and

4388

input buffering.</description>

4389

4390

4391

4392

4393

<description>Convenience function to run a read-eval-print loop. This creates a

4394

new instance of InteractiveConsole and sets readfunc

4395

to be used as the raw_input() method, if provided. If

4396

local is provided, it is passed to the

4397

InteractiveConsole constructor for use as the default

4398

namespace for the interpreter loop. The interact() method

4399

of the instance is then run with banner passed as the banner

4400

to use, if provided. The console object is discarded after use.</description>

4401

4402

4403

4404

4405

<description>This function is useful for programs that want to emulate Python's

4406

interpreter main loop (a.k.a. the read-eval-print loop). The tricky

4407

part is to determine when the user has entered an incomplete command

4408

that can be completed by entering more text (as opposed to a

4409

complete command or a syntax error). This function

4410

almost always makes the same decision as the real interpreter

4411

main loop.

4412

source is the source string; filename is the optional

4413

filename from which source was read, defaulting to '<input>';

4414

and symbol is the optional grammar start symbol, which should

4415

be either 'single' (the default) or 'eval'.

4416

Returns a code object (the same as compile(source,

4417

filename, symbol)) if the command is complete and

4418

valid; None if the command is incomplete; raises

4419

SyntaxError if the command is complete and contains a

4420

syntax error, or raises OverflowError or

4421

ValueError if the command cotains an invalid literal.</description>

4422

4423

4424

4425

4426

4427

<description>Compile and run some source in the interpreter.

4428

Arguments are the same as for compile_command(); the

4429

default for filename is '<input>', and for

4430

symbol is 'single'. One several things can happen:

4431

The input is incorrect; compile_command() raised an

4432

exception (SyntaxError or OverflowError). A

4433

syntax traceback will be printed by calling the

4434

showsyntaxerror() method. runsource() returns

4435

False.

4436

The input is incomplete, and more input is required;

4437

compile_command() returned None.

4438

runsource() returns True.

4439

The input is complete; compile_command() returned a code

4440

object. The code is executed by calling the runcode() (which

4441

also handles run-time exceptions, except for SystemExit).

4442

runsource() returns False.

4443

The return value can be used to decide whether to use

4444

sys.ps1 or sys.ps2 to prompt the next line.</description>

4445

4446

4447

4448

4449

<description>Execute a code object.

4450

When an exception occurs, showtraceback() is called to

4451

display a traceback. All exceptions are caught except

4452

SystemExit, which is allowed to propagate.

4453

A note about KeyboardInterrupt: this exception may occur

4454

elsewhere in this code, and may not always be caught. The caller

4455

should be prepared to deal with it.</description>

4456

4457

4458

4459

4460

<description>Display the syntax error that just occurred. This does not display

4461

a stack trace because there isn't one for syntax errors.

4462

If filename is given, it is stuffed into the exception instead

4463

of the default filename provided by Python's parser, because it

4464

always uses '<string>' when reading from a string.

4465

The output is written by the write() method.</description>

4466

4467

4468

4469

4470

<description>Display the exception that just occurred. We remove the first stack

4471

item because it is within the interpreter object implementation.

4472

The output is written by the write() method.</description>

4473

4474

</element>

4475

4476

4477

<description>Write a string to the standard error stream (sys.stderr).

4478

Derived classes should override this to provide the appropriate output

4479

handling as needed.</description>

4480

4481

4482

4483

</group>

4484

4485

<description>The InteractiveConsole class is a subclass of

4486

InteractiveInterpreter, and so offers all the methods of the

4487

interpreter objects as well as the following additions.

4488

</description>

4489

4490

<description>Closely emulate the interactive Python console.

4491

The optional banner argument specify the banner to print before the

4492

first interaction; by default it prints a banner similar to the one

4493

printed by the standard Python interpreter, followed by the class

4494

name of the console object in parentheses (so as not to confuse this

4495

with the real interpreter -- since it's so close!).</description>

4496

4497

4498

4499

4500

<description>Push a line of source text to the interpreter.

4501

The line should not have a trailing newline; it may have internal

4502

newlines. The line is appended to a buffer and the interpreter's

4503

runsource() method is called with the concatenated contents

4504

of the buffer as source. If this indicates that the command was

4505

executed or invalid, the buffer is reset; otherwise, the command is

4506

incomplete, and the buffer is left as it was after the line was

4507

appended. The return value is True if more input is required,

4508

False if the line was dealt with in some way (this is the same as

4509

runsource()).</description>

4510

4511

4512

4513

4514

<description>Remove any unhandled source text from the input buffer.</description>

4515

4516

</element>

4517

4518

4519

<description>Write a prompt and read a line. The returned line does not include

4520

the trailing newline. When the user enters the key sequence,

4521

EOFError is raised. The base implementation uses the

4522

built-in function raw_input(); a subclass may replace this

4523

with a different implementation.</description>

4524

4525

4526

4527

</group>

4528

</group>

4529

4530

<description>% LaTeXed from excellent doc-string.

4531

Compile (possibly incomplete) Python code.

4532

The codeop module provides utilities upon which the Python

4533

read-eval-print loop can be emulated, as is done in the

4534

code module. As a result, you probably don't want to use

4535

the module directly; if you want to include such a loop in your

4536

program you probably want to use the code module instead.

4537

There are two parts to this job: Being able to tell if a line of input completes a Python statement: in short, telling whether to print

4538

`>>>~ or `...~' next.

4539

Remembering which future statements the user has entered, so subsequent input can be compiled with these in effect.

4540

The codeop module provides a way of doing each of these

4541

things, and a way of doing them both.

4542

To do just the former:

4543

</description>

4544

4545

<description>Tries to compile source, which should be a string of Python

4546

code and return a code object if source is valid

4547

Python code. In that case, the filename attribute of the code object

4548

will be filename, which defaults to '<input>'.

4549

Returns None if source is not valid Python

4550

code, but is a prefix of valid Python code.

4551

If there is a problem with source, an exception will be raised.

4552

SyntaxError is raised if there is invalid Python syntax,

4553

and OverflowError or ValueError if there is an

4554

invalid literal.

4555

The symbol argument determines whether source is compiled

4556

as a statement ('single', the default) or as an expression

4557

('eval'). Any other value will cause ValueError to be raised.

4558

Caveat:

4559

It is possible (but not likely) that the parser stops parsing

4560

with a successful outcome before reaching the end of the source;

4561

in this case, trailing symbols may be ignored instead of causing an

4562

error. For example, a backslash followed by two newlines may be

4563

followed by arbitrary garbage. This will be fixed once the API

4564

for the parser is better.</description>

4565

4566

4567

4568

4569

<description>Instances of this class have __call__() methods indentical in

4570

signature to the built-in function compile(), but with the

4571

difference that if the instance compiles program text containing a

4572

__future__ statement, the instance 'remembers' and compiles

4573

all subsequent program texts with the statement in force.</description>

4574

4575

</element>

4576

4577

4578

<description>Instances of this class have __call__() methods identical in

4579

signature to compile_command(); the difference is that if

4580

the instance compiles program text containing a __future__

4581

statement, the instance 'remembers' and compiles all subsequent

4582

program texts with the statement in force.</description>

4583

4584

</element>

4585

4586

</group>

4587

4588

<description>Data pretty printer.

4589

The pprint module provides a capability to ``pretty-print''

4590

arbitrary Python data structures in a form which can be used as input

4591

to the interpreter. If the formatted structures include objects which

4592

are not fundamental Python types, the representation may not be

4593

loadable. This may be the case if objects such as files, sockets,

4594

classes, or instances are included, as well as many other builtin

4595

objects which are not representable as Python constants.

4596

The formatted representation keeps objects on a single line if it can,

4597

and breaks them onto multiple lines if they don't fit within the

4598

allowed width. Construct PrettyPrinter objects explicitly if

4599

you need to adjust the width constraint.

4600

The pprint module defines one class:

4601

% First the implementation class:

4602

</description>

4603

4604

<description>Construct a PrettyPrinter instance. This constructor

4605

understands several keyword parameters. An output stream may be set

4606

using the stream keyword; the only method used on the stream

4607

object is the file protocol's write() method. If not

4608

specified, the PrettyPrinter adopts sys.stdout. Three

4609

additional parameters may be used to control the formatted

4610

representation. The keywords are indent, depth, and

4611

width. The amount of indentation added for each recursive level

4612

is specified by indent; the default is one. Other values can

4613

cause output to look a little odd, but can make nesting easier to

4614

spot. The number of levels which may be printed is controlled by

4615

depth; if the data structure being printed is too deep, the next

4616

contained level is replaced by .... By default, there is no

4617

constraint on the depth of the objects being formatted. The desired

4618

output width is constrained using the width parameter; the

4619

default is eighty characters. If a structure cannot be formatted

4620

within the constrained width, a best effort will be made.

4621

>>> import pprint, sys

4622

>>> stuff = sys.path[:]

4623

>>> stuff.insert(0, stuff[:])

4624

>>> pp = pprint.PrettyPrinter(indent=4)

4625

>>> pp.pprint(stuff)

4626

[ [ '',

4627

'/usr/local/lib/python1.5',

4628

'/usr/local/lib/python1.5/test',

4629

'/usr/local/lib/python1.5/sunos5',

4630

'/usr/local/lib/python1.5/sharedmodules',

4631

'/usr/local/lib/python1.5/tkinter'],

4632

'',

4633

'/usr/local/lib/python1.5',

4634

'/usr/local/lib/python1.5/test',

4635

'/usr/local/lib/python1.5/sunos5',

4636

'/usr/local/lib/python1.5/sharedmodules',

4637

'/usr/local/lib/python1.5/tkinter']

4638

>>>

4639

>>> import parser

4640

>>> tup = parser.ast2tuple(

4641

... parser.suite(open('pprint.py').read()))[1][1][1]

4642

>>> pp = pprint.PrettyPrinter(depth=6)

4643

>>> pp.pprint(tup)

4644

(266, (267, (307, (287, (288, (...))))))

4645

</description>

4646

4647

4648

4649

4650

<description>Return the formatted representation of object as a string. indent,

4651

width and depth will be passed to the PrettyPrinter

4652

constructor as formatting parameters.

4653

Changed in version 2.4: The parameters indent, width and depth

4654

were added</description>

4655

4656

4657

4658

4659

<description>Prints the formatted representation of object on stream,

4660

followed by a newline. If stream is omitted, sys.stdout

4661

is used. This may be used in the interactive interpreter instead of a

4662

print statement for inspecting values. indent,

4663

width and depth will be passed to the PrettyPrinter

4664

constructor as formatting parameters.

4665

>>> stuff = sys.path[:]

4666

>>> stuff.insert(0, stuff)

4667

>>> pprint.pprint(stuff)

4668

[<Recursion on list with id=869440>,

4669

'',

4670

'/usr/local/lib/python1.5',

4671

'/usr/local/lib/python1.5/test',

4672

'/usr/local/lib/python1.5/sunos5',

4673

'/usr/local/lib/python1.5/sharedmodules',

4674

'/usr/local/lib/python1.5/tkinter']

4675

Changed in version 2.4: The parameters indent, width and depth

4676

were added</description>

4677

4678

4679

4680

4681

<description>Determine if the formatted representation of object is

4682

``readable,'' or can be used to reconstruct the value using

4683

eval()eval. This always returns false for

4684

recursive objects.

4685

>>> pprint.isreadable(stuff)

4686

False

4687

</description>

4688

4689

4690

4691

4692

<description>Determine if object requires a recursive representation.</description>

4693

4694

4695

4696

4697

<description>Return a string representation of object, protected against

4698

recursive data structures. If the representation of object

4699

exposes a recursive entry, the recursive reference will be represented

4700

as <Recursion on typename with id=number>. The

4701

representation is not otherwise formatted.</description>

4702

4703

4704

4705

4706

4707

<description>Return the formatted representation of object. This takes into

4708

Account the options passed to the PrettyPrinter constructor.</description>

4709

4710

4711

4712

4713

<description>Print the formatted representation of object on the configured

4714

stream, followed by a newline.</description>

4715

4716

4717

4718

4719

<description>Determine if the formatted representation of the object is

4720

``readable,'' or can be used to reconstruct the value using

4721

eval()eval. Note that this returns false for

4722

recursive objects. If the depth parameter of the

4723

PrettyPrinter is set and the object is deeper than allowed,

4724

this returns false.</description>

4725

4726

4727

4728

4729

<description>Determine if the object requires a recursive representation.</description>

4730

4731

4732

4733

4734

<description>Returns three values: the formatted version of object as a

4735

string, a flag indicating whether the result is readable, and a flag

4736

indicating whether recursion was detected. The first argument is the

4737

object to be presented. The second is a dictionary which contains the

4738

id() of objects that are part of the current presentation

4739

context (direct and indirect containers for object that are

4740

affecting the presentation) as the keys; if an object needs to be

4741

presented which is already represented in context, the third

4742

return value should be true. Recursive calls to the format()

4743

method should add additionaly entries for containers to this

4744

dictionary. The fourth argument, maxlevels, gives the requested

4745

limit to recursion; this will be 0 if there is no requested

4746

limit. This argument should be passed unmodified to recursive calls.

4747

The fourth argument, level gives the current level; recursive

4748

calls should be passed a value less than that of the current call.

4749

New in version 2.3</description>

4750

4751

4752

4753

</group>

4754

</group>

4755

4756

<description>Alternate repr() implementation with size limits.

4757

The repr module provides a means for producing object

4758

representations with limits on the size of the resulting strings.

4759

This is used in the Python debugger and may be useful in other

4760

contexts as well.

4761

This module provides a class, an instance, and a function:

4762

</description>

4763

4764

<description>Class which provides formatting services useful in implementing

4765

functions similar to the built-in repr(); size limits for different object types are added to avoid the generation of

4766

representations which are excessively long.</description>

4767

4768

</element>

4769

4770

4771

<description>This is the repr() method of aRepr. It returns a

4772

string similar to that returned by the built-in function of the same name, but with limits on most sizes.</description>

4773

4774

4775

4776

4777

<description>Repr instances provide several members which can be used to

4778

provide size limits for the representations of different object types, and methods which format specific object types.

4779

{maxlevel}

4780

Depth limit on the creation of recursive representations. The

4781

default is 6.

4782

{maxdict}

4783

maxlist

4784

maxtuple

4785

Limits on the number of entries represented for the named object

4786

type. The default for maxdict is 4, for the others, 6.

4787

{maxlong}

4788

Maximum number of characters in the representation for a long

4789

integer. Digits are dropped from the middle. The default is

4790

40.

4791

{maxstring}

4792

Limit on the number of characters in the representation of the

4793

string. Note that the ``normal'' representation of the string is

4794

used as the character source: if escape sequences are needed in the

4795

representation, these may be mangled when the representation is

4796

shortened. The default is 30.

4797

{maxother}

4798

This limit is used to control the size of object types for which no

4799

specific formatting method is available on the Repr object.

4800

It is applied in a similar manner as maxstring. The

4801

default is 20.

4802

</description>

4803

4804

<description>The equivalent to the built-in repr() that uses the

4805

formatting imposed by the instance.</description>

4806

4807

4808

4809

4810

<description>Recursive implementation used by repr(). This uses the

4811

type of obj to determine which formatting method to call,

4812

passing it obj and level. The type-specific methods

4813

should call repr1() to perform recursive formatting, with

4814

level - 1 for the value of level in the recursive call.</description>

4815

4816

4817

4818

</group>

4819

4820

</group>

4821

</group>

4822

4823

<description>Interface to the creation of runtime implementation objects.

4824

The new module allows an interface to the interpreter object

4825

creation functions. This is for use primarily in marshal-type functions,

4826

when a new object needs to be created ``magically'' and not by using the

4827

regular creation functions. This module provides a low-level interface

4828

to the interpreter, so care must be exercised when using this module.

4829

The new module defines the following functions:

4830

</description>

4831

4832

<description>This function creates an instance of class with dictionary

4833

dict without calling the __init__() constructor. If

4834

dict is omitted or None, a new, empty dictionary is

4835

created for the new instance. Note that there are no guarantees that

4836

the object will be in a consistent state.</description>

4837

4838

4839

4840

4841

<description>This function will return a method object, bound to instance, or

4842

unbound if instance is None. function must be

4843

callable.</description>

4844

4845

4846

4847

4848

<description>Returns a (Python) function with the given code and globals. If

4849

name is given, it must be a string or None. If it is a

4850

string, the function will have the given name, otherwise the function

4851

name will be taken from code.co_name. If

4852

argdefs is given, it must be a tuple and will be used to

4853

determine the default values of parameters.</description>

4854

4855

4856

4857

4858

<description>This function is an interface to the PyCode_New() C

4859

function.

4860

%XXX This is still undocumented!!!!!!!!!!!</description>

4861

4862

4863

4864

4865

<description>This function returns a new module object with name name.

4866

name must be a string.</description>

4867

4868

4869

4870

4871

<description>This function returns a new class object, with name name, derived

4872

from baseclasses (which should be a tuple of classes) and with

4873

namespace dict.</description>

4874

4875

4876

4877

</group>

4878

4879

</group>

4880

4881

</group>

4882

4883

</group>

4884

4885

</group>

4886

4887

</group>

4888

</group>

4889

4890

4891

<description>Common string operations.

4892

This module defines some constants useful for checking character

4893

classes and some useful string functions. See the module

4894

rere for string functions based on regular

4895

expressions.

4896

The constants defined in this module are:

4897

{ascii_letters}

4898

The concatenation of the ascii_lowercase and

4899

ascii_uppercase constants described below. This value is

4900

not locale-dependent.

4901

{ascii_lowercase}

4902

The lowercase letters 'abcdefghijklmnopqrstuvwxyz'. This

4903

value is not locale-dependent and will not change.

4904

{ascii_uppercase}

4905

The uppercase letters 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. This

4906

value is not locale-dependent and will not change.

4907

{digits}

4908

The string '0123456789'.

4909

{hexdigits}

4910

The string '0123456789abcdefABCDEF'.

4911

{letters}

4912

The concatenation of the strings lowercase and

4913

uppercase described below. The specific value is

4914

locale-dependent, and will be updated when

4915

locale.setlocale() is called.

4916

{lowercase}

4917

A string containing all the characters that are considered lowercase

4918

letters. On most systems this is the string

4919

'abcdefghijklmnopqrstuvwxyz'. Do not change its definition ---

4920

the effect on the routines upper() and

4921

swapcase() is undefined. The specific value is

4922

locale-dependent, and will be updated when

4923

locale.setlocale() is called.

4924

{octdigits}

4925

The string '01234567'.

4926

{punctuation}

4927

String of ASCII characters which are considered punctuation

4928

characters in the C locale.

4929

{printable}

4930

String of characters which are considered printable. This is a

4931

combination of digits, letters,

4932

punctuation, and whitespace.

4933

{uppercase}

4934

A string containing all the characters that are considered uppercase

4935

letters. On most systems this is the string

4936

'ABCDEFGHIJKLMNOPQRSTUVWXYZ'. Do not change its definition ---

4937

the effect on the routines lower() and

4938

swapcase() is undefined. The specific value is

4939

locale-dependent, and will be updated when

4940

locale.setlocale() is called.

4941

{whitespace}

4942

A string containing all characters that are considered whitespace.

4943

On most systems this includes the characters space, tab, linefeed,

4944

return, formfeed, and vertical tab. Do not change its definition ---

4945

the effect on the routines strip() and split()

4946

is undefined.

4947

Many of the functions provided by this module are also defined as

4948

methods of string and Unicode objects; see ``String Methods'' (section

4949

string-methods) for more information on those.

4950

The functions defined in this module are:

4951

</description>

4952

4953

<description>2.0{Use the float() built-in function.}

4954

Convert a string to a floating point number. The string must have

4955

the standard syntax for a floating point literal in Python,

4956

optionally preceded by a sign (+ or -). Note that

4957

this behaves identical to the built-in function

4958

float()float when passed a string.

4959

When passing in a string, values for NaN</description>

4960

4961

4962

4963

4964

<description>2.0{Use the int() built-in function.}

4965

Convert string s to an integer in the given base. The

4966

string must consist of one or more digits, optionally preceded by a

4967

sign (+ or -). The base defaults to 10. If it

4968

is 0, a default base is chosen depending on the leading characters

4969

of the string (after stripping the sign): 0x or 0X

4970

means 16, 0 means 8, anything else means 10. If base

4971

is 16, a leading 0x or 0X is always accepted, though

4972

not required. This behaves identically to the built-in function

4973

int() when passed a string. (Also note: for a more

4974

flexible interpretation of numeric literals, use the built-in

4975

function eval()eval.)</description>

4976

4977

4978

4979

4980

<description>2.0{Use the long() built-in function.}

4981

Convert string s to a long integer in the given base.

4982

The string must consist of one or more digits, optionally preceded

4983

by a sign (+ or -). The base argument has the

4984

same meaning as for atoi(). A trailing l or

4985

L is not allowed, except if the base is 0. Note that when

4986

invoked without base or with base set to 10, this

4987

behaves identical to the built-in function

4988

long()long when passed a string.</description>

4989

4990

4991

4992

4993

<description>Return a copy of word with only its first character capitalized.</description>

4994

4995

4996

4997

4998

<description>Split the argument into words using split(), capitalize

4999

each word using capitalize(), and join the capitalized

5000

words using join(). Note that this replaces runs of

5001

whitespace characters by a single space, and removes leading and

5002

trailing whitespace.</description>

5003

5004

5005

5006

5007

<description>Expand tabs in a string, i.e. them by one or more spaces,

5008

depending on the current column and the given tab size. The column

5009

number is reset to zero after each newline occurring in the string.

5010

This doesn't understand other non-printing characters or escape

5011

sequences. The tab size defaults to 8.</description>

5012

5013

5014

5015

5016

<description>Return the lowest index in s where the substring sub is

5017

found such that sub is wholly contained in

5018

s[start:end]. Return -1 on failure.

5019

Defaults for start and end and interpretation of

5020

negative values is the same as for slices.</description>

5021

5022

5023

5024

5025

<description>Like find() but find the highest index.</description>

5026

5027

5028

5029

5030

<description>Like find() but raise ValueError when the

5031

substring is not found.</description>

5032

5033

5034

5035

5036

<description>Like rfind() but raise ValueError when the

5037

substring is not found.</description>

5038

5039

5040

5041

5042

<description>Return the number of (non-overlapping) occurrences of substring

5043

sub in string s[start:end].

5044

Defaults for start and end and interpretation of

5045

negative values are the same as for slices.</description>

5046

5047

5048

5049

5050

<description>Return a copy of s, but with upper case letters converted to

5051

lower case.</description>

5052

5053

5054

5055

5056

<description>Return a translation table suitable for passing to

5057

translate() or regex.compile(), that will map

5058

each character in from into the character at the same position

5059

in to; from and to must have the same length.

5060

Don't use strings derived from lowercase

5061

and uppercase as arguments; in some locales, these don't have

5062

the same length. For case conversions, always use

5063

lower() and upper().</description>

5064

5065

5066

5067

5068

<description>Return a list of the words of the string s. If the optional

5069

second argument sep is absent or None, the words are

5070

separated by arbitrary strings of whitespace characters (space, tab, newline, return, formfeed). If the second argument sep is

5071

present and not None, it specifies a string to be used as the word separator. The returned list will then have one more item

5072

than the number of non-overlapping occurrences of the separator in

5073

the string. The optional third argument maxsplit defaults to

5074

0. If it is nonzero, at most maxsplit number of splits occur,

5075

and the remainder of the string is returned as the final element of

5076

the list (thus, the list will have at most maxsplit+1

5077

elements).</description>

5078

5079

5080

5081

5082

<description>Return a list of the words of the string s, scanning s

5083

from the end. To all intents and purposes, the resulting list of

5084

words is the same as returned by split(), except when the

5085

optional third argument maxsplit is explicitly specified and

5086

nonzero. When maxsplit is nonzero, at most maxsplit

5087

number of splits -- the rightmost ones -- occur, and the remainder

5088

of the string is returned as the first element of the list (thus, the

5089

list will have at most maxsplit+1 elements).

5090

New in version 2.4</description>

5091

5092

5093

5094

5095

<description>This function behaves identically to split(). (In the

5096

past, split() was only used with one argument, while

5097

splitfields() was only used with two arguments.)</description>

5098

5099

5100

5101

5102

<description>Concatenate a list or tuple of words with intervening occurrences of sep. The default value for sep is a single space

5103

character. It is always true that

5104

string.join(string.split(s, sep), sep)

5105

equals s.</description>

5106

5107

5108

5109

5110

<description>This function behaves identically to join(). (In the past, join() was only used with one argument, while

5111

joinfields() was only used with two arguments.)

5112

Note that there is no joinfields() method on string

5113

objects; use the join() method instead.</description>

5114

5115

5116

5117

5118

<description>Return a copy of the string with leading characters removed. If

5119

chars is omitted or None, whitespace characters are

5120

removed. If given and not None, chars must be a string;

5121

the characters in the string will be stripped from the beginning of

5122

the string this method is called on.

5123

Changed in version 2.2.3: The chars parameter was added. The chars

5124

parameter cannot be passed in earlier 2.2 versions</description>

5125

5126

5127

5128

5129

<description>Return a copy of the string with trailing characters removed. If

5130

chars is omitted or None, whitespace characters are

5131

removed. If given and not None, chars must be a string;

5132

the characters in the string will be stripped from the end of the

5133

string this method is called on.

5134

Changed in version 2.2.3: The chars parameter was added. The chars

5135

parameter cannot be passed in 2.2 versions</description>

5136

5137

5138

5139

5140

<description>Return a copy of the string with leading and trailing characters

5141

removed. If chars is omitted or None, whitespace

5142

characters are removed. If given and not None, chars

5143

must be a string; the characters in the string will be stripped from

5144

the both ends of the string this method is called on.

5145

Changed in version 2.2.3: The chars parameter was added. The chars

5146

parameter cannot be passed in earlier 2.2 versions</description>

5147

5148

5149

5150

5151

<description>Return a copy of s, but with lower case letters

5152

converted to upper case and vice versa.</description>

5153

5154

5155

5156

5157

<description>Delete all characters from s that are in deletechars (if present), and then translate the characters using table, which must be a 256-character string giving the translation for each

5158

character value, indexed by its ordinal.</description>

5159

5160

5161

5162

5163

<description>Return a copy of s, but with lower case letters converted to

5164

upper case.</description>

5165

5166

5167

5168

5169

<description>rjust{s, width}

5170

center{s, width}

5171

These functions respectively left-justify, right-justify and center

5172

a string in a field of given width. They return a string that is at

5173

least width characters wide, created by padding the string

5174

s with spaces until the given width on the right, left or both

5175

sides. The string is never truncated.</description>

5176

5177

5178

5179

5180

<description>Pad a numeric string on the left with zero digits until the given

5181

width is reached. Strings starting with a sign are handled

5182

correctly.</description>

5183

5184

5185

5186

5187

<description>Return a copy of string str with all occurrences of substring

5188

old replaced by new. If the optional argument

5189

maxreplace is given, the first maxreplace occurrences are

5190

replaced.</description>

5191

5192

5193

5194

</group>

5195

5196

<description>Regular expression search and match operations with a

5197

Perl-style expression syntax.

5198

This module provides regular expression matching operations similar to

5199

those found in Perl. Regular expression pattern strings may not

5200

contain null bytes, but can specify the null byte using the

5201

\number notation. Both patterns and strings to be

5202

searched can be Unicode strings as well as 8-bit strings. The

5203

re module is always available.

5204

Regular expressions use the backslash character (\) to

5205

indicate special forms or to allow special characters to be used

5206

without invoking their special meaning. This collides with Python's

5207

usage of the same character for the same purpose in string literals;

5208

for example, to match a literal backslash, one might have to write

5209

'\e\e' as the pattern string, because the regular expression

5210

must be \e, and each backslash must be expressed as

5211

\e inside a regular Python string literal.

5212

The solution is to use Python's raw string notation for regular

5213

expression patterns; backslashes are not handled in any special way in

5214

a string literal prefixed with r. So r"\n" is a

5215

two-character string containing \ and n,

5216

while "\n" is a one-character string containing a newline.

5217

Usually patterns will be expressed in Python code using this raw

5218

string notation.

5219

See also Mastering Regular Expressions - Book on regular expressions

5220

by Jeffrey Friedl, published by O'Reilly. The second edition of the book no longer covers Python at all, but the first edition covered writing good regular expression

5221

patterns in great detail.

5222

</description>

5223

5224

<description>A regular expression (or RE) specifies a set of strings that matches

5225

it; the functions in this module let you check if a particular string

5226

matches a given regular expression (or if a given regular expression

5227

matches a particular string, which comes down to the same thing).

5228

Regular expressions can be concatenated to form new regular

5229

expressions; if A and B are both regular expressions,

5230

then AB is also a regular expression. In general, if a string

5231

p matches A and another string q matches B,

5232

the string pq will match AB. This holds unless A or

5233

B contain low precedence operations; boundary conditions between

5234

A and B; or have numbered group references. Thus, complex

5235

expressions can easily be constructed from simpler primitive

5236

expressions like the ones described here. For details of the theory

5237

and implementation of regular expressions, consult the Friedl book

5238

referenced above, or almost any textbook about compiler construction.

5239

A brief explanation of the format of regular expressions follows. For

5240

further information and a gentler presentation, consult the Regular

5241

Expression HOWTO, accessible from http://www.python.org/doc/howto/.

5242

Regular expressions can contain both special and ordinary characters.

5243

Most ordinary characters, like A, a, or

5244

0, are the simplest regular expressions; they simply match

5245

themselves. You can concatenate ordinary characters, so last

5246

matches the string 'last'. (In the rest of this section, we'll

5247

write RE's in this special style, usually without quotes, and

5248

strings to be matched 'in single quotes'.)

5249

Some characters, like | or (, are special.

5250

Special characters either stand for classes of ordinary characters, or

5251

affect how the regular expressions around them are interpreted.

5252

The special characters are:

5253

{}{ 0.7in 0.65in}

5254

[.] (Dot.) In the default mode, this matches any

5255

character except a newline. If the DOTALL flag has been

5256

specified, this matches any character including a newline.

5257

[] (Caret.) Matches the start of the

5258

string, and in MULTILINE mode also matches immediately

5259

after each newline.

5260

[$] Matches the end of the string or just before the

5261

newline at the end of the string, and in MULTILINE mode

5262

also matches before a newline. foo matches both 'foo' and

5263

'foobar', while the regular expression foo$ matches only

5264

'foo'. More interestingly, searching for foo.$ in

5265

'foo1 nfoo2 n' matches 'foo2' normally,

5266

but 'foo1' in MULTILINE mode.

5267

[*] Causes the resulting RE to

5268

match 0 or more repetitions of the preceding RE, as many repetitions

5269

as are possible. ab* will

5270

match 'a', 'ab', or 'a' followed by any number of 'b's.

5271

[+] Causes the

5272

resulting RE to match 1 or more repetitions of the preceding RE.

5273

ab+ will match 'a' followed by any non-zero number of 'b's; it

5274

will not match just 'a'.

5275

[?] Causes the resulting RE to

5276

match 0 or 1 repetitions of the preceding RE. ab? will

5277

match either 'a' or 'ab'.

5278

[*?, +?, ??] The *,

5279

+, and ? qualifiers are all greedy; they

5280

match as much text as possible. Sometimes this behaviour isn't

5281

desired; if the RE <.*> is matched against

5282

'<H1>title</H1>', it will match the entire string, and not just

5283

'<H1>'. Adding ? after the qualifier makes it

5284

perform the match in non-greedy or minimal fashion; as

5285

few characters as possible will be matched. Using .*?

5286

in the previous expression will match only '<H1>'.

5287

[{m}]

5288

Specifies that exactly m copies of the previous RE should be

5289

matched; fewer matches cause the entire RE not to match. For example,

5290

a{6} will match exactly six a characters, but

5291

not five.

5292

[{m,n}] Causes the resulting RE to match from

5293

m to n repetitions of the preceding RE, attempting to

5294

match as many repetitions as possible. For example, a{3,5}

5295

will match from 3 to 5 a characters. Omitting m

5296

specifies a lower bound of zero, and omitting n specifies an infinite upper bound. As an

5297

example, a{4,}b will match aaaab or a thousand

5298

a characters followed by a b, but not aaab.

5299

The comma may not be omitted or the modifier would be confused with

5300

the previously described form.

5301

[{m,n}?] Causes the resulting RE to

5302

match from m to n repetitions of the preceding RE,

5303

attempting to match as few repetitions as possible. This is

5304

the non-greedy version of the previous qualifier. For example, on the

5305

6-character string 'aaaaaa', a{3,5} will match 5

5306

a characters, while a{3,5}? will only match 3

5307

characters.

5308

[\] Either escapes special characters (permitting

5309

you to match characters like *, ?, and so

5310

forth), or signals a special sequence; special sequences are discussed

5311

below.

5312

If you're not using a raw string to

5313

express the pattern, remember that Python also uses the

5314

backslash as an escape sequence in string literals; if the escape

5315

sequence isn't recognized by Python's parser, the backslash and

5316

subsequent character are included in the resulting string. However,

5317

if Python would recognize the resulting sequence, the backslash should

5318

be repeated twice. This is complicated and hard to understand, so

5319

it's highly recommended that you use raw strings for all but the

5320

simplest expressions.

5321

[[]] Used to indicate a set of characters. Characters can

5322

be listed individually, or a range of characters can be indicated by

5323

giving two characters and separating them by a -. Special

5324

characters are not active inside sets. For example, [akm]

5325

will match any of the characters a, k,

5326

m, or $; [a-z]

5327

will match any lowercase letter, and [a-zA-Z0-9] matches any

5328

letter or digit. Character classes such as \w or \S

5329

(defined below) are also acceptable inside a range. If you want to

5330

include a ] or a - inside a set, precede it with a

5331

backslash, or place it as the first character. The

5332

pattern []] will match ']', for example.

5333

You can match the characters not within a range by complementing

5334

the set. This is indicated by including a

5335

as the first character of the set;

5336

elsewhere will simply match the

5337

character. For example,

5338

[{}5] will match

5339

any character except 5, and

5340

[] will match any character

5341

except .

5342

[|]A|B, where A and B can be arbitrary REs,

5343

creates a regular expression that will match either A or B. An

5344

arbitrary number of REs can be separated by the | in this

5345

way. This can be used inside groups (see below) as well. As the target

5346

string is scanned, REs separated by | are tried from left to

5347

right. When one pattern completely matches, that branch is accepted.

5348

This means that once A matches, B will not be tested further,

5349

even if it would produce a longer overall match. In other words, the

5350

| operator is never greedy. To match a literal |,

5351

use \, or enclose it inside a character class, as in [|].

5352

[(...)] Matches whatever regular expression is inside the

5353

parentheses, and indicates the start and end of a group; the contents

5354

of a group can be retrieved after a match has been performed, and can

5355

be matched later in the string with the \number special

5356

sequence, described below. To match the literals ( or

5357

), use \ or \, or enclose them

5358

inside a character class: [(] [)].

5359

[(?...)] This is an extension notation (a ?

5360

following a ( is not meaningful otherwise). The first

5361

character after the ?

5362

determines what the meaning and further syntax of the construct is.

5363

Extensions usually do not create a new group;

5364

(?P<name>...) is the only exception to this rule.

5365

Following are the currently supported extensions.

5366

[(?iLmsux)] (One or more letters from the set i,

5367

L, m, s, u,

5368

x.) The group matches the empty string; the letters set

5369

the corresponding flags (re.I, re.L,

5370

re.M, re.S, re.U, re.X)

5371

for the entire regular expression. This is useful if you wish to

5372

include the flags as part of the regular expression, instead of

5373

passing a flag argument to the compile() function.

5374

Note that the (?x) flag changes how the expression is parsed.

5375

It should be used first in the expression string, or after one or more

5376

whitespace characters. If there are non-whitespace characters before

5377

the flag, the results are undefined.

5378

[(?:...)] A non-grouping version of regular parentheses.

5379

Matches whatever regular expression is inside the parentheses, but the

5380

substring matched by the

5381

group cannot be retrieved after performing a match or

5382

referenced later in the pattern.

5383

[(?P<name>...)] Similar to regular parentheses, but

5384

the substring matched by the group is accessible via the symbolic group

5385

name name. Group names must be valid Python identifiers, and

5386

each group name must be defined only once within a regular expression. A

5387

symbolic group is also a numbered group, just as if the group were not

5388

named. So the group named 'id' in the example above can also be

5389

referenced as the numbered group 1.

5390

For example, if the pattern is

5391

(?P<id>[a-zA-Z_]\w*), the group can be referenced by its

5392

name in arguments to methods of match objects, such as

5393

m.group('id') or m.end('id'), and also by name in

5394

pattern text (for example, (?P=id)) and replacement text

5395

(such as \g<id>).

5396

[(?P=name)] Matches whatever text was matched by the

5397

earlier group named name.

5398

[(?)] A comment; the contents of the parentheses are

5399

simply ignored.

5400

[(?=...)] Matches if ... matches next, but doesn't

5401

consume any of the string. This is called a lookahead assertion. For

5402

example, Isaac (?=Asimov) will match 'Isaac~' only if it's

5403

followed by 'Asimov'.

5404

[(?!...)] Matches if ... doesn't match next. This

5405

is a negative lookahead assertion. For example,

5406

Isaac (?!Asimov) will match 'Isaac~' only if it's not

5407

followed by 'Asimov'.

5408

[(?<=...)] Matches if the current position in the string

5409

is preceded by a match for ... that ends at the current

5410

position. This is called a positive lookbehind assertion.

5411

(?<=abc)def will find a match in abcdef, since the

5412

lookbehind will back up 3 characters and check if the contained

5413

pattern matches. The contained pattern must only match strings of

5414

some fixed length, meaning that abc or a|b are

5415

allowed, but a* and a{3,4} are not. Note that

5416

patterns which start with positive lookbehind assertions will never

5417

match at the beginning of the string being searched; you will most

5418

likely want to use the search() function rather than the

5419

match() function:

5420

>>> import re

5421

>>> m = re.search('(?<=abc)def', 'abcdef')

5422

>>> m.group(0)

5423

'def'

5424

This example looks for a word following a hyphen:

5425

>>> m = re.search('(?<=-)+', 'spam-egg')

5426

>>> m.group(0)

5427

'egg'

5428

[(?<!...)] Matches if the current position in the string

5429

is not preceded by a match for .... This is called a

5430

negative lookbehind assertion. Similar to positive lookbehind

5431

assertions, the contained pattern must only match strings of some

5432

fixed length. Patterns which start with negative lookbehind

5433

assertions may match at the beginning of the string being searched.

5434

[(?(id/name)yes-pattern|no-pattern)] Will try to match

5435

with yes-pattern if the group with given id or name

5436

exists, and with no-pattern if it doesn't. |no-pattern

5437

is optional and can be omitted. For example, (<)?(\w+@\w+(?:\.\w+)+)(?(1)>) is a poor email matching

5438

pattern, which will match with '<user@host.com>' as well as

5439

'user@host.com', but not with '<user@host.com'.

5440

New in version 2.4

5441

The special sequences consist of \ and a character from the

5442

list below. If the ordinary character is not on the list, then the

5443

resulting RE will match the second character. For example,

5444

\$ matches the character $.

5445

{}{ 0.7in 0.65in}

5446

[\number] Matches the contents of the group of the

5447

same number. Groups are numbered starting from 1. For example,

5448

(.+) \1 matches 'the the' or '55 55', but not

5449

'the end' (note

5450

the space after the group). This special sequence can only be used to

5451

match one of the first 99 groups. If the first digit of number

5452

is 0, or number is 3 octal digits long, it will not be interpreted

5453

as a group match, but as the character with octal value number.

5454

Inside the [ and ] of a character class, all numeric

5455

escapes are treated as characters.

5456

[\A] Matches only at the start of the string.

5457

[\b] Matches the empty string, but only at the

5458

beginning or end of a word. A word is defined as a sequence of

5459

alphanumeric or underscore characters, so the end of a word is indicated by

5460

whitespace or a non-alphanumeric, non-underscore character. Note that {}\b is defined as the boundary between \w and \W, so the precise set of characters deemed to be alphanumeric depends on the

5461

values of the UNICODE and LOCALE flags. Inside a character

5462

range, \b represents the backspace character, for compatibility

5463

with Python's string literals.

5464

[\B] Matches the empty string, but only when it is not

5465

at the beginning or end of a word. This is just the opposite of {}\b, so is also subject to the settings of LOCALE and UNICODE.

5466

[\d]Matches any decimal digit; this is

5467

equivalent to the set [0-9].

5468

[\D]Matches any non-digit character; this is

5469

equivalent to the set [{}0-9].

5470

[\s]Matches any whitespace character; this is

5471

equivalent to the set [ \t\n\r\f\v].

5472

[\S]Matches any non-whitespace character; this is

5473

equivalent to the set [ t\n\r\f\v].

5474

[\w]When the LOCALE and UNICODE

5475

flags are not specified, matches any alphanumeric character and the

5476

underscore; this is equivalent to the set

5477

[a-zA-Z0-9_]. With LOCALE, it will match the set

5478

[0-9_] plus whatever characters are defined as alphanumeric for

5479

the current locale. If UNICODE is set, this will match the

5480

characters [0-9_] plus whatever is classified as alphanumeric

5481

in the Unicode character properties database.

5482

[\W]When the LOCALE and UNICODE

5483

flags are not specified, matches any non-alphanumeric character; this

5484

is equivalent to the set [{}a-zA-Z0-9_]. With

5485

LOCALE, it will match any character not in the set

5486

[0-9_], and not defined as alphanumeric for the current locale.

5487

If UNICODE is set, this will match anything other than

5488

[0-9_] and characters marked as alphanumeric in the Unicode

5489

character properties database.

5490

[\Z]Matches only at the end of the string.

5491

Most of the standard escapes supported by Python string literals are

5492

also accepted by the regular expression parser:

5493

Octal escapes are included in a limited form: If the first digit is a

5494

0, or if there are three octal digits, it is considered an octal

5495

escape. Otherwise, it is a group reference.

5496

% Note the lack of a period in the section title; it causes problems

5497

% with readers of the GNU info version. See http://www.python.org/sf/581414.

5498

</description>

5499

</group>

5500

5501

<description>Python offers two different primitive operations based on regular

5502

expressions: match and search. If you are accustomed to Perl's

5503

semantics, the search operation is what you're looking for. See the

5504

search() function and corresponding method of compiled

5505

regular expression objects.

5506

Note that match may differ from search using a regular expression

5507

beginning with :

5508

matches only at the

5509

start of the string, or in MULTILINE mode also immediately

5510

following a newline. The ``match'' operation succeeds only if the

5511

pattern matches at the start of the string regardless of mode, or at

5512

the starting position given by the optional pos argument

5513

regardless of whether a newline precedes it.

5514

% Examples from Tim Peters:

5515

re.compile("a").match("ba", 1) # succeeds

5516

re.compile("^a").search("ba", 1) # fails; 'a' not at start

5517

re.compile("^a").search("", 1) # fails; 'a' not at start

5518

re.compile("^a", re.M).search("", 1) # succeeds

5519

re.compile("^a", re.M).search("ba", 1) # fails; no preceding </description>

5520

</group>

5521

5522

<description>Contents of Module re

5523

The module defines the following functions and constants, and an exception:

5524

</description>

5525

5526

<description>Compile a regular expression pattern into a regular expression

5527

object, which can be used for matching using its match() and

5528

search() methods, described below.

5529

The expression's behaviour can be modified by specifying a

5530

flags value. Values can be any of the following variables,

5531

combined using bitwise OR (the | operator).

5532

The sequence

5533

prog = re.compile(pat)

5534

result = prog.match(str)

5535

is equivalent to

5536

result = re.match(pat, str)

5537

but the version using compile() is more efficient when the

5538

expression will be used several times in a single program.

5539

%(The compiled version of the last pattern passed to

5540

%re.match() or re.search() is cached, so

5541

%programs that use only a single regular expression at a time needn't

5542

%worry about compiling regular expressions.)</description>

5543

5544

5545

5546

5547

<description>Scan through string looking for a location where the regular

5548

expression pattern produces a match, and return a

5549

corresponding MatchObject instance.

5550

Return None if no

5551

position in the string matches the pattern; note that this is

5552

different from finding a zero-length match at some point in the string.</description>

5553

5554

5555

5556

5557

<description>If zero or more characters at the beginning of string match

5558

the regular expression pattern, return a corresponding

5559

MatchObject instance. Return None if the string does not

5560

match the pattern; note that this is different from a zero-length

5561

match.

5562

If you want to locate a match anywhere in

5563

string, use search() instead.</description>

5564

5565

5566

5567

5568

<description>Split string by the occurrences of pattern. If

5569

capturing parentheses are used in pattern, then the text of all

5570

groups in the pattern are also returned as part of the resulting list.

5571

If maxsplit is nonzero, at most maxsplit splits

5572

occur, and the remainder of the string is returned as the final

5573

element of the list. (Incompatibility note: in the original Python

5574

1.5 release, maxsplit was ignored. This has been fixed in

5575

later releases.)

5576

>>> re.split('+', 'Words, words, words.')

5577

['Words', 'words', 'words', '']

5578

>>> re.split('(+)', 'Words, words, words.')

5579

['Words', ', ', 'words', ', ', 'words', '.', '']

5580

>>> re.split('+', 'Words, words, words.', 1)

5581

['Words', 'words, words.']

5582

This function combines and extends the functionality of

5583

the old regsub.split() and regsub.splitx().</description>

5584

5585

5586

5587

5588

<description>Return a list of all non-overlapping matches of pattern in

5589

string. If one or more groups are present in the pattern,

5590

return a list of groups; this will be a list of tuples if the

5591

pattern has more than one group. Empty matches are included in the

5592

result unless they touch the beginning of another match.

5593

New in version 1.5.2</description>

5594

5595

5596

5597

5598

<description>Return an iterator over all non-overlapping matches for the RE

5599

pattern in string. For each match, the iterator returns

5600

a match object. Empty matches are included in the result unless they

5601

touch the beginning of another match.

5602

New in version 2.2</description>

5603

5604

5605

5606

5607

<description>Return the string obtained by replacing the leftmost non-overlapping

5608

occurrences of pattern in string by the replacement

5609

repl. If the pattern isn't found, string is returned

5610

unchanged. repl can be a string or a function; if it is a

5611

string, any backslash escapes in it are processed. That is,

5612

\n is converted to a single newline character, \r

5613

is converted to a linefeed, and so forth. Unknown escapes such as

5614

\j are left alone. Backreferences, such as \, are

5615

replaced with the substring matched by group 6 in the pattern. For

5616

example:

5617

>>> re.sub(r'def+([a-zA-Z_][a-zA-Z_0-9]*)**'static PyObject*_)',

5618

... 'def myfunc():')

5619

'static PyObject*_myfunc(void)'

5620

If repl is a function, it is called for every non-overlapping

5621

occurrence of pattern. The function takes a single match

5622

object argument, and returns the replacement string. For example:

5623

>>> def dashrepl(matchobj):

5624

.... if matchobj.group(0) == '-': return ' '

5625

.... else: return '-'

5626

>>> re.sub('-{1,2}', dashrepl, 'pro----gram-files')

5627

'pro--gram files'

5628

The pattern may be a string or an RE object; if you need to specify

5629

regular expression flags, you must use a RE object, or use embedded

5630

modifiers in a pattern; for example, sub("(?i)b+", "x", "bbbb

5631

BBBB") returns 'x x'.

5632

The optional argument count is the maximum number of pattern

5633

occurrences to be replaced; count must be a non-negative

5634

integer. If omitted or zero, all occurrences will be replaced.

5635

Empty matches for the pattern are replaced only when not adjacent to

5636

a previous match, so sub('x*', '-', 'abc') returns

5637

'-a-b-c-'.

5638

In addition to character escapes and backreferences as described

5639

above, \g<name> will use the substring matched by the group

5640

named name, as defined by the (?P<name>...) syntax.

5641

\g<number> uses the corresponding group number;

5642

\g<2> is therefore equivalent to \2, but isn't

5643

ambiguous in a replacement such as \g<2>0. \20

5644

would be interpreted as a reference to group 20, not a reference to

5645

group 2 followed by the literal character 0. The

5646

backreference \g<0> substitutes in the entire substring

5647

matched by the R</description>

5648

5649

5650

5651

5652

<description>Perform the same operation as sub(), but return a tuple

5653

(new_string, number_of_subs_made).</description>

5654

5655

5656

5657

5658

<description>Return string with all non-alphanumerics backslashed; this is

5659

useful if you want to match an arbitrary literal string that may have

5660

regular expression metacharacters in it.</description>

5661

5662

5663

5664

</group>

5665

5666

<description>Compiled regular expression objects support the following methods and

5667

attributes:

5668

</description>

5669

5670

<description>If zero or more characters at the beginning of string match

5671

this regular expression, return a corresponding

5672

MatchObject instance. Return None if the string does not

5673

match the pattern; note that this is different from a zero-length

5674

match.

5675

If you want to locate a match anywhere in

5676

string, use search() instead.

5677

The optional second parameter pos gives an index in the string

5678

where the search is to start; it defaults to 0. This is not

5679

completely equivalent to slicing the string; the

5680

'' pattern

5681

character matches at the real beginning of the string and at positions

5682

just after a newline, but not necessarily at the index where the search

5683

is to start.

5684

The optional parameter endpos limits how far the string will

5685

be searched; it will be as if the string is endpos characters

5686

long, so only the characters from pos to endpos -

5687

1 will be searched for a match. If endpos is less than

5688

pos, no match will be found, otherwise, if rx is a

5689

compiled regular expression object,

5690

rx.match(string, 0, 50) is equivalent to

5691

rx.match(string[:50], 0).</description>

5692

5693

5694

5695

5696

<description>Scan through string looking for a location where this regular

5697

expression produces a match, and return a

5698

corresponding MatchObject instance. Return None if no

5699

position in the string matches the pattern; note that this is

5700

different from finding a zero-length match at some point in the string.

5701

The optional pos and endpos parameters have the same

5702

meaning as for the match() method.</description>

5703

5704

5705

5706

5707

<description>Identical to the split() function, using the compiled pattern.</description>

5708

5709

5710

5711

5712

<description>Identical to the findall() function, using the compiled pattern.</description>

5713

5714

5715

5716

5717

<description>Identical to the finditer() function, using the compiled pattern.</description>

5718

5719

5720

5721

5722

<description>Identical to the sub() function, using the compiled pattern.</description>

5723

5724

5725

5726

5727

<description>Identical to the subn() function, using the compiled pattern.</description>

5728

5729

5730

5731

</group>

5732

5733

<description>MatchObject instances support the following methods and

5734

attributes:

5735

</description>

5736

5737

<description>Return the string obtained by doing backslash substitution on the

5738

template string template, as done by the sub() method.

5739

Escapes such as \n are converted to the appropriate

5740

characters, and numeric backreferences (\1, \2) and

5741

named backreferences (\g<1>, \g<name>) are replaced

5742

by the contents of the corresponding group.</description>

5743

5744

5745

5746

5747

<description>Returns one or more subgroups of the match. If there is a single

5748

argument, the result is a single string; if there are

5749

multiple arguments, the result is a tuple with one item per argument.

5750

Without arguments, group1 defaults to zero (the whole match

5751

is returned).

5752

If a groupN argument is zero, the corresponding return value is the

5753

entire matching string; if it is in the inclusive range [1..99], it is

5754

the string matching the corresponding parenthesized group. If a

5755

group number is negative or larger than the number of groups defined

5756

in the pattern, an IndexError exception is raised.

5757

If a group is contained in a part of the pattern that did not match,

5758

the corresponding result is None. If a group is contained in a

5759

part of the pattern that matched multiple times, the last match is

5760

returned.

5761

If the regular expression uses the (?P<name>...) syntax,

5762

the groupN arguments may also be strings identifying groups by

5763

their group name. If a string argument is not used as a group name in

5764

the pattern, an IndexError exception is raised.

5765

A moderately complicated example:

5766

m = re.match(r"(?P<int>+)*)", '3.14')

5767

After performing this match, m.group(1) is '3', as is

5768

m.group('int'), and m.group(2) is '14'.</description>

5769

5770

5771

5772

5773

<description>Return a tuple containing all the subgroups of the match, from 1 up to

5774

however many groups are in the pattern. The default argument is

5775

used for groups that did not participate in the match; it defaults to

5776

None. (Incompatibility note: in the original Python 1.5

5777

release, if the tuple was one element long, a string would be returned

5778

instead. In later versions (from 1.5.1 on), a singleton tuple is

5779

returned in such cases.)</description>

5780

5781

5782

5783

5784

<description>Return a dictionary containing all the named subgroups of the

5785

match, keyed by the subgroup name. The default argument is

5786

used for groups that did not participate in the match; it defaults to

5787

None.</description>

5788

5789

5790

5791

5792

<description>end{group}

5793

Return the indices of the start and end of the substring

5794

matched by group; group defaults to zero (meaning the whole

5795

matched substring).

5796

Return -1 if group exists but

5797

did not contribute to the match. For a match object

5798

m, and a group g that did contribute to the match, the

5799

substring matched by group g (equivalent to

5800

m.group(g)) is

5801

m.string[m.start(g):m.end(g)]

5802

Note that

5803

m.start(group) will equal m.end(group) if

5804

group matched a null string. For example, after m =

5805

re.search('b(c?)', 'cba'), m.start(0) is 1,

5806

m.end(0) is 2, m.start(1) and

5807

m.end(1) are both 2, and m.start(2) raises

5808

an IndexError exception.</description>

5809

5810

5811

5812

5813

<description>For MatchObject m, return the 2-tuple

5814

(m.start(group), m.end(group)).

5815

Note that if group did not contribute to the match, this is

5816

(-1, -1). Again, group defaults to zero.</description>

5817

5818

5819

5820

</group>

5821

5822

</group>

5823

</group>

5824

5825

<description>Interpret strings as packed binary data.

5826

packing{binary}{data}

5827

This module performs conversions between Python values and C

5828

structs represented as Python strings. It uses format strings

5829

(explained below) as compact descriptions of the lay-out of the C

5830

structs and the intended conversion to/from Python values. This can

5831

be used in handling binary data stored in files or from network

5832

connections, among other sources.

5833

The module defines the following exception and functions:

5834

{error}

5835

Exception raised on various occasions; argument is a string

5836

describing what is wrong.

5837

</description>

5838

5839

<description>Return a string containing the values

5840

v1, v2, ... packed according to the given

5841

format. The arguments must match the values required by the format

5842

exactly.</description>

5843

5844

5845

5846

5847

<description>Unpack the string (presumably packed by pack(fmt,

5848

...)) according to the given format. The result is a

5849

tuple even if it contains exactly one item. The string must contain

5850

exactly the amount of data required by the format

5851

(len(string) must equal calcsize(fmt)).</description>

5852

5853

5854

5855

5856

<description>Return the size of the struct (and hence of the string)

5857

corresponding to the given format.</description>

5858

5859

5860

5861

</group>

5862

5863

<description>Helpers for computing differences between objects.

5864

% LaTeXification by Fred L. Drake, Jr. <fdrake@acm.org>.

5865

New in version 2.1

5866

{SequenceMatcher}

5867

This is a flexible class for comparing pairs of sequences of any

5868

type, so long as the sequence elements are hashable. The basic

5869

algorithm predates, and is a little fancier than, an algorithm

5870

published in the late 1980's by Ratcliff and Obershelp under the

5871

hyperbolic name ``gestalt pattern matching.'' The idea is to find

5872

the longest contiguous matching subsequence that contains no

5873

``junk'' elements (the Ratcliff and Obershelp algorithm doesn't

5874

address junk). The same idea is then applied recursively to the

5875

pieces of the sequences to the left and to the right of the matching

5876

subsequence. This does not yield minimal edit sequences, but does

5877

tend to yield matches that ``look right'' to people.

5878

Timing: The basic Ratcliff-Obershelp algorithm is cubic

5879

time in the worst case and quadratic time in the expected case.

5880

SequenceMatcher is quadratic time for the worst case and has

5881

expected-case behavior dependent in a complicated way on how many

5882

elements the sequences have in common; best case time is linear.

5883

{Differ}

5884

This is a class for comparing sequences of lines of text, and

5885

producing human-readable differences or deltas. Differ uses

5886

SequenceMatcher both to compare sequences of lines, and to

5887

compare sequences of characters within similar (near-matching)

5888

lines.

5889

Each line of a Differ delta begins with a two-letter code:

5890

{l|l}{code}{Code}{Meaning}

5891

'- '{line unique to sequence 1}

5892

'+ '{line unique to sequence 2}

5893

' '{line common to both sequences}

5894

'? '{line not present in either input sequence}

5895

Lines beginning with `?~' attempt to guide the eye to

5896

intraline differences, and were not present in either input

5897

sequence. These lines can be confusing if the sequences contain tab

5898

characters.

5899

</description>

5900

5901

<description>Compare a and b (lists of strings); return a

5902

delta (a generator generating the delta lines) in context diff

5903

format.

5904

Context diffs are a compact way of showing just the lines that have

5905

changed plus a few lines of context. The changes are shown in a

5906

before/after style. The number of context lines is set by n

5907

which defaults to three.

5908

By default, the diff control lines (those with *** or ---)

5909

are created with a trailing newline. This is helpful so that inputs created

5910

from file.readlines() result in diffs that are suitable for use

5911

with file.writelines() since both the inputs and outputs have

5912

trailing newlines.

5913

For inputs that do not have trailing newlines, set the lineterm

5914

argument to "" so that the output will be uniformly newline free.

5915

The context diff format normally has a header for filenames and

5916

modification times. Any or all of these may be specified using strings for

5917

fromfile, tofile, fromfiledate, and tofiledate.

5918

The modification times are normally expressed in the format returned by

5919

time.ctime(). If not specified, the strings default to blanks.

5920

Tools/scripts/diff.py is a command-line front-end for this

5921

function.

5922

New in version 2.3</description>

5923

5924

5925

5926

5927

<description>Return a list of the best ``good enough'' matches. word is a

5928

sequence for which close matches are desired (typically a string),

5929

and possibilities is a list of sequences against which to

5930

match word (typically a list of strings).

5931

Optional argument n (default 3) is the maximum number

5932

of close matches to return; n must be greater than 0.

5933

Optional argument cutoff (default 0.6) is a float in

5934

the range [0, 1]. Possibilities that don't score at least that

5935

similar to word are ignored.

5936

The best (no more than n) matches among the possibilities are

5937

returned in a list, sorted by similarity score, most similar first.

5938

>>> get_close_matches('appel', ['ape', 'apple', 'peach', 'puppy'])

5939

['apple', 'ape']

5940

>>> import keyword

5941

>>> get_close_matches('wheel', keyword.kwlist)

5942

['while']

5943

>>> get_close_matches('apple', keyword.kwlist)

5944

[]

5945

>>> get_close_matches('accept', keyword.kwlist)

5946

['except']

5947

</description>

5948

5949

5950

5951

5952

<description>Compare a and b (lists of strings); return a

5953

Differ-style delta (a generator generating the delta lines).

5954

Optional keyword parameters linejunk and charjunk are

5955

for filter functions (or None):

5956

linejunk: A function that accepts a single string

5957

argument, and returns true if the string is junk, or false if not.

5958

The default is (None), starting with Python 2.3. Before then,

5959

the default was the module-level function

5960

IS_LINE_JUNK(), which filters out lines without visible

5961

characters, except for at most one pound character (#).

5962

As of Python 2.3, the underlying SequenceMatcher class

5963

does a dynamic analysis of which lines are so frequent as to

5964

constitute noise, and this usually works better than the pre-2.3

5965

default.

5966

charjunk: A function that accepts a character (a string of

5967

length 1), and returns if the character is junk, or false if not.

5968

The default is module-level function IS_CHARACTER_JUNK(),

5969

which filters out whitespace characters (a blank or tab; note: bad

5970

idea to include newline in this!).

5971

Tools/scripts/ndiff.py is a command-line front-end to this

5972

function.

5973

>>> diff = ndiff('one'.splitlines(1),

5974

... 'ore'.splitlines(1))

5975

>>> print ''.join(diff),

5976

- one

5977

? ^

5978

+ ore

5979

? ^

5980

- two

5981

- three

5982

? -

5983

+ tree

5984

+ emu

5985

</description>

5986

5987

5988

5989

5990

<description>Return one of the two sequences that generated a delta.

5991

Given a sequence produced by Differ.compare() or

5992

ndiff(), extract lines originating from file 1 or 2

5993

(parameter which), stripping off line prefixes.

5994

Example:

5995

>>> diff = ndiff('one'.splitlines(1),

5996

... 'ore'.splitlines(1))

5997

>>> diff = list(diff) # materialize the generated delta into a list

5998

>>> print ''.join(restore(diff, 1)),

5999

one

6000

two

6001

three

6002

>>> print ''.join(restore(diff, 2)),

6003

ore

6004

tree

6005

emu

6006

</description>

6007

6008

6009

6010

6011

<description>Compare a and b (lists of strings); return a

6012

delta (a generator generating the delta lines) in unified diff

6013

format.

6014

Unified diffs are a compact way of showing just the lines that have

6015

changed plus a few lines of context. The changes are shown in a

6016

inline style (instead of separate before/after blocks). The number

6017

of context lines is set by n which defaults to three.

6018

By default, the diff control lines (those with ---, +++,

6019

or @@) are created with a trailing newline. This is helpful so

6020

that inputs created from file.readlines() result in diffs

6021

that are suitable for use with file.writelines() since both

6022

the inputs and outputs have trailing newlines.

6023

For inputs that do not have trailing newlines, set the lineterm

6024

argument to "" so that the output will be uniformly newline free.

6025

The context diff format normally has a header for filenames and

6026

modification times. Any or all of these may be specified using strings for

6027

fromfile, tofile, fromfiledate, and tofiledate.

6028

The modification times are normally expressed in the format returned by

6029

time.ctime(). If not specified, the strings default to blanks.

6030

Tools/scripts/diff.py is a command-line front-end for this

6031

function.

6032

New in version 2.3</description>

6033

6034

6035

6036

6037

<description>Return true for ignorable lines. The line line is ignorable

6038

if line is blank or contains a single #,

6039

otherwise it is not ignorable. Used as a default for parameter

6040

linejunk in ndiff() before Python 2.3.</description>

6041

6042

6043

6044

6045

<description>Return true for ignorable characters. The character ch is

6046

ignorable if ch is a space or tab, otherwise it is not

6047

ignorable. Used as a default for parameter charjunk in

6048

ndiff().</description>

6049

6050

6051

6052

6053

<description>The SequenceMatcher class has this constructor:

6054

</description>

6055

6056

<description>Optional argument isjunk must be None (the default) or

6057

a one-argument function that takes a sequence element and returns

6058

true if and only if the element is ``junk'' and should be ignored.

6059

Passing None for b is equivalent to passing

6060

lambda x: 0; in other words, no elements are ignored. For

6061

example, pass:

6062

lambda x: x in " "

6063

if you're comparing lines as sequences of characters, and don't want

6064

to synch up on blanks or hard tabs.

6065

The optional arguments a and b are sequences to be

6066

compared; both default to empty strings. The elements of both

6067

sequences must be hashable.</description>

6068

6069

6070

6071

6072

<description>Set the two sequences to be compared.</description>

6073

6074

6075

6076

6077

<description>Set the first sequence to be compared. The second sequence to be

6078

compared is not changed.</description>

6079

6080

6081

6082

6083

<description>Set the second sequence to be compared. The first sequence to be

6084

compared is not changed.</description>

6085

6086

6087

6088

6089

<description>Find longest matching block in a[alo:ahi]

6090

and b[blo:bhi].

6091

If isjunk was omitted or None,

6092

get_longest_match() returns (i, j,

6093

k) such that a[i:i+k] is equal

6094

to b[j:j+k], where

6095

alo <= i <= i+k <= ahi and

6096

blo <= j <= j+k <= bhi.

6097

For all (i', j', k') meeting those

6098

conditions, the additional conditions

6099

k >= k',

6100

i <= i',

6101

and if i == i', j <= j'

6102

are also met.

6103

In other words, of all maximal matching blocks, return one that

6104

starts earliest in a, and of all those maximal matching blocks

6105

that start earliest in a, return the one that starts earliest

6106

in b.

6107

>>> s = SequenceMatcher(None, " abcd", "abcd abcd")

6108

>>> s.find_longest_match(0, 5, 0, 9)

6109

(0, 4, 5)

6110

If isjunk was provided, first the longest matching block is

6111

determined as above, but with the additional restriction that no

6112

junk element appears in the block. Then that block is extended as

6113

far as possible by matching (only) junk elements on both sides.

6114

So the resulting block never matches on junk except as identical

6115

junk happens to be adjacent to an interesting match.

6116

Here's the same example as before, but considering blanks to be junk.

6117

That prevents ' abcd' from matching the ' abcd' at the

6118

tail end of the second sequence directly. Instead only the

6119

'abcd' can match, and matches the leftmost 'abcd' in

6120

the second sequence:

6121

>>> s = SequenceMatcher(lambda x: x==" ", " abcd", "abcd abcd")

6122

>>> s.find_longest_match(0, 5, 0, 9)

6123

(1, 0, 4)

6124

If no blocks match, this returns (alo, blo, 0).</description>

6125

6126

6127

6128

6129

<description>Return list of triples describing matching subsequences.

6130

Each triple is of the form (i, j, n), and

6131

means that a[i:i+n] ==

6132

b[j:j+n]. The triples are monotonically

6133

increasing in i and j.

6134

The last triple is a dummy, and has the value (len(a),

6135

len(b), 0). It is the only triple with n == 0.

6136

% Explain why a dummy is used!

6137

>>> s = SequenceMatcher(None, "abxcd", "abcd")

6138

>>> s.get_matching_blocks()

6139

[(0, 0, 2), (3, 2, 2), (5, 4, 0)]

6140

</description>

6141

6142

</element>

6143

6144

6145

<description>Return list of 5-tuples describing how to turn a into b.

6146

Each tuple is of the form (tag, i1, i2,

6147

j1, j2). The first tuple has i1 ==

6148

j1 == 0, and remaining tuples have i1 equal to the

6149

i2 from the preceeding tuple, and, likewise, j1 equal to

6150

the previous j2.

6151

The tag values are strings, with these meanings:

6152

{l|l}{code}{Value}{Meaning}

6153

'replace'{a[i1:i2] should be

6154

replaced by b[j1:j2].}

6155

'delete'{a[i1:i2] should be

6156

deleted. Note that j1 == j2 in

6157

this case.}

6158

'insert'{b[j1:j2] should be

6159

inserted at a[i1:i1].

6160

Note that i1 == i2 in this

6161

case.}

6162

'equal'{a[i1:i2] ==

6163

b[j1:j2] (the sub-sequences are

6164

equal).}

6165

For example:

6166

>>> a = "qabxcd"

6167

>>> b = "abycdf"

6168

>>> s = SequenceMatcher(None, a, b)

6169

>>> for tag, i1, i2, j1, j2 in s.get_opcodes():

6170

... print ("%7s a[%d:%d] (%s) b[%d:%d] (%s)" %

6171

... (tag, i1, i2, a[i1:i2], j1, j2, b[j1:j2]))

6172

delete a[0:1] (q) b[0:0] ()

6173

equal a[1:3] (ab) b[0:2] (ab)

6174

replace a[3:4] (x) b[2:3] (y)

6175

equal a[4:6] (cd) b[3:5] (cd)

6176

insert a[6:6] () b[5:6] (f)

6177

</description>

6178

6179

</element>

6180

6181

6182

<description>Return a generator of groups with up to n lines of context.

6183

Starting with the groups returned by get_opcodes(),

6184

this method splits out smaller change clusters and eliminates

6185

intervening ranges which have no changes.

6186

The groups are returned in the same format as get_opcodes().

6187

New in version 2.3</description>

6188

6189

6190

6191

6192

<description>Return a measure of the sequences' similarity as a float in the

6193

range [0, 1].

6194

Where T is the total number of elements in both sequences, and M is

6195

the number of matches, this is 2.0*M / T. Note that this is

6196

1.0 if the sequences are identical, and 0.0 if they

6197

have nothing in common.

6198

This is expensive to compute if get_matching_blocks() or

6199

get_opcodes() hasn't already been called, in which case you

6200

may want to try quick_ratio() or

6201

real_quick_ratio() first to get an upper bound.</description>

6202

6203

</element>

6204

6205

6206

<description>Return an upper bound on ratio() relatively quickly.

6207

This isn't defined beyond that it is an upper bound on

6208

ratio(), and is faster to compute.</description>

6209

6210

</element>

6211

6212

6213

<description>Return an upper bound on ratio() very quickly.

6214

This isn't defined beyond that it is an upper bound on

6215

ratio(), and is faster to compute than either

6216

ratio() or quick_ratio().</description>

6217

6218

</element>

6219

6220

</group>

6221

6222

<description>This example compares two strings, considering blanks to be ``junk:''

6223

>>> s = SequenceMatcher(lambda x: x == " ",

6224

... "private Thread currentThread;",

6225

... "private volatile Thread currentThread;")

6226

ratio() returns a float in [0, 1], measuring the similarity

6227

of the sequences. As a rule of thumb, a ratio() value over

6228

0.6 means the sequences are close matches:

6229

>>> print round(s.ratio(), 3)

6230

0.866

6231

If you're only interested in where the sequences match,

6232

get_matching_blocks() is handy:

6233

>>> for block in s.get_matching_blocks():

6234

... print "a[%d] and b[%d] match for %d elements" % block

6235

a[0] and b[0] match for 8 elements

6236

a[8] and b[17] match for 6 elements

6237

a[14] and b[23] match for 15 elements

6238

a[29] and b[38] match for 0 elements

6239

Note that the last tuple returned by get_matching_blocks() is

6240

always a dummy, (len(a), len(b), 0), and this is

6241

the only case in which the last tuple element (number of elements

6242

matched) is 0.

6243

If you want to know how to change the first sequence into the second,

6244

use get_opcodes():

6245

>>> for opcode in s.get_opcodes():

6246

... print "%6s a[%d:%d] b[%d:%d]" % opcode

6247

equal a[0:8] b[0:8]

6248

insert a[8:8] b[8:17]

6249

equal a[8:14] b[17:23]

6250

equal a[14:29] b[23:38]

6251

See also the function get_close_matches() in this module,

6252

which shows how simple code building on SequenceMatcher can be

6253

used to do useful work.

6254

</description>

6255

</group>

6256

6257

<description>Note that Differ-generated deltas make no claim to be

6258

minimal diffs. To the contrary, minimal diffs are often

6259

counter-intuitive, because they synch up anywhere possible, sometimes

6260

accidental matches 100 pages apart. Restricting synch points to

6261

contiguous matches preserves some notion of locality, at the

6262

occasional cost of producing a longer diff.

6263

The Differ class has this constructor:

6264

</description>

6265

6266

<description>Optional keyword parameters linejunk and charjunk are

6267

for filter functions (or None):

6268

linejunk: A function that accepts a single string

6269

argument, and returns true if the string is junk. The default is

6270

None, meaning that no line is considered junk.

6271

charjunk: A function that accepts a single character argument

6272

(a string of length 1), and returns true if the character is junk.

6273

The default is None, meaning that no character is

6274

considered junk.</description>

6275

6276

6277

6278

6279

<description>Compare two sequences of lines, and generate the delta (a sequence

6280

of lines).

6281

Each sequence must contain individual single-line strings ending

6282

with newlines. Such sequences can be obtained from the

6283

readlines() method of file-like objects. The delta generated

6284

also consists of newline-terminated strings, ready to be printed as-is

6285

via the writelines() method of a file-like object.</description>

6286

6287

6288

6289

</group>

6290

6291

</group>

6292

</group>

6293

6294

<description>General floating point formatting functions.

6295

The fpformat module defines functions for dealing with

6296

floating point numbers representations in 100% pure

6297

Python. This module is unneeded: everything here could

6298

be done via the % string interpolation operator.

6299

The fpformat module defines the following functions and an

6300

exception:

6301

</description>

6302

6303

<description>Format x as [-]ddd.ddd with digs digits after the

6304

point and at least one digit before.

6305

If digs <= 0, the decimal point is suppressed.

6306

x can be either a number or a string that looks like

6307

one. digs is an integer.

6308

Return value is a string.</description>

6309

6310

6311

6312

6313

<description>Format x as [-]d.dddE[+-]ddd with digs digits after the point and exactly one digit before.

6314

If digs <= 0, one digit is kept and the point is suppressed.

6315

x can be either a real number, or a string that looks like

6316

one. digs is an integer.

6317

Return value is a string.</description>

6318

6319

6320

6321

</group>

6322

6323

<description>Read and write strings as if they were files.

6324

This module implements a file-like class, StringIO,

6325

that reads and writes a string buffer (also known as memory

6326

files). See the description of file objects for operations (section

6327

bltin-file-objects).

6328

</description>

6329

6330

<description>When a StringIO object is created, it can be initialized

6331

to an existing string by passing the string to the constructor.

6332

If no string is given, the StringIO will start empty.

6333

The StringIO object can accept either Unicode or 8-bit

6334

strings, but mixing the two may take some care. If both are used,

6335

8-bit strings that cannot be interpreted as 7-bit ASCII (that

6336

use the 8th bit) will cause a UnicodeError to be raised

6337

when getvalue() is called.</description>

6338

6339

6340

6341

6342

<description>Retrieve the entire contents of the ``file'' at any time before the

6343

StringIO object's close() method is called. See the

6344

note above for information about mixing Unicode and 8-bit strings;

6345

such mixing can cause this method to raise UnicodeError.</description>

6346

6347

</element>

6348

6349

6350

<description>Free the memory buffer.</description>

6351

6352

</element>

6353

6354

</group>

6355

6356

<description>Text wrapping and filling

6357

New in version 2.3

6358

The textwrap module provides two convenience functions,

6359

wrap() and fill(), as well as

6360

TextWrapper, the class that does all the work, and a utility function dedent(). If you're just wrapping or filling one or two text strings, the convenience functions should be good enough; otherwise, you should use an instance of TextWrapper for efficiency.

6361

</description>

6362

6363

<description>Wraps the single paragraph in text (a string) so every line is at

6364

most width characters long. Returns a list of output lines,

6365

without final newlines.

6366

Optional keyword arguments correspond to the instance attributes of

6367

TextWrapper, documented below. width defaults to

6368

70.</description>

6369

6370

6371

6372

6373

<description>Wraps the single paragraph in text, and returns a single string

6374

containing the wrapped paragraph. fill() is shorthand for

6375

"".join(wrap(text, ...))

6376

In particular, fill() accepts exactly the same keyword

6377

arguments as wrap().</description>

6378

6379

6380

6381

6382

<description>Remove any whitespace than can be uniformly removed from the left

6383

of every line in text.

6384

This is typically used to make triple-quoted strings line up with

6385

the left edge of screen/whatever, while still presenting it in the

6386

source code in indented form. For example:

6387

def test():

6388

# end first line with avoid the empty line!

6389

s = '''

6390

world

6391

'''

6392

print repr(s) # prints ' hello world '

6393

print repr(dedent(s)) # prints 'hello world'

6394

</description>

6395

6396

6397

6398

6399

<description>The TextWrapper constructor accepts a number of optional

6400

keyword arguments. Each argument corresponds to one instance attribute,

6401

so for example

6402

wrapper = TextWrapper(initial_indent="* ")

6403

is the same as

6404

wrapper = TextWrapper()

6405

wrapper.initial_indent = "* "

6406

You can re-use the same TextWrapper object many times, and you

6407

can change any of its options through direct assignment to instance

6408

attributes between uses.</description>

6409

6410

6411

6412

6413

<description>Wraps the single paragraph in text (a string) so every line is

6414

at most width characters long. All wrapping options are

6415

taken from instance attributes of the TextWrapper instance.

6416

Returns a list of output lines, without final newlines.</description>

6417

6418

6419

6420

6421

<description>Wraps the single paragraph in text, and returns a single string

6422

containing the wrapped paragraph.</description>

6423

6424

6425

6426

</group>

6427

6428

<description>Encode and decode data and streams.

6429

</description>

6430

6431

<description>Register a codec search function. Search functions are expected to

6432

take one argument, the encoding name in all lower case letters, and

6433

return a tuple of functions (encoder, decoder, stream_reader,

6434

stream_writer) taking the following arguments:

6435

encoder and decoder: These must be functions or methods

6436

which have the same interface as the

6437

encode()/decode() methods of Codec instances (see

6438

Codec Interface). The functions/methods are expected to work in a

6439

stateless mode.

6440

stream_reader and stream_writer: These have to be

6441

factory functions providing the following interface:

6442

factory(stream, errors='strict')

6443

The factory functions must return objects providing the interfaces

6444

defined by the base classes StreamWriter and

6445

StreamReader, respectively. Stream codecs can maintain

6446

state.

6447

Possible values for errors are 'strict' (raise an exception

6448

in case of an encoding error), 'replace' (replace malformed

6449

data with a suitable replacement marker, such as ?),

6450

'ignore' (ignore malformed data and continue without further

6451

notice), 'xmlcharrefreplace' (replace with the appropriate XML

6452

character reference (for encoding only)) and 'backslashreplace'

6453

(replace with backslashed escape sequences (for encoding only)) as

6454

well as any other error handling name defined via

6455

register_error().

6456

In case a search function cannot find a given encoding, it should

6457

return None.</description>

6458

6459

6460

6461

6462

<description>Looks up a codec tuple in the Python codec registry and returns the

6463

function tuple as defined above.

6464

Encodings are first looked up in the registry's cache. If not found,

6465

the list of registered search functions is scanned. If no codecs tuple

6466

is found, a LookupError is raised. Otherwise, the codecs

6467

tuple is stored in the cache and returned to the caller.</description>

6468

6469

6470

6471

6472

<description>Lookup up the codec for the given encoding and return its encoder

6473

function.

6474

Raises a LookupError in case the encoding cannot be found.</description>

6475

6476

6477

6478

6479

<description>Lookup up the codec for the given encoding and return its decoder

6480

function.

6481

Raises a LookupError in case the encoding cannot be found.</description>

6482

6483

6484

6485

6486

<description>Lookup up the codec for the given encoding and return its StreamReader

6487

class or factory function.

6488

Raises a LookupError in case the encoding cannot be found.</description>

6489

6490

6491

6492

6493

<description>Lookup up the codec for the given encoding and return its StreamWriter

6494

class or factory function.

6495

Raises a LookupError in case the encoding cannot be found.</description>

6496

6497

6498

6499

6500

<description>Register the error handling function error_handler under the

6501

name name. error_handler will be called during encoding

6502

and decoding in case of an error, when name is specified as the

6503

errors parameter.

6504

For encoding error_handler will be called with a

6505

UnicodeEncodeError instance, which contains information about

6506

the location of the error. The error handler must either raise this or

6507

a different exception or return a tuple with a replacement for the

6508

unencodable part of the input and a position where encoding should

6509

continue. The encoder will encode the replacement and continue encoding

6510

the original input at the specified position. Negative position values

6511

will be treated as being relative to the end of the input string. If the

6512

resulting position is out of bound an IndexError will be raised.

6513

Decoding and translating works similar, except UnicodeDecodeError

6514

or UnicodeTranslateError will be passed to the handler and

6515

that the replacement from the error handler will be put into the output

6516

directly.</description>

6517

6518

6519

6520

6521

<description>Return the error handler previously register under the name name.

6522

Raises a LookupError in case the handler cannot be found.</description>

6523

6524

6525

6526

6527

<description>Implements the strict error handling.</description>

6528

6529

6530

6531

6532

<description>Implements the replace error handling.</description>

6533

6534

6535

6536

6537

<description>Implements the ignore error handling.</description>

6538

6539

6540

6541

6542

<description>Implements the xmlcharrefreplace error handling.</description>

6543

6544

6545

6546

6547

<description>Implements the backslashreplace error handling.</description>

6548

6549

6550

6551

6552

<description>Open an encoded file using the given mode and return

6553

a wrapped version providing transparent encoding/decoding.

6554

The wrapped version will only accept the object format

6555

defined by the codecs, i.e. objects for most built-in

6556

codecs. Output is also codec-dependent and will usually be Unicode as

6557

well.

6558

encoding specifies the encoding which is to be used for the

6559

file.

6560

errors may be given to define the error handling. It defaults

6561

to 'strict' which causes a ValueError to be raised

6562

in case an encoding error occurs.

6563

buffering has the same meaning as for the built-in

6564

open() function. It defaults to line buffered.</description>

6565

6566

6567

6568

6569

<description>Return a wrapped version of file which provides transparent

6570

encoding translation.

6571

Strings written to the wrapped file are interpreted according to the

6572

given input encoding and then written to the original file as

6573

strings using the output encoding. The intermediate encoding will

6574

usually be Unicode but depends on the specified codecs.

6575

If output is not given, it defaults to input.

6576

errors may be given to define the error handling. It defaults to

6577

'strict', which causes ValueError to be raised in case

6578

an encoding error occurs.</description>

6579

6580

6581

6582

6583

<description>The codecs defines a set of base classes which define the

6584

interface and can also be used to easily write you own codecs for use

6585

in Python.

6586

Each codec has to define four interfaces to make it usable as codec in

6587

Python: stateless encoder, stateless decoder, stream reader and stream

6588

writer. The stream reader and writers typically reuse the stateless

6589

encoder/decoder to implement the file protocols.

6590

The Codec class defines the interface for stateless

6591

encoders/decoders.

6592

To simplify and standardize error handling, the encode() and

6593

decode() methods may implement different error handling

6594

schemes by providing the errors string argument. The following

6595

string values are defined and implemented by all standard Python

6596

codecs:

6597

{l|l}{code}{Value}{Meaning}

6598

'strict'{Raise UnicodeError (or a subclass);

6599

this is the default.}

6600

'ignore'{Ignore the character and continue with the next.}

6601

'replace'{Replace with a suitable replacement character;

6602

Python will use the official U+FFFD REPLACEMENT

6603

CHARACTER for the built-in Unicode codecs on

6604

decoding and '?' on encoding.}

6605

'xmlcharrefreplace'{Replace with the appropriate XML

6606

character reference (only for encoding).}

6607

'backslashreplace'{Replace with backslashed escape sequences

6608

(only for encoding).}

6609

The set of allowed values can be extended via register_error.

6610

Codec Objects The Codec class defines these methods which also define the

6611

function interfaces of the stateless encoder and decoder:

6612

</description>

6613

6614

<description>Encodes the object input and returns a tuple (output object,

6615

length consumed). While codecs are not restricted to use with Unicode, in

6616

a Unicode context, encoding converts a Unicode object to a plain string

6617

using a particular character set encoding (e.g., cp1252 or

6618

iso-8859-1).

6619

errors defines the error handling to apply. It defaults to

6620

'strict' handling.

6621

The method may not store state in the Codec instance. Use

6622

StreamCodec for codecs which have to keep state in order to

6623

make encoding/decoding efficient.

6624

The encoder must be able to handle zero length input and return an

6625

empty object of the output object type in this situation.</description>

6626

6627

6628

6629

6630

<description>Decodes the object input and returns a tuple (output object,

6631

length consumed). In a Unicode context, decoding converts a plain string

6632

encoded using a particular character set encoding to a Unicode object.

6633

input must be an object which provides the bf_getreadbuf

6634

buffer slot. Python strings, buffer objects and memory mapped files

6635

are examples of objects providing this slot.

6636

errors defines the error handling to apply. It defaults to

6637

'strict' handling.

6638

The method may not store state in the Codec instance. Use

6639

StreamCodec for codecs which have to keep state in order to

6640

make encoding/decoding efficient.

6641

The decoder must be able to handle zero length input and return an

6642

empty object of the output object type in this situation.</description>

6643

6644

6645

6646

6647

<description>Constructor for a StreamWriter instance. All stream writers must provide this constructor interface. They are

6648

free to add additional keyword arguments, but only the ones defined

6649

here are used by the Python codec registry.

6650

stream must be a file-like object open for writing (binary)

6651

data.

6652

The StreamWriter may implement different error handling

6653

schemes by providing the errors keyword argument. These

6654

parameters are predefined:

6655

'strict' Raise ValueError (or a subclass);

6656

this is the default.

6657

'ignore' Ignore the character and continue with the next.

6658

'replace' Replace with a suitable replacement character

6659

'xmlcharrefreplace' Replace with the appropriate XML

6660

character reference

6661

'backslashreplace' Replace with backslashed escape sequences.

6662

The errors argument will be assigned to an attribute of the

6663

same name. Assigning to this attribute makes it possible to switch

6664

between different error handling strategies during the lifetime

6665

of the StreamWriter object.

6666

The set of allowed values for the errors argument can

6667

be extended with register_error().</description>

6668

6669

6670

6671

6672

<description>Writes the object's contents encoded to the stream.</description>

6673

6674

6675

6676

6677

<description>Writes the concatenated list of strings to the stream (possibly by

6678

reusing the write() method).</description>

6679

6680

6681

6682

6683

<description>Flushes and resets the codec buffers used for keeping state.

6684

Calling this method should ensure that the data on the output is put

6685

into a clean state, that allows appending of new fresh data without

6686

having to rescan the whole stream to recover state.</description>

6687

6688

</element>

6689

6690

6691

<description>Constructor for a StreamReader instance. All stream readers must provide this constructor interface. They are

6692

free to add additional keyword arguments, but only the ones defined

6693

here are used by the Python codec registry.

6694

stream must be a file-like object open for reading (binary)

6695

data.

6696

The StreamReader may implement different error handling

6697

schemes by providing the errors keyword argument. These

6698

parameters are defined:

6699

'strict' Raise ValueError (or a subclass);

6700

this is the default.

6701

'ignore' Ignore the character and continue with the next.

6702

'replace' Replace with a suitable replacement character.

6703

The errors argument will be assigned to an attribute of the

6704

same name. Assigning to this attribute makes it possible to switch

6705

between different error handling strategies during the lifetime

6706

of the StreamReader object.

6707

The set of allowed values for the errors argument can

6708

be extended with register_error().</description>

6709

6710

6711

6712

6713

<description>Decodes data from the stream and returns the resulting object.

6714

size indicates the approximate maximum number of bytes to read

6715

from the stream for decoding purposes. The decoder can modify this

6716

setting as appropriate. The default value -1 indicates to read and

6717

decode as much as possible. size is intended to prevent having

6718

to decode huge files in one step.

6719

The method should use a greedy read strategy meaning that it should

6720

read as much data as is allowed within the definition of the encoding

6721

and the given size, e.g. if optional encoding endings or state

6722

markers are available on the stream, these should be read too.</description>

6723

6724

6725

6726

6727

<description>Read one line from the input stream and return the

6728

decoded data.

6729

Unlike the readlines() method, this method inherits

6730

the line breaking knowledge from the underlying stream's

6731

readline() method -- there is currently no support for line

6732

breaking using the codec decoder due to lack of line buffering.

6733

Sublcasses should however, if possible, try to implement this method

6734

using their own knowledge of line breaking.

6735

size, if given, is passed as size argument to the stream's

6736

readline() method.</description>

6737

6738

6739

6740

6741

<description>Read all lines available on the input stream and return them as list

6742

of lines.

6743

Line breaks are implemented using the codec's decoder method and are

6744

included in the list entries.

6745

sizehint, if given, is passed as size argument to the

6746

stream's read() method.</description>

6747

6748

6749

6750

6751

<description>Resets the codec buffers used for keeping state.

6752

Note that no stream repositioning should take place. This method is

6753

primarily intended to be able to recover from decoding errors.</description>

6754

6755

</element>

6756

6757

6758

<description>Creates a StreamReaderWriter instance.

6759

stream must be a file-like object.

6760

Reader and Writer must be factory functions or classes

6761

providing the StreamReader and StreamWriter interface

6762

resp.

6763

Error handling is done in the same way as defined for the

6764

stream readers and writers.</description>

6765

6766

6767

6768

6769

<description>Creates a StreamRecoder instance which implements a two-way

6770

conversion: encode and decode work on the frontend (the

6771

input to read() and output of write()) while

6772

Reader and Writer work on the backend (reading and

6773

writing to the stream).

6774

You can use these objects to do transparent direct recodings from

6775

e.g.-1 to UTF-8 and back.

6776

stream must be a file-like object.

6777

encode, decode must adhere to the Codec

6778

interface, Reader, Writer must be factory functions or

6779

classes providing objects of the StreamReader and

6780

StreamWriter interface respectively.

6781

encode and decode are needed for the frontend

6782

translation, Reader and Writer for the backend

6783

translation. The intermediate format used is determined by the two

6784

sets of codecs, e.g. the Unicode codecs will use Unicode as

6785

intermediate encoding.

6786

Error handling is done in the same way as defined for the

6787

stream readers and writers.</description>

6788

6789

6790

6791

</group>

6792

6793

<description>Python comes with a number of codecs builtin, either implemented as C

6794

functions, or with dictionaries as mapping tables. The following table

6795

lists the codecs by name, together with a few common aliases, and the

6796

languages for which the encoding is likely used. Neither the list of

6797

aliases nor the list of languages is meant to be exhaustive. Notice

6798

that spelling alternatives that only differ in case or use a hyphen

6799

instead of an underscore are also valid aliases.

6800

Many of the character sets support the same languages. They vary in

6801

individual characters (e.g. whether the EURO SIGN is supported or

6802

not), and in the assignment of characters to code positions. For the

6803

European languages in particular, the following variants typically

6804

exist:

6805

an ISO 8859 codeset

6806

a Microsoft Windows code page, which is typically derived from

6807

a 8859 codeset, but replaces control characters with additional

6808

graphic characters

6809

an IBM EBCDIC code page

6810

an IBM PC code page, which is ASCII compatible

6811

{l|l|l}{textrm}{Codec}{Aliases}{Languages}

6812

ascii

6813

{646, us-ascii}

6814

{English}

6815

cp037

6816

{IBM037, IBM039}

6817

{English}

6818

cp424

6819

{EBCDIC-CP-HE, IBM424}

6820

{Hebrew}

6821

cp437

6822

{437, IBM437}

6823

{English}

6824

cp500

6825

{EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500}

6826

{Western Europe}

6827

cp737

6828

{}

6829

{Greek}

6830

cp775

6831

{IBM775}

6832

{Baltic languages}

6833

cp850

6834

{850, IBM850}

6835

{Western Europe}

6836

cp852

6837

{852, IBM852}

6838

{Central and Eastern Europe}

6839

cp855

6840

{855, IBM855}

6841

{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}

6842

cp856

6843

{}

6844

{Hebrew}

6845

cp857

6846

{857, IBM857}

6847

{Turkish}

6848

cp860

6849

{860, IBM860}

6850

{Portuguese}

6851

cp861

6852

{861, CP-IS, IBM861}

6853

{Icelandic}

6854

cp862

6855

{862, IBM862}

6856

{Hebrew}

6857

cp863

6858

{863, IBM863}

6859

{Canadian}

6860

cp864

6861

{IBM864}

6862

{Arabic}

6863

cp865

6864

{865, IBM865}

6865

{Danish, Norwegian}

6866

cp869

6867

{869, CP-GR, IBM869}

6868

{Greek}

6869

cp874

6870

{}

6871

{Thai}

6872

cp875

6873

{}

6874

{Greek}

6875

cp1006

6876

{}

6877

{Urdu}

6878

cp1026

6879

{ibm1026}

6880

{Turkish}

6881

cp1140

6882

{ibm1140}

6883

{Western Europe}

6884

cp1250

6885

{windows-1250}

6886

{Central and Eastern Europe}

6887

cp1251

6888

{windows-1251}

6889

{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}

6890

cp1252

6891

{windows-1252}

6892

{Western Europe}

6893

cp1253

6894

{windows-1253}

6895

{Greek}

6896

cp1254

6897

{windows-1254}

6898

{Turkish}

6899

cp1255

6900

{windows-1255}

6901

{Hebrew}

6902

cp1256

6903

{windows1256}

6904

{Arabic}

6905

cp1257

6906

{windows-1257}

6907

{Baltic languages}

6908

cp1258

6909

{windows-1258}

6910

{Vietnamese}

6911

latin_1

6912

{iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1}

6913

{West Europe}

6914

iso8859_2

6915

{iso-8859-2, latin2, L2}

6916

{Central and Eastern Europe}

6917

iso8859_3

6918

{iso-8859-3, latin3, L3}

6919

{Esperanto, Maltese}

6920

iso8859_4

6921

{iso-8859-4, latin4, L4}

6922

{Baltic languagues}

6923

iso8859_5

6924

{iso-8859-5, cyrillic}

6925

{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}

6926

iso8859_6

6927

{iso-8859-6, arabic}

6928

{Arabic}

6929

iso8859_7

6930

{iso-8859-7, greek, greek8}

6931

{Greek}

6932

iso8859_8

6933

{iso-8859-8, hebrew}

6934

{Hebrew}

6935

iso8859_9

6936

{iso-8859-9, latin5, L5}

6937

{Turkish}

6938

iso8859_10

6939

{iso-8859-10, latin6, L6}

6940

{Nordic languages}

6941

iso8859_13

6942

{iso-8859-13}

6943

{Baltic languages}

6944

iso8859_14

6945

{iso-8859-14, latin8, L8}

6946

{Celtic languages}

6947

iso8859_15

6948

{iso-8859-15}

6949

{Western Europe}

6950

koi8_r

6951

{}

6952

{Russian}

6953

koi8_u

6954

{}

6955

{Ukrainian}

6956

mac_cyrillic

6957

{maccyrillic}

6958

{Bulgarian, Byelorussian, Macedonian, Russian, Serbian}

6959

mac_greek

6960

{macgreek}

6961

{Greek}

6962

mac_iceland

6963

{maciceland}

6964

{Icelandic}

6965

mac_latin2

6966

{maclatin2, maccentraleurope}

6967

{Central and Eastern Europe}

6968

mac_roman

6969

{macroman}

6970

{Western Europe}

6971

mac_turkish

6972

{macturkish}

6973

{Turkish}

6974

utf_16

6975

{U16, utf16}

6976

{all languages}

6977

utf_16_be

6978

{UTF-16BE}

6979

{all languages (BMP only)}

6980

utf_16_le

6981

{UTF-16LE}

6982

{all languages (BMP only)}

6983

utf_7

6984

{U7}

6985

{all languages}

6986

utf_8

6987

{U8, UTF, utf8}

6988

{all languages}

6989

A number of codecs are specific to Python, so their codec names have

6990

no meaning outside Python. Some of them don't convert from Unicode

6991

strings to byte strings, but instead use the property of the Python

6992

codecs machinery that any bijective function with one argument can be

6993

considered as an encoding.

6994

For the codecs listed below, the result in the ``encoding'' direction

6995

is always a byte string. The result of the ``decoding'' direction is

6996

listed as operand type in the table.

6997

{l|l|l|l}{textrm}{Codec}{Aliases}{Operand type}{Purpose}

6998

base64_codec

6999

{base64, base-64}

7000

{byte string}

7001

{Convert operand to MIME base64}

7002

bz2_codec

7003

{bz2}

7004

{byte string}

7005

{Compress the operand using bz2}

7006

hex_codec

7007

{hex}

7008

{byte string}

7009

{Convert operand to hexadecimal representation, with two

7010

digits per byte}

7011

idna

7012

{}

7013

{Unicode string}

7014

{Implements 3490.

7015

New in version 2.3

7016

See also Curses

13671

Programming with Python - Tutorial material on using curses

13672

with Python, by Andrew Kuchling and Eric Raymond, is

13673

available on the Python Web site.

13674

The Demo/curses/ directory in the Python source

13675

distribution contains some example programs using the

13676

curses bindings provided by this module.

13677

</description>

13678

13679

<description>The module curses defines the following exception:

13680

{error}

13681

Exception raised when a curses library function returns an error.

13682

Whenever x or y arguments to a function

13683

or a method are optional, they default to the current cursor location.

13684

Whenever attr is optional, it defaults to A_NORMAL.

13685

The module curses defines the following functions:

13686

</description>

13687

13688

<description>Returns the output speed of the terminal in bits per second. On

13689

software terminal emulators it will have a fixed high value.

13690

Included for historical reasons; in former times, it was used to write output loops for time delays and occasionally to change

13691

interfaces depending on the line speed.</description>

13692

13693

</element>

13694

13695

13696

<description>Emit a short attention sound.</description>

13697

13698

</element>

13699

13700

13701

<description>Returns true or false, depending on whether the programmer can change

13702

the colors displayed by the terminal.</description>

13703

13704

</element>

13705

13706

13707

<description>Enter cbreak mode. In cbreak mode (sometimes called ``rare'' mode)

13708

normal tty line buffering is turned off and characters are available

13709

to be read one by one. However, unlike raw mode, special characters

13710

(interrupt, quit, suspend, and flow control) retain their effects on

13711

the tty driver and calling program. Calling first raw()

13712

then cbreak() leaves the terminal in cbreak mode.</description>

13713

13714

</element>

13715

13716

13717

<description>Returns the intensity of the red, green, and blue (RGB) components in

13718

the color color_number, which must be between 0 and

13719

COLORS. A 3-tuple is returned, containing the R,G,B values

13720

for the given color, which will be between 0 (no component) and

13721

1000 (maximum amount of component).</description>

13722

13723

13724

13725

13726

<description>Returns the attribute value for displaying text in the specified

13727

color. This attribute value can be combined with

13728

A_STANDOUT, A_REVERSE, and the other

13729

A_* attributes. pair_number() is the

13730

counterpart to this function.</description>

13731

13732

13733

13734

13735

<description>Sets the cursor state. visibility can be set to 0, 1, or 2, for

13736

invisible, normal, or very visible. If the terminal supports the

13737

visibility requested, the previous cursor state is returned;

13738

otherwise, an exception is raised. On many terminals, the ``visible''

13739

mode is an underline cursor and the ``very visible'' mode is a block cursor.</description>

13740

13741

13742

13743

13744

<description>Saves the current terminal mode as the ``program'' mode, the mode when

13745

the running program is using curses. (Its counterpart is the

13746

``shell'' mode, for when the program is not in curses.) Subsequent calls

13747

to reset_prog_mode() will restore this mode.</description>

13748

13749

</element>

13750

13751

13752

<description>Saves the current terminal mode as the ``shell'' mode, the mode when

13753

the running program is not using curses. (Its counterpart is the

13754

``program'' mode, when the program is using curses capabilities.)

13755

Subsequent calls

13756

to reset_shell_mode() will restore this mode.</description>

13757

13758

</element>

13759

13760

13761

<description>Inserts an ms millisecond pause in output.</description>

13762

13763

13764

13765

13766

<description>Update the physical screen. The curses library keeps two data

13767

structures, one representing the current physical screen contents

13768

and a virtual screen representing the desired next state. The

13769

doupdate() ground updates the physical screen to match the

13770

virtual screen.

13771

The virtual screen may be updated by a noutrefresh() call

13772

after write operations such as addstr() have been performed

13773

on a window. The normal refresh() call is simply

13774

noutrefresh() followed by doupdate(); if you have

13775

to update multiple windows, you can speed performance and perhaps

13776

reduce screen flicker by issuing noutrefresh() calls on

13777

all windows, followed by a single doupdate().</description>

13778

13779

</element>

13780

13781

13782

<description>Enter echo mode. In echo mode, each character input is echoed to the

13783

screen as it is entered.</description>

13784

13785

</element>

13786

13787

13788

<description>De-initialize the library, and return terminal to normal status.</description>

13789

13790

</element>

13791

13792

13793

<description>Returns the user's current erase character. Under operating

13794

systems this is a property of the controlling tty of the curses

13795

program, and is not set by the curses library itself.</description>

13796

13797

</element>

13798

13799

13800

<description>The filter() routine, if used, must be called before

13801

initscr() is called. The effect is that, during those

13802

calls, LINES is set to 1; the capabilities clear, cup, cud, cud1,

13803

cuu1, cuu, vpa are disabled; and the home string is set to the value of cr.

13804

The effect is that the cursor is confined to the current line, and so

13805

are screen updates. This may be used for enabling cgaracter-at-a-time line editing without touching the rest of the screen.</description>

13806

13807

</element>

13808

13809

13810

<description>Flash the screen. That is, change it to reverse-video and then change

13811

it back in a short interval. Some people prefer such as `visible bell'

13812

to the audible attention signal produced by beep().</description>

13813

13814

</element>

13815

13816

13817

<description>Flush all input buffers. This throws away any typeahead that has

13818

been typed by the user and has not yet been processed by the program.</description>

13819

13820

</element>

13821

13822

13823

<description>After getch() returns KEY_MOUSE to signal a mouse

13824

event, this method should be call to retrieve the queued mouse event,

13825

represented as a 5-tuple

13826

(id, x, y, z, bstate).

13827

id is an ID value used to distinguish multiple devices,

13828

and x, y, z are the event's coordinates. (z

13829

is currently unused.). bstate is an integer value whose bits

13830

will be set to indicate the type of event, and will be the bitwise OR

13831

of one or more of the following constants, where n is the button

13832

number from 1 to 4:

13833

BUTTONn_PRESSED,

13834

BUTTONn_RELEASED,

13835

BUTTONn_CLICKED,

13836

BUTTONn_DOUBLE_CLICKED,

13837

BUTTONn_TRIPLE_CLICKED,

13838

BUTTON_SHIFT,

13839

BUTTON_CTRL,

13840

BUTTON_ALT.</description>

13841

13842

</element>

13843

13844

13845

<description>Returns the current coordinates of the virtual screen cursor in y and

13846

x. If leaveok is currently true, then -1,-1 is returned.</description>

13847

13848

</element>

13849

13850

13851

<description>Reads window related data stored in the file by an earlier

13852

putwin() call. The routine then creates and initializes a

13853

new window using that data, returning the new window object.</description>

13854

13855

13856

13857

13858

<description>Returns true if the terminal can display colors; otherwise, it

13859

returns false.</description>

13860

13861

</element>

13862

13863

13864

<description>Returns true if the terminal has insert- and delete- character

13865

capabilities. This function is included for historical reasons only,

13866

as all modern software terminal emulators have such capabilities.</description>

13867

13868

</element>

13869

13870

13871

<description>Returns true if the terminal has insert- and

13872

delete-line capabilities, or can simulate them using

13873

scrolling regions. This function is included for historical reasons only,

13874

as all modern software terminal emulators have such capabilities.</description>

13875

13876

</element>

13877

13878

13879

<description>Takes a key value ch, and returns true if the current terminal

13880

type recognizes a key with that value.</description>

13881

13882

13883

13884

13885

<description>Used for half-delay mode, which is similar to cbreak mode in that

13886

characters typed by the user are immediately available to the program.

13887

However, after blocking for tenths tenths of seconds, an

13888

exception is raised if nothing has been typed. The value of

13889

tenths must be a number between 1 and 255. Use

13890

nocbreak() to leave half-delay mode.</description>

13891

13892

13893

13894

13895

<description>Changes the definition of a color, taking the number of the color to

13896

be changed followed by three RGB values (for the amounts of red,

13897

green, and blue components). The value of color_number must be

13898

between 0 and COLORS. Each of r, g,

13899

b, must be a value between 0 and 1000. When

13900

init_color() is used, all occurrences of that color on the

13901

screen immediately change to the new definition. This function is a

13902

no-op on most terminals; it is active only if

13903

can_change_color() returns 1.</description>

13904

13905

13906

13907

13908

<description>Changes the definition of a color-pair. It takes three arguments: the

13909

number of the color-pair to be changed, the foreground color number,

13910

and the background color number. The value of pair_number must

13911

be between 1 and COLOR_PAIRS - 1 (the 0 color

13912

pair is wired to white on black and cannot be changed). The value of

13913

fg and bg arguments must be between 0 and

13914

COLORS. If the color-pair was previously initialized, the

13915

screen is refreshed and all occurrences of that color-pair are changed

13916

to the new definition.</description>

13917

13918

13919

13920

13921

<description>Initialize the library. Returns a WindowObject which represents

13922

the whole screen. If there is an error opening the terminal,

13923

the underlying curses library may cause the interpreter to exit.</description>

13924

13925

</element>

13926

13927

13928

<description>Returns true if endwin() has been called (that is, the curses library has been deinitialized).</description>

13929

13930

</element>

13931

13932

13933

<description>Return the name of the key numbered k. The name of a key

13934

generating printable ASCII character is the key's character. The name

13935

of a control-key combination is a two-character string consisting of a

13936

caret followed by the corresponding printable ASCII character. The

13937

name of an alt-key combination (128-255) is a string consisting of the

13938

prefix `M-' followed by the name of the corresponding ASCII character.</description>

13939

13940

13941

13942

13943

<description>Returns the user's current line kill character. Under operating

13944

systems this is a property of the controlling tty of the curses

13945

program, and is not set by the curses library itself.</description>

13946

13947

</element>

13948

13949

13950

<description>Returns a string containing the terminfo long name field describing the current

13951

terminal. The maximum length of a verbose description is 128

13952

characters. It is defined only after the call to

13953

initscr().</description>

13954

13955

</element>

13956

13957

13958

<description>If yes is 1, allow 8-bit characters to be input. If yes is 0, allow only 7-bit chars.</description>

13959

13960

13961

13962

13963

<description>Sets the maximum time in milliseconds that can elapse between press and

13964

release events in order for them to be recognized as a click, and

13965

returns the previous interval value. The default value is 200 msec,

13966

or one fifth of a second.</description>

13967

13968

13969

13970

13971

<description>Sets the mouse events to be reported, and returns a tuple

13972

(availmask, oldmask). availmask indicates which of the

13973

specified mouse events can be reported; on complete failure it returns

13974

0. oldmask is the previous value of the given window's mouse

13975

event mask. If this function is never called, no mouse events are

13976

ever reported.</description>

13977

13978

13979

13980

13981

<description>Sleep for ms milliseconds.</description>

13982

13983

13984

13985

13986

<description>Creates and returns a pointer to a new pad data structure with the

13987

given number of lines and columns. A pad is returned as a

13988

window object.

13989

A pad is like a window, except that it is not restricted by the screen

13990

size, and is not necessarily associated with a particular part of the

13991

screen. Pads can be used when a large window is needed, and only a

13992

part of the window will be on the screen at one time. Automatic

13993

refreshes of pads (such as from scrolling or echoing of input) do not

13994

occur. The refresh() and noutrefresh() methods of a

13995

pad require 6 arguments to specify the part of the pad to be

13996

displayed and the location on the screen to be used for the display.

13997

The arguments are pminrow, pmincol, sminrow, smincol, smaxrow,

13998

smaxcol; the p arguments refer to the upper left corner of the pad

13999

region to be displayed and the s arguments define a clipping box on

14000

the screen within which the pad region is to be displayed.</description>

14001

14002

14003

14004

14005

<description>Return a new window, whose left-upper corner is at (begin_y, begin_x), and whose height/width is nlines/ncols. By default, the window will extend from the specified position to the lower right corner of the screen.</description>

14006

14007

14008

14009

14010

<description>Enter newline mode. This mode translates the return key into newline

14011

on input, and translates newline into return and line-feed on output.

14012

Newline mode is initially on.</description>

14013

14014

</element>

14015

14016

14017

<description>Leave cbreak mode. Return to normal ``cooked'' mode with line buffering.</description>

14018

14019

</element>

14020

14021

14022

<description>Leave echo mode. Echoing of input characters is turned off.</description>

14023

14024

</element>

14025

14026

14027

<description>Leave newline mode. Disable translation of return into newline on

14028

input, and disable low-level translation of newline into

14029

newline/return on output (but this does not change the behavior of

14030

addch('\n'), which always does the equivalent of return and

14031

line feed on the virtual screen). With translation off, curses can

14032

sometimes speed up vertical motion a little; also, it will be able to

14033

detect the return key on input.</description>

14034

14035

</element>

14036

14037

14038

<description>When the noqiflush routine is used, normal flush of input and

14039

output queues associated with the INTR, QUIT and SUSP

14040

characters will not be done. You may want to call

14041

noqiflush() in a signal handler if you want output

14042

to continue as though the interrupt had not occurred, after the

14043

handler exits.</description>

14044

14045

</element>

14046

14047

14048

<description>Leave raw mode. Return to normal ``cooked'' mode with line buffering.</description>

14049

14050

</element>

14051

14052

14053

<description>Returns a tuple (fg, bg) containing the colors for

14054

the requested color pair. The value of pair_number must be

14055

between 0 and COLOR_PAIRS - 1.</description>

14056

14057

14058

14059

14060

<description>Returns the number of the color-pair set by the attribute value

14061

attr. color_pair() is the counterpart to this

14062

function.</description>

14063

14064

14065

14066

14067

<description>Equivalent to tputs(str, 1, putchar); emits the value of a

14068

specified terminfo capability for the current terminal. Note that the

14069

output of putp always goes to standard output.</description>

14070

14071

14072

14073

14074

<description>If flag is false, the effect is the same as calling

14075

noqiflush(). If flag is true, or no argument is

14076

provided, the queues will be flushed when these control characters are

14077

read.</description>

14078

14079

14080

14081

14082

<description>Enter raw mode. In raw mode, normal line buffering and processing of interrupt, quit, suspend, and flow control keys are

14083

turned off; characters are presented to curses input functions one

14084

by one.</description>

14085

14086

</element>

14087

14088

14089

<description>Restores the terminal to ``program'' mode, as previously saved by def_prog_mode().</description>

14090

14091

</element>

14092

14093

14094

<description>Restores the terminal to ``shell'' mode, as previously saved by def_shell_mode().</description>

14095

14096

</element>

14097

14098

14099

<description>Sets the virtual screen cursor to y, x.

14100

If y and x are both -1, then leaveok is set.</description>

14101

14102

14103

14104

14105

<description>Initializes the terminal. termstr is a string giving the

14106

terminal name; if omitted, the value of the TERM environment variable

14107

will be used. fd is the file descriptor to which any

14108

initialization sequences will be sent; if not supplied, the file

14109

descriptor for sys.stdout will be used.</description>

14110

14111

14112

14113

14114

<description>Must be called if the programmer wants to use colors, and before any

14115

other color manipulation routine is called. It is good

14116

practice to call this routine right after initscr().

14117

start_color() initializes eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), and two global

14118

variables in the curses module, COLORS and

14119

COLOR_PAIRS, containing the maximum number of colors and

14120

color-pairs the terminal can support. It also restores the colors on

14121

the terminal to the values they had when the terminal was just turned

14122

on.</description>

14123

14124

</element>

14125

14126

14127

<description>Returns a logical OR of all video attributes supported by the

14128

terminal. This information is useful when a curses program needs

14129

complete control over the appearance of the screen.</description>

14130

14131

</element>

14132

14133

14134

<description>Returns the value of the environment variable TERM, truncated to 14

14135

characters.</description>

14136

14137

</element>

14138

14139

14140

<description>Returns the value of the Boolean capability corresponding to the

14141

terminfo capability name capname. The value -1 is

14142

returned if capname is not a Boolean capability, or 0 if

14143

it is canceled or absent from the terminal description.</description>

14144

14145

14146

14147

14148

<description>Returns the value of the numeric capability corresponding to the

14149

terminfo capability name capname. The value -2 is

14150

returned if capname is not a numeric capability, or -1 if

14151

it is canceled or absent from the terminal description.</description>

14152

14153

14154

14155

14156

<description>Returns the value of the string capability corresponding to the

14157

terminfo capability name capname. None is returned if

14158

capname is not a string capability, or is canceled or absent

14159

from the terminal description.</description>

14160

14161

14162

14163

14164

<description>Instantiates the string str with the supplied parameters, where str should be a parameterized string obtained from the terminfo database. E.g. tparm(tigetstr("cup"), 5, 3) could result in '033[6;4H', the exact result depending on terminal type.</description>

14165

14166

14167

14168

14169

<description>Specifies that the file descriptor fd be used for typeahead

14170

checking. If fd is -1, then no typeahead checking is

14171

done.

14172

The curses library does ``line-breakout optimization'' by looking for

14173

typeahead periodically while updating the screen. If input is found,

14174

and it is coming from a tty, the current update is postponed until

14175

refresh or doupdate is called again, allowing faster response to

14176

commands typed in advance. This function allows specifying a different

14177

file descriptor for typeahead checking.</description>

14178

14179

14180

14181

14182

<description>Returns a string which is a printable representation of the character

14183

ch. Control characters are displayed as a caret followed by the

14184

character, for example as C. Printing

14185

characters are left as they are.</description>

14186

14187

14188

14189

14190

<description>Push ch so the next getch() will return it.

14191

Only one ch can be pushed before getch()

14192

is called.</description>

14193

14194

14195

14196

14197

<description>Push a KEY_MOUSE event onto the input queue, associating

14198

the given state data with it.</description>

14199

14200

14201

14202

14203

<description>If used, this function should be called before initscr() or

14204

newterm are called. When flag is false, the values of

14205

lines and columns specified in the terminfo database will be

14206

used, even if environment variables LINES and

14207

COLUMNS (used by default) are set, or if curses is running in

14208

a window (in which case default behavior would be to use the window

14209

size if LINES and COLUMNS are not set).</description>

14210

14211

14212

14213

14214

<description>Allow use of default values for colors on terminals supporting this

14215

feature. Use this to support transparency in your

14216

application. The default color is assigned to the color number -1.

14217

After calling this function, init_pair(x, curses.COLOR_RED, -1) initializes, for instance,

14218

color pair x to a red foreground color on the default background.</description>

14219

14220

</element>

14221

14222

</group>

14223

14224

<description>Window objects, as returned by initscr() and

14225

newwin() above, have the

14226

following methods:

14227

</description>

14228

14229

<description>A character means a C character (an

14230

ASCII code), rather then a Python character (a string of length 1).

14231

(This note is true whenever the documentation mentions a character.)

14232

The builtin ord() is handy for conveying strings to codes.

14233

Paint character ch at (y, x) with attributes

14234

attr, overwriting any character previously painter at that

14235

location. By default, the character position and attributes are the

14236

current settings for the window object.</description>

14237

14238

14239

14240

14241

<description>Paint at most n characters of the string str at (y, x) with attributes

14242

attr, overwriting anything previously on the display.</description>

14243

14244

14245

14246

14247

<description>Paint the string str at (y, x) with attributes

14248

attr, overwriting anything previously on the display.</description>

14249

14250

14251

14252

14253

<description>Remove attribute attr from the ``background'' set applied to all

14254

writes to the current window.</description>

14255

14256

14257

14258

14259

<description>Add attribute attr from the ``background'' set applied to all

14260

writes to the current window.</description>

14261

14262

14263

14264

14265

<description>Set the ``background'' set of attributes to attr. This set is

14266

initially 0 (no attributes).</description>

14267

14268

14269

14270

14271

<description>Sets the background property of the window to the character ch,

14272

with attributes attr. The change is then applied to every

14273

character position in that window:

14274

The attribute of every character in the window is

14275

changed to the new background attribute.

14276

Wherever the former background character appears,

14277

it is changed to the new background character.

14278

</description>

14279

14280

14281

14282

14283

<description>Sets the window's background. A window's background consists of a

14284

character and any combination of attributes. The attribute part of

14285

the background is combined (OR'ed) with all non-blank characters that

14286

are written into the window. Both the character and attribute parts

14287

of the background are combined with the blank characters. The

14288

background becomes a property of the character and moves with the

14289

character through any scrolling and insert/delete line/character

14290

operations.</description>

14291

14292

14293

14294

14295

<description>Draw a border around the edges of the window. Each parameter specifies the character to use for a specific part of the border; see the table

14296

below for more details. The characters can be specified as integers

14297

or as one-character strings.

14298

A 0 value for any parameter will cause the

14299

default character to be used for that parameter. Keyword parameters

14300

can not be used. The defaults are listed in this table:

14301

{l|l|l}{var}{Parameter}{Description}{Default value}

14302

ls{Left side}{ACS_VLINE}

14303

rs{Right side}{ACS_VLINE}

14304

ts{Top}{ACS_HLINE}

14305

bs{Bottom}{ACS_HLINE}

14306

tl{Upper-left corner}{ACS_ULCORNER}

14307

tr{Upper-right corner}{ACS_URCORNER}

14308

bl{Bottom-left corner}{ACS_BLCORNER}

14309

br{Bottom-right corner}{ACS_BRCORNER}

14310

</description>

14311

14312

14313

14314

14315

<description>Similar to border(), but both ls and rs are

14316

vertch and both ts and {bs} are horch. The default

14317

corner characters are always used by this function.</description>

14318

14319

14320

14321

14322

<description>Like erase(), but also causes the whole window to be repainted

14323

upon next call to refresh().</description>

14324

14325

</element>

14326

14327

14328

<description>If yes is 1, the next call to refresh()

14329

will clear the window completely.</description>

14330

14331

14332

14333

14334

<description>Erase from cursor to the end of the window: all lines below the cursor

14335

are deleted, and then the equivalent of clrtoeol() is performed.</description>

14336

14337

</element>

14338

14339

14340

<description>Erase from cursor to the end of the line.</description>

14341

14342

</element>

14343

14344

14345

<description>Updates the current cursor position of all the ancestors of the window

14346

to reflect the current cursor position of the window.</description>

14347

14348

</element>

14349

14350

14351

<description>Delete any character at (y, x).</description>

14352

14353

14354

14355

14356

<description>Delete the line under the cursor. All following lines are moved up

14357

by 1 line.</description>

14358

14359

</element>

14360

14361

14362

<description>An abbreviation for ``derive window'', derwin() is the same

14363

as calling subwin(), except that begin_y and

14364

begin_x are relative to the origin of the window, rather than

14365

relative to the entire screen. Returns a window object for the

14366

derived window.</description>

14367

14368

14369

14370

14371

<description>Add character ch with attribute attr, and immediately call refresh() on the window.</description>

14372

14373

14374

14375

14376

<description>Tests whether the given pair of screen-relative character-cell

14377

coordinates are enclosed by the given window, returning true or

14378

false. It is useful for determining what subset of the screen

14379

windows enclose the location of a mouse event.</description>

14380

14381

14382

14383

14384

<description>Clear the window.</description>

14385

14386

</element>

14387

14388

14389

<description>Return a tuple (y, x) of co-ordinates of upper-left

14390

corner.</description>

14391

14392

</element>

14393

14394

14395

<description>Get a character. Note that the integer returned does not have to

14396

be in ASCII range: function keys, keypad keys and so on return numbers

14397

higher than 256. In no-delay mode, -1 is returned if there is no input.</description>

14398

14399

14400

14401

14402

<description>Get a character, returning a string instead of an integer, as

14403

getch() does. Function keys, keypad keys and so on return a

14404

multibyte string containing the key name. In no-delay mode, an

14405

exception is raised if there is no input.</description>

14406

14407

14408

14409

14410

<description>Return a tuple (y, x) of the height and width of

14411

the window.</description>

14412

14413

</element>

14414

14415

14416

<description>Returns the beginning coordinates of this window relative to its

14417

parent window into two integer variables y and x. Returns

14418

-1,-1 if this window has no parent.</description>

14419

14420

</element>

14421

14422

14423

<description>Read a string from the user, with primitive line editing capacity.</description>

14424

14425

14426

14427

14428

<description>Return a tuple (y, x) of current cursor position relative to the window's upper-left corner.</description>

14429

14430

</element>

14431

14432

14433

<description>Display a horizontal line starting at (y, x) with

14434

length n consisting of the character ch.</description>

14435

14436

14437

14438

14439

<description>If flag is false, curses no longer considers using the hardware

14440

insert/delete character feature of the terminal; if flag is

14441

true, use of character insertion and deletion is enabled. When curses

14442

is first initialized, use of character insert/delete is enabled by

14443

default.</description>

14444

14445

14446

14447

14448

<description>If called with yes equal to 1, curses will try and use

14449

hardware line editing facilities. Otherwise, line insertion/deletion

14450

are disabled.</description>

14451

14452

14453

14454

14455

<description>If flag is true, any change in the window image

14456

automatically causes the window to be refreshed; you no longer

14457

have to call refresh() yourself. However, it may

14458

degrade performance considerably, due to repeated calls to

14459

wrefresh. This option is disabled by default.</description>

14460

14461

14462

14463

14464

<description>Return the character at the given position in the window. The bottom

14465

8 bits are the character proper, and upper bits are the attributes.</description>

14466

14467

14468

14469

14470

<description>Paint character ch at (y, x) with attributes

14471

attr, moving the line from position x right by one

14472

character.</description>

14473

14474

14475

14476

14477

<description>Inserts nlines lines into the specified window above the current

14478

line. The nlines bottom lines are lost. For negative

14479

nlines, delete nlines lines starting with the one under

14480

the cursor, and move the remaining lines up. The bottom nlines

14481

lines are cleared. The current cursor position remains the same.</description>

14482

14483

14484

14485

14486

<description>Insert a blank line under the cursor. All following lines are moved

14487

down by 1 line.</description>

14488

14489

</element>

14490

14491

14492

<description>Insert a character string (as many characters as will fit on the line)

14493

before the character under the cursor, up to n characters. If n is zero or negative,

14494

the entire string is inserted.

14495

All characters to the right of

14496

the cursor are shifted right, with the rightmost characters on the

14497

line being lost. The cursor position does not change (after moving to

14498

y, x, if specified).</description>

14499

14500

14501

14502

14503

<description>Insert a character string (as many characters as will fit on the line)

14504

before the character under the cursor. All characters to the right of

14505

the cursor are shifted right, with the rightmost characters on the

14506

line being lost. The cursor position does not change (after moving to

14507

y, x, if specified).</description>

14508

14509

14510

14511

14512

<description>Returns a string of characters, extracted from the window starting at

14513

the current cursor position, or at y, x if specified.

14514

Attributes are stripped from the characters. If n is specified,

14515

instr() returns return a string at most n characters

14516

long (exclusive of the trailing NUL).</description>

14517

14518

14519

14520

14521

<description>Returns true if the specified line was modified since the last call to

14522

refresh(); otherwise returns false. Raises a

14523

curses.error exception if line is not valid

14524

for the given window.</description>

14525

14526

14527

14528

14529

<description>Returns true if the specified window was modified since the last call to

14530

refresh(); otherwise returns false.</description>

14531

14532

</element>

14533

14534

14535

<description>If yes is 1, escape sequences generated by some keys (keypad, function keys) will be interpreted by curses.

14536

If yes is 0, escape sequences will be left as is in the input

14537

stream.</description>

14538

14539

14540

14541

14542

<description>If yes is 1, cursor is left where it is on update, instead of

14543

being at ``cursor position.'' This reduces cursor movement where

14544

possible. If possible the cursor will be made invisible.

14545

If yes is 0, cursor will always be at ``cursor position'' after

14546

an update.</description>

14547

14548

14549

14550

14551

<description>Move cursor to (new_y, new_x).</description>

14552

14553

14554

14555

14556

<description>Moves the window inside its parent window. The screen-relative

14557

parameters of the window are not changed. This routine is used to

14558

display different parts of the parent window at the same physical

14559

position on the screen.</description>

14560

14561

14562

14563

14564

<description>Move the window so its upper-left corner is at

14565

(new_y, new_x).</description>

14566

14567

14568

14569

14570

<description>If yes is 1, getch() will be non-blocking.</description>

14571

14572

14573

14574

14575

<description>If yes is 1, escape sequences will not be timed out.

14576

If yes is 0, after a few milliseconds, an escape sequence

14577

will not be interpreted, and will be left in the input stream as is.</description>

14578

14579

14580

14581

14582

<description>Mark for refresh but wait. This function updates the data structure

14583

representing the desired state of the window, but does not force

14584

an update of the physical screen. To accomplish that, call doupdate().</description>

14585

14586

</element>

14587

14588

14589

<description>Overlay the window on top of destwin. The windows need not be

14590

the same size, only the overlapping region is copied. This copy is

14591

non-destructive, which means that the current background character

14592

does not overwrite the old contents of destwin.

14593

To get fine-grained control over the copied region, the second form

14594

of overlay() can be used. sminrow and smincol are

14595

the upper-left coordinates of the source window, and the other variables

14596

mark a rectangle in the destination window.</description>

14597

14598

14599

14600

14601

<description>Overwrite the window on top of destwin. The windows need not be

14602

the same size, in which case only the overlapping region is

14603

copied. This copy is destructive, which means that the current

14604

background character overwrites the old contents of destwin.

14605

To get fine-grained control over the copied region, the second form

14606

of overwrite() can be used. sminrow and smincol are

14607

the upper-left coordinates of the source window, the other variables

14608

mark a rectangle in the destination window.</description>

14609

14610

14611

14612

14613

<description>Writes all data associated with the window into the provided file

14614

object. This information can be later retrieved using the

14615

getwin() function.</description>

14616

14617

14618

14619

14620

<description>Indicates that the num screen lines, starting at line beg,

14621

are corrupted and should be completely redrawn on the next

14622

refresh() call.</description>

14623

14624

14625

14626

14627

<description>Touches the entire window, causing it to be completely redrawn on the

14628

next refresh() call.</description>

14629

14630

</element>

14631

14632

14633

<description>Update the display immediately (sync actual screen with previous

14634

drawing/deleting methods).

14635

The 6 optional arguments can only be specified when the window is a

14636

pad created with newpad(). The additional parameters are

14637

needed to indicate what part of the pad and screen are involved.

14638

pminrow and pmincol specify the upper left-hand corner of the

14639

rectangle to be displayed in the pad. sminrow, smincol,

14640

smaxrow, and smaxcol specify the edges of the rectangle to

14641

be displayed on the screen. The lower right-hand corner of the

14642

rectangle to be displayed in the pad is calculated from the screen

14643

coordinates, since the rectangles must be the same size. Both

14644

rectangles must be entirely contained within their respective

14645

structures. Negative values of pminrow, pmincol,

14646

sminrow, or smincol are treated as if they were zero.</description>

14647

14648

14649

14650

14651

<description>Scroll the screen or scrolling region upward by lines lines.</description>

14652

14653

14654

14655

14656

<description>Controls what happens when the cursor of a window is moved off the

14657

edge of the window or scrolling region, either as a result of a

14658

newline action on the bottom line, or typing the last character

14659

of the last line. If flag is false, the cursor is left

14660

on the bottom line. If flag is true, the window is

14661

scrolled up one line. Note that in order to get the physical

14662

scrolling effect on the terminal, it is also necessary to call

14663

idlok().</description>

14664

14665

14666

14667

14668

<description>Set the scrolling region from line top to line bottom. All

14669

scrolling actions will take place in this region.</description>

14670

14671

14672

14673

14674

<description>Turn off the standout attribute. On some terminals this has the

14675

side effect of turning off all attributes.</description>

14676

14677

</element>

14678

14679

14680

<description>Turn on attribute A_STANDOUT.</description>

14681

14682

</element>

14683

14684

14685

<description>Return a sub-window, whose upper-left corner is at

14686

(begin_y, begin_x), and whose width/height is

14687

ncols/nlines.</description>

14688

14689

14690

14691

14692

<description>Return a sub-window, whose upper-left corner is at

14693

(begin_y, begin_x), and whose width/height is

14694

ncols/nlines.

14695

By default, the sub-window will extend from the

14696

specified position to the lower right corner of the window.</description>

14697

14698

14699

14700

14701

<description>Touches each location in the window that has been touched in any of

14702

its ancestor windows. This routine is called by refresh(),

14703

so it should almost never be necessary to call it manually.</description>

14704

14705

</element>

14706

14707

14708

<description>If called with flag set to true, then syncup() is

14709

called automatically whenever there is a change in the window.</description>

14710

14711

14712

14713

14714

<description>Touches all locations in ancestors of the window that have been changed in the window.</description>

14715

14716

</element>

14717

14718

14719

<description>Sets blocking or non-blocking read behavior for the window. If

14720

delay is negative, blocking read is used (which will wait

14721

indefinitely for input). If delay is zero, then non-blocking

14722

read is used, and -1 will be returned by getch() if no input

14723

is waiting. If delay is positive, then getch() will

14724

block for delay milliseconds, and return -1 if there is still no

14725

input at the end of that time.</description>

14726

14727

14728

14729

14730

<description>Pretend count lines have been changed, starting with line

14731

start.</description>

14732

14733

14734

14735

14736

<description>Pretend the whole window has been changed, for purposes of drawing

14737

optimizations.</description>

14738

14739

</element>

14740

14741

14742

<description>Marks all lines in the window as unchanged since the last call to

14743

refresh().</description>

14744

14745

</element>

14746

14747

14748

<description>Display a vertical line starting at (y, x) with

14749

length n consisting of the character ch.</description>

14750

14751

14752

14753

</group>

14754

14755

<description>The curses module defines the following data members:

14756

{ERR}

14757

Some curses routines that return an integer, such as getch(), return ERR upon failure. {OK}

14758

Some curses routines that return an integer, such as napms(), return OK upon success. {version}

14759

A string representing the current version of the module. Also available as __version__.

14760

Several constants are available to specify character cell attributes:

14761

{l|l}{code}{Attribute}{Meaning}

14762

A_ALTCHARSET{Alternate character set mode.}

14763

A_BLINK{Blink mode.}

14764

A_BOLD{Bold mode.}

14765

A_DIM{Dim mode.}

14766

A_NORMAL{Normal attribute.}

14767

A_STANDOUT{Standout mode.}

14768

A_UNDERLINE{Underline mode.}

14769

Keys are referred to by integer constants with names starting with KEY_. The exact keycaps available are system dependent.

14770

% XXX this table is far too large!

14771

% XXX should this table be alphabetized?

14772

{l|l}{code}{Key constant}{Key}

14773

KEY_MIN{Minimum key value}

14774

KEY_BREAK{ Break key (unreliable) }

14775

KEY_DOWN{ Down-arrow }

14776

KEY_UP{ Up-arrow }

14777

KEY_LEFT{ Left-arrow }

14778

KEY_RIGHT{ Right-arrow }

14779

KEY_HOME{ Home key (upward+left arrow) }

14780

KEY_BACKSPACE{ Backspace (unreliable) }

14781

KEY_F0{ Function keys. Up to 64 function keys are supported. }

14782

KEY_Fn{ Value of function key n }

14783

KEY_DL{ Delete line }

14784

KEY_IL{ Insert line }

14785

KEY_DC{ Delete character }

14786

KEY_IC{ Insert char or enter insert mode }

14787

KEY_EIC{ Exit insert char mode }

14788

KEY_CLEAR{ Clear screen }

14789

KEY_EOS{ Clear to end of screen }

14790

KEY_EOL{ Clear to end of line }

14791

KEY_SF{ Scroll 1 line forward }

14792

KEY_SR{ Scroll 1 line backward (reverse) }

14793

KEY_NPAGE{ Next page }

14794

KEY_PPAGE{ Previous page }

14795

KEY_STAB{ Set tab }

14796

KEY_CTAB{ Clear tab }

14797

KEY_CATAB{ Clear all tabs }

14798

KEY_ENTER{ Enter or send (unreliable) }

14799

KEY_SRESET{ Soft (partial) reset (unreliable) }

14800

KEY_RESET{ Reset or hard reset (unreliable) }

14801

KEY_PRINT{ Print }

14802

KEY_LL{ Home down or bottom (lower left) }

14803

KEY_A1{ Upper left of keypad }

14804

KEY_A3{ Upper right of keypad }

14805

KEY_B2{ Center of keypad }

14806

KEY_C1{ Lower left of keypad }

14807

KEY_C3{ Lower right of keypad }

14808

KEY_BTAB{ Back tab }

14809

KEY_BEG{ Beg (beginning) }

14810

KEY_CANCEL{ Cancel }

14811

KEY_CLOSE{ Close }

14812

KEY_COMMAND{ Cmd (command) }

14813

KEY_COPY{ Copy }

14814

KEY_CREATE{ Create }

14815

KEY_END{ End }

14816

KEY_EXIT{ Exit }

14817

KEY_FIND{ Find }

14818

KEY_HELP{ Help }

14819

KEY_MARK{ Mark }

14820

KEY_MESSAGE{ Message }

14821

KEY_MOVE{ Move }

14822

KEY_NEXT{ Next }

14823

KEY_OPEN{ Open }

14824

KEY_OPTIONS{ Options }

14825

KEY_PREVIOUS{ Prev (previous) }

14826

KEY_REDO{ Redo }

14827

KEY_REFERENCE{ Ref (reference) }

14828

KEY_REFRESH{ Refresh }

14829

KEY_REPLACE{ Replace }

14830

KEY_RESTART{ Restart }

14831

KEY_RESUME{ Resume }

14832

KEY_SAVE{ Save }

14833

KEY_SBEG{ Shifted Beg (beginning) }

14834

KEY_SCANCEL{ Shifted Cancel }

14835

KEY_SCOMMAND{ Shifted Command }

14836

KEY_SCOPY{ Shifted Copy }

14837

KEY_SCREATE{ Shifted Create }

14838

KEY_SDC{ Shifted Delete char }

14839

KEY_SDL{ Shifted Delete line }

14840

KEY_SELECT{ Select }

14841

KEY_SEND{ Shifted End }

14842

KEY_SEOL{ Shifted Clear line }

14843

KEY_SEXIT{ Shifted Dxit }

14844

KEY_SFIND{ Shifted Find }

14845

KEY_SHELP{ Shifted Help }

14846

KEY_SHOME{ Shifted Home }

14847

KEY_SIC{ Shifted Input }

14848

KEY_SLEFT{ Shifted Left arrow }

14849

KEY_SMESSAGE{ Shifted Message }

14850

KEY_SMOVE{ Shifted Move }

14851

KEY_SNEXT{ Shifted Next }

14852

KEY_SOPTIONS{ Shifted Options }

14853

KEY_SPREVIOUS{ Shifted Prev }

14854

KEY_SPRINT{ Shifted Print }

14855

KEY_SREDO{ Shifted Redo }

14856

KEY_SREPLACE{ Shifted Replace }

14857

KEY_SRIGHT{ Shifted Right arrow }

14858

KEY_SRSUME{ Shifted Resume }

14859

KEY_SSAVE{ Shifted Save }

14860

KEY_SSUSPEND{ Shifted Suspend }

14861

KEY_SUNDO{ Shifted Undo }

14862

KEY_SUSPEND{ Suspend }

14863

KEY_UNDO{ Undo }

14864

KEY_MOUSE{ Mouse event has occurred }

14865

KEY_RESIZE{ Terminal resize event }

14866

KEY_MAX{Maximum key value}

14867

On VT100s and their software emulations, such as X terminal emulators,

14868

there are normally at least four function keys (KEY_F1,

14869

KEY_F2, KEY_F3, KEY_F4) available,

14870

and the arrow keys mapped to KEY_UP, KEY_DOWN,

14871

KEY_LEFT and KEY_RIGHT in the obvious way. If

14872

your machine has a PC keybboard, it is safe to expect arrow keys and

14873

twelve function keys (older PC keyboards may have only ten function

14874

keys); also, the following keypad mappings are standard:

14875

{l|l}{kbd}{Keycap}{Constant}

14876

Insert{KEY_IC}

14877

Delete{KEY_DC}

14878

Home{KEY_HOME}

14879

End{KEY_END}

14880

Page Up{KEY_NPAGE}

14881

Page Down{KEY_PPAGE}

14882

The following table lists characters from the alternate character set.

14883

These are inherited from the VT100 terminal, and will generally be available on software emulations such as X terminals. When there

14884

is no graphic available, curses falls back on a crude printable ASCII

14885

approximation.

14886

These are available only after initscr() has been called.

14887

{l|l}{code}{ACS code}{Meaning}

14888

ACS_BBSS{alternate name for upper right corner}

14889

ACS_BLOCK{solid square block}

14890

ACS_BOARD{board of squares}

14891

ACS_BSBS{alternate name for horizontal line}

14892

ACS_BSSB{alternate name for upper left corner}

14893

ACS_BSSS{alternate name for top tee}

14894

ACS_BTEE{bottom tee}

14895

ACS_BULLET{bullet}

14896

ACS_CKBOARD{checker board (stipple)}

14897

ACS_DARROW{arrow pointing down}

14898

ACS_DEGREE{degree symbol}

14899

ACS_DIAMOND{diamond}

14900

ACS_GEQUAL{greater-than-or-equal-to}

14901

ACS_HLINE{horizontal line}

14902

ACS_LANTERN{lantern symbol}

14903

ACS_LARROW{left arrow}

14904

ACS_LEQUAL{less-than-or-equal-to}

14905

ACS_LLCORNER{lower left-hand corner}

14906

ACS_LRCORNER{lower right-hand corner}

14907

ACS_LTEE{left tee}

14908

ACS_NEQUAL{not-equal sign}

14909

ACS_PI{letter pi}

14910

ACS_PLMINUS{plus-or-minus sign}

14911

ACS_PLUS{big plus sign}

14912

ACS_RARROW{right arrow}

14913

ACS_RTEE{right tee}

14914

ACS_S1{scan line 1}

14915

ACS_S3{scan line 3}

14916

ACS_S7{scan line 7}

14917

ACS_S9{scan line 9}

14918

ACS_SBBS{alternate name for lower right corner}

14919

ACS_SBSB{alternate name for vertical line}

14920

ACS_SBSS{alternate name for right tee}

14921

ACS_SSBB{alternate name for lower left corner}

14922

ACS_SSBS{alternate name for bottom tee}

14923

ACS_SSSB{alternate name for left tee}

14924

ACS_SSSS{alternate name for crossover or big plus}

14925

ACS_STERLING{pound sterling}

14926

ACS_TTEE{top tee}

14927

ACS_UARROW{up arrow}

14928

ACS_ULCORNER{upper left corner}

14929

ACS_URCORNER{upper right corner}

14930

ACS_VLINE{vertical line}

14931

The following table lists the predefined colors:

14932

{l|l}{code}{Constant}{Color}

14933

COLOR_BLACK{Black}

14934

COLOR_BLUE{Blue}

14935

COLOR_CYAN{Cyan (light greenish blue)}

14936

COLOR_GREEN{Green}

14937

COLOR_MAGENTA{Magenta (purplish red)}

14938

COLOR_RED{Red}

14939

COLOR_WHITE{White}

14940

COLOR_YELLOW{Yellow}

14941

curses.textpad ---

14942

Text input widget for curses programs

14943

Emacs-like input editing in a curses window.

14944

New in version 1.6

14945

The curses.textpad module provides a Textbox class

14946

that handles elementary text editing in a curses window, supporting a

14947

set of keybindings resembling those of Emacs (thus, also of Netscape

14948

Navigator, BBedit 6.x, FrameMaker, and many other programs). The

14949

module also provides a rectangle-drawing function useful for framing

14950

text boxes or for other purposes.

14951

The module curses.textpad defines the following function:

14952

</description>

14953

14954

<description>Draw a rectangle. The first argument must be a window object; the

14955

remaining arguments are coordinates relative to that window. The

14956

second and third arguments are the y and x coordinates of the upper

14957

left hand corner of the rectangle To be drawn; the fourth and fifth

14958

arguments are the y and x coordinates of the lower right hand corner.

14959

The rectangle will be drawn using VT100/IBM PC forms characters on

14960

terminals that make this possible (including xterm and most other

14961

software terminal emulators). Otherwise it will be drawn with ASCII dashes, vertical bars, and plus signs.</description>

14962

14963

14964

14965

</group>

14966

14967

<description>You can instantiate a Textbox object as follows:

14968

</description>

14969

14970

<description>Return a textbox widget object. The win argument should be a

14971

curses WindowObject in which the textbox is to be contained.

14972

The edit cursor of the textbox is initially located at the upper left

14973

hand corner of the containin window, with coordinates (0, 0).

14974

The instance's stripspaces flag is initially on.</description>

14975

14976

14977

14978

14979

<description>This is the entry point you will normally use. It accepts editing

14980

keystrokes until one of the termination keystrokes is entered. If

14981

validator is supplied, it must be a function. It will be called

14982

for each keystroke entered with the keystroke as a parameter; command

14983

dispatch is done on the result. This method returns the window

14984

contents as a string; whether blanks in the window are included is

14985

affected by the stripspaces member.</description>

14986

14987

14988

14989

14990

<description>Process a single command keystroke. Here are the supported special

14991

keystrokes: {l|l}{kbd}{Keystroke}{Action}

14992

Control-A{Go to left edge of window.}

14993

Control-B{Cursor left, wrapping to previous line if appropriate.}

14994

Control-D{Delete character under cursor.}

14995

Control-E{Go to right edge (stripspaces off) or end of line

14996

(stripspaces on).}

14997

Control-F{Cursor right, wrapping to next line when appropriate.}

14998

Control-G{Terminate, returning the window contents.}

14999

Control-H{Delete character backward.}

15000

Control-J{Terminate if the window is 1 line, otherwise

15001

insert newline.}

15002

Control-K{If line is blank, delete it, otherwise clear to

15003

end of line.}

15004

Control-L{Refresh screen.}

15005

Control-N{Cursor down; move down one line.}

15006

Control-O{Insert a blank line at cursor location.}

15007

Control-P{Cursor up; move up one line.}

15008

Move operations do nothing if the cursor is at an edge where the

15009

movement is not possible. The following synonyms are supported where

15010

possible:

15011

{l|l}{constant}{Constant}{Keystroke}

15012

KEY_LEFT{Control-B}

15013

KEY_RIGHT{Control-F}

15014

KEY_UP{Control-P}

15015

KEY_DOWN{Control-N}

15016

KEY_BACKSPACE{Control-h}

15017

All other keystrokes are treated as a command to insert the given

15018

character and move right (with line wrapping).</description>

15019

15020

15021

15022

15023

<description>This method returns the window contents as a string; whether blanks in

15024

the window are included is affected by the stripspaces

15025

member.</description>

15026

15027

</element>

15028

15029

15030

<description>Wrapper function that initializes curses and calls another function,

15031

func, restoring normal keyboard/screen behavior on error.

15032

The callable object func is then passed the main window 'stdscr'

15033

as its first argument, followed by any other arguments passed to

15034

wrapper().</description>

15035

15036

15037

15038

</group>

15039

</group>

15040

15041

<description>Constants and set-membership functions for

15042

.

15043

New in version 1.6

15044

The curses.ascii module supplies name constants for

15045

ASCII characters and functions to test membership in various

15046

ASCII character classes. The constants supplied are names for

15047

control characters as follows:

15048

{l|l}{constant}{Name}{Meaning}

15049

NUL{}

15050

SOH{Start of heading, console interrupt}

15051

STX{Start of text}

15052

ETX{End of text}

15053

EOT{End of transmission}

15054

ENQ{Enquiry, goes with ACK flow control}

15055

ACK{Acknowledgement}

15056

BEL{Bell}

15057

BS{Backspace}

15058

TAB{Tab}

15059

HT{Alias for TAB: ``Horizontal tab''}

15060

LF{Line feed}

15061

NL{Alias for LF: ``New line''}

15062

VT{Vertical tab}

15063

FF{Form feed}

15064

CR{Carriage return}

15065

SO{Shift-out, begin alternate character set}

15066

SI{Shift-in, resume default character set}

15067

DLE{Data-link escape}

15068

DC1{XON, for flow control}

15069

DC2{Device control 2, block-mode flow control}

15070

DC3{XOFF, for flow control}

15071

DC4{Device control 4}

15072

NAK{Negative acknowledgement}

15073

SYN{Synchronous idle}

15074

ETB{End transmission block}

15075

CAN{Cancel}

15076

EM{End of medium}

15077

SUB{Substitute}

15078

ESC{Escape}

15079

FS{File separator}

15080

GS{Group separator}

15081

RS{Record separator, block-mode terminator}

15082

US{Unit separator}

15083

SP{Space}

15084

DEL{Delete}

15085

Note that many of these have little practical significance in modern

15086

usage. The mnemonics derive from teleprinter conventions that predate

15087

digital computers.

15088

The module supplies the following functions, patterned on those in the

15089

standard C library:

15090

</description>

15091

15092

<description>Checks for an ASCII alphanumeric character; it is equivalent to

15093

isalpha(c) or isdigit(c).</description>

15094

15095

15096

15097

15098

<description>Checks for an ASCII alphabetic character; it is equivalent to

15099

isupper(c) or islower(c).</description>

15100

15101

15102

15103

15104

<description>Checks for a character value that fits in the 7-bit ASCII set.</description>

15105

15106

15107

15108

15109

<description>Checks for an ASCII whitespace character.</description>

15110

15111

15112

15113

15114

<description>Checks for an ASCII control character (in the range 0x00 to 0x1f).</description>

15115

15116

15117

15118

15119

<description>Checks for an ASCII decimal digit, 0 through

15120

9. This is equivalent to c in string.digits.</description>

15121

15122

15123

15124

15125

<description>Checks for ASCII any printable character except space.</description>

15126

15127

15128

15129

15130

<description>Checks for an ASCII lower-case character.</description>

15131

15132

15133

15134

15135

<description>Checks for any ASCII printable character including space.</description>

15136

15137

15138

15139

15140

<description>Checks for any printable ASCII character which is not a space or an

15141

alphanumeric character.</description>

15142

15143

15144

15145

15146

<description>Checks for ASCII white-space characters; space, line feed,

15147

carriage return, form feed, horizontal tab, vertical tab.</description>

15148

15149

15150

15151

15152

<description>Checks for an ASCII uppercase letter.</description>

15153

15154

15155

15156

15157

<description>Checks for an ASCII hexadecimal digit. This is equivalent to

15158

c in string.hexdigits.</description>

15159

15160

15161

15162

15163

<description>Checks for an ASCII control character (ordinal values 0 to 31).</description>

15164

15165

15166

15167

15168

<description>Checks for a non-ASCII character (ordinal values 0x80 and above).</description>

15169

15170

15171

15172

15173

<description>Return the ASCII value corresponding to the low 7 bits of c.</description>

15174

15175

15176

15177

15178

<description>Return the control character corresponding to the given character

15179

(the character bit value is bitwise-anded with 0x1f).</description>

15180

15181

15182

15183

15184

<description>Return the 8-bit character corresponding to the given ASCII character

15185

(the character bit value is bitwise-ored with 0x80).</description>

15186

15187

15188

15189

15190

<description>Return a string representation of the ASCII character c. If

15191

c is printable, this string is the character itself. If the

15192

character is a control character (0x00-0x1f) the string consists of a

15193

caret (^) followed by the corresponding uppercase letter.

15194

If the character is an ASCII delete (0x7f) the string is

15195

''. If the character has its meta bit (0x80) set, the meta

15196

bit is stripped, the preceding rules applied, and

15197

! prepended to the result.</description>

15198

15199

15200

15201

</group>

15202

15203

<description>A panel stack extension that adds depth to curses windows.

15204

Panels are windows with the added feature of depth, so they can be

15205

stacked on top of each other, and only the visible portions of

15206

each window will be displayed. Panels can be added, moved up

15207

or down in the stack, and removed. </description>

15208

15209

<description>The module curses.panel defines the following functions:

15210

</description>

15211

15212

<description>Returns the bottom panel in the panel stack.</description>

15213

15214

</element>

15215

15216

15217

<description>Returns a panel object, associating it with the given window win.</description>

15218

15219

15220

15221

15222

<description>Returns the top panel in the panel stack.</description>

15223

15224

</element>

15225

15226

15227

<description>Updates the virtual screen after changes in the panel stack. This does

15228

not call curses.doupdate(), so you'll have to do this yourself.</description>

15229

15230

</element>

15231

15232

</group>

15233

15234

<description>Panel objects, as returned by new_panel() above, are windows

15235

with a stacking order. There's always a window associated with a

15236

panel which determines the content, while the panel methods are

15237

responsible for the window's depth in the panel stack.

15238

Panel objects have the following methods:

15239

</description>

15240

15241

<description>Returns the panel above the current panel.</description>

15242

15243

</element>

15244

15245

15246

<description>Returns the panel below the current panel.</description>

15247

15248

</element>

15249

15250

15251

<description>Push the panel to the bottom of the stack.</description>

15252

15253

</element>

15254

15255

15256

<description>Returns true if the panel is hidden (not visible), false otherwise.</description>

15257

15258

</element>

15259

15260

15261

<description>Hide the panel. This does not delete the object, it just makes the

15262

window on screen invisible.</description>

15263

15264

</element>

15265

15266

15267

<description>Move the panel to the screen coordinates (y, x).</description>

15268

15269

15270

15271

15272

<description>Change the window associated with the panel to the window win.</description>

15273

15274

15275

15276

15277

<description>Set the panel's user pointer to obj. This is used to associate an

15278

arbitrary piece of data with the panel, and can be any Python object.</description>

15279

15280

15281

15282

15283

<description>Display the panel (which might have been hidden).</description>

15284

15285

</element>

15286

15287

15288

<description>Push panel to the top of the stack.</description>

15289

15290

</element>

15291

15292

15293

<description>Returns the user pointer for the panel. This might be any Python object.</description>

15294

15295

</element>

15296

15297

15298

<description>Returns the window object associated with the panel.</description>

15299

15300

</element>

15301

15302

</group>

15303

</group>

15304

15305

<description>Portable parser for command line options; support both

15306

short and long option names.

15307

This module helps scripts to parse the command line arguments in

15308

sys.argv.

15309

It supports the same conventions as the getopt()

15310

function (including the special meanings of arguments of the form

15311

`-' and `--').

15312

% That's to fool latex2html into leaving the two hyphens alone!

15313

Long options similar to those supported by

15314

GNU software may be used as well via an optional third argument.

15315

This module provides a single function and an exception:

15316

</description>

15317

15318

<description>Parses command line options and parameter list. args is the

15319

argument list to be parsed, without the leading reference to the

15320

running program. Typically, this means sys.argv[1:].

15321

options is the string of option letters that the script wants to

15322

recognize, with options that require an argument followed by a colon

15323

(:; i.e., the same format that getopt() uses).

15324

Unlike GNU getopt(), after a non-option

15325

argument, all further arguments are considered also non-options.

15326

This is similar to the way non-GNU systems work.

15327

long_options, if specified, must be a list of strings with the

15328

names of the long options which should be supported. The leading

15329

'--' characters should not be included in the option

15330

name. Long options which require an argument should be followed by an

15331

equal sign (=). To accept only long options,

15332

options should be an empty string. Long options on the command

15333

line can be recognized so long as they provide a prefix of the option

15334

name that matches exactly one of the accepted options. For example,

15335

it long_options is ['foo', 'frob'], the option

15336

fo will match as foo, but

15337

f will not match uniquely, so GetoptError

15338

will be raised.

15339

The return value consists of two elements: the first is a list of

15340

(option, value) pairs; the second is the list of

15341

program arguments left after the option list was stripped (this is a

15342

trailing slice of args). Each option-and-value pair returned

15343

has the option as its first element, prefixed with a hyphen for short

15344

options (e.g., '-x') or two hyphens for long options (e.g.,

15345

'--long-option'), and the option argument as its second

15346

element, or an empty string if the option has no argument. The

15347

options occur in the list in the same order in which they were found,

15348

thus allowing multiple occurrences. Long and short options may be

15349

mixed.</description>

15350

15351

15352

15353

15354

<description>This function works like getopt(), except that GNU style

15355

scanning mode is used by default. This means that option and

15356

non-option arguments may be intermixed. The getopt()

15357

function stops processing options as soon as a non-option argument is

15358

encountered.

15359

If the first character of the option string is `+', or if the

15360

environment variable POSIXLY_CORRECT is set, then option processing

15361

stops as soon as a non-option argument is encountered.</description>

15362

15363

15364

15365

</group>

15366

15367

<description>Powerful, flexible, extensible, easy-to-use command-line

15368

parsing library.

15369

New in version 2.3

15370

The optparse module is a powerful, flexible, extensible,

15371

easy-to-use command-line parsing library for Python. Using

15372

optparse, you can add intelligent, sophisticated handling of

15373

command-line options to your scripts with very little overhead.

15374

Here's an example of using optparse to add some command-line

15375

options to a simple script:

15376

from optparse import OptionParser

15377

parser = OptionParser()

15378

parser.add_option("-f", "--file", dest="filename",

15379

help="write report to FILE", metavar="FILE")

15380

parser.add_option("-q", "--quiet",

15381

action="store_false", dest="verbose", default=True,

15382

help="don't print status messages to stdout")

15383

(options, args) = parser.parse_args()

15384

With these few lines of code, users of your script can now do the

15385

``usual thing'' on the command-line:

15386

$ <yourscript> -f outfile --quiet

15387

$ <yourscript> -qfoutfile

15388

$ <yourscript> --file=outfile -q

15389

$ <yourscript> --quiet --file outfile

15390

(All of these result in options.filename == "outfile" and

15391

options.verbose == False, just as you might expect.)

15392

Even niftier, users can run one of

15393

$ <yourscript> -h

15394

$ <yourscript> --help

15395

and optparse will print out a brief summary of your script's

15396

options:

15397

usage: <yourscript> [options]

15398

options:

15399

-h, --help show this help message and exit

15400

-fFILE, --file=FILE write report to FILE

15401

-q, --quiet don't print status messages to stdout

15402

That's just a taste of the flexibility optparse gives you in

15403

parsing your command-line.

15404

</description>

15405

15406

<description>The purpose of optparse is to make it very easy to provide the

15407

most standard, obvious, straightforward, and user-friendly user

15408

interface for command-line programs. The optparse

15409

philosophy is heavily influenced by the and GNU toolkits, and

15410

this section is meant to explain that philosophy.

15411

Terminology

15412

First, we need to establish some terminology.

15413

argument

15414

a chunk of text that a user enters on the command-line, and that the

15415

shell passes to execl() or execv(). In

15416

Python, arguments are elements of

15417

sys.argv[1:]. (sys.argv[0] is the name of the program

15418

being executed; in the context of parsing arguments, it's not very

15419

important.) shells also use the term ``word''.

15420

It is occasionally desirable to use an argument list other than

15421

sys.argv[1:], so you should read ``argument'' as ``an element of

15422

sys.argv[1:], or of some other list provided as a substitute for

15423

sys.argv[1:]''.

15424

option

15425

an argument used to supply extra information to guide or customize

15426

the execution of a program. There are many different syntaxes for

15427

options; the traditional syntax is - followed by a

15428

single letter, e.g. -x or -F. Also,

15429

traditional syntax allows multiple options to be merged into a

15430

single argument, e.g. -x -F is equivalent to

15431

-xF. The GNU project introduced followed by a series of hyphen-separated words,

15432

e.g. file or dry-run. These are

15433

the only two option syntaxes provided by optparse.

15434

Some other option syntaxes that the world has seen include:

15435

a hyphen followed by a few letters, e.g. -pf (this is

15436

not the same as multiple options merged into a single

15437

argument.)

15438

a hyphen followed by a whole word, e.g. -file (this is

15439

technically equivalent to the previous syntax, but they aren't

15440

usually seen in the same program.)

15441

a plus sign followed by a single letter, or a few letters,

15442

or a word, e.g. +f, +rgb.

15443

a slash followed by a letter, or a few letters, or a word, e.g.

15444

/f, /file.

15445

optparse does not support these option syntaxes, and it never

15446

will. (If you really want to use one of those option syntaxes, you'll

15447

have to subclass OptionParser and override all the difficult

15448

bits. But please don't! optparse does things the traditional

15449

/GNU way deliberately; the first three are non-standard anywhere,

15450

and the last one makes sense only if you're exclusively targeting

15451

MS-DOS/Windows and/or VMS.)

15452

option argument

15453

an argument that follows an option, is closely associated with that

15454

option, and is consumed from the argument list when the option is.

15455

Often, option arguments may also be included in the same argument as

15456

the option, e.g. :

15457

["-f", "foo"]

15458

may be equivalent to:

15459

["-ffoo"]

15460

(optparse supports this syntax.)

15461

Some options never take an argument. Some options always take an

15462

argument. Lots of people want an ``optional option arguments'' feature,

15463

meaning that some options will take an argument if they see it, and

15464

won't if they don't. This is somewhat controversial, because it makes

15465

parsing ambiguous: if -a and -b are both

15466

options, and -a takes an optional argument, how do we

15467

interpret -ab? optparse does not support optional

15468

option arguments.

15469

positional argument

15470

something leftover in the argument list after options have been

15471

parsed, i.e., after options and their arguments have been parsed and

15472

removed from the argument list.

15473

required option

15474

an option that must be supplied on the command-line. The phrase

15475

``required option'' is an oxymoron; the presence of ``required options''

15476

in a program is usually a sign of careless user interface design.

15477

optparse doesn't prevent you from implementing required

15478

options, but doesn't give you much help with it either. See ``Extending

15479

Examples'' (section~optparse-extending-examples) for two ways to

15480

implement required options with optparse.

15481

For example, consider this hypothetical command-line:

15482

prog -v --report /tmp/report.txt foo bar

15483

-v and report are both options. Assuming

15484

the report option takes one argument,

15485

/tmp/report.txt is an option argument. foo and bar

15486

are positional arguments.

15487

What are options for?

15488

Options are used to provide extra information to tune or customize the

15489

execution of a program. In case it wasn't clear, options should be

15490

optional. A program should be able to run just fine with no

15491

options whatsoever. (Pick a random program from the or GNU

15492

toolsets. Can it run without any options at all and still make sense?

15493

The only exceptions I can think of are find, tar,

15494

and dd---all of which are mutant oddballs that have been

15495

rightly criticized for their non-standard syntax and confusing

15496

interfaces.)

15497

Lots of people want their programs to have ``required options''.

15498

Think about it. If it's required, then it's not optional! If

15499

there is a piece of information that your program absolutely requires

15500

in order to run successfully, that's what positional arguments are

15501

for. (However, if you insist on adding ``required options'' to your

15502

programs, look in ``Extending Examples''

15503

(section~optparse-extending-examples) for two ways of

15504

implementing them with optparse.)

15505

Consider the humble cp utility, for copying files. It

15506

doesn't make much sense to try to copy files without supplying a

15507

destination and at least one source. Hence, cp fails if you

15508

run it with no arguments. However, it has a flexible, useful syntax

15509

that does not rely on options at all:

15510

$ cp SOURCE DEST

15511

$ cp SOURCE ... DEST-DIR

15512

You can get pretty far with just that. Most cp

15513

implementations provide a bunch of options to tweak exactly how the

15514

files are copied: you can preserve mode and modification time, avoid

15515

following symlinks, ask before clobbering existing files, etc. But

15516

none of this distracts from the core mission of cp, which is

15517

to copy one file to another, or N files to another directory.

15518

What are positional arguments for? In case it wasn't clear from the above example: positional arguments

15519

are for those pieces of information that your program absolutely,

15520

positively requires to run.

15521

A good user interface should have as few absolute requirements as

15522

possible. If your program requires 17 distinct pieces of information in

15523

order to run successfully, it doesn't much matter how you get that

15524

information from the user---most people will give up and walk away

15525

before they successfully run the program. This applies whether the user

15526

interface is a command-line, a configuration file, a GUI, or whatever:

15527

if you make that many demands on your users, most of them will just give

15528

up.

15529

In short, try to minimize the amount of information that users are

15530

absolutely required to supply---use sensible defaults whenever

15531

possible. Of course, you also want to make your programs reasonably

15532

flexible. That's what options are for. Again, it doesn't matter if

15533

they are entries in a config file, checkboxes in the ``Preferences''

15534

dialog of a GUI, or command-line options---the more options you

15535

implement, the more flexible your program is, and the more complicated

15536

its implementation becomes. It's quite easy to overwhelm users (and

15537

yourself!) with too much flexibility, so be careful there.

15538

</description>

15539

</group>

15540

15541

<description>While optparse is quite flexible and powerful, you don't have

15542

to jump through hoops or read reams of documentation to get it working

15543

in basic cases. This document aims to demonstrate some simple usage

15544

patterns that will get you started using optparse in your

15545

scripts.

15546

To parse a command line with optparse, you must create an

15547

OptionParser instance and populate it. Obviously, you'll have

15548

to import the OptionParser classes in any script that uses

15549

optparse:

15550

from optparse import OptionParser

15551

Early on in the main program, create a parser:

15552

parser = OptionParser()

15553

Then you can start populating the parser with options. Each option is

15554

really a set of synonymous option strings; most commonly, you'll have

15555

one short option string and one long option string ---

15556

e.g. -f and file:

15557

parser.add_option("-f", "--file", ...)

15558

The interesting stuff, of course, is what comes after the option

15559

strings. For now, we'll only cover four of the things you can put

15560

there: action, type, dest (destination), and

15561

help.

15562

The store action%

15563

The action tells optparse what to do when it sees one of the

15564

option strings for this option on the command-line. For example, the

15565

action store means: take the next argument (or the remainder of

15566

the current argument), ensure that it is of the correct type, and

15567

store it to your chosen destination.

15568

For example, let's fill in the ``...'' of that last option:

15569

parser.add_option("-f", "--file",

15570

action="store", type="string", dest="filename")

15571

Now let's make up a fake command-line and ask optparse to

15572

parse it:

15573

args = ["-f", "foo.txt"]

15574

(options, args) = parser.parse_args(args)

15575

(Note that if you don't pass an argument list to

15576

parse_args(), it automatically uses sys.argv[1:].)

15577

When optparse sees the -f, it consumes the next

15578

argument---foo.txt---and stores it in the filename

15579

attribute of a special object. That object is the first return value

15580

from parse_args(), so:

15581

print options.filename

15582

will print foo.txt.

15583

Other option types supported by optparse are int and

15584

float. Here's an option that expects an integer argument:

15585

parser.add_option("-n", type="int", dest="num")

15586

This example doesn't provide a long option, which is perfectly

15587

acceptable. It also doesn't specify the action---it defaults to

15588

``store''.

15589

Let's parse another fake command-line. This time, we'll jam the option

15590

argument right up against the option, since -n42 (one

15591

argument) is equivalent to -n 42 (two arguments).

15592

(options, args) = parser.parse_args(["-n42"])

15593

print options.num

15594

This prints 42.

15595

Trying out the ``float'' type is left as an exercise for the reader.

15596

If you don't specify a type, optparse assumes ``string''.

15597

Combined with the fact that the default action is ``store'', that

15598

means our first example can be a lot shorter:

15599

parser.add_option("-f", "--file", dest="filename")

15600

If you don't supply a destination, optparse figures out a

15601

sensible default from the option strings: if the first long option

15602

string is foo-bar, then the default destination is

15603

foo_bar. If there are no long option strings,

15604

optparse looks at the first short option: the default

15605

destination for -f is f.

15606

Adding types is fairly easy; please refer to

15607

section~optparse-adding-types, ``Adding new types.''

15608

Other store_* actions%

15609

Flag options---set a variable to true or false when a particular

15610

option is seen---are quite common. optparse supports them

15611

with two separate actions, ``store_true'' and ``store_false''. For

15612

example, you might have a verbose flag that is turned on with

15613

-v and off with -q:

15614

parser.add_option("-v", action="store_true", dest="verbose")

15615

parser.add_option("-q", action="store_false", dest="verbose")

15616

Here we have two different options with the same destination, which is

15617

perfectly OK. (It just means you have to be a bit careful when setting

15618

default values---see below.)

15619

When optparse sees -v on the command line, it sets

15620

options.verbose to True; when it sees -q, it

15621

sets options.verbose to False.

15622

Setting default values

15623

All of the above examples involve setting some variable (the

15624

``destination'') when certain command-line options are seen. What

15625

happens if those options are never seen? Since we didn't supply any

15626

defaults, they are all set to None. Sometimes, this is just fine (which

15627

is why it's the default), but sometimes, you want more control. To

15628

address that need, optparse lets you supply a default value for

15629

each destination, which is assigned before the command-line is parsed.

15630

First, consider the verbose/quiet example. If we want

15631

optparse to set verbose to True unless

15632

-q is seen, then we can do this:

15633

parser.add_option("-v", action="store_true", dest="verbose", default=True)

15634

parser.add_option("-q", action="store_false", dest="verbose")

15635

Oddly enough, this is exactly equivalent:

15636

parser.add_option("-v", action="store_true", dest="verbose")

15637

parser.add_option("-q", action="store_false", dest="verbose", default=True)

15638

Those are equivalent because you're supplying a default value for the

15639

option's destination, and these two options happen to have the same

15640

destination (the verbose variable).

15641

Consider this:

15642

parser.add_option("-v", action="store_true", dest="verbose", default=False)

15643

parser.add_option("-q", action="store_false", dest="verbose", default=True)

15644

Again, the default value for verbose will be True: the last

15645

default value supplied for any particular destination is the one that

15646

counts.

15647

Generating help

15648

The last feature that you will use in every script is

15649

optparse's ability to generate help messages. All you have

15650

to do is supply a help argument when you add an option. Let's

15651

create a new parser and populate it with user-friendly (documented)

15652

options:

15653

usage = "usage: %prog [options] arg1 arg2"

15654

parser = OptionParser(usage=usage)

15655

parser.add_option("-v", "--verbose",

15656

action="store_true", dest="verbose", default=True,

15657

help="make lots of noise [default]")

15658

parser.add_option("-q", "--quiet",

15659

action="store_false", dest="verbose", help="be vewwy quiet (I'm hunting wabbits)")

15660

parser.add_option("-f", "--file", dest="filename",

15661

metavar="FILE", help="write output to FILE"),

15662

parser.add_option("-m", "--mode",

15663

default="intermediate",

15664

help="interaction mode: one of 'novice', "

15665

"'intermediate' [default], 'expert'")

15666

If optparse encounters either -h or

15667

help on the command-line, or if you just call

15668

parser.print_help(), it prints the following to stdout:

15669

usage: <yourscript> [options] arg1 arg2

15670

options:

15671

-h, --help show this help message and exit

15672

-v, --verbose make lots of noise [default]

15673

-q, --quiet be vewwy quiet (I'm hunting wabbits)

15674

-fFILE, --file=FILE write output to FILE

15675

-mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'

15676

[default], 'expert'

15677

There's a lot going on here to help optparse generate the

15678

best possible help message:

15679

the script defines its own usage message:

15680

usage = "usage: %prog [options] arg1 arg2"

15681

optparse expands in the usage string to the name of the

15682

current script, i.e. os.path.basename(sys.argv[0]). The

15683

expanded string is then printed before the detailed option help.

15684

If you don't supply a usage string, optparse uses a bland but

15685

sensible default: "usage: [options]", which is fine if your

15686

script doesn't take any positional arguments.

15687

every option defines a help string, and doesn't worry about line-wrapping---optparse takes care of wrapping lines and making the help output look good.

15688

options that take a value indicate this fact in their

15689

automatically-generated help message, e.g. for the ``mode'' option:

15690

-mMODE, --mode=MODE

15691

Here, ``MODE'' is called the meta-variable: it stands for the argument

15692

that the user is expected to supply to

15693

-m/mode. By default, optparse

15694

converts the destination variable name to uppercase and uses that for

15695

the meta-variable. Sometimes, that's not what you want---for

15696

example, the filename option explicitly sets

15697

metavar="FILE", resulting in this automatically-generated

15698

option description:

15699

-fFILE, --file=FILE

15700

This is important for more than just saving space, though: the

15701

manually written help text uses the meta-variable ``FILE'', to clue

15702

the user in that there's a connection between the formal syntax

15703

``-fFILE'' and the informal semantic description ``write output to

15704

FILE''. This is a simple but effective way to make your help text a

15705

lot clearer and more useful for end users.

15706

When dealing with many options, it is convenient to group these

15707

options for better help output. An OptionParser can contain

15708

several option groups, each of which can contain several options.

15709

Continuing with the parser defined above, adding an

15710

OptionGroup to a parser is easy:

15711

group = OptionGroup(parser, "Dangerous Options",

15712

"Caution: use these options at your own risk. "

15713

"It is believed that some of them bite.")

15714

group.add_option("-g", action="store_true", help="Group option.")

15715

parser.add_option_group(group)

15716

This would result in the following help output:

15717

usage: [options] arg1 arg2

15718

options:

15719

-h, --help show this help message and exit

15720

-v, --verbose make lots of noise [default]

15721

-q, --quiet be vewwy quiet (I'm hunting wabbits)

15722

-fFILE, --file=FILE write output to FILE

15723

-mMODE, --mode=MODE interaction mode: one of 'novice', 'intermediate'

15724

[default], 'expert'

15725

Dangerous Options:

15726

Caution: use of these options is at your own risk. It is believed that

15727

some of them bite.

15728

-g Group option.

15729

Print a version number

15730

Similar to the brief usage string, optparse can also print a

15731

version string for your program. You have to supply the string, as

15732

the version argument to OptionParser:

15733

parser = OptionParser(usage="%prog [-f] [-q]", version="%prog 1.0")

15734

version can contain anything you like; is expanded

15735

in version just as with usage. When you supply it,

15736

optparse automatically adds a version option

15737

to your parser. If it encounters this option on the command line, it

15738

expands your version string (by replacing ), prints

15739

it to stdout, and exits.

15740

For example, if your script is called /usr/bin/foo, a user might do:

15741

$ /usr/bin/foo --version

15742

foo 1.0

15743

% $ (avoid confusing emacs)

15744

Error-handling

15745

The one thing you need to know for basic usage is how

15746

optparse behaves when it encounters an error on the

15747

command-line---e.g. -n 4x where -n is an

15748

integer-valued option. In this case, optparse prints your

15749

usage message to stderr, followed by a useful and human-readable error

15750

message. Then it terminates (calls sys.exit()) with a

15751

non-zero exit status.

15752

If you don't like this, subclass OptionParser and override the

15753

error() method. See section~optparse-extending,

15754

``Extending optparse.''

15755

Putting it all together

15756

Here's what optparse-based scripts typically look like:

15757

from optparse import OptionParser

15758

[...]

15759

def main():

15760

usage = "usage: [-f] [-v] [-q] firstarg secondarg"

15761

parser = OptionParser(usage)

15762

parser.add_option("-f", "--file", type="string", dest="filename",

15763

help="read data from FILENAME")

15764

parser.add_option("-v", "--verbose",

15765

action="store_true", dest="verbose")

15766

parser.add_option("-q", "--quiet",

15767

action="store_false", dest="verbose")

15768

(options, args) = parser.parse_args()

15769

if len(args) != 1:

15770

parser.error("incorrect number of arguments")

15771

if options.verbose:

15772

print "reading ..." % options.filename

15773

[... go to work ...]

15774

if __name__ == "__main__":

15775

main()

15776

</description>

15777

</group>

15778

15779

<description>Creating and populating the

15780

parser

15781

There are several ways to populate the parser with options. One way

15782

is to pass a list of Options to the OptionParser

15783

constructor:

15784

from optparse import OptionParser, make_option

15785

[...]

15786

parser = OptionParser(option_list=[

15787

make_option("-f", "--filename",

15788

action="store", type="string", dest="filename"),

15789

make_option("-q", "--quiet",

15790

action="store_false", dest="verbose")])

15791

(make_option() is a factory function for generating

15792

Option objects.)

15793

For long option lists, it may be more convenient/readable to create the

15794

list separately:

15795

option_list = [make_option("-f", "--filename",

15796

action="store", type="string", dest="filename"),

15797

[... more options ...]

15798

make_option("-q", "--quiet",

15799

action="store_false", dest="verbose")]

15800

parser = OptionParser(option_list=option_list)

15801

Or, you can use the add_option() method of

15802

OptionParser to add options one-at-a-time:

15803

parser = OptionParser()

15804

parser.add_option("-f", "--filename",

15805

action="store", type="string", dest="filename")

15806

parser.add_option("-q", "--quiet",

15807

action="store_false", dest="verbose")

15808

This method makes it easier to track down exceptions raised by the

15809

Option constructor, which are common because of the complicated

15810

interdependencies among the various keyword arguments. (If you get it

15811

wrong, optparse raises OptionError.)

15812

add_option() can be called in one of two ways:

15813

pass it an Option instance (as returned by make_option())

15814

pass it any combination of positional and keyword arguments that

15815

are acceptable to make_option() (i.e., to the Option

15816

constructor), and it will create the Option instance for you

15817

(shown above).

15818

Defining options

15819

Each Option instance represents a set of synonymous

15820

command-line options, i.e. options that have the same meaning and

15821

effect, but different spellings. You can specify any number of short

15822

or long option strings, but you must specify at least one option

15823

string.

15824

To define an option with only a short option string:

15825

make_option("-f", ...)

15826

And to define an option with only a long option string:

15827

make_option("--foo", ...)

15828

The ``...'' represents a set of keyword arguments that define attributes

15829

of the Option object. The rules governing which keyword args

15830

you must supply for a given Option are fairly complicated, but

15831

you always have to supply some. If you get it wrong,

15832

optparse raises an OptionError exception explaining

15833

your mistake.

15834

The most important attribute of an option is its action, i.e. what to do

15835

when we encounter this option on the command-line. The possible actions

15836

are:

15837

{l|l}{code}{Action}{Meaning}

15838

store{store this option's argument (default)}

15839

store_const{store a constant value}

15840

store_true{store a true value}

15841

store_false{store a false value}

15842

append{append this option's argument to a list}

15843

count{increment a counter by one}

15844

callback{call a specified function}

15845

help{print a usage message including all options and the

15846

documentation for them} (If you don't supply an action, the default is ``store''. For this

15847

action, you may also supply type and dest keywords; see

15848

below.)

15849

As you can see, most actions involve storing or updating a value

15850

somewhere. optparse always creates a particular object (an

15851

instance of the Values class) specifically for this

15852

purpose. Option arguments (and various other values) are stored as

15853

attributes of this object, according to the dest (destination)

15854

argument to make_option()/add_option().

15855

For example, when you call:

15856

parser.parse_args()

15857

one of the first things optparse does is create a

15858

values object:

15859

values = Values()

15860

If one of the options in this parser is defined with:

15861

make_option("-f", "--file", action="store", type="string", dest="filename")

15862

and the command-line being parsed includes any of the following:

15863

-ffoo

15864

-f foo

15865

--file=foo

15866

--file foo

15867

then optparse, on seeing the -f or

15868

file option, will do the equivalent of this:

15869

values.filename = "foo"

15870

Clearly, the type and dest arguments are almost

15871

as important as action. action is the only attribute that

15872

is meaningful for all options, though, so it is the most

15873

important.

15874

Option actions

15875

The various option actions all have slightly different requirements

15876

and effects. Except for the ``help'' action, you must supply at least

15877

one other keyword argument when creating the Option; the exact

15878

requirements for each action are listed here.

15879

store [relevant: type, dest, nargs, choices]

15880

The option must be followed by an argument, which is converted to a

15881

value according to type and stored in dest. If

15882

nargs > 1, multiple arguments will be consumed from the command

15883

line; all will be converted according to type and stored to

15884

dest as a tuple. See section~optparse-option-types,

15885

``Option types,'' below.

15886

If choices (a sequence of strings) is supplied, the type

15887

defaults to ``choice''.

15888

If type is not supplied, it defaults to ``string''.

15889

If dest is not supplied, optparse derives a

15890

destination from the first long option strings (e.g.,

15891

foo-bar becomes foo_bar). If there are no long

15892

option strings, optparse derives a destination from the first

15893

short option string (e.g., -f becomes f).

15894

Example:

15895

make_option("-f")

15896

make_option("-p", type="float", nargs=3, dest="point")

15897

Given the following command line:

15898

-f foo.txt -p 1 -3.5 4 -fbar.txt

15899

optparse will set:

15900

values.f = "bar.txt"

15901

values.point = (1.0, -3.5, 4.0)

15902

(Actually, values.f will be set twice, but only the second

15903

time is visible in the end.)

15904

store_const [required: const, dest]

15905

The const value supplied to the Option constructor is

15906

stored in dest.

15907

Example:

15908

make_option("-q", "--quiet",

15909

action="store_const", const=0, dest="verbose"),

15910

make_option("-v", "--verbose",

15911

action="store_const", const=1, dest="verbose"),

15912

make_option("--noisy",

15913

action="store_const", const=2, dest="verbose"),

15914

If noisy is seen, optparse will set:

15915

values.verbose = 2

15916

store_true [required: dest]

15917

A special case of ``store_const'' that stores True to dest.

15918

store_false [required: dest]

15919

Like ``store_true'', but stores False

15920

Example:

15921

make_option(None, "--clobber", action="store_true", dest="clobber")

15922

make_option(None, "--no-clobber", action="store_false", dest="clobber")

15923

append [relevant: type, dest, nargs, choices]

15924

The option must be followed by an argument, which is appended to the

15925

list in dest. If no default value for dest is supplied

15926

(i.e. the default is None), an empty list is automatically created when

15927

optparse first encounters this option on the command-line.

15928

If nargs > 1, multiple arguments are consumed, and a tuple of

15929

length nargs is appended to dest.

15930

The defaults for type and dest are the same as for the

15931

``store'' action.

15932

Example:

15933

make_option("-t", "--tracks", action="append", type="int")

15934

If -t3 is seen on the command-line, optparse does the equivalent of:

15935

values.tracks = []

15936

values.tracks.append(int("3"))

15937

If, a little later on, tracks=4 is seen, it does:

15938

values.tracks.append(int("4"))

15939

See ``Error handling'' (section~optparse-error-handling) for

15940

information on how optparse deals with something like

15941

tracks=x.

15942

count [required: dest]

15943

Increment the integer stored at dest. dest is set to zero

15944

before being incremented the first time (unless you supply a default

15945

value).

15946

Example:

15947

make_option("-v", action="count", dest="verbosity")

15948

The first time -v is seen on the command line,

15949

optparse does the equivalent of:

15950

values.verbosity = 0

15951

values.verbosity += 1

15952

Every subsequent occurrence of -v results in:

15953

values.verbosity += 1

15954

callback [required: callback;

15955

relevant: type, nargs, callback_args,

15956

callback_kwargs]

15957

Call the function specified by callback. The signature of

15958

this function should be:

15959

func(option : Option,

15960

opt : string,

15961

value : any,

15962

parser : OptionParser,

15963

*args, **kwargs)

15964

Callback options are covered in detail in

15965

section~optparse-callback-options, ``Callback Options.''

15966

help [required: none]

15967

Prints a complete help message for all the options in the current

15968

option parser. The help message is constructed from the usage

15969

string passed to OptionParser's constructor and the help

15970

string passed to every option.

15971

If no help string is supplied for an option, it will still be

15972

listed in the help message. To omit an option entirely, use the

15973

special value optparse.SUPPRESS_HELP.

15974

Example:

15975

from optparse import Option, OptionParser, SUPPRESS_HELP

15976

usage = "usage: %prog [options]"

15977

parser = OptionParser(usage, option_list=[

15978

make_option("-h", "--help", action="help"),

15979

make_option("-v", action="store_true", dest="verbose",

15980

help="Be moderately verbose")

15981

make_option("--file", dest="filename",

15982

help="Input file to read data from"),

15983

make_option("--secret", help=SUPPRESS_HELP)

15984

])

15985

If optparse sees either -h or

15986

help on the command line, it will print something

15987

like the following help message to stdout:

15988

usage: <yourscript> [options]

15989

options:

15990

-h, --help Show this help message and exit

15991

-v Be moderately verbose

15992

--file=FILENAME Input file to read data from

15993

After printing the help message, optparse terminates your process

15994

with sys.exit(0).

15995

version [required: none]

15996

Prints the version number supplied to the OptionParser to

15997

stdout and exits. The version number is actually formatted and

15998

printed by the print_version() method of

15999

OptionParser. Generally only relevant if the version

16000

argument is supplied to the OptionParser constructor.

16001

Option types

16002

optparse supports six option types out of the box: string,

16003

int, long, choice, float and complex.

16004

(Of these, string, int, float, and choice are the most commonly used

16005

---long and complex are there mainly for completeness.) It's easy to

16006

add new option types by subclassing the Option class; see

16007

section~optparse-extending, ``Extending optparse.''

16008

Arguments to string options are not checked or converted in any way:

16009

the text on the command line is stored in the destination (or passed

16010

to the callback) as-is.

16011

Integer arguments are passed to int() to convert them to

16012

Python integers. If int() fails, so will

16013

optparse, although with a more useful error message.

16014

Internally, optparse raises OptionValueError in

16015

optparse.check_builtin(); at a higher level (in

16016

OptionParser), optparse catches this exception and

16017

terminates your program with a useful error message.

16018

Likewise, float arguments are passed to float() for

16019

conversion, long arguments to long(), and complex arguments

16020

to complex(). Apart from that, they are handled

16021

identically to integer arguments.

16022

Choice options are a subtype of string options. A master list or

16023

tuple of choices (strings) must be passed to the option constructor

16024

(make_option() or OptionParser.add_option()) as

16025

the choices keyword argument. Choice option arguments are

16026

compared against this master list in

16027

optparse.check_choice(), and OptionValueError

16028

is raised if an unknown string is given.

16029

Querying and manipulating your option parser

16030

Sometimes, it's useful to poke around your option parser and see what's

16031

there. OptionParser provides a couple of methods to help you out:

16032

</description>

16033

16034

<description>Given an option string such as -q or

16035

verbose, returns true if the OptionParser

16036

has an option with that option string.</description>

16037

16038

16039

16040

16041

<description>Returns the Option instance that implements the option

16042

string you supplied, or None if no options implement it.</description>

16043

16044

16045

16046

16047

<description>If the OptionParser has an option corresponding to

16048

opt_str, that option is removed. If that option provided

16049

any other option strings, all of those option strings become

16050

invalid.

16051

If opt_str does not occur in any option belonging to this

16052

OptionParser, raises ValueError.</description>

16053

16054

16055

16056

</group>

16057

16058

<description>If optparse's built-in actions and types just don't fit the

16059

bill for you, but it's not worth extending optparse to define

16060

your own actions or types, you'll probably need to define a callback

16061

option. Defining callback options is quite easy; the tricky part is

16062

writing a good callback (the function that is called when

16063

optparse encounters the option on the command line).

16064

Defining a callback option

16065

As always, you can define a callback option either by directly

16066

instantiating the Option class, or by using the

16067

add_option() method of your OptionParser object. The

16068

only option attribute you must specify is callback, the function

16069

to call:

16070

parser.add_option("-c", callback=my_callback)

16071

Note that you supply a function object here---so you must have

16072

already defined a function my_callback() when you define

16073

the callback option. In this simple case, optparse knows

16074

nothing about the arguments the -c option expects to

16075

take. Usually, this means that the option doesn't take any arguments

16076

-- the mere presence of -c on the command-line is all it

16077

needs to know. In some circumstances, though, you might want your

16078

callback to consume an arbitrary number of command-line arguments.

16079

This is where writing callbacks gets tricky; it's covered later in

16080

this document.

16081

There are several other option attributes that you can supply when you

16082

define an option attribute:

16083

type

16084

has its usual meaning: as with the ``store'' or ``append'' actions, it

16085

instructs optparse to consume one argument that must be

16086

convertible to type. Rather than storing the value(s) anywhere,

16087

though, optparse converts it to type and passes it to

16088

your callback function.

16089

nargs

16090

also has its usual meaning: if it is supplied and nargs > 1,

16091

optparse will consume nargs arguments, each of which

16092

must be convertible to type. It then passes a tuple of

16093

converted values to your callback.

16094

callback_args

16095

a tuple of extra positional arguments to pass to the callback.

16096

callback_kwargs

16097

a dictionary of extra keyword arguments to pass to the callback.

16098

How callbacks are called

16099

All callbacks are called as follows:

16100

func(option, opt, value, parser, *args, **kwargs)

16101

where

16102

option

16103

is the Option instance that's calling the callback.

16104

opt

16105

is the option string seen on the command-line that's triggering the

16106

callback. (If an abbreviated long option was used, opt will be

16107

the full, canonical option string---for example, if the user puts

16108

foo on the command-line as an abbreviation for

16109

foobar, then opt will be

16110

foobar.)

16111

value

16112

is the argument to this option seen on the command-line.

16113

optparse will only expect an argument if type is

16114

set; the type of value will be the type implied by the

16115

option's type (see~optparse-option-types, ``Option types''). If

16116

type for this option is None (no argument expected), then

16117

value will be None. If nargs > 1, value will

16118

be a tuple of values of the appropriate type.

16119

parser

16120

is the OptionParser instance driving the whole thing, mainly

16121

useful because you can access some other interesting data through it,

16122

as instance attributes:

16123

parser.rargs

16124

the current remaining argument list, i.e. with opt (and

16125

value, if any) removed, and only the arguments following

16126

them still there. Feel free to modify parser.rargs,

16127

e.g. by consuming more arguments.

16128

parser.largs

16129

the current set of leftover arguments, i.e. arguments that have been

16130

processed but have not been consumed as options (or arguments to

16131

options). Feel free to modify parser.largs e.g. by adding

16132

more arguments to it.

16133

parser.values

16134

the object where option values are by default stored. This is useful

16135

because it lets callbacks use the same mechanism as the rest of

16136

optparse for storing option values; you don't need to mess

16137

around with globals or closures. You can also access the value(s) of

16138

any options already encountered on the command-line.

16139

args

16140

is a tuple of arbitrary positional arguments supplied via the

16141

callback_args option attribute.

16142

kwargs

16143

is a dictionary of arbitrary keyword arguments supplied via

16144

callback_kwargs.

16145

Since args and kwargs are optional (they are only passed

16146

if you supply callback_args and/or callback_kwargs when

16147

you define your callback option), the minimal callback function is:

16148

def my_callback (option, opt, value, parser):

16149

pass

16150

Error handling

16151

The callback function should raise OptionValueError if

16152

there are any problems with the option or its

16153

argument(s). optparse catches this and terminates the

16154

program, printing the error message you supply to stderr. Your

16155

message should be clear, concise, accurate, and mention the option at

16156

fault. Otherwise, the user will have a hard time figuring out what he

16157

did wrong.

16158

Examples

16159

Here's an example of a callback option that takes no arguments, and

16160

simply records that the option was seen:

16161

def record_foo_seen (option, opt, value, parser):

16162

parser.saw_foo = 1

16163

parser.add_option("--foo", action="callback", callback=record_foo_seen)

16164

Of course, you could do that with the ``store_true'' action. Here's a

16165

slightly more interesting example: record the fact that

16166

-a is seen, but blow up if it comes after -b

16167

in the command-line.

16168

def check_order (option, opt, value, parser):

16169

if parser.values.b:

16170

raise OptionValueError("can't use -a after -b")

16171

parser.values.a = 1

16172

...

16173

parser.add_option("-a", action="callback", callback=check_order)

16174

parser.add_option("-b", action="store_true", dest="b")

16175

If you want to reuse this callback for several similar options (set a

16176

flag, but blow up if -b has already been seen), it needs

16177

a bit of work: the error message and the flag that it sets must be

16178

generalized.

16179

def check_order (option, opt, value, parser):

16180

if parser.values.b:

16181

raise OptionValueError("can't use %s after -b" % opt)

16182

setattr(parser.values, option.dest, 1)

16183

...

16184

parser.add_option("-a", action="callback", callback=check_order, dest='a')

16185

parser.add_option("-b", action="store_true", dest="b")

16186

parser.add_option("-c", action="callback", callback=check_order, dest='c')

16187

Of course, you could put any condition in there---you're not limited

16188

to checking the values of already-defined options. For example, if

16189

you have options that should not be called when the moon is full, all

16190

you have to do is this:

16191

def check_moon (option, opt, value, parser):

16192

if is_full_moon():

16193

raise OptionValueError("%s option invalid when moon full" % opt)

16194

setattr(parser.values, option.dest, 1)

16195

...

16196

parser.add_option("--foo",

16197

action="callback", callback=check_moon, dest="foo")

16198

(The definition of is_full_moon() is left as an exercise for the

16199

reader.)

16200

Fixed arguments

16201

Things get slightly more interesting when you define callback options

16202

that take a fixed number of arguments. Specifying that a callback

16203

option takes arguments is similar to defining a ``store'' or

16204

``append'' option: if you define type, then the option takes one

16205

argument that must be convertible to that type; if you further define

16206

nargs, then the option takes that many arguments.

16207

Here's an example that just emulates the standard ``store'' action:

16208

def store_value (option, opt, value, parser):

16209

setattr(parser.values, option.dest, value)

16210

...

16211

parser.add_option("--foo",

16212

action="callback", callback=store_value,

16213

type="int", nargs=3, dest="foo")

16214

Note that optparse takes care of consuming 3 arguments and

16215

converting them to integers for you; all you have to do is store them.

16216

(Or whatever: obviously you don't need a callback for this example.

16217

Use your imagination!)

16218

Variable arguments

16219

Things get hairy when you want an option to take a variable number of

16220

arguments. For this case, you have to write a callback;

16221

optparse doesn't provide any built-in capabilities for it.

16222

You have to deal with the full-blown syntax for conventional command-line parsing. (Previously, optparse took care of

16223

this for you, but I got it wrong. It was fixed at the cost of making

16224

this kind of callback more complex.) In particular, callbacks have to

16225

worry about bare and - arguments; the

16226

convention is:

16227

bare , if not the argument to some option,

16228

causes command-line processing to halt and the itself is lost.

16229

bare - similarly causes command-line processing to

16230

halt, but the - itself is kept.

16231

either or - can be option

16232

arguments.

16233

If you want an option that takes a variable number of arguments, there

16234

are several subtle, tricky issues to worry about. The exact

16235

implementation you choose will be based on which trade-offs you're

16236

willing to make for your application (which is why optparse

16237

doesn't support this sort of thing directly).

16238

Nevertheless, here's a stab at a callback for an option with variable

16239

arguments:

16240

def varargs (option, opt, value, parser):

16241

assert value is None

16242

done = 0

16243

value = []

16244

rargs = parser.rargs

16245

while rargs:

16246

arg = rargs[0]

16247

# Stop if we hit an arg like "--foo", "-a", "-fx", "--file=f",

16248

# etc. Note that this also stops on "-3" or "-3.0", so if

16249

# your option takes numeric values, you will need to handle

16250

# this.

16251

if ((arg[:2] == "--" and len(arg) > 2) or

16252

(arg[:1] == "-" and len(arg) > 1 and arg[1] != "-")):

16253

break

16254

else:

16255

value.append(arg)

16256

del rargs[0]

16257

setattr(parser.values, option.dest, value)

16258

...

16259

parser.add_option("-c", "--callback",

16260

action="callback", callback=varargs)

16261

The main weakness with this particular implementation is that negative

16262

numbers in the arguments following -c will be interpreted

16263

as further options, rather than as arguments to -c.

16264

Fixing this is left as an exercise for the reader.

16265

</description>

16266

</group>

16267

16268

</group>

16269

</group>

16270

16271

<description>Generate temporary files and directories.

16272

This module generates temporary files and directories. It works on

16273

all supported platforms.

16274

In version 2.3 of Python, this module was overhauled for enhanced

16275

security. It now provides three new functions,

16276

NamedTemporaryFile(), mkstemp(), and

16277

mkdtemp(), which should eliminate all remaining need to use

16278

the insecure mktemp() function. Temporary file names created

16279

by this module no longer contain the process ID; instead a string of

16280

six random characters is used.

16281

Also, all the user-callable functions now take additional arguments

16282

which allow direct control over the location and name of temporary

16283

files. It is no longer necessary to use the global tempdir and

16284

template variables. To maintain backward compatibility, the

16285

argument order is somewhat odd; it is recommended to use keyword

16286

arguments for clarity.

16287

The module defines the following user-callable functions:

16288

</description>

16289

16290

<description>Return a file (or file-like) object that can be used as a temporary

16291

storage area. The file is created using mkstemp. It will

16292

be destroyed as soon as it is closed (including an implicit close when

16293

the object is garbage collected). Under , the directory entry

16294

for the file is removed immediately after the file is created. Other

16295

platforms do not support this; your code should not rely on a

16296

temporary file created using this function having or not having a

16297

visible name in the file system.

16298

The mode parameter defaults to 'w+b' so that the file

16299

created can be read and written without being closed. Binary mode is

16300

used so that it behaves consistently on all platforms without regard

16301

for the data that is stored. bufsize defaults to -1,

16302

meaning that the operating system default is used.

16303

The dir, prefix and suffix parameters are passed to

16304

mkstemp().</description>

16305

16306

16307

16308

16309

<description>This function operates exactly as TemporaryFile() does,

16310

except that the file is guaranteed to have a visible name in the file

16311

system (on , the directory entry is not unlinked). That name can

16312

be retrieved from the name member of the file object. Whether

16313

the name can be used to open the file a second time, while the

16314

named temporary file is still open, varies across platforms (it can

16315

be so used on ; it cannot on Windows NT or later).

16316

New in version 2.3</description>

16317

16318

16319

16320

16321

<description>Creates a temporary file in the most secure manner possible. There

16322

are no race conditions in the file's creation, assuming that the

16323

platform properly implements the O_EXCL flag for

16324

os.open(). The file is readable and writable only by the

16325

creating user ID. If the platform uses permission bits to indicate

16326

whether a file is executable, the file is executable by no one. The

16327

file descriptor is not inherited by child processes.

16328

Unlike TemporaryFile(), the user of mkstemp() is

16329

responsible for deleting the temporary file when done with it.

16330

If suffix is specified, the file name will end with that suffix,

16331

otherwise there will be no suffix. mkstemp() does not put a

16332

dot between the file name and the suffix; if you need one, put it at

16333

the beginning of suffix.

16334

If prefix is specified, the file name will begin with that

16335

prefix; otherwise, a default prefix is used.

16336

If dir is specified, the file will be created in that directory;

16337

otherwise, a default directory is used.

16338

If text is specified, it indicates whether to open the file in

16339

binary mode (the default) or text mode. On some platforms, this makes

16340

no difference.

16341

mkstemp() returns a tuple containing an OS-level handle to

16342

an open file (as would be returned by os.open()) and the

16343

absolute pathname of that file, in that order.

16344

New in version 2.3</description>

16345

16346

16347

16348

16349

<description>Creates a temporary directory in the most secure manner possible.

16350

There are no race conditions in the directory's creation. The

16351

directory is readable, writable, and searchable only by the

16352

creating user ID.

16353

The user of mkdtemp() is responsible for deleting the

16354

temporary directory and its contents when done with it.

16355

The prefix, suffix, and dir arguments are the same

16356

as for mkstemp().

16357

mkdtemp() returns the absolute pathname of the new directory.

16358

New in version 2.3</description>

16359

16360

16361

16362

16363

<description>2.3{Use mkstemp() instead.}

16364

Return an absolute pathname of a file that did not exist at the time

16365

the call is made. The prefix, suffix, and dir

16366

arguments are the same as for mkstemp().

16367

Use of this function may introduce a security hole in your

16368

program. By the time you get around to doing anything with the file

16369

name it returns, someone else may have beaten you to the punch.</description>

16370

16371

16372

16373

16374

<description>Return the directory currently selected to create temporary files in.

16375

If tempdir is not None, this simply returns its contents;

16376

otherwise, the search described above is performed, and the result

16377

returned.</description>

16378

16379

</element>

16380

16381

16382

<description>Return the filename prefix used to create temporary files. This does

16383

not contain the directory component. Using this function is preferred

16384

over reading the template variable directly.

16385

New in version 1.5.2</description>

16386

16387

</element>

16388

16389

</group>

16390

16391

</group>

16392

16393

<description>style pathname pattern expansion.

16394

The glob module finds all the pathnames matching a specified

16395

pattern according to the rules used by the shell. No tilde

16396

expansion is done, but *, ?, and character ranges

16397

expressed with [] will be correctly matched. This is done by

16398

using the os.listdir() and fnmatch.fnmatch()

16399

functions in concert, and not by actually invoking a subshell. (For

16400

tilde and shell variable expansion, use os.path.expanduser()

16401

and os.path.expandvars().)

16402

</description>

16403

16404

<description>Returns a possibly-empty list of path names that match pathname,

16405

which must be a string containing a path specification.

16406

pathname can be either absolute (like

16407

/usr/src/Python-1.5/Makefile) or relative (like

16408

../../Tools/*/*.gif), and can contain shell-style wildcards.</description>

16409

16410

16411

16412

</group>

16413

16414

<description>style filename pattern matching.

16415

</description>

16416

16417

<description>Test whether the filename string matches the pattern

16418

string, returning true or false. If the operating system is

16419

case-insensitive, then both parameters will be normalized to all

16420

lower- or upper-case before the comparison is performed. If you

16421

require a case-sensitive comparison regardless of whether that's

16422

standard for your operating system, use fnmatchcase()

16423

instead.</description>

16424

16425

16426

16427

16428

<description>Test whether filename matches pattern, returning true or

16429

false; the comparison is case-sensitive.</description>

16430

16431

16432

16433

16434

<description>Return the subset of the list of names that match pattern.

16435

It is the same as [n for n in names if fnmatch(n, pattern)], but

16436

implemented more efficiently.

16437

New in version 2.2</description>

16438

16439

16440

16441

</group>

16442

16443

<description>High-level file operations, including copying.

16444

% partly based on the docstrings

16445

The shutil module offers a number of high-level operations on

16446

files and collections of files. In particular, functions are provided which support file copying and removal.

16447

</description>

16448

16449

<description>Copy the contents of the file named src to a file named

16450

dst. If dst exists, it will be replaced, otherwise it

16451

will be created. Special files such as character or block devices

16452

and pipes cannot not be copied with this function. src and

16453

dst are path names given as strings.</description>

16454

16455

16456

16457

16458

<description>Copy the contents of the file-like object fsrc to the

16459

file-like object fdst. The integer length, if given,

16460

is the buffer size. In particular, a negative length value

16461

means to copy the data without looping over the source data in

16462

chunks; by default the data is read in chunks to avoid uncontrolled

16463

memory consumption.</description>

16464

16465

16466

16467

16468

<description>Copy the permission bits from src to dst. The file

16469

contents, owner, and group are unaffected. src and dst

16470

are path names given as strings.</description>

16471

16472

16473

16474

16475

<description>Copy the permission bits, last access time, and last modification

16476

time from src to dst. The file contents, owner, and

16477

group are unaffected. src and dst are path names given

16478

as strings.</description>

16479

16480

16481

16482

16483

<description>Copy the file src to the file or directory dst. If

16484

dst is a directory, a file with the same basename as src is created (or overwritten) in the directory specified. Permission

16485

bits are copied. src and dst are path names given as

16486

strings.</description>

16487

16488

16489

16490

16491

<description>Similar to copy(), but last access time and last

16492

modification time are copied as well. This is similar to the

16493

command cp -p.</description>

16494

16495

16496

16497

16498

<description>Recursively copy an entire directory tree rooted at src. The

16499

destination directory, named by dst, must not already exist;

16500

it will be created. Individual files are copied using

16501

copy2(). If symlinks is true, symbolic links in

16502

the source tree are represented as symbolic links in the new tree;

16503

if false or omitted, the contents of the linked files are copied to

16504

the new tree. If exception(s) occur, an Error is raised

16505

with a list of reasons.

16506

The source code for this should be considered an example rather than a tool.

16507

Changed in version 2.3: Error is raised if any exceptions occur during copying,

16508

rather than printing a message</description>

16509

16510

16511

16512

16513

<description>Delete an entire directory tree.</description>

16514

16515

16516

16517

16518

<description>Recursively move a file or directory to another location.

16519

If the destination is on our current filesystem, then simply use

16520

rename. Otherwise, copy src to the dst and then remove src.

16521

New in version 2.3</description>

16522

16523

16524

16525

16526

</group>

16527

</group>

16528

16529

<description>Internationalization services.

16530

The locale module opens access to the locale

16531

database and functionality. The locale mechanism allows

16532

programmers to deal with certain cultural issues in an application,

16533

without requiring the programmer to know all the specifics of each

16534

country where the software is executed.

16535

The locale module is implemented on top of the

16536

_locale_locale module, which in turn uses an

16537

ANSI C locale implementation if available.

16538

The locale module defines the following exception and

16539

functions:

16540

{Error}

16541

Exception raised when setlocale() fails.

16542

</description>

16543

16544

<description>If locale is specified, it may be a string, a tuple of the

16545

form (language code, encoding), or None.

16546

If it is a tuple, it is converted to a string using the locale

16547

aliasing engine. If locale is given and not None,

16548

setlocale() modifies the locale setting for the

16549

category. The available categories are listed in the data

16550

description below. The value is the name of a locale. An empty

16551

string specifies the user's default settings. If the modification of

16552

the locale fails, the exception Error is raised. If

16553

successful, the new locale setting is returned.

16554

If locale is omitted or None, the current setting for

16555

category is returned.

16556

setlocale() is not thread safe on most systems.

16557

Applications typically start with a call of

16558

import locale

16559

locale.setlocale(locale.LC_ALL, '')

16560

This sets the locale for all categories to the user's default

16561

setting (typically specified in the LANG environment

16562

variable). If the locale is not changed thereafter, using

16563

multithreading should not cause problems.

16564

Changed in version 2.0: Added support for tuple values of the locale

16565

parameter</description>

16566

16567

16568

16569

16570

<description>Returns the database of the local conventions as a dictionary.

16571

This dictionary has the following strings as keys:

16572

{l|l|p{3in}}{constant}{Key}{Category}{Meaning}

16573

LC_NUMERIC{'decimal_point'}

16574

{Decimal point character.}

16575

{'grouping'}

16576

{Sequence of numbers specifying which relative positions

16577

the 'thousands_sep' is expected. If the sequence is

16578

terminated with CHAR_MAX, no further grouping

16579

is performed. If the sequence terminates with a 0, the last group size is repeatedly used.}

16580

{'thousands_sep'}

16581

{Character used between groups.}

16582

LC_MONETARY{'int_curr_symbol'}

16583

{International currency symbol.}

16584

{'currency_symbol'}

16585

{Local currency symbol.}

16586

{'mon_decimal_point'}

16587

{Decimal point used for monetary values.}

16588

{'mon_thousands_sep'}

16589

{Group separator used for monetary values.}

16590

{'mon_grouping'}

16591

{Equivalent to 'grouping', used for monetary

16592

values.}

16593

{'positive_sign'}

16594

{Symbol used to annotate a positive monetary value.}

16595

{'negative_sign'}

16596

{Symbol used to annotate a nnegative monetary value.}

16597

{'frac_digits'}

16598

{Number of fractional digits used in local formatting

16599

of monetary values.}

16600

{'int_frac_digits'}

16601

{Number of fractional digits used in international

16602

formatting of monetary values.}

16603

The possible values for 'p_sign_posn' and

16604

'n_sign_posn' are given below.

16605

{c|l}{code}{Value}{Explanation}

16606

0{Currency and value are surrounded by parentheses.}

16607

1{The sign should precede the value and currency symbol.}

16608

2{The sign should follow the value and currency symbol.}

16609

3{The sign should immediately precede the value.}

16610

4{The sign should immediately follow the value.}

16611

LC_MAX{Nothing is specified in this locale.}

16612

</description>

16613

16614

</element>

16615

16616

16617

<description>Return some locale-specific information as a string. This function is

16618

not available on all systems, and the set of possible options might

16619

also vary across platforms. The possible argument values are numbers,

16620

for which symbolic constants are available in the locale module.</description>

16621

16622

16623

16624

16625

<description>Tries to determine the default locale settings and returns

16626

them as a tuple of the form (language code,

16627

encoding).

16628

According to , a program which has not called

16629

setlocale(LC_ALL, '') runs using the portable 'C'

16630

locale. Calling setlocale(LC_ALL, '') lets it use the

16631

default locale as defined by the LANG variable. Since we

16632

do not want to interfere with the current locale setting we thus

16633

emulate the behavior in the way described above.

16634

To maintain compatibility with other platforms, not only the

16635

LANG variable is tested, but a list of variables given as

16636

envvars parameter. The first found to be defined will be

16637

used. envvars defaults to the search path used in GNU gettext;

16638

it must always contain the variable name LANG. The GNU

16639

gettext search path contains 'LANGUAGE', 'LC_ALL',

16640

'LC_CTYPE', and 'LANG', in that order.

16641

Except for the code 'C', the language code corresponds to

16642

1766. language code and encoding may be

16643

None if their values cannot be determined.

16644

New in version 2.0</description>

16645

16646

16647

16648

16649

<description>Returns the current setting for the given locale category as

16650

sequence containing language code, encoding.

16651

category may be one of the LC_* values except

16652

LC_ALL. It defaults to LC_CTYPE.

16653

Except for the code 'C', the language code corresponds to

16654

1766. language code and encoding may be

16655

None if their values cannot be determined.

16656

New in version 2.0</description>

16657

16658

16659

16660

16661

<description>Return the encoding used for text data, according to user

16662

preferences. User preferences are expressed differently on

16663

different systems, and might not be available programmatically on

16664

some systems, so this function only returns a guess.

16665

On some systems, it is necessary to invoke setlocale

16666

to obtain the user preferences, so this function is not thread-safe.

16667

If invoking setlocale is not necessary or desired, do_setlocale

16668

should be set to False.

16669

New in version 2.3</description>

16670

16671

16672

16673

16674

<description>Returns a normalized locale code for the given locale name. The

16675

returned locale code is formatted for use with

16676

setlocale(). If normalization fails, the original name

16677

is returned unchanged.

16678

If the given encoding is not known, the function defaults to

16679

the default encoding for the locale code just like

16680

setlocale().

16681

New in version 2.0</description>

16682

16683

16684

16685

16686

<description>Sets the locale for category to the default setting.

16687

The default setting is determined by calling

16688

getdefaultlocale(). category defaults to

16689

LC_ALL.

16690

New in version 2.0</description>

16691

16692

16693

16694

16695

<description>Compares two strings according to the current

16696

LC_COLLATE setting. As any other compare function,

16697

returns a negative, or a positive value, or 0, depending on

16698

whether string1 collates before or after string2 or is

16699

equal to it.</description>

16700

16701

16702

16703

16704

<description>Transforms a string to one that can be used for the built-in

16705

function cmp()cmp, and still returns

16706

locale-aware results. This function can be used when the same

16707

string is compared repeatedly, e.g. when collating a sequence of

16708

strings.</description>

16709

16710

16711

16712

16713

<description>Formats a number val according to the current

16714

LC_NUMERIC setting. The format follows the conventions

16715

of the % operator. For floating point values, the decimal

16716

point is modified if appropriate. If grouping is true, also

16717

takes the grouping into account.</description>

16718

16719

16720

16721

16722

<description>Formats a floating point number using the same format as the

16723

built-in function str(float), but takes the decimal

16724

point into account.</description>

16725

16726

16727

16728

16729

<description>Converts a string to a floating point number, following the

16730

LC_NUMERIC settings.</description>

16731

16732

16733

16734

16735

<description>Converts a string to an integer, following the

16736

LC_NUMERIC conventions.</description>

16737

16738

16739

16740

16741

<description>The C standard defines the locale as a program-wide property that may

16742

be relatively expensive to change. On top of that, some

16743

implementation are broken in such a way that frequent locale changes

16744

may cause core dumps. This makes the locale somewhat painful to use

16745

correctly.

16746

Initially, when a program is started, the locale is the C locale, no

16747

matter what the user's preferred locale is. The program must

16748

explicitly say that it wants the user's preferred locale settings by

16749

calling setlocale(LC_ALL, '').

16750

It is generally a bad idea to call setlocale() in some library

16751

routine, since as a side effect it affects the entire program. Saving

16752

and restoring it is almost as bad: it is expensive and affects other

16753

threads that happen to run before the settings have been restored.

16754

If, when coding a module for general use, you need a locale

16755

independent version of an operation that is affected by the locale

16756

(such as string.lower(), or certain formats used with

16757

time.strftime()), you will have to find a way to do it

16758

without using the standard library routine. Even better is convincing

16759

yourself that using locale settings is okay. Only as a last resort

16760

should you document that your module is not compatible with

16761

non-C locale settings.

16762

The case conversion functions in the

16763

stringstring module are affected by the

16764

locale settings. When a call to the setlocale() function

16765

changes the LC_CTYPE settings, the variables

16766

string.lowercase, string.uppercase and

16767

string.letters are recalculated. Note that this code that uses

16768

these variable through `from ... import ...',

16769

e.g. from string import letters, is not affected by subsequent

16770

setlocale() calls.

16771

The only way to perform numeric operations according to the locale

16772

is to use the special functions defined by this module:

16773

atof(), atoi(), format(),

16774

str().

16775

</description>

16776

</group>

16777

16778

<description>Extension modules should never call setlocale(), except to

16779

find out what the current locale is. But since the return value can

16780

only be used portably to restore it, that is not very useful (except

16781

perhaps to find out whether or not the locale is C).

16782

When Python is embedded in an application, if the application sets the

16783

locale to something specific before initializing Python, that is

16784

generally okay, and Python will use whatever locale is set,

16785

except that the LC_NUMERIC locale should always be

16786

C.

16787

The setlocale() function in the locale module

16788

gives the Python programmer the impression that you can manipulate the

16789

LC_NUMERIC locale setting, but this not the case at the C

16790

level: C code will always find that the LC_NUMERIC locale

16791

setting is C. This is because too much would break when the

16792

decimal point character is set to something else than a period

16793

(e.g. the Python parser would break). Caveat: threads that run

16794

without holding Python's global interpreter lock may occasionally find

16795

that the numeric locale setting differs; this is because the only

16796

portable way to implement this feature is to set the numeric locale

16797

settings to what the user requests, extract the relevant

16798

characteristics, and then restore the C numeric locale.

16799

When Python code uses the locale module to change the locale,

16800

this also affects the embedding application. If the embedding

16801

application doesn't want this to happen, it should remove the

16802

_locale extension module (which does all the work) from the

16803

table of built-in modules in the config.c file, and make sure

16804

that the _locale module is not accessible as a shared library.

16805

</description>

16806

</group>

16807

16808

</group>

16809

</group>

16810

16811

<description>Multilingual internationalization services.

16812

The gettext module provides internationalization (I18N) and

16813

localization (L10N) services for your Python modules and applications.

16814

It supports both the GNU gettext message catalog API and a

16815

higher level, class-based API that may be more appropriate for Python

16816

files. The interface described below allows you to write your

16817

module and application messages in one natural language, and provide a

16818

catalog of translated messages for running under different natural

16819

languages.

16820

Some hints on localizing your Python modules and applications are also

16821

given.

16822

</description>

16823

16824

<description>The gettext module defines the following API, which is very

16825

similar to the GNU gettext API. If you use this API you

16826

will affect the translation of your entire application globally. Often

16827

this is what you want if your application is monolingual, with the choice

16828

of language dependent on the locale of your user. If you are

16829

localizing a Python module, or if your application needs to switch

16830

languages on the fly, you probably want to use the class-based API

16831

instead.

16832

</description>

16833

16834

<description>Bind the domain to the locale directory

16835

localedir. More concretely, gettext will look for

16836

binary .mo files for the given domain using the path (on ):

16837

localedir/language/LC_MESSAGES/domain.mo,

16838

where languages is searched for in the environment variables

16839

LANGUAGE, LC_ALL, LC_MESSAGES, and

16840

LANG respectively.

16841

If localedir is omitted or None, then the current binding

16842

for domain is returned.

16843

The default locale directory is system dependent; for example,

16844

on RedHat Linux it is /usr/share/locale, but on Solaris

16845

it is /usr/lib/locale. The gettext module

16846

does not try to support these system dependent defaults;

16847

instead its default is sys.prefix/share/locale.

16848

For this reason, it is always best to call

16849

bindtextdomain() with an explicit absolute path at

16850

the start of your application.</description>

16851

16852

16853

16854

16855

<description>Change or query the current global domain. If domain is

16856

None, then the current global domain is returned, otherwise the

16857

global domain is set to domain, which is returned.</description>

16858

16859

16860

16861

16862

<description>Return the localized translation of message, based on the

16863

current global domain, language, and locale directory. This function

16864

is usually aliased as _ in the local namespace (see

16865

examples below).</description>

16866

16867

16868

16869

16870

<description>Like gettext(), but look the message up in the specified

16871

domain.</description>

16872

16873

16874

16875

16876

<description>Like gettext(), but consider plural forms. If a translation

16877

is found, apply the plural formula to n, and return the

16878

resulting message (some languages have more than two plural forms).

16879

If no translation is found, return singular if n is 1;

16880

return plural otherwise.

16881

The Plural formula is taken from the catalog header. It is a C or

16882

Python expression that has a free variable n; the expression evaluates

16883

to the index of the plural in the catalog. See the GNU gettext

16884

documentation for the precise syntax to be used in .po files, and the

16885

formulas for a variety of languages.

16886

New in version 2.3</description>

16887

16888

16889

16890

16891

<description>Like ngettext(), but look the message up in the specified

16892

domain.

16893

New in version 2.3</description>

16894

16895

16896

16897

</group>

16898

16899

<description>The class-based API of the gettext module gives you more

16900

flexibility and greater convenience than the GNU gettext

16901

API. It is the recommended way of localizing your Python applications and

16902

modules. gettext defines a ``translations'' class which

16903

implements the parsing of GNU .mo format files, and has methods

16904

for returning either standard 8-bit strings or Unicode strings.

16905

Translations instances can also install themselves in the built-in

16906

namespace as the function _().

16907

</description>

16908

16909

<description>This function implements the standard .mo file search

16910

algorithm. It takes a domain, identical to what

16911

textdomain() takes. Optional localedir is as in

16912

bindtextdomain() Optional languages is a list of

16913

strings, where each string is a language code.

16914

If localedir is not given, then the default system locale

16915

directory is used.See the footnote for

16916

bindtextdomain() above. If languages is not given,

16917

then the following environment variables are searched: LANGUAGE,

16918

LC_ALL, LC_MESSAGES, and LANG. The first one

16919

returning a non-empty value is used for the languages variable.

16920

The environment variables should contain a colon separated list of

16921

languages, which will be split on the colon to produce the expected

16922

list of language code strings.

16923

find() then expands and normalizes the languages, and then

16924

iterates through them, searching for an existing file built of these

16925

components:

16926

localedir/language/LC_MESSAGES/domain.mo

16927

The first such file name that exists is returned by find().

16928

If no such file is found, then None is returned. If all

16929

is given, it returns a list of all file names, in the order in which

16930

they appear in the languages list or the environment variables.</description>

16931

16932

16933

16934

16935

<description>Return a Translations instance based on the domain,

16936

localedir, and languages, which are first passed to

16937

find() to get a list of the

16938

associated .mo file paths. Instances with

16939

identical .mo file names are cached. The actual class instantiated

16940

is either class_ if provided, otherwise

16941

GNUTranslations. The class's constructor must take a single

16942

file object argument. If multiple files are found, later files are used as fallbacks for

16943

earlier ones. To allow setting the fallback, copy.copy

16944

is used to clone each translation object from the cache; the actual

16945

instance data is still shared with the cache.

16946

If no .mo file is found, this function raises

16947

IOError if fallback is false (which is the default),

16948

and returns a NullTranslations instance if fallback is

16949

true.</description>

16950

16951

16952

16953

16954

<description>This installs the function _ in Python's builtin namespace,

16955

based on domain, and localedir which are passed to the

16956

function translation(). The unicode flag is passed to

16957

the resulting translation object's install method.

16958

As seen below, you usually mark the strings in your application that are

16959

candidates for translation, by wrapping them in a call to the

16960

_() function, like this:

16961

print _('This string will be translated.')

16962

For convenience, you want the _() function to be installed in

16963

Python's builtin namespace, so it is easily accessible in all modules

16964

of your application.</description>

16965

16966

16967

16968

16969

<description>Takes an optional file object fp, which is ignored by the base

16970

class. Initializes ``protected'' instance variables _info and

16971

_charset which are set by derived classes, as well as _fallback,

16972

which is set through add_fallback. It then calls

16973

self._parse(fp) if fp is not None.</description>

16974

16975

16976

16977

16978

<description>No-op'd in the base class, this method takes file object fp, and

16979

reads the data from the file, initializing its message catalog. If

16980

you have an unsupported message catalog file format, you should

16981

override this method to parse your format.</description>

16982

16983

16984

16985

16986

<description>Add fallback as the fallback object for the current translation

16987

object. A translation object should consult the fallback if it cannot

16988

provide a translation for a given message.</description>

16989

16990

16991

16992

16993

<description>If a fallback has been set, forward gettext to the fallback.

16994

Otherwise, return the translated message. Overridden in derived classes.</description>

16995

16996

16997

16998

16999

<description>If a fallback has been set, forward ugettext to the fallback.

17000

Otherwise, return the translated message as a Unicode string.

17001

Overridden in derived classes.</description>

17002

17003

17004

17005

17006

<description>If a fallback has been set, forward ngettext to the fallback.

17007

Otherwise, return the translated message. Overridden in derived classes.

17008

New in version 2.3</description>

17009

17010

17011

17012

17013

<description>If a fallback has been set, forward ungettext to the fallback.

17014

Otherwise, return the translated message as a Unicode string.

17015

Overridden in derived classes.

17016

New in version 2.3</description>

17017

17018

17019

17020

17021

<description>Return the ``protected'' _info variable.</description>

17022

17023

</element>

17024

17025

17026

<description>Return the ``protected'' _charset variable.</description>

17027

17028

</element>

17029

17030

17031

<description>If the unicode flag is false, this method installs

17032

self.gettext() into the built-in namespace, binding it to

17033

_. If unicode is true, it binds self.ugettext()

17034

instead. By default, unicode is false.

17035

Note that this is only one way, albeit the most convenient way, to

17036

make the _ function available to your application. Because it

17037

affects the entire application globally, and specifically the built-in

17038

namespace, localized modules should never install _.

17039

Instead, they should use this code to make _ available to

17040

their module:

17041

import gettext

17042

t = gettext.translation('mymodule', ...)

17043

_ = t.gettext

17044

This puts _ only in the module's global namespace and so

17045

only affects calls within this module.</description>

17046

17047

17048

17049

17050

<description>Look up the message id in the catalog and return the

17051

corresponding message string, as an 8-bit string encoded with the

17052

catalog's charset encoding, if known. If there is no entry in the

17053

catalog for the message id, and a fallback has been set, the

17054

look up is forwarded to the fallback's gettext() method.

17055

Otherwise, the message id is returned.</description>

17056

17057

17058

17059

17060

<description>Look up the message id in the catalog and return the

17061

corresponding message string, as a Unicode string. If there is no

17062

entry in the catalog for the message id, and a fallback has been

17063

set, the look up is forwarded to the fallback's ugettext()

17064

method. Otherwise, the message id is returned.</description>

17065

17066

17067

17068

17069

<description>Do a plural-forms lookup of a message id. singular is used as

17070

the message id for purposes of lookup in the catalog, while n is

17071

used to determine which plural form to use. The returned message

17072

string is an 8-bit string encoded with the catalog's charset encoding,

17073

if known.

17074

If the message id is not found in the catalog, and a fallback is

17075

specified, the request is forwarded to the fallback's

17076

ngettext() method. Otherwise, when n is 1 singular is

17077

returned, and plural is returned in all other cases.

17078

New in version 2.3</description>

17079

17080

17081

17082

17083

<description>Do a plural-forms lookup of a message id. singular is used as

17084

the message id for purposes of lookup in the catalog, while n is

17085

used to determine which plural form to use. The returned message

17086

string is a Unicode string.

17087

If the message id is not found in the catalog, and a fallback is

17088

specified, the request is forwarded to the fallback's

17089

ungettext() method. Otherwise, when n is 1 singular is

17090

returned, and plural is returned in all other cases.

17091

Here is an example:

17092

n = len(os.listdir('.'))

17093

cat = GNUTranslations(somefile)

17094

message = cat.ungettext(

17095

'There is %(num)d file in this directory',

17096

'There are %(num)d files in this directory',

17097

n) % {'n': n}

17098

New in version 2.3</description>

17099

17100

17101

17102

</group>

17103

17104

<description>Internationalization (I18N) refers to the operation by which a program

17105

is made aware of multiple languages. Localization (L10N) refers to

17106

the adaptation of your program, once internationalized, to the local

17107

language and cultural habits. In order to provide multilingual

17108

messages for your Python programs, you need to take the following

17109

steps:

17110

prepare your program or module by specially marking

17111

translatable strings

17112

run a suite of tools over your marked files to generate raw

17113

messages catalogs

17114

create language specific translations of the message catalogs

17115

use the gettext module so that message strings are

17116

properly translated

17117

In order to prepare your code for I18N, you need to look at all the

17118

strings in your files. Any string that needs to be translated

17119

should be marked by wrapping it in _('...') --- that is, a call

17120

to the function _(). For example:

17121

filename = 'mylog.txt'

17122

message = _('writing a log message')

17123

fp = open(filename, 'w')

17124

fp.write(message)

17125

fp.close()

17126

In this example, the string 'writing a log message' is marked as

17127

a candidate for translation, while the strings 'mylog.txt' and

17128

'w' are not.

17129

The Python distribution comes with two tools which help you generate

17130

the message catalogs once you've prepared your source code. These may

17131

or may not be available from a binary distribution, but they can be

17132

found in a source distribution, in the Tools/i18n directory.

17133

The pygettextFran cois Pinard has

17134

written a program called

17135

xpot which does a similar job. It is available as part of

17136

his po-utils package at

17137

http://www.iro.umontreal.ca/contrib/po-utils/HTML/. program

17138

scans all your Python source code looking for the strings you

17139

previously marked as translatable. It is similar to the GNU

17140

gettext program except that it understands all the

17141

intricacies of Python source code, but knows nothing about C or Cpp

17142

source code. You don't need GNU gettext unless you're also

17143

going to be translating C code (such as C extension modules).

17144

pygettext generates textual Uniforum-style human readable

17145

message catalog .pot files, essentially structured human

17146

readable files which contain every marked string in the source code,

17147

along with a placeholder for the translation strings.

17148

pygettext is a command line script that supports a similar

17149

command line interface as xgettext; for details on its use,

17150

run:

17151

pygettext.py --help

17152

Copies of these .pot files are then handed over to the

17153

individual human translators who write language-specific versions for

17154

every supported natural language. They send you back the filled in

17155

language-specific versions as a .po file. Using the

17156

msgfmt.pymsgfmt.py is binary

17157

compatible with GNU msgfmt except that it provides a

17158

simpler, all-Python implementation. With this and

17159

pygettext.py, you generally won't need to install the GNU

17160

gettext package to internationalize your Python

17161

applications. program (in the Tools/i18n directory), you take the

17162

.po files from your translators and generate the

17163

machine-readable .mo binary catalog files. The .mo

17164

files are what the gettext module uses for the actual

17165

translation processing during run-time.

17166

How you use the gettext module in your code depends on

17167

whether you are internationalizing your entire application or a single

17168

module.

17169

Localizing your module

17170

If you are localizing your module, you must take care not to make

17171

global changes, e.g. to the built-in namespace. You should not use

17172

the GNU gettext API but instead the class-based API. Let's say your module is called ``spam'' and the module's various

17173

natural language translation .mo files reside in

17174

/usr/share/locale in GNU gettext format. Here's what

17175

you would put at the top of your module:

17176

import gettext

17177

t = gettext.translation('spam', '/usr/share/locale')

17178

_ = t.gettext

17179

If your translators were providing you with Unicode strings in their

17180

.po files, you'd instead do:

17181

import gettext

17182

t = gettext.translation('spam', '/usr/share/locale')

17183

_ = t.ugettext

17184

Localizing your application

17185

If you are localizing your application, you can install the _()

17186

function globally into the built-in namespace, usually in the main driver file

17187

of your application. This will let all your application-specific

17188

files just use _('...') without having to explicitly install it in

17189

each file.

17190

In the simple case then, you need only add the following bit of code

17191

to the main driver file of your application:

17192

import gettext

17193

gettext.install('myapplication')

17194

If you need to set the locale directory or the unicode flag,

17195

you can pass these into the install() function:

17196

import gettext

17197

gettext.install('myapplication', '/usr/share/locale', unicode=1)

17198

Changing languages on the fly

17199

If your program needs to support many languages at the same time, you

17200

may want to create multiple translation instances and then switch

17201

between them explicitly, like so:

17202

import gettext

17203

lang1 = gettext.translation(languages=['en'])

17204

lang2 = gettext.translation(languages=['fr'])

17205

lang3 = gettext.translation(languages=['de'])

17206

# start by using language1

17207

lang1.install()

17208

# ... time goes by, user selects language 2

17209

lang2.install()

17210

# ... more time goes by, user selects language 3

17211

lang3.install()

17212

Deferred translations

17213

In most coding situations, strings are translated where they are coded.

17214

Occasionally however, you need to mark strings for translation, but

17215

defer actual translation until later. A classic example is:

17216

animals = ['mollusk',

17217

'albatross',

17218

'rat',

17219

'penguin',

17220

'python',

17221

]

17222

# ...

17223

for a in animals:

17224

print a

17225

Here, you want to mark the strings in the animals list as being

17226

translatable, but you don't actually want to translate them until they

17227

are printed.

17228

Here is one way you can handle this situation:

17229

def _(message): return message

17230

animals = [_('mollusk'),

17231

_('albatross'),

17232

_('rat'),

17233

_('penguin'),

17234

_('python'),

17235

]

17236

del _

17237

# ...

17238

for a in animals:

17239

print _(a)

17240

This works because the dummy definition of _() simply returns

17241

the string unchanged. And this dummy definition will temporarily

17242

override any definition of _() in the built-in namespace

17243

(until the del command).

17244

Take care, though if you have a previous definition of _ in

17245

the local namespace.

17246

Note that the second use of _() will not identify ``a'' as

17247

being translatable to the pygettext program, since it is not

17248

a string.

17249

Another way to handle this is with the following example:

17250

def N_(message): return message

17251

animals = [N_('mollusk'),

17252

N_('albatross'),

17253

N_('rat'),

17254

N_('penguin'),

17255

N_('python'),

17256

]

17257

# ...

17258

for a in animals:

17259

print _(a)

17260

In this case, you are marking translatable strings with the function

17261

N_(),The choice of N_() here is totally

17262

arbitrary; it could have just as easily been

17263

MarkThisStringForTranslation().

17264

which won't conflict with any definition of

17265

_(). However, you will need to teach your message extraction

17266

program to look for translatable strings marked with N_().

17267

pygettext and xpot both support this through the

17268

use of command line switches.

17269

</description>

17270

</group>

17271

17272

</group>

17273

</group>

17274

17275

<description>% These apply to all modules, and may be given more than once:

17276

Logging module for Python based on 282.

17277

New in version 2.3

17278

This module defines functions and classes which implement a flexible

17279

error logging system for applications.

17280

Logging is performed by calling methods on instances of the

17281

Logger class (hereafter called loggers). Each instance has a

17282

name, and they are conceptually arranged in a name space hierarchy

17283

using dots (periods) as separators. For example, a logger named

17284

"scan" is the parent of loggers "scan.text", "scan.html" and "scan.pdf".

17285

Logger names can be anything you want, and indicate the area of an

17286

application in which a logged message originates.

17287

Logged messages also have levels of importance associated with them.

17288

The default levels provided are DEBUG, INFO,

17289

WARNING, ERROR and CRITICAL. As a

17290

convenience, you indicate the importance of a logged message by calling

17291

an appropriate method of Logger. The methods are

17292

debug(), info(), warning(), error() and

17293

critical(), which mirror the default levels. You are not

17294

constrained to use these levels: you can specify your own and use a

17295

more general Logger method, log(), which takes an

17296

explicit level argument.

17297

Levels can also be associated with loggers, being set either by the

17298

developer or through loading a saved logging configuration. When a

17299

logging method is called on a logger, the logger compares its own

17300

level with the level associated with the method call. If the logger's

17301

level is higher than the method call's, no logging message is actually

17302

generated. This is the basic mechanism controlling the verbosity of

17303

logging output.

17304

Logging messages are encoded as instances of the LogRecord class.

17305

When a logger decides to actually log an event, an LogRecord

17306

instance is created from the logging message.

17307

Logging messages are subjected to a dispatch mechanism through the

17308

use of handlers, which are instances of subclasses of the

17309

Handler class. Handlers are responsible for ensuring that a logged

17310

message (in the form of a LogRecord) ends up in a particular

17311

location (or set of locations) which is useful for the target audience for

17312

that message (such as end users, support desk staff, system administrators,

17313

developers). Handlers are passed LogRecord instances intended for

17314

particular destinations. Each logger can have zero, one or more handlers

17315

associated with it (via the addHandler method of Logger).

17316

In addition to any handlers directly associated with a logger,

17317

all handlers associated with all ancestors of the logger are

17318

called to dispatch the message.

17319

Just as for loggers, handlers can have levels associated with them.

17320

A handler's level acts as a filter in the same way as a logger's level does.

17321

If a handler decides to actually dispatch an event, the emit() method

17322

is used to send the message to its destination. Most user-defined subclasses

17323

of Handler will need to override this emit().

17324

In addition to the base Handler class, many useful subclasses

17325

are provided:

17326

StreamHandler instances send error messages to

17327

streams (file-like objects).

17328

FileHandler instances send error messages to disk

17329

files.

17330

RotatingFileHandler instances send error messages to disk

17331

files, with support for maximum log file sizes and log file rotation.

17332

SocketHandler instances send error messages to

17333

TCP/IP sockets.

17334

DatagramHandler instances send error messages to UDP

17335

sockets.

17336

SMTPHandler instances send error messages to a

17337

designated email address.

17338

SysLogHandler instances send error messages to a

17339

syslog daemon, possibly on a remote machine.

17340

NTEventLogHandler instances send error messages to a

17341

Windows NT/2000/XP event log.

17342

MemoryHandler instances send error messages to a

17343

buffer in memory, which is flushed whenever specific criteria are

17344

met.

17345

HTTPHandler instances send error messages to an

17346

HTTP server using either GET or POST semantics.

17347

The StreamHandler and FileHandler classes are defined

17348

in the core logging package. The other handlers are defined in a sub-

17349

module, logging.handlers. (There is also another sub-module,

17350

logging.config, for configuration functionality.)

17351

Logged messages are formatted for presentation through instances of the

17352

Formatter class. They are initialized with a format string

17353

suitable for use with the % operator and a dictionary.

17354

For formatting multiple messages in a batch, instances of

17355

BufferingFormatter can be used. In addition to the format string

17356

(which is applied to each message in the batch), there is provision for

17357

header and trailer format strings.

17358

When filtering based on logger level and/or handler level is not enough,

17359

instances of Filter can be added to both Logger and

17360

Handler instances (through their addFilter() method).

17361

Before deciding to process a message further, both loggers and handlers

17362

consult all their filters for permission. If any filter returns a false

17363

value, the message is not processed further.

17364

The basic Filter functionality allows filtering by specific logger

17365

name. If this feature is used, messages sent to the named logger and its

17366

children are allowed through the filter, and all others dropped.

17367

In addition to the classes described above, there are a number of module-

17368

level functions.

17369

</description>

17370

17371

<description>Return a logger with the specified name or, if no name is specified, return

17372

a logger which is the root logger of the hierarchy.

17373

All calls to this function with a given name return the same logger instance.

17374

This means that logger instances never need to be passed between different

17375

parts of an application.</description>

17376

17377

17378

17379

17380

<description>Logs a message with level DEBUG on the root logger.

17381

The msg is the message format string, and the args are the

17382

arguments which are merged into msg. The only keyword argument in

17383

kwargs which is inspected is exc_info which, if it does not

17384

evaluate as false, causes exception information (via a call to

17385

sys.exc_info()) to be added to the logging message.</description>

17386

17387

17388

17389

17390

<description>Logs a message with level INFO on the root logger.

17391

The arguments are interpreted as for debug().</description>

17392

17393

17394

17395

17396

<description>Logs a message with level WARNING on the root logger.

17397

The arguments are interpreted as for debug().</description>

17398

17399

17400

17401

17402

<description>Logs a message with level ERROR on the root logger.

17403

The arguments are interpreted as for debug().</description>

17404

17405

17406

17407

17408

<description>Logs a message with level CRITICAL on the root logger.

17409

The arguments are interpreted as for debug().</description>

17410

17411

17412

17413

17414

<description>Logs a message with level ERROR on the root logger.

17415

The arguments are interpreted as for debug(). Exception info

17416

is added to the logging message. This function should only be called

17417

from an exception handler.</description>

17418

17419

17420

17421

17422

<description>Provides an overriding level lvl for all loggers which takes

17423

precedence over the logger's own level. When the need arises to

17424

temporarily throttle logging output down across the whole application,

17425

this function can be useful.</description>

17426

17427

17428

17429

17430

<description>Associates level lvl with text levelName in an internal

17431

dictionary, which is used to map numeric levels to a textual

17432

representation, for example when a Formatter formats a message.

17433

This function can also be used to define your own levels. The only

17434

constraints are that all levels used must be registered using this

17435

function, levels should be positive integers and they should increase

17436

in increasing order of severity.</description>

17437

17438

17439

17440

17441

<description>Returns the textual representation of logging level lvl. If the

17442

level is one of the predefined levels CRITICAL,

17443

ERROR, WARNING, INFO or DEBUG

17444

then you get the corresponding string. If you have associated levels

17445

with names using addLevelName() then the name you have associated

17446

with lvl is returned. Otherwise, the string "Level " % lvl is

17447

returned.</description>

17448

17449

17450

17451

17452

<description>Creates and returns a new LogRecord instance whose attributes are

17453

defined by attrdict. This function is useful for taking a pickled

17454

LogRecord attribute dictionary, sent over a socket, and reconstituting

17455

it as a LogRecord instance at the receiving end.</description>

17456

17457

17458

17459

17460

<description>Does basic configuration for the logging system by creating a

17461

StreamHandler with a default Formatter and adding it to

17462

the root logger. The functions debug(), info(),

17463

warning(), error() and critical() will call

17464

basicConfig() automatically if no handlers are defined for the

17465

root logger.</description>

17466

17467

</element>

17468

17469

17470

<description>Informs the logging system to perform an orderly shutdown by flushing and

17471

closing all handlers.</description>

17472

17473

</element>

17474

17475

17476

<description>Tells the logging system to use the class klass when instantiating a

17477

logger. The class should define __init__() such that only a name

17478

argument is required, and the __init__() should call

17479

Logger.__init__(). This function is typically called before any

17480

loggers are instantiated by applications which need to use custom logger

17481

behavior.</description>

17482

17483

17484

17485

17486

<description>Loggers have the following attributes and methods. Note that Loggers are

17487

never instantiated directly, but always through the module-level function

17488

logging.getLogger(name).

17489

{propagate}

17490

If this evaluates to false, logging messages are not passed by this

17491

logger or by child loggers to higher level (ancestor) loggers. The

17492

constructor sets this attribute to 1.

17493

</description>

17494

17495

<description>Sets the threshold for this logger to lvl. Logging messages

17496

which are less severe than lvl will be ignored. When a logger is

17497

created, the level is set to NOTSET (which causes all messages

17498

to be processed in the root logger, or delegation to the parent in non-root

17499

loggers).</description>

17500

17501

17502

17503

17504

<description>Indicates if a message of severity lvl would be processed by

17505

this logger. This method checks first the module-level level set by

17506

logging.disable(lvl) and then the logger's effective level as

17507

determined by getEffectiveLevel().</description>

17508

17509

17510

17511

17512

<description>Indicates the effective level for this logger. If a value other than

17513

NOTSET has been set using setLevel(), it is returned.

17514

Otherwise, the hierarchy is traversed towards the root until a value

17515

other than NOTSET is found, and that value is returned.</description>

17516

17517

</element>

17518

17519

17520

<description>Logs a message with level DEBUG on this logger.

17521

The msg is the message format string, and the args are the

17522

arguments which are merged into msg. The only keyword argument in

17523

kwargs which is inspected is exc_info which, if it does not

17524

evaluate as false, causes exception information (via a call to

17525

sys.exc_info()) to be added to the logging message.</description>

17526

17527

17528

17529

17530

<description>Logs a message with level INFO on this logger.

17531

The arguments are interpreted as for debug().</description>

17532

17533

17534

17535

17536

<description>Logs a message with level WARNING on this logger.

17537

The arguments are interpreted as for debug().</description>

17538

17539

17540

17541

17542

<description>Logs a message with level ERROR on this logger.

17543

The arguments are interpreted as for debug().</description>

17544

17545

17546

17547

17548

<description>Logs a message with level CRITICAL on this logger.

17549

The arguments are interpreted as for debug().</description>

17550

17551

17552

17553

17554

<description>Logs a message with level lvl on this logger.

17555

The other arguments are interpreted as for debug().</description>

17556

17557

17558

17559

17560

<description>Logs a message with level ERROR on this logger.

17561

The arguments are interpreted as for debug(). Exception info

17562

is added to the logging message. This method should only be called

17563

from an exception handler.</description>

17564

17565

17566

17567

17568

<description>Adds the specified filter filt to this logger.</description>

17569

17570

17571

17572

17573

<description>Removes the specified filter filt from this logger.</description>

17574

17575

17576

17577

17578

<description>Applies this logger's filters to the record and returns a true value if

17579

the record is to be processed.</description>

17580

17581

17582

17583

17584

<description>Adds the specified handler hdlr to this logger.</description>

17585

17586

17587

17588

17589

<description>Removes the specified handler hdlr from this logger.</description>

17590

17591

17592

17593

17594

<description>Finds the caller's source filename and line number. Returns the filename

17595

and line number as a 2-element tuple.</description>

17596

17597

</element>

17598

17599

17600

<description>Handles a record by passing it to all handlers associated with this logger

17601

and its ancestors (until a false value of propagate is found).

17602

This method is used for unpickled records received from a socket, as well

17603

as those created locally. Logger-level filtering is applied using

17604

filter().</description>

17605

17606

17607

17608

17609

<description>This is a factory method which can be overridden in subclasses to create

17610

specialized LogRecord instances.</description>

17611

17612

17613

17614

</group>

17615

17616

<description>Handlers have the following attributes and methods. Note that

17617

Handler is never instantiated directly; this class acts as a

17618

base for more useful subclasses. However, the __init__()

17619

method in subclasses needs to call Handler.__init__().

17620

</description>

17621

17622

<description>Initializes the Handler instance by setting its level, setting

17623

the list of filters to the empty list and creating a lock (using

17624

createLock()) for serializing access to an I/O mechanism.</description>

17625

17626

17627

17628

17629

<description>Initializes a thread lock which can be used to serialize access to

17630

underlying I/O functionality which may not be threadsafe.</description>

17631

17632

</element>

17633

17634

17635

<description>Acquires the thread lock created with createLock().</description>

17636

17637

</element>

17638

17639

17640

<description>Releases the thread lock acquired with acquire().</description>

17641

17642

</element>

17643

17644

17645

<description>Sets the threshold for this handler to lvl. Logging messages which are

17646

less severe than lvl will be ignored. When a handler is created, the

17647

level is set to NOTSET (which causes all messages to be processed).</description>

17648

17649

17650

17651

17652

<description>Sets the Formatter for this handler to form.</description>

17653

17654

17655

17656

17657

<description>Adds the specified filter filt to this handler.</description>

17658

17659

17660

17661

17662

<description>Removes the specified filter filt from this handler.</description>

17663

17664

17665

17666

17667

<description>Applies this handler's filters to the record and returns a true value if

17668

the record is to be processed.</description>

17669

17670

17671

17672

17673

<description>Ensure all logging output has been flushed. This version does

17674

nothing and is intended to be implemented by subclasses.</description>

17675

17676

</element>

17677

17678

17679

<description>Tidy up any resources used by the handler. This version does

17680

nothing and is intended to be implemented by subclasses.</description>

17681

17682

</element>

17683

17684

17685

<description>Conditionally emits the specified logging record, depending on

17686

filters which may have been added to the handler. Wraps the actual

17687

emission of the record with acquisition/release of the I/O thread

17688

lock.</description>

17689

17690

17691

17692

17693

<description>This method should be called from handlers when an exception is

17694

encountered during an emit() call. By default it does nothing,

17695

which means that exceptions get silently ignored. This is what is

17696

mostly wanted for a logging system - most users will not care

17697

about errors in the logging system, they are more interested in

17698

application errors. You could, however, replace this with a custom

17699

handler if you wish.</description>

17700

17701

</element>

17702

17703

17704

<description>Do formatting for a record - if a formatter is set, use it.

17705

Otherwise, use the default formatter for the module.</description>

17706

17707

17708

17709

17710

<description>Do whatever it takes to actually log the specified logging record.

17711

This version is intended to be implemented by subclasses and so

17712

raises a NotImplementedError.</description>

17713

17714

17715

17716

17717

<description>Returns a new instance of the StreamHandler class. If strm is

17718

specified, the instance will use it for logging output; otherwise,

17719

sys.stderr will be used.</description>

17720

17721

17722

17723

17724

<description>If a formatter is specified, it is used to format the record.

17725

The record is then written to the stream with a trailing newline.

17726

If exception information is present, it is formatted using

17727

traceback.print_exception() and appended to the stream.</description>

17728

17729

17730

17731

17732

<description>Flushes the stream by calling its flush() method. Note that

17733

the close() method is inherited from Handler and

17734

so does nothing, so an explicit flush() call may be needed

17735

at times.</description>

17736

17737

</element>

17738

17739

17740

<description>Returns a new instance of the FileHandler class. The specified

17741

file is opened and used as the stream for logging. If mode is

17742

not specified, 'a' is used. By default, the file grows

17743

indefinitely.</description>

17744

17745

17746

17747

17748

<description>Closes the file.</description>

17749

17750

</element>

17751

17752

17753

<description>Outputs the record to the file.</description>

17754

17755

17756

17757

17758

<description>Returns a new instance of the RotatingFileHandler class. The

17759

specified file is opened and used as the stream for logging. If

17760

mode is not specified, 'a' is used. By default, the

17761

file grows indefinitely. You can use the maxBytes and

17762

backupCount values to allow the file to rollover at a

17763

predetermined size. When the size is about to be exceeded, the file is

17764

closed and a new file is silently opened for output. Rollover occurs

17765

whenever the current log file is nearly maxBytes in length; if

17766

maxBytes is zero, rollover never occurs. If backupCount

17767

is non-zero, the system will save old log files by appending the

17768

extensions ".1", ".2" etc., to the filename. For example, with

17769

a backupCount of 5 and a base file name of

17770

app.log, you would get app.log,

17771

app.log.1, app.log.2, up to app.log.5. The file being

17772

written to is always app.log. When this file is filled, it is

17773

closed and renamed to app.log.1, and if files app.log.1,

17774

app.log.2, etc. exist, then they are renamed to app.log.2,

17775

app.log.3 etc. respectively.</description>

17776

17777

17778

17779

17780

<description>Does a rollover, as described above.</description>

17781

17782

</element>

17783

17784

17785

<description>Outputs the record to the file, catering for rollover as described

17786

in setRollover().</description>

17787

17788

17789

17790

17791

<description>Returns a new instance of the SocketHandler class intended to

17792

communicate with a remote machine whose address is given by host

17793

and port.</description>

17794

17795

17796

17797

17798

<description>Closes the socket.</description>

17799

17800

</element>

17801

17802

17803

17804

17805

</element>

17806

17807

17808

<description>Pickles the record's attribute dictionary and writes it to the socket in

17809

binary format. If there is an error with the socket, silently drops the

17810

packet. If the connection was previously lost, re-establishes the connection.

17811

To unpickle the record at the receiving end into a LogRecord, use the

17812

makeLogRecord function.</description>

17813

17814

</element>

17815

17816

17817

<description>Handles an error which has occurred during emit(). The

17818

most likely cause is a lost connection. Closes the socket so that

17819

we can retry on the next event.</description>

17820

17821

</element>

17822

17823

17824

<description>This is a factory method which allows subclasses to define the precise

17825

type of socket they want. The default implementation creates a TCP

17826

socket (socket.SOCK_STREAM).</description>

17827

17828

</element>

17829

17830

17831

<description>Pickles the record's attribute dictionary in binary format with a length

17832

prefix, and returns it ready for transmission across the socket.</description>

17833

17834

17835

17836

17837

<description>Send a pickled string packet to the socket. This function allows

17838

for partial sends which can happen when the network is busy.</description>

17839

17840

17841

17842

17843

<description>Returns a new instance of the DatagramHandler class intended to

17844

communicate with a remote machine whose address is given by host

17845

and port.</description>

17846

17847

17848

17849

17850

<description>Pickles the record's attribute dictionary and writes it to the socket in

17851

binary format. If there is an error with the socket, silently drops the

17852

packet.

17853

To unpickle the record at the receiving end into a LogRecord, use the

17854

makeLogRecord function.</description>

17855

17856

</element>

17857

17858

17859

<description>The factory method of SocketHandler is here overridden to create

17860

a UDP socket (socket.SOCK_DGRAM).</description>

17861

17862

</element>

17863

17864

17865

<description>Send a pickled string to a socket.</description>

17866

17867

17868

17869

17870

<description>Returns a new instance of the SysLogHandler class intended to

17871

communicate with a remote machine whose address is given by

17872

address in the form of a (host, port)

17873

tuple. If address is not specified, ('localhost', 514) is

17874

used. The address is used to open a UDP socket. If facility is

17875

not specified, LOG_USER is used.</description>

17876

17877

17878

17879

17880

<description>Closes the socket to the remote host.</description>

17881

17882

</element>

17883

17884

17885

<description>The record is formatted, and then sent to the syslog server. If

17886

exception information is present, it is not sent to the server.</description>

17887

17888

17889

17890

17891

<description>Encodes the facility and priority into an integer. You can pass in strings

17892

or integers - if strings are passed, internal mapping dictionaries are used

17893

to convert them to integers.</description>

17894

17895

17896

17897

17898

<description>Returns a new instance of the NTEventLogHandler class. The

17899

appname is used to define the application name as it appears in the

17900

event log. An appropriate registry entry is created using this name.

17901

The dllname should give the fully qualified pathname of a .dll or .exe

17902

which contains message definitions to hold in the log (if not specified,

17903

'win32service.pyd' is used - this is installed with the Win32

17904

extensions and contains some basic placeholder message definitions.

17905

Note that use of these placeholders will make your event logs big, as the

17906

entire message source is held in the log. If you want slimmer logs, you have

17907

to pass in the name of your own .dll or .exe which contains the message

17908

definitions you want to use in the event log). The logtype is one of

17909

'Application', 'System' or 'Security', and

17910

defaults to 'Application'.</description>

17911

17912

17913

17914

17915

<description>At this point, you can remove the application name from the registry as a

17916

source of event log entries. However, if you do this, you will not be able

17917

to see the events as you intended in the Event Log Viewer - it needs to be

17918

able to access the registry to get the .dll name. The current version does

17919

not do this (in fact it doesn't do anything).</description>

17920

17921

</element>

17922

17923

17924

<description>Determines the message ID, event category and event type, and then logs the

17925

message in the NT event log.</description>

17926

17927

17928

17929

17930

<description>Returns the event category for the record. Override this if you

17931

want to specify your own categories. This version returns 0.</description>

17932

17933

17934

17935

17936

<description>Returns the event type for the record. Override this if you want

17937

to specify your own types. This version does a mapping using the

17938

handler's typemap attribute, which is set up in __init__()

17939

to a dictionary which contains mappings for DEBUG,

17940

INFO, WARNING, ERROR and

17941

CRITICAL. If you are using your own levels, you will either need

17942

to override this method or place a suitable dictionary in the

17943

handler's typemap attribute.</description>

17944

17945

17946

17947

17948

<description>Returns the message ID for the record. If you are using your

17949

own messages, you could do this by having the msg passed to the

17950

logger being an ID rather than a format string. Then, in here,

17951

you could use a dictionary lookup to get the message ID. This

17952

version returns 1, which is the base message ID in

17953

win32service.pyd.</description>

17954

17955

17956

17957

17958

<description>Returns a new instance of the SMTPHandler class. The

17959

instance is initialized with the from and to addresses and subject

17960

line of the email. The toaddrs should be a list of strings without

17961

domain names (That's what the mailhost is for). To specify a

17962

non-standard SMTP port, use the (host, port) tuple format for the

17963

mailhost argument. If you use a string, the standard SMTP port

17964

is used.</description>

17965

17966

17967

17968

17969

<description>Formats the record and sends it to the specified addressees.</description>

17970

17971

17972

17973

17974

<description>If you want to specify a subject line which is record-dependent,

17975

override this method.</description>

17976

17977

17978

17979

17980

<description>Initializes the handler with a buffer of the specified capacity.</description>

17981

17982

17983

17984

17985

<description>Appends the record to the buffer. If shouldFlush() returns true,

17986

calls flush() to process the buffer.</description>

17987

17988

17989

17990

17991

<description>You can override this to implement custom flushing behavior. This version

17992

just zaps the buffer to empty.</description>

17993

17994

</element>

17995

17996

17997

<description>Returns true if the buffer is up to capacity. This method can be

17998

overridden to implement custom flushing strategies.</description>

17999

18000

18001

18002

18003

<description>Returns a new instance of the MemoryHandler class. The

18004

instance is initialized with a buffer size of capacity. If

18005

flushLevel is not specified, ERROR is used. If no

18006

target is specified, the target will need to be set using

18007

setTarget() before this handler does anything useful.</description>

18008

18009

18010

18011

18012

<description>Calls flush(), sets the target to None and

18013

clears the buffer.</description>

18014

18015

</element>

18016

18017

18018

<description>For a MemoryHandler, flushing means just sending the buffered

18019

records to the target, if there is one. Override if you want

18020

different behavior.</description>

18021

18022

</element>

18023

18024

18025

<description>Sets the target handler for this handler.</description>

18026

18027

18028

18029

18030

<description>Checks for buffer full or a record at the flushLevel or higher.</description>

18031

18032

18033

18034

18035

<description>Returns a new instance of the HTTPHandler class. The

18036

instance is initialized with a host address, url and HTTP method.

18037

If no method is specified, GET is used.</description>

18038

18039

18040

18041

18042

<description>Sends the record to the Web server as an URL-encoded dictionary.</description>

18043

18044

18045

18046

</group>

18047

18048

<description>Formatters have the following attributes and methods. They are

18049

responsible for converting a LogRecord to (usually) a string

18050

which can be interpreted by either a human or an external system. The

18051

base

18052

Formatter allows a formatting string to be specified. If none is

18053

supplied, the default value of '%(message)s\ is used.

18054

A Formatter can be initialized with a format string which makes use of

18055

knowledge of the LogRecord attributes - such as the default value

18056

mentioned above making use of the fact that the user's message and

18057

arguments are pre-formatted into a LogRecord's message

18058

attribute. This format string contains standard python %-style

18059

mapping keys. See section typesseq-strings, ``String Formatting

18060

Operations,'' for more information on string formatting.

18061

Currently, the useful mapping keys in a LogRecord are:

18062

{l|l}{code}{Format}{Description}

18063

%(name)s {Name of the logger (logging channel).}

18064

%(levelno)s {Numeric logging level for the message

18065

(DEBUG, INFO,

18066

WARNING, ERROR,

18067

CRITICAL).}

18068

%(levelname)s{Text logging level for the message

18069

('DEBUG', 'INFO',

18070

'WARNING', 'ERROR',

18071

'CRITICAL').}

18072

%(pathname)s {Full pathname of the source file where the logging

18073

call was issued (if available).}

18074

%(filename)s {Filename portion of pathname.}

18075

%(module)s {Module (name portion of filename).}

18076

%(lineno)d {Source line number where the logging call was issued

18077

(if available).}

18078

%(created)f {Time when the LogRecord was created (as

18079

returned by time.time()).}

18080

%(asctime)s {Human-readable time when the LogRecord was created.

18081

By default this is of the form

18082

``2003-07-08 16:49:45,896'' (the numbers after the

18083

comma are millisecond portion of the time).}

18084

%(msecs)d {Millisecond portion of the time when the

18085

LogRecord was created.}

18086

%(thread)d {Thread ID (if available).}

18087

%(process)d {Process ID (if available).}

18088

%(message)s {The logged message, computed as msg % args.}

18089

</description>

18090

18091

<description>Returns a new instance of the Formatter class. The

18092

instance is initialized with a format string for the message as a whole,

18093

as well as a format string for the date/time portion of a message. If

18094

no fmt is specified, '%(message)s' is used. If no datefmt

18095

is specified, the ISO8601 date format is used.</description>

18096

18097

18098

18099

18100

<description>The record's attribute dictionary is used as the operand to a

18101

string formatting operation. Returns the resulting string.

18102

Before formatting the dictionary, a couple of preparatory steps

18103

are carried out. The message attribute of the record is computed

18104

using msg % args. If the formatting string contains

18105

'(asctime)', formatTime() is called to format the

18106

event time. If there is exception information, it is formatted using

18107

formatException() and appended to the message.</description>

18108

18109

18110

18111

18112

<description>This method should be called from format() by a formatter which

18113

wants to make use of a formatted time. This method can be overridden

18114

in formatters to provide for any specific requirement, but the

18115

basic behavior is as follows: if datefmt (a string) is specified,

18116

it is used with time.strftime() to format the creation time of the

18117

record. Otherwise, the ISO8601 format is used. The resulting

18118

string is returned.</description>

18119

18120

18121

18122

18123

<description>Formats the specified exception information (a standard exception tuple

18124

as returned by sys.exc_info()) as a string. This default

18125

implementation just uses traceback.print_exception().

18126

The resulting string is returned.</description>

18127

18128

18129

18130

</group>

18131

18132

<description>Filters can be used by Handlers and Loggers for

18133

more sophisticated filtering than is provided by levels. The base filter

18134

class only allows events which are below a certain point in the logger

18135

hierarchy. For example, a filter initialized with "A.B" will allow events

18136

logged by loggers "A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB",

18137

"B.A.B" etc. If initialized with the empty string, all events are passed.

18138

</description>

18139

18140

<description>Returns an instance of the Filter class. If name is specified,

18141

it names a logger which, together with its children, will have its events

18142

allowed through the filter. If no name is specified, allows every event.</description>

18143

18144

18145

18146

18147

<description>Is the specified record to be logged? Returns zero for no, nonzero for

18148

yes. If deemed appropriate, the record may be modified in-place by this

18149

method.</description>

18150

18151

18152

18153

</group>

18154

18155

<description>LogRecord instances are created every time something is logged. They

18156

contain all the information pertinent to the event being logged. The

18157

main information passed in is in msg and args, which are combined

18158

using msg % args to create the message field of the record. The record

18159

also includes information such as when the record was created, the

18160

source line where the logging call was made, and any exception

18161

information to be logged.

18162

LogRecord has no methods; it's just a repository for information about the

18163

logging event. The only reason it's a class rather than a dictionary is to

18164

facilitate extension.

18165

</description>

18166

18167

<description>Returns an instance of LogRecord initialized with interesting

18168

information. The name is the logger name; lvl is the

18169

numeric level; pathname is the absolute pathname of the source

18170

file in which the logging call was made; lineno is the line

18171

number in that file where the logging call is found; msg is the

18172

user-supplied message (a format string); args is the tuple

18173

which, together with msg, makes up the user message; and

18174

exc_info is the exception tuple obtained by calling

18175

sys.exc_info() (or None, if no exception information

18176

is available).</description>

18177

18178

18179

18180

</group>

18181

18182

<description>The logging module is intended to be thread-safe without any special work

18183

needing to be done by its clients. It achieves this though using threading

18184

locks; there is one lock to serialize access to the module's shared data,

18185

and each handler also creates a lock to serialize access to its underlying

18186

I/O.

18187

</description>

18188

</group>

18189

18190

<description>Configuration functions

18191

The following functions allow the logging module to be

18192

configured. Before they can be used, you must import

18193

logging.config. Their use is optional --- you can configure

18194

the logging module entirely by making calls to the main API (defined

18195

in logging itself) and defining handlers which are declared

18196

either in logging or logging.handlers.

18197

</description>

18198

18199

<description>Reads the logging configuration from a ConfigParser-format file named

18200

fname. This function can be called several times from an application,

18201

allowing an end user the ability to select from various pre-canned

18202

configurations (if the developer provides a mechanism to present the

18203

choices and load the chosen configuration). Defaults to be passed to

18204

ConfigParser can be specified in the defaults argument.</description>

18205

18206

18207

18208

18209

<description>Starts up a socket server on the specified port, and listens for new

18210

configurations. If no port is specified, the module's default

18211

DEFAULT_LOGGING_CONFIG_PORT is used. Logging configurations

18212

will be sent as a file suitable for processing by fileConfig().

18213

Returns a Thread instance on which you can call start()

18214

to start the server, and which you can join() when appropriate.

18215

To stop the server, call stopListening().</description>

18216

18217

18218

18219

18220

<description>Stops the listening server which was created with a call to

18221

listen(). This is typically called before calling join()

18222

on the return value from listen().</description>

18223

18224

</element>

18225

18226

</group>

18227

18228

</group>

18229

</group>

18230

18231

<description>Retrieves as much platform identifying data as possible.

18232

New in version 2.3

18233

Specific platforms listed alphabetically, with Linux included in the

18234

section.

18235

</description>

18236

18237

18238

<description>Queries the given executable (defaults to the Python interpreter

18239

binary) for various architecture informations.

18240

Returns a tuple (bits, linkage) which contain information about

18241

the bit architecture and the linkage format used for the

18242

executable. Both values are returned as strings.

18243

Values that cannot be determined are returned as given by the

18244

parameter presets. If bits is given as '', the

18245

sizeof(pointer)

18246

(or sizeof(long) on Python version < 1.5.2) is used as

18247

indicator for the supported pointer size.

18248

The function relies on the system's file command to do the

18249

actual work. This is available on most if not all platforms and some non- platforms and then only if the

18250

executable points to the Python interpreter. Reasonable defaults

18251

are used when the above needs are not met.</description>

18252

18253

18254

18255

18256

<description>Returns the machine type, e.g. 'i386'.

18257

An empty string is returned if the value cannot be determined.</description>

18258

18259

</element>

18260

18261

18262

<description>Returns the computer's network name (may not be fully qualified!).

18263

An empty string is returned if the value cannot be determined.</description>

18264

18265

</element>

18266

18267

18268

<description>Returns a single string identifying the underlying platform

18269

with as much useful information as possible.

18270

The output is intended to be human readable rather than

18271

machine parseable. It may look different on different platforms and

18272

this is intended.

18273

If aliased is true, the function will use aliases for various

18274

platforms that report system names which differ from their common

18275

names, for example SunOS will be reported as Solaris. The

18276

system_alias() function is used to implement this.

18277

Setting terse to true causes the function to return only the

18278

absolute minimum information needed to identify the platform.</description>

18279

18280

18281

18282

18283

<description>Returns the (real) processor name, e.g. 'amdk6'.

18284

An empty string is returned if the value cannot be determined. Note

18285

that many platforms do not provide this information or simply return

18286

the same value as for machine(). NetBSD does this.</description>

18287

18288

</element>

18289

18290

18291

<description>Returns a tuple (buildno, builddate) stating the

18292

Python build number and date as strings.</description>

18293

18294

</element>

18295

18296

18297

<description>Returns a string identifying the compiler used for compiling Python.</description>

18298

18299

</element>

18300

18301

18302

<description>Returns the Python version as string 'major.minor.patchlevel'

18303

Note that unlike the Python sys.version, the returned value

18304

will always include the patchlevel (it defaults to 0).</description>

18305

18306

</element>

18307

18308

18309

<description>Returns the Python version as tuple (major, minor,

18310

patchlevel) of strings.

18311

Note that unlike the Python sys.version, the returned value

18312

will always include the patchlevel (it defaults to '0').</description>

18313

18314

</element>

18315

18316

18317

<description>Returns the system's release, e.g. '2.2.0' or 'NT'

18318

An empty string is returned if the value cannot be determined.</description>

18319

18320

</element>

18321

18322

18323

<description>Returns the system/OS name, e.g. 'Linux', 'Windows',

18324

or 'Java'.

18325

An empty string is returned if the value cannot be determined.</description>

18326

18327

</element>

18328

18329

18330

<description>Returns (system, release, version) aliased

18331

to common marketing names used for some systems. It also does some

18332

reordering of the information in some cases where it would otherwise

18333

cause confusion.</description>

18334

18335

18336

18337

18338

<description>Returns the system's release version, e.g. ' degas'.

18339

An empty string is returned if the value cannot be determined.</description>

18340

18341

</element>

18342

18343

18344

<description>Fairly portable uname interface. Returns a tuple of strings

18345

(system, node, release, version,

18346

machine, processor) identifying the underlying

18347

platform.

18348

Note that unlike the os.uname() function this also returns

18349

possible processor information as additional tuple entry.

18350

Entries which cannot be determined are set to ''.</description>

18351

18352

</element>

18353

18354

</group>

18355

18356

18357

<description>Version interface for JPython.

18358

Returns a tuple (release, vendor, vminfo,

18359

osinfo) with vminfo being a tuple (vm_name,

18360

vm_release, vm_vendor) and osinfo being a tuple

18361

(os_name, os_version, os_arch).

18362

Values which cannot be determined are set to the defaults

18363

given as parameters (which all default to '').</description>

18364

18365

18366

18367

</group>

18368

18369

18370

<description>Get additional version information from the Windows Registry

18371

and return a tuple (version, csd, ptype)

18372

referring to version number, CSD level and OS type (multi/single

18373

processor).

18374

As a hint: ptype is 'Uniprocessor Free' on single

18375

processor NT machines and 'Multiprocessor Free' on multi

18376

processor machines. The 'Free' refers to the OS version being

18377

free of debugging code. It could also state 'Checked' which

18378

means the OS version uses debugging code, i.e. code that

18379

checks arguments, ranges, etc.

18380

[note]

18381

This function only works if Mark Hammond's win32all

18382

package is installed and (obviously) only runs on Win32

18383

compatible platforms.

18384

</description>

18385

18386

18387

18388

18389

<description>Portable popen() interface. Find a working popen

18390

implementation preferring win32pipe.popen(). On Windows

18391

NT, win32pipe.popen() should work; on Windows 9x it hangs

18392

due to bugs in the MS C library.

18393

% This KnowledgeBase article appears to be missing...

18394

%See also MS KnowledgeBase article Q150956{}.</description>

18395

18396

18397

18398

</group>

18399

18400

18401

<description>Get Mac OS version information and return it as tuple

18402

(release, versioninfo, machine) with

18403

versioninfo being a tuple (version,

18404

dev_stage, non_release_version).

18405

Entries which cannot be determined are set to ''. All tuple

18406

entries are strings.

18407

Documentation for the underlying gestalt() API is

18408

available online at http://www.rgaros.nl/gestalt/.</description>

18409

18410

18411

18412

</group>

18413

18414

18415

<description>Tries to determine the name of the OS distribution name

18416

Returns a tuple (distname, version, id)

18417

which defaults to the args given as parameters.</description>

18418

18419

18420

18421

18422

<description>Tries to determine the libc version against which the file

18423

executable (defaults to the Python interpreter) is linked. Returns

18424

a tuple of strings (lib, version) which default

18425

to the given parameters in case the lookup fails.

18426

Note that this function has intimate knowledge of how different

18427

libc versions add symbols to the executable is probably only

18428

useable for executables compiled using gcc.

18429

The file is read and scanned in chunks of chunksize bytes.</description>

18430

18431

18432

18433

</group>

18434

</group>

18435

</group>

18436

18437

18438

<description>Set handlers for asynchronous events.

18439

This module provides mechanisms to use signal handlers in Python.

18440

Some general rules for working with signals and their handlers:

18441

A handler for a particular signal, once set, remains installed until

18442

it is explicitly reset (Python emulates the BSD style interface

18443

regardless of the underlying implementation), with the exception of

18444

the handler for SIGCHLD, which follows the underlying

18445

implementation.

18446

There is no way to ``block'' signals temporarily from critical

18447

sections (since this is not supported by all flavors).

18448

Although Python signal handlers are called asynchronously as far as

18449

the Python user is concerned, they can only occur between the

18450

``atomic'' instructions of the Python interpreter. This means that

18451

signals arriving during long calculations implemented purely in C

18452

(such as regular expression matches on large bodies of text) may be

18453

delayed for an arbitrary amount of time.

18454

When a signal arrives during an I/O operation, it is possible that the

18455

I/O operation raises an exception after the signal handler returns.

18456

This is dependent on the underlying system's semantics regarding

18457

interrupted system calls.

18458

Because the signal handler always returns, it makes little sense to

18459

catch synchronous errors like SIGFPE or SIGSEGV.

18460

Python installs a small number of signal handlers by default:

18461

SIGPIPE is ignored (so write errors on pipes and sockets can be

18462

reported as ordinary Python exceptions) and SIGINT is translated

18463

into a KeyboardInterrupt exception. All of these can be

18464

overridden.

18465

Some care must be taken if both signals and threads are used in the

18466

same program. The fundamental thing to remember in using signals and

18467

threads simultaneously is: perform signal() operations

18468

in the main thread of execution. Any thread can perform an

18469

alarm(), getsignal(), or pause();

18470

only the main thread can set a new signal handler, and the main thread

18471

will be the only one to receive signals (this is enforced by the

18472

Python signal module, even if the underlying thread

18473

implementation supports sending signals to individual threads). This

18474

means that signals can't be used as a means of inter-thread

18475

communication. Use locks instead.

18476

The variables defined in the signal module are:

18477

{SIG_DFL}

18478

This is one of two standard signal handling options; it will simply

18479

perform the default function for the signal. For example, on most

18480

systems the default action for SIGQUIT is to dump core

18481

and exit, while the default action for SIGCLD is to

18482

simply ignore it.

18483

{SIG_IGN}

18484

This is another standard signal handler, which will simply ignore

18485

the given signal.

18486

{SIG*}

18487

All the signal numbers are defined symbolically. For example, the

18488

hangup signal is defined as signal.SIGHUP; the variable names

18489

are identical to the names used in C programs, as found in

18490

<signal.h>.

18491

The man page for `signal()' lists the existing

18492

signals (on some systems this is signal{2}, on others the

18493

list is in signal{7}).

18494

Note that not all systems define the same set of signal names; only

18495

those names defined by the system are defined by this module.

18496

{NSIG}

18497

One more than the number of the highest signal number.

18498

The signal module defines the following functions:

18499

</description>

18500

18501

<description>If time is non-zero, this function requests that a

18502

SIGALRM signal be sent to the process in time seconds.

18503

Any previously scheduled alarm is canceled (only one alarm can

18504

be scheduled at any time). The returned value is then the number of

18505

seconds before any previously set alarm was to have been delivered.

18506

If time is zero, no alarm id scheduled, and any scheduled

18507

alarm is canceled. The return value is the number of seconds

18508

remaining before a previously scheduled alarm. If the return value

18509

is zero, no alarm is currently scheduled. (See the man page

18510

alarm{2}.)

18511

Availability: .</description>

18512

18513

18514

18515

18516

<description>Return the current signal handler for the signal signalnum.

18517

The returned value may be a callable Python object, or one of the

18518

special values signal.SIG_IGN, signal.SIG_DFL or

18519

None. Here, signal.SIG_IGN means that the

18520

signal was previously ignored, signal.SIG_DFL means that the

18521

default way of handling the signal was previously in use, and

18522

None means that the previous signal handler was not installed

18523

from Python.</description>

18524

18525

18526

18527

18528

<description>Cause the process to sleep until a signal is received; the

18529

appropriate handler will then be called. Returns nothing. Not on

18530

Windows. (See the man page signal{2}.)</description>

18531

18532

</element>

18533

18534

18535

<description>Set the handler for signal signalnum to the function

18536

handler. handler can be a callable Python object

18537

taking two arguments (see below), or

18538

one of the special values signal.SIG_IGN or

18539

signal.SIG_DFL. The previous signal handler will be returned

18540

(see the description of getsignal() above). (See the

18541

man page signal{2}.)

18542

When threads are enabled, this function can only be called from the

18543

main thread; attempting to call it from other threads will cause a

18544

ValueError exception to be raised.

18545

The handler is called with two arguments: the signal number

18546

and the current stack frame (None or a frame object; see the

18547

reference manual for a description of frame objects).

18548

frame</description>

18549

18550

18551

18552

18553

</group>

18554

</group>

18555

18556

<description>Low-level networking interface.

18557

This module provides access to the BSD socket interface.

18558

It is available on all modern systems, Windows, MacOS, BeOS,

18559

OS/2, and probably additional platforms.

18560

For an introduction to socket programming (in C), see the following

18561

papers: An Introductory 4.3BSD Interprocess Communication

18562

Tutorial, by Stuart Sechrest and An Advanced 4.3BSD

18563

Interprocess Communication Tutorial, by Samuel J. Leffler et al,

18564

both in the Programmer's Manual, Supplementary Documents 1

18565

(sections PS1:7 and PS1:8). The platform-specific reference material

18566

for the various socket-related system calls are also a valuable source

18567

of information on the details of socket semantics. For , refer

18568

to the manual pages; for Windows, see the WinSock (or Winsock 2)

18569

specification.

18570

For IPv6-ready APIs, readers may want to refer to 2553 titled

18571

Basic Socket Interface Extensions for IPv6.

18572

The Python interface is a straightforward transliteration of the

18573

system call and library interface for sockets to Python's

18574

object-oriented style: the socket() function returns a

18575

socket objectsocket whose methods implement the

18576

various socket system calls. Parameter types are somewhat

18577

higher-level than in the C interface: as with read() and

18578

write() operations on Python files, buffer allocation on

18579

receive operations is automatic, and buffer length is implicit on send

18580

operations.

18581

Socket addresses are represented as follows:

18582

A single string is used for the AF_UNIX address family.

18583

A pair (host, port) is used for the

18584

AF_INET address family, where host is a string

18585

representing either a hostname in Internet domain notation like

18586

'daring.cwi.nl' or an IPv4 address like '100.50.200.5',

18587

and port is an integral port number.

18588

For AF_INET6 address family, a four-tuple

18589

(host, port, flowinfo, scopeid) is

18590

used, where flowinfo and scopeid represents

18591

sin6_flowinfo and sin6_scope_id member in

18592

struct sockaddr_in6 in C.

18593

For socket module methods, flowinfo and scopeid

18594

can be omitted just for backward compatibility. Note, however,

18595

omission of scopeid can cause problems in manipulating scoped

18596

IPv6 addresses. Other address families are currently not supported.

18597

The address format required by a particular socket object is

18598

automatically selected based on the address family specified when the

18599

socket object was created.

18600

For IPv4 addresses, two special forms are accepted instead of a host

18601

address: the empty string represents INADDR_ANY, and the string

18602

'<broadcast>' represents INADDR_BROADCAST.

18603

The behavior is not available for IPv6 for backward compatibility,

18604

therefore, you may want to avoid these if you intend to support IPv6 with

18605

your Python programs.

18606

If you use a hostname in the host portion of IPv4/v6 socket

18607

address, the program may show a nondeterministic behavior, as Python

18608

uses the first address returned from the DNS resolution. The socket

18609

address will be resolved differently into an actual IPv4/v6 address,

18610

depending on the results from DNS resolution and/or the host

18611

configuration. For deterministic behavior use a numeric address in

18612

host portion.

18613

All errors raise exceptions. The normal exceptions for invalid

18614

argument types and out-of-memory conditions can be raised; errors

18615

related to socket or address semantics raise the error

18616

socket.error.

18617

Non-blocking mode is supported through

18618

setblocking(). A generalization of this based on timeouts

18619

is supported through settimeout().

18620

The module socket exports the following constants and functions:

18621

{error}

18622

This exception is raised for socket-related errors.

18623

The accompanying value is either a string telling what went wrong or a

18624

pair (errno, string)

18625

representing an error returned by a system

18626

call, similar to the value accompanying os.error.

18627

See the module errnoerrno, which contains

18628

names for the error codes defined by the underlying operating system.

18629

{herror}

18630

This exception is raised for address-related errors, i.e. for

18631

functions that use h_errno in the C API, including

18632

gethostbyname_ex() and gethostbyaddr().

18633

The accompanying value is a pair (h_errno, string)

18634

representing an error returned by a library call. string

18635

represents the description of h_errno, as returned by

18636

the hstrerror() C function.

18637

{gaierror}

18638

This exception is raised for address-related errors, for

18639

getaddrinfo() and getnameinfo().

18640

The accompanying value is a pair (error, string)

18641

representing an error returned by a library call.

18642

string represents the description of error, as returned

18643

by the gai_strerror() C function.

18644

{timeout}

18645

This exception is raised when a timeout occurs on a socket which has

18646

had timeouts enabled via a prior call to settimeout(). The

18647

accompanying value is a string whose value is currently always ``timed

18648

out''.

18649

New in version 2.3

18650

{AF_UNIX}

18651

AF_INET

18652

AF_INET6

18653

These constants represent the address (and protocol) families,

18654

used for the first argument to socket(). If the

18655

AF_UNIX constant is not defined then this protocol is

18656

unsupported.

18657

{SOCK_STREAM}

18658

SOCK_DGRAM

18659

SOCK_RAW

18660

SOCK_RDM

18661

SOCK_SEQPACKET

18662

These constants represent the socket types,

18663

used for the second argument to socket().

18664

(Only SOCK_STREAM and

18665

SOCK_DGRAM appear to be generally useful.)

18666

{SO_*}

18667

SOMAXCONN

18668

MSG_*

18669

SOL_*

18670

IPPROTO_*

18671

IPPORT_*

18672

INADDR_*

18673

IP_*

18674

IPV6_*

18675

EAI_*

18676

AI_*

18677

NI_*

18678

TCP_*

18679

Many constants of these forms, documented in the documentation on

18680

sockets and/or the IP protocol, are also defined in the socket module.

18681

They are generally used in arguments to the setsockopt() and

18682

getsockopt() methods of socket objects. In most cases, only

18683

those symbols that are defined in the header files are defined;

18684

for a few symbols, default values are provided.

18685

{has_ipv6}

18686

This constant contains a boolean value which indicates if IPv6 is

18687

supported on this platform.

18688

New in version 2.3

18689

</description>

18690

18691

<description>Resolves the host/port argument, into a sequence of

18692

5-tuples that contain all the necessary argument for the sockets

18693

manipulation. host is a domain name, a string representation of

18694

IPv4/v6 address or None.

18695

port is a string service name (like 'http'), a numeric

18696

port number or None.

18697

The rest of the arguments are optional and must be numeric if

18698

specified. For host and port, by passing either an empty

18699

string or None, you can pass NULL to the C API. The

18700

getaddrinfo() function returns a list of 5-tuples with

18701

the following structure:

18702

(family, socktype, proto, canonname,

18703

sockaddr)

18704

family, socktype, proto are all integer and are meant to

18705

be passed to the socket() function.

18706

canonname is a string representing the canonical name of the host.

18707

It can be a numeric IPv4/v6 address when AI_CANONNAME is specified

18708

for a numeric host.

18709

sockaddr is a tuple describing a socket address, as described above.

18710

See the source for the httplib and other library modules

18711

for a typical usage of the function.

18712

New in version 2.2</description>

18713

18714

18715

18716

18717

<description>Return a fully qualified domain name for name.

18718

If name is omitted or empty, it is interpreted as the local

18719

host. To find the fully qualified name, the hostname returned by

18720

gethostbyaddr() is checked, then aliases for the host, if

18721

available. The first name which includes a period is selected. In

18722

case no fully qualified domain name is available, the hostname is

18723

returned.

18724

New in version 2.0</description>

18725

18726

18727

18728

18729

<description>Translate a host name to IPv4 address format. The IPv4 address is

18730

returned as a string, such as '100.50.200.5'. If the host name

18731

is an IPv4 address itself it is returned unchanged. See

18732

gethostbyname_ex() for a more complete interface.

18733

gethostbyname() does not support IPv6 name resolution, and

18734

getaddrinfo() should be used instead for IPv4/v6 dual stack support.</description>

18735

18736

18737

18738

18739

<description>Translate a host name to IPv4 address format, extended interface.

18740

Return a triple (hostname, aliaslist,

18741

ipaddrlist) where

18742

hostname is the primary host name responding to the given

18743

ip_address, aliaslist is a (possibly empty) list of

18744

alternative host names for the same address, and ipaddrlist is

18745

a list of IPv4 addresses for the same interface on the same

18746

host (often but not always a single address).

18747

gethostbyname_ex() does not support IPv6 name resolution, and

18748

getaddrinfo() should be used instead for IPv4/v6 dual stack support.</description>

18749

18750

18751

18752

18753

<description>Return a string containing the hostname of the machine where the Python interpreter is currently executing.

18754

If you want to know the current machine's IP address, you may want to use

18755

gethostbyname(gethostname()).

18756

This operation assumes that there is a valid address-to-host mapping for

18757

the host, and the assumption does not always hold.

18758

Note: gethostname() doesn't always return the fully qualified

18759

domain name; use gethostbyaddr(gethostname())

18760

(see below).</description>

18761

18762

</element>

18763

18764

18765

<description>Return a triple (hostname, aliaslist,

18766

ipaddrlist) where hostname is the primary host name

18767

responding to the given ip_address, aliaslist is a

18768

(possibly empty) list of alternative host names for the same address,

18769

and ipaddrlist is a list of IPv4/v6 addresses for the same interface

18770

on the same host (most likely containing only a single address).

18771

To find the fully qualified domain name, use the function

18772

getfqdn().

18773

gethostbyaddr supports both IPv4 and IPv6.</description>

18774

18775

18776

18777

18778

<description>Translate a socket address sockaddr into a 2-tuple

18779

(host, port).

18780

Depending on the settings of flags, the result can contain a

18781

fully-qualified domain name or numeric address representation in

18782

host. Similarly, port can contain a string port name or a

18783

numeric port number.

18784

New in version 2.2</description>

18785

18786

18787

18788

18789

<description>Translate an Internet protocol name (for example, 'icmp') to a constant

18790

suitable for passing as the (optional) third argument to the

18791

socket() function. This is usually only needed for sockets

18792

opened in ``raw'' mode (SOCK_RAW); for the normal socket

18793

modes, the correct protocol is chosen automatically if the protocol is

18794

omitted or zero.</description>

18795

18796

18797

18798

18799

<description>Translate an Internet service name and protocol name to a port number

18800

for that service. The protocol name should be 'tcp' or

18801

'udp'.</description>

18802

18803

18804

18805

18806

<description>Create a new socket using the given address family, socket type and

18807

protocol number. The address family should be AF_INET, AF_INET6 or

18808

AF_UNIX. The socket type should be SOCK_STREAM,

18809

SOCK_DGRAM or perhaps one of the other SOCK_ constants.

18810

The protocol number is usually zero and may be omitted in that case.</description>

18811

18812

18813

18814

18815

<description>Initiate a SSL connection over the socket sock. keyfile is

18816

the name of a PEM formatted file that contains your private

18817

key. certfile is a PEM formatted certificate chain file. On

18818

success, a new SSLObject is returned.

18819

This does not do any certificate verification!</description>

18820

18821

18822

18823

18824

<description>Build a socket object from an existing file descriptor (an integer as

18825

returned by a file object's fileno() method). Address family,

18826

socket type and protocol number are as for the socket() function

18827

above. The file descriptor should refer to a socket, but this is not

18828

checked --- subsequent operations on the object may fail if the file

18829

descriptor is invalid. This function is rarely needed, but can be

18830

used to get or set socket options on a socket passed to a program as

18831

standard input or output (such as a server started by the inet

18832

daemon). The socket is assumed to be in blocking mode.

18833

Availability: .</description>

18834

18835

18836

18837

18838

<description>Convert 32-bit integers from network to host byte order. On machines

18839

where the host byte order is the same as network byte order, this is a

18840

no-op; otherwise, it performs a 4-byte swap operation.</description>

18841

18842

18843

18844

18845

<description>Convert 16-bit integers from network to host byte order. On machines

18846

where the host byte order is the same as network byte order, this is a

18847

no-op; otherwise, it performs a 2-byte swap operation.</description>

18848

18849

18850

18851

18852

<description>Convert 32-bit integers from host to network byte order. On machines

18853

where the host byte order is the same as network byte order, this is a

18854

no-op; otherwise, it performs a 4-byte swap operation.</description>

18855

18856

18857

18858

18859

<description>Convert 16-bit integers from host to network byte order. On machines

18860

where the host byte order is the same as network byte order, this is a

18861

no-op; otherwise, it performs a 2-byte swap operation.</description>

18862

18863

18864

18865

18866

<description>Convert an IPv4 address from dotted-quad string format (for example,

18867

'123.45.67.89') to 32-bit packed binary format, as a string four

18868

characters in length. This is useful when conversing with a program

18869

that uses the standard C library and needs objects of type

18870

struct in_addr, which is the C type for the 32-bit packed

18871

binary this function returns.

18872

If the IPv4 address string passed to this function is invalid,

18873

socket.error will be raised. Note that exactly what is

18874

valid depends on the underlying C implementation of

18875

inet_aton().

18876

inet_aton() does not support IPv6, and

18877

getnameinfo() should be used instead for IPv4/v6 dual stack

18878

support.</description>

18879

18880

18881

18882

18883

<description>Convert a 32-bit packed IPv4 address (a string four characters in

18884

length) to its standard dotted-quad string representation (for

18885

example, '123.45.67.89'). This is useful when conversing with a

18886

program that uses the standard C library and needs objects of type

18887

struct in_addr, which is the C type for the 32-bit packed

18888

binary data this function takes as an argument.

18889

If the string passed to this function is not exactly 4 bytes in

18890

length, socket.error will be raised.

18891

inet_ntoa() does not support IPv6, and

18892

getnameinfo() should be used instead for IPv4/v6 dual stack

18893

support.</description>

18894

18895

18896

18897

18898

<description>Convert an IP address from its family-specific string format to a packed,

18899

binary format.

18900

inet_pton() is useful when a library or network protocol calls for

18901

an object of type struct in_addr (similar to inet_aton())

18902

or struct in6_addr.

18903

Supported values for address_family are currently

18904

AF_INET and AF_INET6.

18905

If the IP address string ip_string is invalid,

18906

socket.error will be raised. Note that exactly what is valid

18907

depends on both the value of address_family and the underlying

18908

implementation of inet_pton().

18909

Availability: (maybe not all platforms).

18910

New in version 2.3</description>

18911

18912

18913

18914

18915

<description>Convert a packed IP address (a string of some number of characters) to

18916

its standard, family-specific string representation (for example,

18917

'7.10.0.5' or '5aef:2b::8')

18918

inet_ntop() is useful when a library or network protocol returns

18919

an object of type struct in_addr (similar to inet_ntoa())

18920

or struct in6_addr.

18921

Supported values for address_family are currently

18922

AF_INET and AF_INET6.

18923

If the string packed_ip is not the correct length for the

18924

specified address family, ValueError will be raised. A

18925

socket.error is raised for errors from the call to

18926

inet_ntop().

18927

Availability: (maybe not all platforms).

18928

New in version 2.3</description>

18929

18930

18931

18932

18933

<description>Return the default timeout in floating seconds for new socket objects.

18934

A value of None indicates that new socket objects have no timeout.

18935

When the socket module is first imported, the default is None.

18936

New in version 2.3</description>

18937

18938

</element>

18939

18940

18941

<description>Set the default timeout in floating seconds for new socket objects.

18942

A value of None indicates that new socket objects have no timeout.

18943

When the socket module is first imported, the default is None.

18944

New in version 2.3</description>

18945

18946

18947

18948

18949

<description>Socket objects have the following methods. Except for

18950

makefile() these correspond to system calls

18951

applicable to sockets.

18952

</description>

18953

18954

<description>Accept a connection.

18955

The socket must be bound to an address and listening for connections.

18956

The return value is a pair (conn, address)

18957

where conn is a new socket object usable to send and

18958

receive data on the connection, and address is the address bound

18959

to the socket on the other end of the connection.</description>

18960

18961

</element>

18962

18963

18964

<description>Bind the socket to address. The socket must not already be bound.

18965

(The format of address depends on the address family --- see

18966

above.) This method has historically accepted a pair

18967

of parameters for AF_INET addresses instead of only a

18968

tuple. This was never intentional and is no longer be available in

18969

Python 2.0.</description>

18970

18971

18972

18973

18974

<description>Close the socket. All future operations on the socket object will fail.

18975

The remote end will receive no more data (after queued data is flushed).

18976

Sockets are automatically closed when they are garbage-collected.</description>

18977

18978

</element>

18979

18980

18981

<description>Connect to a remote socket at address.

18982

(The format of address depends on the address family --- see

18983

above.) This method has historically accepted a pair

18984

of parameters for AF_INET addresses instead of only a

18985

tuple. This was never intentional and is no longer available in

18986

Python 2.0 and later.</description>

18987

18988

18989

18990

18991

<description>Like connect(address), but return an error indicator

18992

instead of raising an exception for errors returned by the C-level

18993

connect() call (other problems, such as ``host not found,''

18994

can still raise exceptions). The error indicator is 0 if the

18995

operation succeeded, otherwise the value of the errno

18996

variable. This is useful to support, for example, asynchronous connects.

18997

This method has historically accepted a pair of

18998

parameters for AF_INET addresses instead of only a tuple.

18999

This was never intentional and is no longer be available in Python

19000

2.0 and later.</description>

19001

19002

19003

19004

19005

<description>Return the socket's file descriptor (a small integer). This is useful

19006

with select.select().

19007

Under Windows the small integer returned by this method cannot be used where

19008

a file descriptor can be used (such as os.fdopen()). does

19009

not have this limitation.</description>

19010

19011

</element>

19012

19013

19014

<description>Return the remote address to which the socket is connected. This is

19015

useful to find out the port number of a remote IPv4/v6 socket, for instance.

19016

(The format of the address returned depends on the address family ---

19017

see above.) On some systems this function is not supported.</description>

19018

19019

</element>

19020

19021

19022

<description>Return the socket's own address. This is useful to find out the port

19023

number of an IPv4/v6 socket, for instance.

19024

(The format of the address returned depends on the address family ---

19025

see above.)</description>

19026

19027

</element>

19028

19029

19030

<description>Return the value of the given socket option (see the man page

19031

getsockopt{2}). The needed symbolic constants

19032

(SO_* etc.) are defined in this module. If buflen

19033

is absent, an integer option is assumed and its integer value

19034

is returned by the function. If buflen is present, it specifies

19035

the maximum length of the buffer used to receive the option in, and

19036

this buffer is returned as a string. It is up to the caller to decode

19037

the contents of the buffer (see the optional built-in module

19038

struct for a way to decode C structures encoded as strings).</description>

19039

19040

19041

19042

19043

<description>Listen for connections made to the socket. The backlog argument

19044

specifies the maximum number of queued connections and should be at

19045

least 1; the maximum value is system-dependent (usually 5).</description>

19046

19047

19048

19049

19050

<description>Return a file object associated with the socket. (File objects

19051

are described in bltin-file-objects, ``File Objects.'')

19052

The file object references a dup()ped version of the

19053

socket file descriptor, so the file object and socket object may be

19054

closed or garbage-collected independently.

19055

The socket should be in blocking mode.

19056

</description>

19057

19058

19059

19060

19061

<description>Receive data from the socket. The return value is a string representing

19062

the data received. The maximum amount of data to be received

19063

at once is specified by bufsize. See the manual page

19064

recv{2} for the meaning of the optional argument

19065

flags; it defaults to zero.</description>

19066

19067

19068

19069

19070

<description>Receive data from the socket. The return value is a pair

19071

(string, address) where string is a string

19072

representing the data received and address is the address of the

19073

socket sending the data. The optional flags argument has the

19074

same meaning as for recv() above.

19075

(The format of address depends on the address family --- see above.)</description>

19076

19077

19078

19079

19080

<description>Send data to the socket. The socket must be connected to a remote

19081

socket. The optional flags argument has the same meaning as for

19082

recv() above. Returns the number of bytes sent.

19083

Applications are responsible for checking that all data has been sent;

19084

if only some of the data was transmitted, the application needs to

19085

attempt delivery of the remaining data.</description>

19086

19087

19088

19089

19090

<description>Send data to the socket. The socket must be connected to a remote

19091

socket. The optional flags argument has the same meaning as for

19092

recv() above. Unlike send(), this method continues

19093

to send data from string until either all data has been sent or

19094

an error occurs. None is returned on success. On error, an

19095

exception is raised, and there is no way to determine how much data,

19096

if any, was successfully sent.</description>

19097

19098

19099

19100

19101

<description>Send data to the socket. The socket should not be connected to a

19102

remote socket, since the destination socket is specified by

19103

address. The optional flags argument has the same

19104

meaning as for recv() above. Return the number of bytes sent.

19105

(The format of address depends on the address family --- see above.)</description>

19106

19107

19108

19109

19110

<description>Set blocking or non-blocking mode of the socket: if flag is 0,

19111

the socket is set to non-blocking, else to blocking mode. Initially

19112

all sockets are in blocking mode. In non-blocking mode, if a

19113

recv() call doesn't find any data, or if a

19114

send() call can't immediately dispose of the data, a

19115

error exception is raised; in blocking mode, the calls

19116

block until they can proceed.

19117

s.setblocking(0) is equivalent to s.settimeout(0);

19118

s.setblocking(1) is equivalent to s.settimeout(None).</description>

19119

19120

19121

19122

19123

<description>Set a timeout on blocking socket operations. The value argument

19124

can be a nonnegative float expressing seconds, or None.

19125

If a float is

19126

given, subsequent socket operations will raise an timeout

19127

exception if the timeout period value has elapsed before the

19128

operation has completed. Setting a timeout of None disables

19129

timeouts on socket operations.

19130

s.settimeout(0.0) is equivalent to s.setblocking(0);

19131

s.settimeout(None) is equivalent to s.setblocking(1).

19132

New in version 2.3</description>

19133

19134

19135

19136

19137

<description>Returns the timeout in floating seconds associated with socket

19138

operations, or None if no timeout is set. This reflects

19139

the last call to setblocking() or settimeout().

19140

New in version 2.3</description>

19141

19142

</element>

19143

19144

19145

<description>Set the value of the given socket option (see the manual page

19146

setsockopt{2}). The needed symbolic constants are defined in

19147

the socket module (SO_* etc.). The value can be an

19148

integer or a string representing a buffer. In the latter case it is

19149

up to the caller to ensure that the string contains the proper bits

19150

(see the optional built-in module

19151

structstruct for a way to encode C

19152

structures as strings).</description>

19153

19154

19155

19156

19157

<description>Shut down one or both halves of the connection. If how is

19158

SHUT_RD, further receives are disallowed. If how is SHUT_WR,

19159

further sends are disallowed. If how is SHUT_RDWR, further sends

19160

and receives are disallowed.</description>

19161

19162

19163

19164

</group>

19165

19166

<description>SSL objects have the following methods.

19167

</description>

19168

19169

<description>Writes the string s to the on the object's SSL connection.

19170

The return value is the number of bytes written.</description>

19171

19172

19173

19174

19175

<description>If n is provided, read n bytes from the SSL connection, otherwise

19176

read until EOF. The return value is a string of the bytes read.</description>

19177

19178

19179

19180

</group>

19181

19182

</group>

19183

</group>

19184

19185

<description>Wait for I/O completion on multiple streams.

19186

This module provides access to the select()

19187

and poll() functions

19188

available in most operating systems. Note that on Windows, it only

19189

works for sockets; on other operating systems, it also works for other

19190

file types (in particular, on , it works on pipes). It cannot

19191

be used on regular files to determine whether a file has grown since

19192

it was last read.

19193

The module defines the following:

19194

{error}

19195

The exception raised when an error occurs. The accompanying value is

19196

a pair containing the numeric error code from errno and the

19197

corresponding string, as would be printed by the function

19198

perror().

19199

</description>

19200

19201

<description>(Not supported by all operating systems.) Returns a polling object,

19202

which supports registering and unregistering file descriptors, and

19203

then polling them for I/O events;

19204

see section~poll-objects below for the methods supported by

19205

polling objects.</description>

19206

19207

</element>

19208

19209

19210

<description>This is a straightforward interface to the select()

19211

system call. The first three arguments are sequences of `waitable

19212

objects': either integers representing file descriptors or

19213

objects with a parameterless method named fileno() returning

19214

such an integer. The three sequences of waitable objects are for input,

19215

output and `exceptional conditions', respectively. Empty sequences are

19216

allowed, but acceptance of three empty sequences is platform-dependent.

19217

(It is known to work on but not on Windows.) The optional

19218

timeout argument specifies a time-out as a floating point number

19219

in seconds. When the timeout argument is omitted the function

19220

blocks until at least one file descriptor is ready. A time-out value

19221

of zero specifies a poll and never blocks.

19222

The return value is a triple of lists of objects that are ready:

19223

subsets of the first three arguments. When the time-out is reached

19224

without a file descriptor becoming ready, three empty lists are

19225

returned.

19226

Among the acceptable object types in the sequences are Python file

19227

objects (e.g. sys.stdin, or objects returned by

19228

open() or os.popen()), socket objects

19229

returned by socket.socket().%

19230

(in module socket){socket()}

19231

(in module os){popen()}

19232

You may also define a wrapper class yourself, as long as it has

19233

an appropriate fileno() method (that really returns a file

19234

descriptor, not just a random integer).

19235

File objects on Windows are not acceptable, but sockets

19236

are.</description>

19237

19238

19239

19240

19241

<description>The poll() system call, supported on most systems,

19242

provides better scalability for network servers that service many,

19243

many clients at the same time.

19244

poll() scales better because the system call only

19245

requires listing the file descriptors of interest, while select()

19246

builds a bitmap, turns on bits for the fds of interest, and then

19247

afterward the whole bitmap has to be linearly scanned again.

19248

select() is O(highest file descriptor), while

19249

poll() is O(number of file descriptors).

19250

</description>

19251

19252

<description>Register a file descriptor with the polling object. Future calls to

19253

the poll() method will then check whether the file descriptor

19254

has any pending I/O events. fd can be either an integer, or an

19255

object with a fileno() method that returns an integer. File

19256

objects implement

19257

fileno(), so they can also be used as the argument.

19258

eventmask is an optional bitmask describing the type of events you

19259

want to check for, and can be a combination of the constants

19260

POLLIN, POLLPRI, and POLLOUT,

19261

described in the table below. If not specified, the default value

19262

used will check for all 3 types of events.

19263

{l|l}{constant}{Constant}{Meaning}

19264

POLLIN{There is data to read}

19265

POLLPRI{There is urgent data to read}

19266

POLLOUT{Ready for output: writing will not block}

19267

POLLERR{Error condition of some sort}

19268

POLLHUP{Hung up}

19269

POLLNVAL{Invalid request: descriptor not open}

19270

Registering a file descriptor that's already registered is not an

19271

error, and has the same effect as registering the descriptor exactly

19272

once.</description>

19273

19274

19275

19276

19277

<description>Remove a file descriptor being tracked by a polling object. Just like

19278

the register() method, fd can be an integer or an

19279

object with a fileno() method that returns an integer.

19280

Attempting to remove a file descriptor that was never registered

19281

causes a KeyError exception to be raised.</description>

19282

19283

19284

19285

19286

<description>Polls the set of registered file descriptors, and returns a

19287

possibly-empty list containing (fd, event) 2-tuples

19288

for the descriptors that have events or errors to report.

19289

fd is the file descriptor, and event is a bitmask

19290

with bits set for the reported events for that descriptor

19291

--- POLLIN for waiting input,

19292

POLLOUT to indicate that the descriptor can be written to, and

19293

so forth.

19294

An empty list indicates that the call timed out and no file

19295

descriptors had any events to report.

19296

If timeout is given, it specifies the length of time in

19297

milliseconds which the system will wait for events before returning.

19298

If timeout is omitted, negative, or None, the call will

19299

block until there is an event for this poll object.</description>

19300

19301

19302

19303

</group>

19304

</group>

19305

19306

<description>Create multiple threads of control within one interpreter.

19307

This module provides low-level primitives for working with multiple

19308

threads (a.k.a. light-weight processes or tasks) --- multiple

19309

threads of control sharing their global data space. For

19310

synchronization, simple locks (a.k.a. mutexes or binary

19311

semaphores) are provided.

19312

</description>

19313

19314

<description>Start a new thread and return its identifier. The thread executes the function

19315

function with the argument list args (which must be a tuple). The

19316

optional kwargs argument specifies a dictionary of keyword arguments.

19317

When the function returns, the thread silently exits. When the function

19318

terminates with an unhandled exception, a stack trace is printed and

19319

then the thread exits (but other threads continue to run).</description>

19320

19321

19322

19323

19324

<description>Raise a KeyboardInterrupt in the main thread. A subthread can use this

19325

function to interrupt the main thread.

19326

New in version 2.3</description>

19327

19328

</element>

19329

19330

19331

<description>Raise the SystemExit exception. When not caught, this

19332

will cause the thread to exit silently.</description>

19333

19334

</element>

19335

19336

19337

<description>%Exit all threads and report the value of the integer argument

19338

%status as the exit status of the entire program.

19339

%Caveat: code in pending finally clauses, in this thread

19340

%or in other threads, is not executed.

19341

%</description>

19342

19343

19344

19345

19346

<description>Return a new lock object. Methods of locks are described below. The

19347

lock is initially unlocked.</description>

19348

19349

</element>

19350

19351

19352

<description>Return the `thread identifier' of the current thread. This is a

19353

nonzero integer. Its value has no direct meaning; it is intended as a

19354

magic cookie to be used e.g. to index a dictionary of thread-specific

19355

data. Thread identifiers may be recycled when a thread exits and

19356

another thread is created.</description>

19357

19358

</element>

19359

19360

19361

<description>Without the optional argument, this method acquires the lock

19362

unconditionally, if necessary waiting until it is released by another

19363

thread (only one thread at a time can acquire a lock --- that's their

19364

reason for existence), and returns None. If the integer

19365

waitflag argument is present, the action depends on its

19366

value: if it is zero, the lock is only acquired if it can be acquired

19367

immediately without waiting, while if it is nonzero, the lock is

19368

acquired unconditionally as before. If an argument is present, the

19369

return value is True if the lock is acquired successfully,

19370

False if not.</description>

19371

19372

19373

19374

19375

<description>Releases the lock. The lock must have been acquired earlier, but not

19376

necessarily by the same thread.</description>

19377

19378

</element>

19379

19380

19381

<description>Return the status of the lock: True if it has been acquired by

19382

some thread, False if not.</description>

19383

19384

</element>

19385

19386

</group>

19387

19388

<description>Higher-level threading interface.

19389

This module constructs higher-level threading interfaces on top of the lower level thread module.

19390

The dummy_threading module is provided for

19391

situations where threading cannot be used because

19392

thread is missing.

19393

This module defines the following functions and objects:

19394

</description>

19395

19396

<description>Return the number of currently active Thread objects.

19397

The returned count is equal to the length of the list returned by

19398

enumerate().

19399

A function that returns the number of currently active threads.</description>

19400

19401

</element>

19402

19403

19404

<description>A factory function that returns a new condition variable object.

19405

A condition variable allows one or more threads to wait until they

19406

are notified by another thread.</description>

19407

19408

</element>

19409

19410

19411

<description>Return the current Thread object, corresponding to the

19412

caller's thread of control. If the caller's thread of control was not

19413

created through the

19414

threading module, a dummy thread object with limited functionality

19415

is returned.</description>

19416

19417

</element>

19418

19419

19420

<description>Return a list of all currently active Thread objects.

19421

The list includes daemonic threads, dummy thread objects created

19422

by currentThread(), and the main thread. It excludes terminated

19423

threads and threads that have not yet been started.</description>

19424

19425

</element>

19426

19427

19428

<description>A factory function that returns a new event object. An event manages

19429

a flag that can be set to true with the set() method and

19430

reset to false with the clear() method. The wait()

19431

method blocks until the flag is true.</description>

19432

19433

</element>

19434

19435

19436

<description>A factory function that returns a new primitive lock object. Once

19437

a thread has acquired it, subsequent attempts to acquire it block,

19438

until it is released; any thread may release it.</description>

19439

19440

</element>

19441

19442

19443

<description>A factory function that returns a new reentrant lock object.

19444

A reentrant lock must be released by the thread that acquired it.

19445

Once a thread has acquired a reentrant lock, the same thread may

19446

acquire it again without blocking; the thread must release it once

19447

for each time it has acquired it.</description>

19448

19449

</element>

19450

19451

19452

<description>A factory function that returns a new semaphore object. A

19453

semaphore manages a counter representing the number of release()

19454

calls minus the number of acquire() calls, plus an initial value.

19455

The acquire() method blocks if necessary until it can return

19456

without making the counter negative. If not given, value defaults to

19457

1.</description>

19458

19459

19460

19461

19462

<description>A factory function that returns a new bounded semaphore object. A bounded

19463

semaphore checks to make sure its current value doesn't exceed its initial

19464

value. If it does, ValueError is raised. In most situations

19465

semaphores are used to guard resources with limited capacity. If the

19466

semaphore is released too many times it's a sign of a bug. If not given,

19467

value defaults to 1.</description>

19468

19469

19470

19471

19472

<description>Set a trace function</description>

19473

19474

19475

19476

19477

<description>Set a profile function</description>

19478

19479

19480

19481

19482

<description>A primitive lock is a synchronization primitive that is not owned

19483

by a particular thread when locked. In Python, it is currently

19484

the lowest level synchronization primitive available, implemented

19485

directly by the thread extension module.

19486

A primitive lock is in one of two states, ``locked'' or ``unlocked''.

19487

It is created in the unlocked state. It has two basic methods,

19488

acquire() and release(). When the state is

19489

unlocked, acquire() changes the state to locked and returns

19490

immediately. When the state is locked, acquire() blocks

19491

until a call to release() in another thread changes it to

19492

unlocked, then the acquire() call resets it to locked and

19493

returns. The release() method should only be called in the

19494

locked state; it changes the state to unlocked and returns

19495

immediately. When more than one thread is blocked in

19496

acquire() waiting for the state to turn to unlocked, only one

19497

thread proceeds when a release() call resets the state to

19498

unlocked; which one of the waiting threads proceeds is not defined,

19499

and may vary across implementations.

19500

All methods are executed atomically.

19501

</description>

19502

19503

<description>Acquire a lock, blocking or non-blocking.

19504

When invoked without arguments, block until the lock is

19505

unlocked, then set it to locked, and return. There is no

19506

return value in this case.

19507

When invoked with the blocking argument set to true, do the

19508

same thing as when called without arguments, and return true.

19509

When invoked with the blocking argument set to false, do not

19510

block. If a call without an argument would block, return false

19511

immediately; otherwise, do the same thing as when called

19512

without arguments, and return true.</description>

19513

19514

19515

19516

19517

<description>Release a lock.

19518

When the lock is locked, reset it to unlocked, and return. If

19519

any other threads are blocked waiting for the lock to become

19520

unlocked, allow exactly one of them to proceed.

19521

Do not call this method when the lock is unlocked.

19522

There is no return value.</description>

19523

19524

</element>

19525

19526

</group>

19527

19528

<description>A reentrant lock is a synchronization primitive that may be

19529

acquired multiple times by the same thread. Internally, it uses

19530

the concepts of ``owning thread'' and ``recursion level'' in

19531

addition to the locked/unlocked state used by primitive locks. In

19532

the locked state, some thread owns the lock; in the unlocked

19533

state, no thread owns it.

19534

To lock the lock, a thread calls its acquire() method; this

19535

returns once the thread owns the lock. To unlock the lock, a

19536

thread calls its release() method.

19537

acquire()/release() call pairs may be nested; only

19538

the final release() (the release() of the outermost

19539

pair) resets the lock to unlocked and allows another thread blocked in

19540

acquire() to proceed.

19541

</description>

19542

19543

<description>Acquire a lock, blocking or non-blocking.

19544

When invoked without arguments: if this thread already owns

19545

the lock, increment the recursion level by one, and return

19546

immediately. Otherwise, if another thread owns the lock,

19547

block until the lock is unlocked. Once the lock is unlocked

19548

(not owned by any thread), then grab ownership, set the

19549

recursion level to one, and return. If more than one thread

19550

is blocked waiting until the lock is unlocked, only one at a

19551

time will be able to grab ownership of the lock. There is no

19552

return value in this case.

19553

When invoked with the blocking argument set to true, do the

19554

same thing as when called without arguments, and return true.

19555

When invoked with the blocking argument set to false, do not

19556

block. If a call without an argument would block, return false

19557

immediately; otherwise, do the same thing as when called

19558

without arguments, and return true.</description>

19559

19560

19561

19562

19563

<description>Release a lock, decrementing the recursion level. If after the

19564

decrement it is zero, reset the lock to unlocked (not owned by any

19565

thread), and if any other threads are blocked waiting for the lock to

19566

become unlocked, allow exactly one of them to proceed. If after the

19567

decrement the recursion level is still nonzero, the lock remains

19568

locked and owned by the calling thread.

19569

Only call this method when the calling thread owns the lock.

19570

Do not call this method when the lock is unlocked.

19571

There is no return value.</description>

19572

19573

</element>

19574

19575

</group>

19576

19577

<description>A condition variable is always associated with some kind of lock;

19578

this can be passed in or one will be created by default. (Passing

19579

one in is useful when several condition variables must share the

19580

same lock.)

19581

A condition variable has acquire() and release()

19582

methods that call the corresponding methods of the associated lock.

19583

It also has a wait() method, and notify() and

19584

notifyAll() methods. These three must only be called when

19585

the calling thread has acquired the lock.

19586

The wait() method releases the lock, and then blocks until it

19587

is awakened by a notify() or notifyAll() call for

19588

the same condition variable in another thread. Once awakened, it

19589

re-acquires the lock and returns. It is also possible to specify a

19590

timeout.

19591

The notify() method wakes up one of the threads waiting for

19592

the condition variable, if any are waiting. The notifyAll()

19593

method wakes up all threads waiting for the condition variable.

19594

Note: the notify() and notifyAll() methods don't

19595

release the lock; this means that the thread or threads awakened will

19596

not return from their wait() call immediately, but only when

19597

the thread that called notify() or notifyAll()

19598

finally relinquishes ownership of the lock.

19599

Tip: the typical programming style using condition variables uses the

19600

lock to synchronize access to some shared state; threads that are

19601

interested in a particular change of state call wait()

19602

repeatedly until they see the desired state, while threads that modify

19603

the state call notify() or notifyAll() when they

19604

change the state in such a way that it could possibly be a desired

19605

state for one of the waiters. For example, the following code is a

19606

generic producer-consumer situation with unlimited buffer capacity:

19607

# Consume one item

19608

cv.acquire()

19609

while not an_item_is_available():

19610

cv.wait()

19611

get_an_available_item()

19612

cv.release()

19613

# Produce one item

19614

cv.acquire()

19615

make_an_item_available()

19616

cv.notify()

19617

cv.release()

19618

To choose between notify() and notifyAll(), consider

19619

whether one state change can be interesting for only one or several

19620

waiting threads. E.g. in a typical producer-consumer situation,

19621

adding one item to the buffer only needs to wake up one consumer

19622

thread.

19623

</description>

19624

19625

<description>If the lock argument is given and not None, it must be a

19626

Lock or RLock object, and it is used as the underlying

19627

lock. Otherwise, a new RLock object is created and used as

19628

the underlying lock.</description>

19629

19630

19631

19632

19633

<description>Acquire the underlying lock.

19634

This method calls the corresponding method on the underlying

19635

lock; the return value is whatever that method returns.</description>

19636

19637

19638

19639

19640

<description>Release the underlying lock.

19641

This method calls the corresponding method on the underlying

19642

lock; there is no return value.</description>

19643

19644

</element>

19645

19646

19647

<description>Wait until notified or until a timeout occurs.

19648

This must only be called when the calling thread has acquired the

19649

lock.

19650

This method releases the underlying lock, and then blocks until it is

19651

awakened by a notify() or notifyAll() call for the

19652

same condition variable in another thread, or until the optional

19653

timeout occurs. Once awakened or timed out, it re-acquires the lock

19654

and returns.

19655

When the timeout argument is present and not None, it

19656

should be a floating point number specifying a timeout for the

19657

operation in seconds (or fractions thereof).

19658

When the underlying lock is an RLock, it is not released using

19659

its release() method, since this may not actually unlock the

19660

lock when it was acquired multiple times recursively. Instead, an

19661

internal interface of the RLock class is used, which really

19662

unlocks it even when it has been recursively acquired several times.

19663

Another internal interface is then used to restore the recursion level

19664

when the lock is reacquired.</description>

19665

19666

19667

19668

19669

<description>Wake up a thread waiting on this condition, if any.

19670

This must only be called when the calling thread has acquired the

19671

lock.

19672

This method wakes up one of the threads waiting for the condition

19673

variable, if any are waiting; it is a no-op if no threads are waiting.

19674

The current implementation wakes up exactly one thread, if any are

19675

waiting. However, it's not safe to rely on this behavior. A future,

19676

optimized implementation may occasionally wake up more than one

19677

thread.

19678

Note: the awakened thread does not actually return from its

19679

wait() call until it can reacquire the lock. Since

19680

notify() does not release the lock, its caller should.</description>

19681

19682

</element>

19683

19684

19685

<description>Wake up all threads waiting on this condition. This method acts like

19686

notify(), but wakes up all waiting threads instead of one.</description>

19687

19688

</element>

19689

19690

</group>

19691

19692

<description>This is one of the oldest synchronization primitives in the history of

19693

computer science, invented by the early Dutch computer scientist

19694

Edsger W. Dijkstra (he used P() and V() instead of

19695

acquire() and release()).

19696

A semaphore manages an internal counter which is decremented by each

19697

acquire() call and incremented by each release()

19698

call. The counter can never go below zero; when acquire()

19699

finds that it is zero, it blocks, waiting until some other thread

19700

calls release().

19701

</description>

19702

19703

<description>The optional argument gives the initial value for the internal

19704

counter; it defaults to 1.</description>

19705

19706

19707

19708

19709

<description>Acquire a semaphore.

19710

When invoked without arguments: if the internal counter is larger than

19711

zero on entry, decrement it by one and return immediately. If it is

19712

zero on entry, block, waiting until some other thread has called

19713

release() to make it larger than zero. This is done with

19714

proper interlocking so that if multiple acquire() calls are

19715

blocked, release() will wake exactly one of them up. The

19716

implementation may pick one at random, so the order in which blocked

19717

threads are awakened should not be relied on. There is no return

19718

value in this case.

19719

When invoked with blocking set to true, do the same thing as

19720

when called without arguments, and return true.

19721

When invoked with blocking set to false, do not block. If a

19722

call without an argument would block, return false immediately;

19723

otherwise, do the same thing as when called without arguments, and

19724

return true.</description>

19725

19726

19727

19728

19729

<description>Release a semaphore,

19730

incrementing the internal counter by one. When it was zero on

19731

entry and another thread is waiting for it to become larger

19732

than zero again, wake up that thread.</description>

19733

19734

</element>

19735

19736

</group>

19737

19738

<description>This is one of the simplest mechanisms for communication between

19739

threads: one thread signals an event and other threads wait for it.

19740

An event object manages an internal flag that can be set to true with

19741

the set() method and reset to false with the clear()

19742

method. The wait() method blocks until the flag is true.

19743

</description>

19744

19745

<description>The internal flag is initially false.</description>

19746

19747

</element>

19748

19749

19750

<description>Return true if and only if the internal flag is true.</description>

19751

19752

</element>

19753

19754

19755

<description>Set the internal flag to true.

19756

All threads waiting for it to become true are awakened.

19757

Threads that call wait() once the flag is true will not block

19758

at all.</description>

19759

19760

</element>

19761

19762

19763

<description>Reset the internal flag to false.

19764

Subsequently, threads calling wait() will block until

19765

set() is called to set the internal flag to true again.</description>

19766

19767

</element>

19768

19769

19770

<description>Block until the internal flag is true.

19771

If the internal flag is true on entry, return immediately. Otherwise,

19772

block until another thread calls set() to set the flag to

19773

true, or until the optional timeout occurs.

19774

When the timeout argument is present and not None, it should be a

19775

floating point number specifying a timeout for the operation in

19776

seconds (or fractions thereof).</description>

19777

19778

19779

19780

</group>

19781

19782

<description>This class represents an activity that is run in a separate thread

19783

of control. There are two ways to specify the activity: by

19784

passing a callable object to the constructor, or by overriding the

19785

run() method in a subclass. No other methods (except for the

19786

constructor) should be overridden in a subclass. In other words, only override the __init__() and run()

19787

methods of this class.

19788

Once a thread object is created, its activity must be started by

19789

calling the thread's start() method. This invokes the

19790

run() method in a separate thread of control.

19791

Once the thread's activity is started, the thread is considered

19792

'alive' and 'active' (these concepts are almost, but not quite

19793

exactly, the same; their definition is intentionally somewhat

19794

vague). It stops being alive and active when its run()

19795

method terminates -- either normally, or by raising an unhandled

19796

exception. The isAlive() method tests whether the thread is

19797

alive.

19798

Other threads can call a thread's join() method. This blocks

19799

the calling thread until the thread whose join() method is

19800

called is terminated.

19801

A thread has a name. The name can be passed to the constructor,

19802

set with the setName() method, and retrieved with the

19803

getName() method.

19804

A thread can be flagged as a ``daemon thread''. The significance

19805

of this flag is that the entire Python program exits when only

19806

daemon threads are left. The initial value is inherited from the

19807

creating thread. The flag can be set with the setDaemon()

19808

method and retrieved with the isDaemon() method.

19809

There is a ``main thread'' object; this corresponds to the

19810

initial thread of control in the Python program. It is not a

19811

daemon thread.

19812

There is the possibility that ``dummy thread objects'' are

19813

created. These are thread objects corresponding to ``alien

19814

threads''. These are threads of control started outside the

19815

threading module, such as directly from C code. Dummy thread objects

19816

have limited functionality; they are always considered alive,

19817

active, and daemonic, and cannot be join()ed. They are never deleted, since it is impossible to detect the termination of alien

19818

threads.

19819

</description>

19820

19821

<description>This constructor should always be called with keyword

19822

arguments. Arguments are:

19823

group should be None; reserved for future extension when

19824

a ThreadGroup class is implemented.

19825

target is the callable object to be invoked by the

19826

run() method. Defaults to None, meaning nothing is

19827

called.

19828

name is the thread name. By default, a unique name is

19829

constructed of the form ``Thread-N'' where N is a small

19830

decimal number.

19831

args is the argument tuple for the target invocation. Defaults

19832

to ().

19833

kwargs is a dictionary of keyword arguments for the target

19834

invocation. Defaults to {}.

19835

If the subclass overrides the constructor, it must make sure

19836

to invoke the base class constructor (Thread.__init__())

19837

before doing anything else to the thread.</description>

19838

19839

19840

19841

19842

<description>Start the thread's activity.

19843

This must be called at most once per thread object. It

19844

arranges for the object's run() method to be invoked in a

19845

separate thread of control.</description>

19846

19847

</element>

19848

19849

19850

<description>Method representing the thread's activity.

19851

You may override this method in a subclass. The standard

19852

run() method invokes the callable object passed to the

19853

object's constructor as the target argument, if any, with

19854

sequential and keyword arguments taken from the args and

19855

kwargs arguments, respectively.</description>

19856

19857

</element>

19858

19859

19860

<description>Wait until the thread terminates.

19861

This blocks the calling thread until the thread whose join()

19862

method is called terminates -- either normally or through an

19863

unhandled exception -- or until the optional timeout occurs.

19864

When the timeout argument is present and not None, it

19865

should be a floating point number specifying a timeout for the

19866

operation in seconds (or fractions thereof).

19867

A thread can be join()ed many times.

19868

A thread cannot join itself because this would cause a

19869

deadlock.

19870

It is an error to attempt to join() a thread before it has

19871

been started.</description>

19872

19873

19874

19875

19876

<description>Return the thread's name.</description>

19877

19878

</element>

19879

19880

19881

<description>Set the thread's name.

19882

The name is a string used for identification purposes only.

19883

It has no semantics. Multiple threads may be given the same

19884

name. The initial name is set by the constructor.</description>

19885

19886

19887

19888

19889

<description>Return whether the thread is alive.

19890

Roughly, a thread is alive from the moment the start() method

19891

returns until its run() method terminates.</description>

19892

19893

</element>

19894

19895

19896

<description>Return the thread's daemon flag.</description>

19897

19898

</element>

19899

19900

19901

<description>Set the thread's daemon flag to the Boolean value daemonic.

19902

This must be called before start() is called.

19903

The initial value is inherited from the creating thread.

19904

The entire Python program exits when no active non-daemon

19905

threads are left.</description>

19906

19907

19908

19909

</group>

19910

19911

<description>This class represents an action that should be run only after a

19912

certain amount of time has passed --- a timer. Timer is a

19913

subclass of Thread and as such also functions as an example of

19914

creating custom threads.

19915

Timers are started, as with threads, by calling their start()

19916

method. The timer can be stopped (before its action has begun) by

19917

calling the cancel() method. The interval the timer will

19918

wait before executing its action may not be exactly the same as the

19919

interval specified by the user.

19920

For example:

19921

def hello():

19922

print "hello, world"

19923

t = Timer(30.0, hello)

19924

t.start() # after 30 seconds, "hello, world" will be printed

19925

</description>

19926

19927

<description>Create a timer that will run function with arguments args and keyword arguments kwargs, after interval seconds have passed.</description>

19928

19929

19930

19931

19932

<description>Stop the timer, and cancel the execution of the timer's action. This

19933

will only work if the timer is still in its waiting stage.</description>

19934

19935

</element>

19936

19937

</group>

19938

</group>

19939

19940

</group>

19941

19942

</group>

19943

19944

<description>A synchronized queue class.

19945

The Queue module implements a multi-producer, multi-consumer

19946

FIFO queue. It is especially useful in threads programming when

19947

information must be exchanged safely between multiple threads. The

19948

Queue class in this module implements all the required locking

19949

semantics. It depends on the availability of thread support in

19950

Python.

19951

bisect{PriorityQueue example using the Queue class}

19952

The Queue module defines the following class and exception:

19953

</description>

19954

19955

<description>Constructor for the class. maxsize is an integer that sets the

19956

upperbound limit on the number of items that can be placed in the

19957

queue. Insertion will block once this size has been reached, until

19958

queue items are consumed. If maxsize is less than or equal to

19959

zero, the queue size is infinite.</description>

19960

19961

19962

19963

19964

19965

<description>Return the approximate size of the queue. Because of multithreading

19966

semantics, this number is not reliable.</description>

19967

19968

</element>

19969

19970

19971

<description>Return True if the queue is empty, False otherwise.

19972

Becauseof multithreading semantics, this is not reliable.</description>

19973

19974

</element>

19975

19976

19977

<description>Return True if the queue is full, False otherwise.

19978

Because of multithreading semantics, this is not reliable.</description>

19979

19980

</element>

19981

19982

19983

<description>Put item into the queue. If optional args block is true

19984

and timeout is None (the default), block if necessary until a

19985

free slot is available. If timeout is a positive number, it

19986

blocks at most timeout seconds and raises the Full

19987

exception if no free slot was available within that time.

19988

Otherwise (block is false), put an item on the queue if a free

19989

slot is immediately available, else raise the Full

19990

exception (timeout is ignored in that case).

19991

New in version 2.3</description>

19992

19993

19994

19995

19996

<description>Equivalent to put(item, False).</description>

19997

19998

19999

20000

20001

<description>Remove and return an item from the queue. If optional args

20002

block is true and timeout is None (the default),

20003

block if necessary until an item is available. If timeout is

20004

a positive number, it blocks at most timeout seconds and raises

20005

the Empty exception if no item was available within that

20006

time. Otherwise (block is false), return an item if one is

20007

immediately available, else raise the Empty exception

20008

(timeout is ignored in that case).

20009

New in version 2.3</description>

20010

20011

20012

20013

20014

<description>Equivalent to get(False).</description>

20015

20016

</element>

20017

20018

</group>

20019

</group>

20020

20021

<description>Interface to memory-mapped files for Windows.

20022

Memory-mapped file objects behave like both strings and like

20023

file objects. Unlike normal string objects, however, these are

20024

mutable. You can use mmap objects in most places where strings

20025

are expected; for example, you can use the re module to

20026

search through a memory-mapped file. Since they're mutable, you can

20027

change a single character by doing obj[index] = 'a', or

20028

change a substring by assigning to a slice:

20029

obj[i1:i2] = '...'. You can also read and write

20030

data starting at the current file position, and seek()

20031

through the file to different positions.

20032

A memory-mapped file is created by the mmap() function,

20033

which is different on and on Windows. In either case you must

20034

provide a file descriptor for a file opened for update.

20035

If you wish to map an existing Python file object, use its

20036

fileno() method to obtain the correct value for the

20037

fileno parameter. Otherwise, you can open the file using the

20038

os.open() function, which returns a file descriptor

20039

directly (the file still needs to be closed when done).

20040

For both the and Windows versions of the function,

20041

access may be specified as an optional keyword parameter.

20042

access accepts one of three values: ACCESS_READ,

20043

ACCESS_WRITE, or ACCESS_COPY to specify

20044

readonly, write-through or copy-on-write memory respectively.

20045

access can be used on both and Windows. If

20046

access is not specified, Windows mmap returns a write-through

20047

mapping. The initial memory values for all three access types are

20048

taken from the specified file. Assignment to an

20049

ACCESS_READ memory map raises a TypeError

20050

exception. Assignment to an ACCESS_WRITE memory map

20051

affects both memory and the underlying file. Assigment to an

20052

ACCESS_COPY memory map affects memory but does not update

20053

the underlying file.

20054

</description>

20055

20056

<description>(Windows version) Maps length bytes from the file

20057

specified by the file handle fileno, and returns a mmap

20058

object. If length is 0, the maximum length of the map

20059

will be the current size of the file when mmap() is

20060

called.

20061

tagname, if specified and not None, is a string giving

20062

a tag name for the mapping. Windows allows you to have many

20063

different mappings against the same file. If you specify the name

20064

of an existing tag, that tag is opened, otherwise a new tag of this

20065

name is created. If this parameter is omitted or None, the

20066

mapping is created without a name. Avoiding the use of the tag

20067

parameter will assist in keeping your code portable between and Windows.</description>

20068

20069

20070

20071

20072

<description>Close the file. Subsequent calls to other methods of the object

20073

will result in an exception being raised.</description>

20074

20075

</element>

20076

20077

20078

<description>Returns the lowest index in the object where the substring

20079

string is found. Returns -1 on failure. start

20080

is the index at which the search begins, and defaults to zero.</description>

20081

20082

20083

20084

20085

<description>Flushes changes made to the in-memory copy of a file back to disk.

20086

Without use of this call there is no guarantee that changes are

20087

written back before the object is destroyed. If offset and

20088

size are specified, only changes to the given range of bytes

20089

will be flushed to disk; otherwise, the whole extent of the mapping

20090

is flushed.</description>

20091

20092

20093

20094

20095

<description>Copy the count bytes starting at offset src to the

20096

destination index dest. If the mmap was created with

20097

ACCESS_READ, then calls to move will throw a

20098

TypeError exception.</description>

20099

20100

20101

20102

20103

<description>Return a string containing up to num bytes starting from the

20104

current file position; the file position is updated to point after the

20105

bytes that were returned.</description>

20106

20107

20108

20109

20110

<description>Returns a string of length 1 containing the character at the current

20111

file position, and advances the file position by 1.</description>

20112

20113

</element>

20114

20115

20116

<description>Returns a single line, starting at the current file position and up to the next newline.</description>

20117

20118

</element>

20119

20120

20121

<description>If the mmap was created with ACCESS_READ or

20122

ACCESS_COPY, resizing the map will throw a TypeError exception.</description>

20123

20124

20125

20126

20127

<description>Set the file's current position. whence argument is optional

20128

and defaults to 0 (absolute file positioning); other values

20129

are 1 (seek relative to the current position) and 2

20130

(seek relative to the file's end).</description>

20131

20132

20133

20134

20135

<description>Return the length of the file, which can be larger than the size of

20136

the memory-mapped area.</description>

20137

20138

</element>

20139

20140

20141

<description>Returns the current position of the file pointer.</description>

20142

20143

</element>

20144

20145

20146

<description>Write the bytes in string into memory at the current position

20147

of the file pointer; the file position is updated to point after the

20148

bytes that were written. If the mmap was created with

20149

ACCESS_READ, then writing to it will throw a

20150

TypeError exception.</description>

20151

20152

20153

20154

20155

<description>Write the single-character string byte into memory at the

20156

current position of the file pointer; the file position is advanced

20157

by 1.If the mmap was created with ACCESS_READ,

20158

then writing to it will throw a TypeError exception.</description>

20159

20160

20161

20162

</group>

20163

20164

<description>Generic interface to DBM-style database modules.

20165

anydbm is a generic interface to variants of the DBM

20166

database --- dbhashdbhash (requires

20167

bsddbbsddb),

20168

gdbmgdbm, or

20169

dbmdbm. If none of these modules is

20170

installed, the slow-but-simple implementation in module

20171

dumbdbmdumbdbm will be used.

20172

</description>

20173

20174

<description>Open the database file filename and return a corresponding object.

20175

If the database file already exists, the whichdb module is used to determine its type and the appropriate module is used; if it

20176

does not exist, the first module listed above that can be imported is

20177

used.

20178

The optional flag argument can be

20179

'r' to open an existing database for reading only,

20180

'w' to open an existing database for reading and writing,

20181

'c' to create the database if it doesn't exist, or

20182

'n', which will always create a new empty database. If not

20183

specified, the default value is 'r'.

20184

The optional mode argument is the mode of the file, used

20185

only when the database has to be created. It defaults to octal

20186

0666 (and will be modified by the prevailing umask).</description>

20187

20188

20189

20190

</group>

20191

20192

<description>Unix, Windows

20193

DBM-style interface to the BSD database library.

20194

The dbhash module provides a function to open databases using

20195

the BSD db library. This module mirrors the interface of the

20196

other Python database modules that provide access to DBM-style

20197

databases. The bsddbbsddb module is required to use dbhash.

20198

This module provides an exception and a function:

20199

{error}

20200

Exception raised on database errors other than

20201

KeyError. It is a synonym for bsddb.error.

20202

</description>

20203

20204

<description>Open a db database and return the database object. The

20205

path argument is the name of the database file.

20206

The flag argument can be

20207

'r' (the default), 'w',

20208

'c' (which creates the database if it doesn't exist), or

20209

'n' (which always creates a new empty database).

20210

For platforms on which the BSD db library supports locking,

20211

an l can be appended to indicate that locking should be

20212

used.

20213

The optional mode parameter is used to indicate the permission bits that should be set if a new database must be

20214

created; this will be masked by the current umask value for the

20215

process.</description>

20216

20217

20218

20219

20220

<description>The database objects returned by open() provide the methods common to all the DBM-style databases and mapping objects. The following

20221

methods are available in addition to the standard methods.

20222

</description>

20223

20224

<description>It's possible to loop over every key/value pair in the database using

20225

this method and the next() method. The traversal is ordered by

20226

the databases internal hash values, and won't be sorted by the key

20227

values. This method returns the starting key.</description>

20228

20229

</element>

20230

20231

20232

<description>Return the last key/value pair in a database traversal. This may be used to

20233

begin a reverse-order traversal; see previous().</description>

20234

20235

</element>

20236

20237

20238

<description>Returns the key next key/value pair in a database traversal. The

20239

following code prints every key in the database db, without

20240

having to create a list in memory that contains them all:

20241

print db.first()

20242

for i in xrange(1, len(db)):

20243

print db.next()

20244

</description>

20245

20246

</element>

20247

20248

20249

<description>Returns the previous key/value pair in a forward-traversal of the database.

20250

In conjunction with last(), this may be used to implement

20251

a reverse-order traversal.</description>

20252

20253

</element>

20254

20255

20256

<description>This method forces any unwritten data to be written to the disk.</description>

20257

20258

</element>

20259

20260

</group>

20261

</group>

20262

20263

<description>Guess which DBM-style module created a given database.

20264

The single function in this module attempts to guess which of the

20265

several simple database modules available--dbm,

20266

gdbm, or dbhash--should be used to open a

20267

given file.

20268

</description>

20269

20270

<description>Returns one of the following values: None if the file can't be

20271

opened because it's unreadable or doesn't exist; the empty string

20272

('') if the file's format can't be guessed; or a string

20273

containing the required module name, such as 'dbm' or

20274

'gdbm'.</description>

20275

20276

20277

20278

</group>

20279

20280

<description>Unix, Windows

20281

Interface to Berkeley DB database library

20282

The bsddb module provides an interface to the Berkeley DB

20283

library. Users can create hash, btree or record based library files

20284

using the appropriate open call. Bsddb objects behave generally like

20285

dictionaries. Keys and values must be strings, however, so to use

20286

other objects as keys or to store other kinds of objects the user must

20287

serialize them somehow, typically using marshal.dumps or pickle.dumps.

20288

Starting with Python 2.3 the bsddb module requires the

20289

Berkeley DB library version 3.2 or later (it is known to work with 3.2

20290

thru 4.2 at the time of this writing).

20291

http://pybsddb.sourceforge.net/{Website with documentation

20292

for the new python Berkeley DB interface that closely mirrors the sleepycat object oriented interface provided in Berkeley DB 3 and 4.}

20293

http://www.sleepycat.com/{Sleepycat Software produces the

20294

modern Berkeley DB library.}

20295

The following is a description of the legacy bsddb interface

20296

compatible with the old python bsddb module. For details about the more

20297

modern Db and DbEnv object oriented interface see the above mentioned

20298

pybsddb URL.

20299

The bsddb module defines the following functions that create

20300

objects that access the appropriate type of Berkeley DB file. The

20301

first two arguments of each function are the same. For ease of

20302

portability, only the first two arguments should be used in most

20303

instances.

20304

</description>

20305

20306

<description>Open the hash format file named filename. Files never intended

20307

to be preserved on disk may be created by passing None as the filename. The optional

20308

flag identifies the mode used to open the file. It may be

20309

r (read only, default), w (read-write) ,

20310

c (read-write - create if necessary) or

20311

n (read-write - truncate to zero length). The other

20312

arguments are rarely used and are just passed to the low-level

20313

dbopen() function. Consult the Berkeley DB documentation

20314

for their use and interpretation.</description>

20315

20316

20317

20318

20319

<description>Open the btree format file named filename. Files never intended to be preserved on disk may be created by passing None as the filename. The optional

20320

flag identifies the mode used to open the file. It may be

20321

r (read only, default), w (read-write),

20322

c (read-write - create if necessary) or

20323

n (read-write - truncate to zero length). The other

20324

arguments are rarely used and are just passed to the low-level dbopen

20325

function. Consult the Berkeley DB documentation for their use and

20326

interpretation.</description>

20327

20328

20329

20330

20331

<description>Open a DB record format file named filename. Files never intended to be preserved on disk may be created by passing None as the filename. The optional

20332

flag identifies the mode used to open the file. It may be

20333

r (read only, default), w (read-write),

20334

c (read-write - create if necessary) or

20335

n (read-write - truncate to zero length). The other

20336

arguments are rarely used and are just passed to the low-level dbopen

20337

function. Consult the Berkeley DB documentation for their use and

20338

interpretation.</description>

20339

20340

20341

20342

20343

<description>Once instantiated, hash, btree and record objects support

20344

the same methods as dictionaries. In addition, they support

20345

the methods listed below.

20346

Changed in version 2.3.1: Added dictionary methods

20347

</description>

20348

20349

<description>Close the underlying file. The object can no longer be accessed. Since

20350

there is no open open method for these objects, to open the file

20351

again a new bsddb module open function must be called.</description>

20352

20353

</element>

20354

20355

20356

<description>Return the list of keys contained in the DB file. The order of the list is

20357

unspecified and should not be relied on. In particular, the order of the

20358

list returned is different for different file formats.</description>

20359

20360

</element>

20361

20362

20363

<description>Return 1 if the DB file contains the argument as a key.</description>

20364

20365

20366

20367

20368

<description>Set the cursor to the item indicated by key and return a tuple

20369

containing the key and its value. For binary tree databases (opened

20370

using btopen()), if key does not actually exist in

20371

the database, the cursor will point to the next item in sorted order

20372

and return that key and value. For other databases,

20373

KeyError will be raised if key is not found in the

20374

database.</description>

20375

20376

20377

20378

20379

<description>Set the cursor to the first item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases.</description>

20380

20381

</element>

20382

20383

20384

<description>Set the cursor to the next item in the DB file and return it. The order of keys in the file is unspecified, except in the case of B-Tree databases.</description>

20385

20386

</element>

20387

20388

20389

<description>Set the cursor to the previous item in the DB file and return it. The

20390

order of keys in the file is unspecified, except in the case of B-Tree

20391

databases. This is not supported on hashtable databases (those opened

20392

with hashopen()).</description>

20393

20394

</element>

20395

20396

20397

<description>Set the cursor to the last item in the DB file and return it. The

20398

order of keys in the file is unspecified. This is not supported on

20399

hashtable databases (those opened with hashopen()).</description>

20400

20401

</element>

20402

20403

20404

<description>Synchronize the database on disk.</description>

20405

20406

</element>

20407

20408

</group>

20409

</group>

20410

20411

<description>Portable implementation of the simple DBM interface.

20412

</description>

20413

20414

<description>Open a dumbdbm database and return a dumbdbm object. The filename

20415

argument is the basename of the database file (without any specific

20416

extensions). When a dumbdbm database is created, files with .dat and

20417

.dir extensions are created.

20418

The optional flag argument is currently ignored; the database is

20419

always opened for update, and will be created if it does not exist.

20420

The optional mode argument is the mode of the file, used

20421

only when the database has to be created. It defaults to octal

20422

0666 (and will be modified by the prevailing umask).

20423

Changed in version 2.2: The mode argument was ignored in earlier

20424

versions</description>

20425

20426

20427

20428

20429

<description>In addition to the methods provided by the UserDict.DictMixin class,

20430

dumbdbm objects provide the following methods.

20431

</description>

20432

20433

<description>Synchronize the on-disk directory and data files. This method is called by

20434

the sync method of Shelve objects.</description>

20435

20436

</element>

20437

20438

</group>

20439

</group>

20440

20441

<description>Low-level interface to compression and decompression

20442

routines compatible with gzip.

20443

For applications that require data compression, the functions in this

20444

module allow compression and decompression, using the zlib library.

20445

The zlib library has its own home page at

20446

http://www.gzip.org/zlib/. Version 1.1.3 is the

20447

most recent version as of September 2000; use a later version if one

20448

is available. There are known incompatibilities between the Python

20449

module and earlier versions of the zlib library.

20450

The available exception and functions in this module are:

20451

{error}

20452

Exception raised on compression and decompression errors.

20453

</description>

20454

20455

<description>Computes a Adler-32 checksum of string. (An Adler-32

20456

checksum is almost as reliable as a CRC32 but can be computed much

20457

more quickly.) If value is present, it is used as the

20458

starting value of the checksum; otherwise, a fixed default value is

20459

used. This allows computing a running checksum over the

20460

concatenation of several input strings. The algorithm is not

20461

cryptographically strong, and should not be used for

20462

authentication or digital signatures. Since the algorithm is

20463

designed for use as a checksum algorithm, it is not suitable for

20464

use as a general hash algorithm.</description>

20465

20466

20467

20468

20469

<description>Compresses the data in string, returning a string contained

20470

compressed data. level is an integer from 1 to

20471

9 controlling the level of compression; 1 is fastest

20472

and produces the least compression, 9 is slowest and produces

20473

the most. The default value is 6. Raises the

20474

error exception if any error occurs.</description>

20475

20476

20477

20478

20479

<description>Returns a compression object, to be used for compressing data streams

20480

that won't fit into memory at once. level is an integer from

20481

1 to 9 controlling the level of compression; 1 is

20482

fastest and produces the least compression, 9 is slowest and

20483

produces the most. The default value is 6.</description>

20484

20485

20486

20487

20488

<description>Computes a CRC (Cyclic Redundancy Check)%

20489

</description>

20490

20491

20492

20493

20494

<description>Decompresses the data in string, returning a string containing

20495

the uncompressed data. The wbits parameter controls the size of

20496

the window buffer. If bufsize is given, it is used as the

20497

initial size of the output buffer. Raises the error

20498

exception if any error occurs.

20499

The absolute value of wbits is the base two logarithm of the

20500

size of the history buffer (the ``window size'') used when compressing

20501

data. Its absolute value should be between 8 and 15 for the most

20502

recent versions of the zlib library, larger values resulting in better

20503

compression at the expense of greater memory usage. The default value

20504

is 15. When wbits is negative, the standard

20505

gzip header is suppressed; this is an undocumented feature

20506

of the zlib library, used for compatibility with unzip's

20507

compression file format.

20508

bufsize is the initial size of the buffer used to hold

20509

decompressed data. If more space is required, the buffer size will be

20510

increased as needed, so you don't have to get this value exactly

20511

right; tuning it will only save a few calls to malloc(). The

20512

default size is 16384.</description>

20513

20514

20515

20516

20517

<description>Returns a decompression object, to be used for decompressing data

20518

streams that won't fit into memory at once. The wbits

20519

parameter controls the size of the window buffer.</description>

20520

20521

20522

20523

20524

<description>Compress string, returning a string containing compressed data

20525

for at least part of the data in string. This data should be

20526

concatenated to the output produced by any preceding calls to the

20527

compress() method. Some input may be kept in internal buffers

20528

for later processing.</description>

20529

20530

20531

20532

20533

<description>All pending input is processed, and a string containing the remaining

20534

compressed output is returned. mode can be selected from the

20535

constants Z_SYNC_FLUSH, Z_FULL_FLUSH, or Z_FINISH, defaulting to Z_FINISH. Z_SYNC_FLUSH and Z_FULL_FLUSH allow compressing further strings of data and

20536

are used to allow partial error recovery on decompression, while

20537

Z_FINISH finishes the compressed stream and prevents compressing any more data. After calling

20538

flush() with mode set to Z_FINISH, the

20539

compress() method cannot be called again; the only realistic

20540

action is to delete the object.</description>

20541

20542

20543

20544

20545

<description>{max_length}

20546

Decompress string, returning a string containing the

20547

uncompressed data corresponding to at least part of the data in

20548

string. This data should be concatenated to the output produced

20549

by any preceding calls to the

20550

decompress() method. Some of the input data may be preserved

20551

in internal buffers for later processing.

20552

If the optional parameter max_length is supplied then the return value

20553

will be no longer than max_length. This may mean that not all of the

20554

compressed input can be processed; and unconsumed data will be stored

20555

in the attribute unconsumed_tail. This string must be passed

20556

to a subsequent call to decompress() if decompression is to

20557

continue. If max_length is not supplied then the whole input is

20558

decompressed, and unconsumed_tail is an empty string.</description>

20559

20560

20561

20562

20563

<description>All pending input is processed, and a string containing the remaining

20564

uncompressed output is returned. After calling flush(), the

20565

decompress() method cannot be called again; the only realistic

20566

action is to delete the object.</description>

20567

20568

</element>

20569

20570

</group>

20571

20572

<description>Interfaces for gzip compression and

20573

decompression using file objects.

20574

The data compression provided by the zlib module is compatible

20575

with that used by the GNU compression program gzip.

20576

Accordingly, the gzip module provides the GzipFile

20577

class to read and write gzip-format files, automatically

20578

compressing or decompressing the data so it looks like an ordinary

20579

file object. Note that additional file formats which can be

20580

decompressed by the gzip and gunzip programs, such as those produced by compress and pack, are not

20581

supported by this module.

20582

The module defines the following items:

20583

</description>

20584

20585

<description>Constructor for the GzipFile class, which simulates most of

20586

the methods of a file object, with the exception of the readinto()

20587

and truncate() methods. At least one of

20588

fileobj and filename must be given a non-trivial value.

20589

The new class instance is based on fileobj, which can be a

20590

regular file, a StringIO object, or any other object which

20591

simulates a file. It defaults to None, in which case

20592

filename is opened to provide a file object.

20593

When fileobj is not None, the filename argument is

20594

only used to be included in the gzip file header, which may

20595

includes the original filename of the uncompressed file. It defaults

20596

to the filename of fileobj, if discernible; otherwise, it

20597

defaults to the empty string, and in this case the original filename

20598

is not included in the header.

20599

The mode argument can be any of 'r', 'rb',

20600

'a', 'ab', 'w', or 'wb', depending on

20601

whether the file will be read or written. The default is the mode of

20602

fileobj if discernible; otherwise, the default is 'rb'.

20603

If not given, the 'b' flag will be added to the mode to ensure the

20604

file is opened in binary mode for cross-platform portability.

20605

The compresslevel argument is an integer from 1 to

20606

9 controlling the level of compression; 1 is fastest and

20607

produces the least compression, and 9 is slowest and produces

20608

the most compression. The default is 9.

20609

Calling a GzipFile object's close() method does not

20610

close fileobj, since you might wish to append more material

20611

after the compressed data. This also allows you to pass a

20612

StringIO object opened for writing as fileobj, and

20613

retrieve the resulting memory buffer using the StringIO

20614

object's getvalue() method.</description>

20615

20616

20617

20618

20619

<description>This is a shorthand for GzipFile(filename,

20620

mode, compresslevel). The filename

20621

argument is required; mode defaults to 'rb' and

20622

compresslevel defaults to 9.</description>

20623

20624

20625

20626

</group>

20627

20628

<description>Interface to compression and decompression

20629

routines compatible with bzip2.

20630

New in version 2.3

20631

This module provides a comprehensive interface for the bz2 compression library.

20632

It implements a complete file interface, one-shot (de)compression functions,

20633

and types for sequential (de)compression.

20634

Here is a resume of the features offered by the bz2 module:

20635

BZ2File class implements a complete file interface, including

20636

readline(), readlines(),

20637

writelines(), seek(), etc;

20638

BZ2File class implements emulated seek() support;

20639

BZ2File class implements universal newline support;

20640

BZ2File class offers an optimized line iteration using

20641

the readahead algorithm borrowed from file objects;

20642

Sequential (de)compression supported by BZ2Compressor and

20643

BZ2Decompressor classes;

20644

One-shot (de)compression supported by compress() and

20645

decompress() functions;

20646

Thread safety uses individual locking mechanism;

20647

Complete inline documentation;

20648

</description>

20649

20650

<description>Handling of compressed files is offered by the BZ2File class.

20651

</description>

20652

20653

<description>Open a bz2 file. Mode can be either 'r' or 'w', for reading (default) or writing. When opened for writing, the file will be created if

20654

it doesn't exist, and truncated otherwise. If buffering is given,

20655

0 means unbuffered, and larger numbers specify the buffer size;

20656

the default is 0. If

20657

compresslevel is given, it must be a number between 1 and

20658

9; the default is 9.

20659

Add a U to mode to open the file for input with universal newline

20660

support. Any line ending in the input file will be seen as a

20661

\n in Python. Also, a file so opened gains the

20662

attribute newlines; the value for this attribute is one of

20663

None (no newline read yet), '\r', '\n',

20664

'\r\n' or a tuple containing all the newline types

20665

seen. Universal newlines are available only when reading.

20666

Instances support iteration in the same way as normal file

20667

instances.</description>

20668

20669

20670

20671

</group>

20672

20673

<description>Sequential compression and decompression is done using the classes

20674

BZ2Compressor and BZ2Decompressor.

20675

</description>

20676

20677

<description>Create a new compressor object. This object may be used to compress

20678

data sequentially. If you want to compress data in one shot, use the

20679

compress() function instead. The compresslevel parameter,

20680

if given, must be a number between 1 and 9; the default

20681

is 9.</description>

20682

20683

20684

20685

20686

<description>Create a new decompressor object. This object may be used to decompress

20687

data sequentially. If you want to decompress data in one shot, use the

20688

decompress() function instead.</description>

20689

20690

</element>

20691

20692

</group>

20693

20694

<description>One-shot compression and decompression is provided through the

20695

compress() and decompress() functions.

20696

</description>

20697

20698

<description>Compress data in one shot. If you want to compress data sequentially,

20699

use an instance of BZ2Compressor instead. The compresslevel

20700

parameter, if given, must be a number between 1 and 9;

20701

the default is 9.</description>

20702

20703

20704

20705

20706

<description>Decompress data in one shot. If you want to decompress data

20707

sequentially, use an instance of BZ2Decompressor instead.</description>

20708

20709

20710

20711

</group>

20712

</group>

20713

20714

<description>Read and write ZIP-format archive files.

20715

% LaTeX markup by Fred L. Drake, Jr. <fdrake@acm.org>

20716

New in version 1.6

20717

The ZIP file format is a common archive and compression standard.

20718

This module provides tools to create, read, write, append, and list a

20719

ZIP file. Any advanced use of this module will require an

20720

understanding of the format, as defined in

20721

PKZIP Application

20722

Note.

20723

This module does not currently handle ZIP files which have appended

20724

comments, or multi-disk ZIP files.

20725

The available attributes of this module are:

20726

{error}

20727

The error raised for bad ZIP files.

20728

{ZipFile}

20729

The class for reading and writing ZIP files. See

20730

``ZipFile Objects'' (section zipfile-objects) for

20731

constructor details.

20732

{PyZipFile}

20733

Class for creating ZIP archives containing Python libraries.

20734

</description>

20735

20736

<description>Class used the represent infomation about a member of an archive.

20737

Instances of this class are returned by the getinfo() and

20738

infolist() methods of ZipFile objects. Most users

20739

of the zipfile module will not need to create these, but

20740

only use those created by this module.

20741

filename should be the full name of the archive member, and

20742

date_time should be a tuple containing six fields which

20743

describe the time of the last modification to the file; the fields

20744

are described in section zipinfo-objects, ``ZipInfo Objects.''</description>

20745

20746

20747

20748

20749

<description>Returns True if filename is a valid ZIP file based on its magic

20750

number, otherwise returns False. This module does not currently

20751

handle ZIP files which have appended comments.</description>

20752

20753

20754

20755

20756

20757

<description>Open a ZIP file, where file can be either a path to a file

20758

(a string) or a file-like object. The mode parameter

20759

should be 'r' to read an existing file, 'w' to

20760

truncate and write a new file, or 'a' to append to an

20761

existing file. For mode is 'a' and file

20762

refers to an existing ZIP file, then additional files are added to

20763

it. If file does not refer to a ZIP file, then a new ZIP

20764

archive is appended to the file. This is meant for adding a ZIP

20765

archive to another file, such as python.exe. Using

20766

cat myzip.zip >> python.exe

20767

also works, and at least WinZip can read such files.

20768

compression is the ZIP compression method to use when writing

20769

the archive, and should be ZIP_STORED or

20770

ZIP_DEFLATED; unrecognized values will cause

20771

RuntimeError to be raised. If ZIP_DEFLATED

20772

is specified but the zlib module is not available,

20773

RuntimeError is also raised. The default is

20774

ZIP_STORED.</description>

20775

20776

20777

20778

20779

<description>Close the archive file. You must call close() before

20780

exiting your program or essential records will not be written.</description>

20781

20782

</element>

20783

20784

20785

<description>Return a ZipInfo object with information about the archive

20786

member name.</description>

20787

20788

20789

20790

20791

<description>Return a list containing a ZipInfo object for each member of

20792

the archive. The objects are in the same order as their entries in

20793

the actual ZIP file on disk if an existing archive was opened.</description>

20794

20795

</element>

20796

20797

20798

<description>Return a list of archive members by name.</description>

20799

20800

</element>

20801

20802

20803

<description>Print a table of contents for the archive to sys.stdout.</description>

20804

20805

</element>

20806

20807

20808

<description>Return the bytes of the file in the archive. The archive must be

20809

open for read or append.</description>

20810

20811

20812

20813

20814

<description>Read all the files in the archive and check their CRC's. Return the

20815

name of the first bad file, or else return None.</description>

20816

20817

</element>

20818

20819

20820

<description>Write the file named filename to the archive, giving it the

20821

archive name arcname (by default, this will be the same as

20822

filename). If given, compress_type overrides the value

20823

given for the compression parameter to the constructor for

20824

the new entry. The archive must be open with mode 'w' or

20825

'a'.</description>

20826

20827

20828

20829

20830

<description>Write the string bytes to the archive; zinfo_or_arcname

20831

is either the file name it will be given in the archive, or a

20832

ZipInfo instance. If it's an instance, at least the

20833

filename, date, and time must be given. If it's a name, the date

20834

and time is set to the current date and time. The archive must be

20835

opened with mode 'w' or 'a'.</description>

20836

20837

20838

20839

</group>

20840

20841

<description>The PyZipFile constructor takes the same parameters as the

20842

ZipFile constructor. Instances have one method in addition to

20843

those of ZipFile objects.

20844

</description>

20845

20846

<description>Search for files *.py and add the corresponding file to the

20847

archive. The corresponding file is a *.pyo file if

20848

available, else a *.pyc file, compiling if necessary. If the

20849

pathname is a file, the filename must end with .py, and just

20850

the (corresponding *.py[co]) file is added at the top level

20851

(no path information). If it is a directory, and the directory is

20852

not a package directory, then all the files *.py[co] are

20853

added at the top level. If the directory is a package directory,

20854

then all *.py[oc] are added under the package name as a file

20855

path, and if any subdirectories are package directories, all of

20856

these are added recursively. basename is intended for

20857

internal use only. The writepy() method makes archives

20858

with file names like this:

20859

string.pyc # Top level name test/__init__.pyc # Package directory test/testall.pyc # Module test.testall

20860

test/bogus/__init__.pyc # Subpackage directory test/bogus/myfile.pyc # Submodule test.bogus.myfile

20861

</description>

20862

20863

20864

20865

</group>

20866

20867

</group>

20868

</group>

20869

20870

<description>Read and write tar-format archive files.

20871

New in version 2.3

20872

The tarfile module makes it possible to read and create tar archives.

20873

Some facts and figures:

20874

reads and writes gzip and bzip2 compressed archives.

20875

creates POSIX 1003.1-1990 compliant or GNU tar compatible archives.

20876

reads GNU tar extensions longname, longlink and

20877

sparse.

20878

stores pathnames of unlimited length using GNU tar extensions.

20879

handles directories, regular files, hardlinks, symbolic links, fifos,

20880

character devices and block devices and is able to acquire and

20881

restore file information like timestamp, access permissions and owner.

20882

can handle tape devices.

20883

</description>

20884

20885

<description>Return a TarFile object for the pathname name.

20886

For detailed information on TarFile objects,

20887

see TarFile Objects (section tarfile-objects).

20888

mode has to be a string of the form 'filemode[:compression]',

20889

it defaults to 'r'. Here is a full list of mode combinations:

20890

{c|l}{code}{mode}{action}

20891

'r'{Open for reading with transparent compression (recommended).}

20892

'r:'{Open for reading exclusively without compression.}

20893

'r:gz'{Open for reading with gzip compression.}

20894

'r:bz2'{Open for reading with bzip2 compression.}

20895

'a' or 'a:'{Open for appending with no compression.}

20896

'w' or 'w:'{Open for uncompressed writing.}

20897

'w:gz'{Open for gzip compressed writing.}

20898

'w:bz2'{Open for bzip2 compressed writing.}

20899

Note that 'a:gz' or 'a:bz2' is not possible.

20900

If mode is not suitable to open a certain (compressed) file for

20901

reading, ReadError is raised. Use mode 'r' to

20902

avoid this. If a compression method is not supported,

20903

CompressionError is raised.

20904

If fileobj is specified, it is used as an alternative to

20905

a file object opened for name.

20906

For special purposes, there is a second format for mode:

20907

'filemode|[compression]'. open will return a TarFile

20908

object that processes its data as a stream of blocks. No random

20909

seeking will be done on the file. If given, fileobj may be any

20910

object that has a read() resp. write() method.

20911

bufsize specifies the blocksize and defaults to 20 * 512

20912

bytes. Use this variant in combination with e.g. sys.stdin, a socket

20913

file object or a tape device.

20914

However, such a TarFile object is limited in that it does not allow

20915

to be accessed randomly, see Examples (section

20916

tar-examples).

20917

The currently possible modes:

20918

{c|l}{code}{mode}{action}

20919

'r|'{Open a stream of uncompressed tar blocks for reading.}

20920

'r|gz'{Open a gzip compressed stream for reading.}

20921

'r|bz2'{Open a bzip2 compressed stream for reading.}

20922

'w|'{Open an uncompressed stream for writing.}

20923

'w|gz'{Open an gzip compressed stream for writing.}

20924

'w|bz2'{Open an bzip2 compressed stream for writing.}

20925

</description>

20926

20927

20928

20929

20930

<description>Return True if name is a tar archive file, that the

20931

tarfile module can read.</description>

20932

20933

20934

20935

20936

<description>Class for limited access to tar archives with a zipfile-like

20937

interface. Please consult the documentation of zipfile for more

20938

details.

20939

compression must be one of the following constants:

20940

{TAR_PLAIN}

20941

Constant for an uncompressed tar archive.

20942

{TAR_GZIPPED}

20943

Constant for a gzip compressed tar archive.

20944

</description>

20945

20946

20947

20948

20949

<description>The TarFile object provides an interface to a tar archive. A tar

20950

archive is a sequence of blocks. An archive member (a stored file) is made up

20951

of a header block followed by data blocks. It is possible, to store a file in a

20952

tar archive several times. Each archive member is represented by a

20953

TarInfo object, see TarInfo Objects (section

20954

tarinfo-objects) for details.

20955

</description>

20956

20957

<description>Open an (uncompressed) tar archive name.

20958

mode is either 'r' to read from an existing archive,

20959

'a' to append data to an existing file or 'w' to create a new

20960

file overwriting an existing one. mode defaults to 'r'.

20961

If fileobj is given, it is used for reading or writing data.

20962

If it can be determined, mode is overridden by fileobj's mode.

20963

fileobj is not closed, when TarFile is closed.

20964

</description>

20965

20966

20967

20968

20969

<description>Alternative constructor. The open() function on module level is

20970

actually a shortcut to this classmethod. See section module-tarfile

20971

for details.</description>

20972

20973

20974

20975

20976

<description>Return a TarInfo object for member name. If name can

20977

not be found in the archive, KeyError is raised.

20978

If a member occurs more than once in the archive, its last

20979

occurence is assumed to be the most up-to-date version.

20980

</description>

20981

20982

20983

20984

20985

<description>Return the members of the archive as a list of TarInfo objects.

20986

The list has the same order as the members in the archive.</description>

20987

20988

</element>

20989

20990

20991

<description>Return the members as a list of their names. It has the same order as

20992

the list returned by getmembers().</description>

20993

20994

</element>

20995

20996

20997

<description>Print a table of contents to sys.stdout. If verbose is

20998

False, only the names of the members are printed. If it is

20999

True, an "ls -l"-like output is produced.</description>

21000

21001

21002

21003

21004

<description>Return the next member of the archive as a TarInfo object, when

21005

TarFile is opened for reading. Return None if there is no

21006

more available.</description>

21007

21008

</element>

21009

21010

21011

<description>Extract a member from the archive to the current working directory,

21012

using its full name. Its file information is extracted as accurately as

21013

possible.

21014

member may be a filename or a TarInfo object.

21015

You can specify a different directory using path.</description>

21016

21017

21018

21019

21020

<description>Extract a member from the archive as a file object.

21021

member may be a filename or a TarInfo object.

21022

If member is a regular file, a file-like object is returned.

21023

If member is a link, a file-like object is constructed from the

21024

link's target.

21025

If member is none of the above, None is returned.

21026

The file-like object is read-only and provides the following methods:

21027

read(), readline(), readlines(),

21028

seek(), tell().

21029

</description>

21030

21031

21032

21033

21034

<description>Add the file name to the archive. name may be any type

21035

of file (directory, fifo, symbolic link, etc.).

21036

If given, arcname specifies an alternative name for the file in the

21037

archive. Directories are added recursively by default.

21038

This can be avoided by setting recursive to False.</description>

21039

21040

21041

21042

21043

<description>Add the TarInfo object tarinfo to the archive.

21044

If fileobj is given, tarinfo.size bytes are read

21045

from it and added to the archive. You can create TarInfo objects

21046

using gettarinfo().

21047

On Windows platforms, fileobj should always be opened with mode

21048

'rb' to avoid irritation about the file size.

21049

</description>

21050

21051

21052

21053

21054

<description>Create a TarInfo object for either the file name or the

21055

file object fileobj (using os.fstat() on its file descriptor).

21056

You can modify some of the TarInfo's attributes before you add it

21057

using addfile().

21058

If given, arcname specifies an alternative name for the file in the

21059

archive.</description>

21060

21061

21062

21063

21064

<description>Close the TarFile. In write-mode, two finishing zero blocks are

21065

appended to the archive.</description>

21066

21067

</element>

21068

21069

</group>

21070

21071

<description>A TarInfo object represents one member in a TarFile. Aside from

21072

storing all required attributes of a file (like file type, size, time,

21073

permissions, owner etc.), it provides some useful methods to determine its

21074

type. It does not contain the file's data itself.

21075

TarInfo objects are returned by TarFile's methods

21076

getmember(), getmembers() and gettarinfo().

21077

</description>

21078

21079

<description>Create a TarInfo object.</description>

21080

21081

21082

21083

21084

<description>Create and return a TarInfo object from a string buffer.</description>

21085

21086

</element>

21087

21088

21089

<description>Create a string buffer from a TarInfo object.</description>

21090

21091

</element>

21092

21093

21094

<description>Return True if the Tarinfo object is a regular file.</description>

21095

21096

</element>

21097

21098

21099

<description>Same as isfile().</description>

21100

21101

</element>

21102

21103

21104

<description>Return True if it is a directory.</description>

21105

21106

</element>

21107

21108

21109

<description>Return True if it is a symbolic link.</description>

21110

21111

</element>

21112

21113

21114

<description>Return True if it is a hard link.</description>

21115

21116

</element>

21117

21118

21119

<description>Return True if it is a character device.</description>

21120

21121

</element>

21122

21123

21124

<description>Return True if it is a block device.</description>

21125

21126

</element>

21127

21128

21129

<description>Return True if it is a FIFO.</description>

21130

21131

</element>

21132

21133

21134

<description>Return True if it is one of character device, block device or FIFO.</description>

21135

21136

</element>

21137

21138

</group>

21139

21140

</group>

21141

</group>

21142

21143

<description>Unix

21144

GNU readline support for Python.

21145

The readline module defines a number of functions used either

21146

directly or from the rlcompleter module to facilitate

21147

completion and history file read and write from the Python

21148

interpreter.

21149

The readline module defines the following functions:

21150

</description>

21151

21152

<description>Parse and execute single line of a readline init file.</description>

21153

21154

21155

21156

21157

<description>Return the current contents of the line buffer.</description>

21158

21159

</element>

21160

21161

21162

<description>Insert text into the command line.</description>

21163

21164

21165

21166

21167

<description>Parse a readline initialization file.

21168

The default filename is the last filename used.</description>

21169

21170

21171

21172

21173

<description>Load a readline history file.

21174

The default filename is .</description>

21175

21176

21177

21178

21179

<description>Save a readline history file.

21180

The default filename is .</description>

21181

21182

21183

21184

21185

<description>Clear the current history. (Note: this function is not available if

21186

the installed version of GNU readline doesn't support it.)

21187

New in version 2.4</description>

21188

21189

</element>

21190

21191

21192

<description>Return the desired length of the history file. Negative values imply

21193

unlimited history file size.</description>

21194

21195

</element>

21196

21197

21198

<description>Set the number of lines to save in the history file.

21199

write_history_file() uses this value to truncate the

21200

history file when saving. Negative values imply unlimited history

21201

file size.</description>

21202

21203

21204

21205

21206

<description>Set or remove the startup_hook function. If function is specified,

21207

it will be used as the new startup_hook function; if omitted or

21208

None, any hook function already installed is removed. The

21209

startup_hook function is called with no arguments just

21210

before readline prints the first prompt.</description>

21211

21212

21213

21214

21215

<description>Set or remove the pre_input_hook function. If function is specified,

21216

it will be used as the new pre_input_hook function; if omitted or

21217

None, any hook function already installed is removed. The

21218

pre_input_hook function is called with no arguments after the first prompt

21219

has been printed and just before readline starts reading input characters.</description>

21220

21221

21222

21223

21224

<description>Set or remove the completer function. If function is specified,

21225

it will be used as the new completer function; if omitted or

21226

None, any completer function already installed is removed. The

21227

completer function is called as function(text,

21228

state), for state in 0, 1, 2, ...,

21229

until it returns a non-string value. It should return the next

21230

possible completion starting with text.</description>

21231

21232

21233

21234

21235

<description>Get the completer function, or None if no completer function

21236

has been set. New in version 2.3</description>

21237

21238

</element>

21239

21240

21241

<description>Get the beginning index of the readline tab-completion scope.</description>

21242

21243

</element>

21244

21245

21246

<description>Get the ending index of the readline tab-completion scope.</description>

21247

21248

</element>

21249

21250

21251

<description>Set the readline word delimiters for tab-completion.</description>

21252

21253

21254

21255

21256

<description>Get the readline word delimiters for tab-completion.</description>

21257

21258

</element>

21259

21260

21261

<description>Append a line to the history buffer, as if it was the last line typed.</description>

21262

21263

21264

21265

21266

</group>

21267

</group>

21268

21269

<description>Unix

21270

Python identifier completion for the GNU readline library.

21271

The rlcompleter module defines a completion function for

21272

the readline module by completing valid Python identifiers

21273

and keywords.

21274

This module is -specific due to its dependence on the

21275

readline module.

21276

The rlcompleter module defines the Completer class.

21277

Example:

21278

>>> import rlcompleter

21279

>>> import readline

21280

>>> readline.parse_and_bind("tab: complete")

21281

>>> readline. <TAB PRESSED>

21282

readline.__doc__ readline.get_line_buffer readline.read_init_file

21283

readline.__file__ readline.insert_text readline.set_completer

21284

readline.__name__ readline.parse_and_bind

21285

>>> readline.

21286

The rlcompleter module is designed for use with Python's

21287

interactive mode. A user can add the following lines to his or her

21288

initialization file (identified by the PYTHONSTARTUP

21289

environment variable) to get automatic Tab completion:

21290

try:

21291

import readline

21292

except ImportError:

21293

print "Module readline not available."

21294

else:

21295

import rlcompleter

21296

readline.parse_and_bind("tab: complete")

21297

</description>

21298

21299

<description>Completer objects have the following method:

21300

</description>

21301

21302

<description>Return the stateth completion for text.

21303

If called for text that doesn't include a period character

21304

(.), it will complete from names currently defined in

21305

__main__, __builtin__ and

21306

keywords (as defined by the keyword module).

21307

If called for a dotted name, it will try to evaluate anything without

21308

obvious side-effects (functions will not be evaluated, but it

21309

can generate calls to __getattr__()) up to the last part, and

21310

find matches for the rest via the dir() function.</description>

21311

21312

21313

21314

</group>

21315

</group>

21316

</group>

21317

21318

21319

<description>Unix

21320

The most common calls (normally used

21321

via module os).

21322

This module provides access to operating system functionality that is

21323

standardized by the C Standard and the standard (a thinly

21324

disguised interface).

21325

Do not import this module directly. Instead, import the

21326

module os, which provides a portable version of this

21327

interface. On , the os module provides a superset of

21328

the posix interface. On non- operating systems the

21329

posix module is not available, but a subset is always

21330

available through the os interface. Once os is

21331

imported, there is no performance penalty in using it instead

21332

of posix. In addition, osos

21333

provides some additional functionality, such as automatically calling

21334

putenv() when an entry in os.environ is changed.

21335

The descriptions below are very terse; refer to the corresponding

21336

manual (or documentation) entry for more information.

21337

Arguments called path refer to a pathname given as a string.

21338

Errors are reported as exceptions; the usual exceptions are given for

21339

type errors, while errors reported by the system calls raise

21340

error (a synonym for the standard exception

21341

OSError), described below.

21342

</description>

21343

21344

</group>

21345

21346

</group>

21347

</group>

21348

21349

<description>Unix

21350

The password database (getpwnam() and friends).

21351

This module provides access to the user account and password

21352

database. It is available on all versions.

21353

Password database entries are reported as a tuple-like object, whose

21354

attributes correspond to the members of the passwd structure

21355

(Attribute field below, see <pwd.h>):

21356

{r|l|l}{textrm}{Index}{Attribute}{Meaning}

21357

0{pw_name}{Login name}

21358

1{pw_passwd}{Optional encrypted password}

21359

2{pw_uid}{Numerical user ID}

21360

3{pw_gid}{Numerical group ID}

21361

4{pw_gecos}{User name or comment field}

21362

5{pw_dir}{User home directory}

21363

6{pw_shell}{User command interpreter}

21364

The uid and gid items are integers, all others are strings.

21365

KeyError is raised if the entry asked for cannot be found.

21366

In traditional the field pw_passwd usually

21367

contains a password encrypted with a DES derived algorithm (see module

21368

cryptcrypt). However most modern unices use a so-called shadow password system. On those unices the

21369

field pw_passwd only contains a asterisk ('*') or the letter x where the encrypted password is stored in a file

21370

/etc/shadow which is not world readable.

21371

It defines the following items:

21372

</description>

21373

21374

<description>Return the password database entry for the given numeric user ID.</description>

21375

21376

21377

21378

21379

<description>Return the password database entry for the given user name.</description>

21380

21381

21382

21383

21384

<description>Return a list of all available password database entries, in arbitrary order.</description>

21385

21386

</element>

21387

21388

</group>

21389

21390

<description>Unix

21391

The group database (getgrnam() and friends).

21392

This module provides access to the group database.

21393

It is available on all versions.

21394

Group database entries are reported as a tuple-like object, whose

21395

attributes correspond to the members of the group structure

21396

(Attribute field below, see <pwd.h>):

21397

{r|l|l}{textrm}{Index}{Attribute}{Meaning}

21398

0{gr_name}{the name of the group}

21399

1{gr_passwd}{the (encrypted) group password; often empty}

21400

2{gr_gid}{the numerical group ID}

21401

3{gr_mem}{all the group member's user names}

21402

The gid is an integer, name and password are strings, and the member

21403

list is a list of strings.

21404

(Note that most users are not explicitly listed as members of the

21405

group they are in according to the password database. Check both

21406

databases to get complete membership information.)

21407

It defines the following items:

21408

</description>

21409

21410

<description>Return the group database entry for the given numeric group ID.

21411

KeyError is raised if the entry asked for cannot be found.</description>

21412

21413

21414

21415

21416

<description>Return the group database entry for the given group name.

21417

KeyError is raised if the entry asked for cannot be found.</description>

21418

21419

21420

21421

21422

<description>Return a list of all available group entries, in arbitrary order.</description>

21423

21424

</element>

21425

21426

</group>

21427

21428

<description>Unix

21429

The crypt() function used to check

21430

.

21431

This module implements an interface to the

21432

crypt{3}</description>

21433

21434

<description>word will usually be a user's password as typed at a prompt or in a graphical interface. salt is usually a random

21435

two-character string which will be used to perturb the DES algorithm

21436

in one of 4096 ways. The characters in salt must be in the

21437

set [./a-zA-Z0-9]. Returns the hashed password as a

21438

string, which will be composed of characters from the same alphabet

21439

as the salt (the first two characters represent the salt itself).</description>

21440

21441

21442

21443

</group>

21444

21445

<description>Unix %?????????? Anyone????????????

21446

Call C functions in shared objects.

21447

The dl module defines an interface to the

21448

dlopen() function, which is the most common interface on

21449

platforms for handling dynamically linked libraries. It allows

21450

the program to call arbitrary functions in such a library.

21451

This module will not work unless

21452

sizeof(int) == sizeof(long) == sizeof(char *)

21453

If this is not the case, SystemError will be raised on

21454

import.

21455

The dl module defines the following function:

21456

</description>

21457

21458

<description>Open a shared object file, and return a handle. Mode

21459

signifies late binding (RTLD_LAZY) or immediate binding

21460

(RTLD_NOW). Default is RTLD_LAZY. Note that some

21461

systems do not support RTLD_NOW.

21462

Return value is a dlobject.</description>

21463

21464

21465

21466

21467

<description>Dl objects, as returned by open() above, have the

21468

following methods:

21469

</description>

21470

21471

<description>Free all resources, except the memory.</description>

21472

21473

</element>

21474

21475

21476

<description>Return the pointer for the function named name, as a number, if

21477

it exists in the referenced shared object, otherwise None. This

21478

is useful in code like:

21479

>>> if a.sym('time'): ... a.call('time')

21480

... else: ... time.time()

21481

(Note that this function will return a non-zero number, as zero is the

21482

pointer)</description>

21483

21484

21485

21486

21487

<description>Call the function named name in the referenced shared object.

21488

The arguments must be either Python integers, which will be passed as is, Python strings, to which a pointer will be passed, or None, which will be passed as . Note that strings should only be passed to functions as const char*, as

21489

Python will not like its string mutated.

21490

There must be at most 10 arguments, and arguments not given will be

21491

treated as None. The function's return value must be a C

21492

long, which is a Python integer.</description>

21493

21494

21495

21496

</group>

21497

</group>

21498

21499

<description>Unix

21500

The standard ``database'' interface, based on ndbm.

21501

The dbm module provides an interface to the (n)dbm library. Dbm objects behave like mappings

21502

(dictionaries), except that keys and values are always strings.

21503

Printing a dbm object doesn't print the keys and values, and the

21504

items() and values() methods are not supported.

21505

This module can be used with the ``classic'' ndbm interface, the BSD

21506

DB compatibility interface, or the GNU GDBM compatibility interface.

21507

On , the configure script will attempt to locate the

21508

appropriate header file to simplify building this module.

21509

The module defines the following:

21510

{error}

21511

Raised on dbm-specific errors, such as I/O errors.

21512

KeyError is raised for general mapping errors like

21513

specifying an incorrect key.

21514

{library}

21515

Name of the ndbm implementation library used.

21516

</description>

21517

21518

<description>Open a dbm database and return a dbm object. The filename

21519

argument is the name of the database file (without the .dir or

21520

.pag extensions; note that the BSD DB implementation of the

21521

interface will append the extension .db and only create one

21522

file).

21523

The optional flag argument must be one of these values:

21524

{c|l}{code}{Value}{Meaning}

21525

'r'{Open existing database for reading only (default)}

21526

'w'{Open existing database for reading and writing}

21527

'c'{Open database for reading and writing, creating it if

21528

it doesn't exist}

21529

'n'{Always create a new, empty database, open for reading

21530

and writing}

21531

The optional mode argument is the mode of the file, used

21532

only when the database has to be created. It defaults to octal

21533

0666.</description>

21534

21535

21536

21537

</group>

21538

21539

<description>Unix

21540

GNU's reinterpretation of dbm.

21541

This module is quite similar to the dbmdbm

21542

module, but uses gdbm instead to provide some additional

21543

functionality. Please note that the file formats created by

21544

gdbm and dbm are incompatible.

21545

The gdbm module provides an interface to the GNU DBM

21546

library. gdbm objects behave like mappings

21547

(dictionaries), except that keys and values are always strings.

21548

Printing a gdbm object doesn't print the keys and values, and

21549

the items() and values() methods are not supported.

21550

The module defines the following constant and functions:

21551

{error}

21552

Raised on gdbm-specific errors, such as I/O errors.

21553

KeyError is raised for general mapping errors like

21554

specifying an incorrect key.

21555

</description>

21556

21557

<description>Open a gdbm database and return a gdbm object. The

21558

filename argument is the name of the database file.

21559

The optional flag argument can be

21560

'r' (to open an existing database for reading only --- default),

21561

'w' (to open an existing database for reading and writing),

21562

'c' (which creates the database if it doesn't exist), or

21563

'n' (which always creates a new empty database).

21564

The following additional characters may be appended to the flag to

21565

control how the database is opened:

21566

'f' --- Open the database in fast mode. Writes to the database

21567

will not be syncronized.

21568

's' --- Synchronized mode. This will cause changes to the database

21569

will be immediately written to the file.

21570

'u' --- Do not lock database. Not all flags are valid for all versions of gdbm. The

21571

module constant open_flags is a string of supported flag

21572

characters. The exception error is raised if an invalid

21573

flag is specified.

21574

The optional mode argument is the mode of the file, used

21575

only when the database has to be created. It defaults to octal

21576

0666.</description>

21577

21578

21579

21580

21581

<description>It's possible to loop over every key in the database using this method and the nextkey() method. The traversal is ordered by

21582

gdbm's internal hash values, and won't be sorted by the key

21583

values. This method returns the starting key.</description>

21584

21585

</element>

21586

21587

21588

<description>Returns the key that follows key in the traversal. The

21589

following code prints every key in the database db, without

21590

having to create a list in memory that contains them all:

21591

k = db.firstkey()

21592

while k != None:

21593

print k

21594

k = db.nextkey(k)

21595

</description>

21596

21597

21598

21599

21600

<description>If you have carried out a lot of deletions and would like to shrink

21601

the space used by the gdbm file, this routine will reorganize

21602

the database. gdbm will not shorten the length of a database

21603

file except by using this reorganization; otherwise, deleted file

21604

space will be kept and reused as new (key, value) pairs are added.</description>

21605

21606

</element>

21607

21608

21609

<description>When the database has been opened in fast mode, this method forces any unwritten data to be written to the disk.</description>

21610

21611

</element>

21612

21613

</group>

21614

21615

<description>Unix

21616

tty control.

21617

This module provides an interface to the calls for tty I/O

21618

control. For a complete description of these calls, see the or

21619

manual pages. It is only available for those versions

21620

that support termios style tty I/O control (and then

21621

only if configured at installation time).

21622

All functions in this module take a file descriptor fd as their

21623

first argument. This can be an integer file descriptor, such as

21624

returned by sys.stdin.fileno(), or a file object, such as

21625

sys.stdin itself.

21626

This module also defines all the constants needed to work with the

21627

functions provided here; these have the same name as their

21628

counterparts in C. Please refer to your system documentation for more

21629

information on using these terminal control interfaces.

21630

The module defines the following functions:

21631

</description>

21632

21633

<description>Return a list containing the tty attributes for file descriptor

21634

fd, as follows: [iflag, oflag, cflag,

21635

lflag, ispeed, ospeed, cc] where

21636

cc is a list of the tty special characters (each a string of

21637

length 1, except the items with indices VMIN and

21638

VTIME, which are integers when these fields are

21639

defined). The interpretation of the flags and the speeds as well as

21640

the indexing in the cc array must be done using the symbolic

21641

constants defined in the termios

21642

module.</description>

21643

21644

21645

21646

21647

<description>Set the tty attributes for file descriptor fd from the

21648

attributes, which is a list like the one returned by

21649

tcgetattr(). The when argument determines when the

21650

attributes are changed: TCSANOW to change immediately,

21651

TCSADRAIN to change after transmitting all queued output,

21652

or TCSAFLUSH to change after transmitting all queued

21653

output and discarding all queued input.</description>

21654

21655

21656

21657

21658

<description>Send a break on file descriptor fd. A zero duration sends

21659

a break for 0.25--0.5 seconds; a nonzero duration has a system

21660

dependent meaning.</description>

21661

21662

21663

21664

21665

<description>Wait until all output written to file descriptor fd has been

21666

transmitted.</description>

21667

21668

21669

21670

21671

<description>Discard queued data on file descriptor fd. The queue

21672

selector specifies which queue: TCIFLUSH for the input

21673

queue, TCOFLUSH for the output queue, or

21674

TCIOFLUSH for both queues.</description>

21675

21676

21677

21678

21679

<description>Suspend or resume input or output on file descriptor fd. The

21680

action argument can be TCOOFF to suspend output,

21681

TCOON to restart output, TCIOFF to suspend

21682

input, or TCION to restart input.</description>

21683

21684

21685

21686

21687

</group>

21688

</group>

21689

21690

<description>Unix

21691

Utility functions that perform common terminal control

21692

operations.

21693

The tty module defines functions for putting the tty into

21694

cbreak and raw modes.

21695

Because it requires the termios module, it will work

21696

only on .

21697

The tty module defines the following functions:

21698

</description>

21699

21700

<description>Change the mode of the file descriptor fd to raw. If when

21701

is omitted, it defaults to TERMIOS.TCAFLUSH, and is passed

21702

to termios.tcsetattr().</description>

21703

21704

21705

21706

21707

<description>Change the mode of file descriptor fd to cbreak. If when

21708

is omitted, it defaults to TERMIOS.TCAFLUSH, and is passed

21709

to termios.tcsetattr().</description>

21710

21711

21712

21713

</group>

21714

21715

<description>IRIX, Linux

21716

Pseudo-Terminal Handling for SGI and Linux.

21717

The pty module defines operations for handling the

21718

pseudo-terminal concept: starting another process and being able to

21719

write to and read from its controlling terminal programmatically.

21720

Because pseudo-terminal handling is highly platform dependant, there

21721

is code to do it only for SGI and Linux. (The Linux code is supposed

21722

to work on other platforms, but hasn't been tested yet.)

21723

The pty module defines the following functions:

21724

</description>

21725

21726

<description>Fork. Connect the child's controlling terminal to a pseudo-terminal.

21727

Return value is (pid, fd). Note that the child gets pid 0, and the fd is invalid. The parent's

21728

return value is the pid of the child, and fd is a file

21729

descriptor connected to the child's controlling terminal (and also

21730

to the child's standard input and output).</description>

21731

21732

</element>

21733

21734

21735

<description>Open a new pseudo-terminal pair, using os.openpty() if

21736

possible, or emulation code for SGI and generic systems.

21737

Return a pair of file descriptors (master, slave),

21738

for the master and the slave end, respectively.</description>

21739

21740

</element>

21741

21742

21743

<description>Spawn a process, and connect its controlling terminal with the current process's standard io. This is often used to baffle programs which

21744

insist on reading from the controlling terminal.

21745

The functions master_read and stdin_read should be

21746

functions which read from a file-descriptor. The defaults try to read

21747

1024 bytes each time they are called.</description>

21748

21749

21750

21751

</group>

21752

21753

<description>Unix

21754

The fcntl() and ioctl() system calls.

21755

This module performs file control and I/O control on file descriptors.

21756

It is an interface to the fcntl() and ioctl()

21757

routines.

21758

All functions in this module take a file descriptor fd as their

21759

first argument. This can be an integer file descriptor, such as

21760

returned by sys.stdin.fileno(), or a file object, such as

21761

sys.stdin itself, which provides a fileno() which

21762

returns a genuine file descriptor.

21763

The module defines the following functions:

21764

</description>

21765

21766

<description>Perform the requested operation on file descriptor fd (file

21767

objects providing a fileno() method are accepted as well).

21768

The operation is defined by op and is operating system

21769

dependent. These codes are also found in the fcntl

21770

module. The argument arg is optional, and defaults to the

21771

integer value 0. When present, it can either be an integer

21772

value, or a string. With the argument missing or an integer value,

21773

the return value of this function is the integer return value of the

21774

C fcntl() call. When the argument is a string it

21775

represents a binary structure, e.g. by

21776

struct.pack(). The binary data is copied to a buffer

21777

whose address is passed to the C fcntl() call. The

21778

return value after a successful call is the contents of the buffer,

21779

converted to a string object. The length of the returned string

21780

will be the same as the length of the arg argument. This is

21781

limited to 1024 bytes. If the information returned in the buffer by

21782

the operating system is larger than 1024 bytes, this is most likely

21783

to result in a segmentation violation or a more subtle data

21784

corruption.

21785

If the fcntl() fails, an IOError is

21786

raised.</description>

21787

21788

21789

21790

21791

<description>This function is identical to the fcntl() function,

21792

except that the operations are typically defined in the library

21793

module termios and the argument handling is even more

21794

complicated.

21795

The parameter arg can be one of an integer, absent (treated

21796

identically to the integer 0), an object supporting the

21797

read-only buffer interface (most likely a plain Python string) or an

21798

object supporting the read-write buffer interface.

21799

In all but the last case, behaviour is as for the fcntl()

21800

function.

21801

If a mutable buffer is passed, then the behaviour is determined by

21802

the value of the mutate_flag parameter.

21803

If it is false, the buffer's mutability is ignored and behaviour is

21804

as for a read-only buffer, except that the 1024 byte limit mentioned

21805

above is avoided -- so long as the buffer you pass is longer than

21806

what the operating system wants to put there, things should work.

21807

If mutate_flag is true, then the buffer is (in effect) passed

21808

to the underlying ioctl() system call, the latter's

21809

return code is passed back to the calling Python, and the buffer's

21810

new contents reflect the action of the ioctl. This is a

21811

slight simplification, because if the supplied buffer is less than

21812

1024 bytes long it is first copied into a static buffer 1024 bytes

21813

long which is then passed to ioctl and copied back into

21814

the supplied buffer.

21815

If mutate_flag is not supplied, then in 2.3 it defaults to

21816

false. This is planned to change over the next few Python versions:

21817

in 2.4 failing to supply mutate_flag will get a warning but

21818

the same behavior and in versions later than 2.5 it will default to

21819

true.

21820

An example:

21821

>>> import array, fcntl, struct, termios, os

21822

>>> os.getpgrp()

21823

13341

21824

>>> struct.unpack('h', fcntl.ioctl(0, termios.TIOCGPGRP, " "))[0]

21825

13341

21826

>>> buf = array.array('h', [0])

21827

>>> fcntl.ioctl(0, termios.TIOCGPGRP, buf, 1)

21828

0

21829

>>> buf

21830

array('h', [13341])

21831

</description>

21832

21833

21834

21835

21836

<description>Perform the lock operation op on file descriptor fd (file

21837

objects providing a fileno() method are accepted as well).

21838

See the manual flock{3} for details. (On some

21839

systems, this function is emulated using fcntl().)</description>

21840

21841

21842

21843

21844

<description>This is essentially a wrapper around the fcntl() locking

21845

calls. fd is the file descriptor of the file to lock or unlock,

21846

and operation is one of the following values:

21847

LOCK_UN -- unlock

21848

LOCK_SH -- acquire a shared lock

21849

LOCK_EX -- acquire an exclusive lock

21850

When operation is LOCK_SH or LOCK_EX, it

21851

can also be bit-wise OR'd with LOCK_NB to avoid blocking on

21852

lock acquisition. If LOCK_NB is used and the lock cannot

21853

be acquired, an IOError will be raised and the exception

21854

will have an errno attribute set to EACCES or

21855

EAGAIN (depending on the operating system; for portability,

21856

check for both values). On at least some systems, LOCK_EX

21857

can only be used if the file descriptor refers to a file opened for

21858

writing.

21859

length is the number of bytes to lock, start is the byte

21860

offset at which the lock starts, relative to whence, and

21861

whence is as with fileobj.seek(), specifically:

21862

0 -- relative to the start of the file

21863

(SEEK_SET)

21864

1 -- relative to the current buffer position

21865

(SEEK_CUR)

21866

2 -- relative to the end of the file

21867

(SEEK_END)

21868

The default for start is 0, which means to start at the

21869

beginning of the file. The default for length is 0 which means

21870

to lock to the end of the file. The default for whence is also

21871

0.</description>

21872

21873

21874

21875

</group>

21876

21877

<description>Unix

21878

A Python interface to pipelines.

21879

The pipes module defines a class to abstract the concept of

21880

a pipeline --- a sequence of convertors from one file to another.

21881

Because the module uses /bin/sh command lines, a or

21882

compatible shell for os.system() and os.popen()

21883

is required.

21884

The pipes module defines the following class:

21885

</description>

21886

21887

<description>An abstraction of a pipeline.</description>

21888

21889

</element>

21890

21891

21892

<description>Template objects following methods:

21893

</description>

21894

21895

<description>Restore a pipeline template to its initial state.</description>

21896

21897

</element>

21898

21899

21900

<description>Return a new, equivalent, pipeline template.</description>

21901

21902

</element>

21903

21904

21905

<description>If flag is true, turn debugging on. Otherwise, turn debugging

21906

off. When debugging is on, commands to be executed are printed, and

21907

the shell is given set -x command to be more verbose.</description>

21908

21909

21910

21911

21912

<description>Append a new action at the end. The cmd variable must be a valid

21913

bourne shell command. The kind variable consists of two letters.

21914

The first letter can be either of '-' (which means the command

21915

reads its standard input), 'f' (which means the commands reads

21916

a given file on the command line) or '.' (which means the commands

21917

reads no input, and hence must be first.)

21918

Similarly, the second letter can be either of '-' (which means the command writes to standard output), 'f' (which means the command writes a file on the command line) or '.' (which means

21919

the command does not write anything, and hence must be last.)</description>

21920

21921

21922

21923

21924

<description>Add a new action at the beginning. See append() for explanations

21925

of the arguments.</description>

21926

21927

21928

21929

21930

<description>Return a file-like object, open to file, but read from or

21931

written to by the pipeline. Note that only one of 'r',

21932

'w' may be given.</description>

21933

21934

21935

21936

21937

<description>Copy infile to outfile through the pipe.</description>

21938

21939

21940

21941

</group>

21942

</group>

21943

21944

<description>Unix

21945

A file-like object with support for locking.

21946

1.5{The locking operation that this module provides is

21947

done better and more portably by the

21948

fcntl.lockf() call.

21949

(in module fcntl){lockf()}}

21950

This module implements some additional functionality over the built-in

21951

file objects. In particular, it implements file locking, control over

21952

the file flags, and an easy interface to duplicate the file object.

21953

The module defines a new file object, the posixfile object. It

21954

has all the standard file object methods and adds the methods

21955

described below. This module only works for certain flavors of

21956

, since it uses fcntl.fcntl() for file locking.%

21957

(in module fcntl){fcntl()}

21958

To instantiate a posixfile object, use the open() function

21959

in the posixfile module. The resulting object looks and

21960

feels roughly the same as a standard file object.

21961

The posixfile module defines the following constants:

21962

{SEEK_SET}

21963

Offset is calculated from the start of the file.

21964

{SEEK_CUR}

21965

Offset is calculated from the current position in the file.

21966

{SEEK_END}

21967

Offset is calculated from the end of the file.

21968

The posixfile module defines the following functions:

21969

</description>

21970

21971

<description>Create a new posixfile object with the given filename and mode. The

21972

filename, mode and bufsize arguments are

21973

interpreted the same way as by the built-in open()

21974

function.</description>

21975

21976

21977

21978

21979

<description>Create a new posixfile object with the given standard file object.

21980

The resulting object has the same filename and mode as the original

21981

file object.</description>

21982

21983

21984

21985

21986

<description>Lock the specified section of the file that the file object is

21987

referring to. The format is explained

21988

below in a table. The len argument specifies the length of the

21989

section that should be locked. The default is 0. start

21990

specifies the starting offset of the section, where the default is

21991

0. The whence argument specifies where the offset is

21992

relative to. It accepts one of the constants SEEK_SET,

21993

SEEK_CUR or SEEK_END. The default is

21994

SEEK_SET. For more information about the arguments refer

21995

to the fcntl{2} manual page on your system.</description>

21996

21997

21998

21999

22000

<description>Set the specified flags for the file that the file object is referring

22001

to. The new flags are ORed with the old flags, unless specified

22002

otherwise. The format is explained below in a table. Without

22003

the flags argument

22004

a string indicating the current flags is returned (this is

22005

the same as the ? modifier). For more information about the

22006

flags refer to the fcntl{2} manual page on your system.</description>

22007

22008

22009

22010

22011

<description>Duplicate the file object and the underlying file pointer and file

22012

descriptor. The resulting object behaves as if it were newly

22013

opened.</description>

22014

22015

</element>

22016

22017

22018

<description>Duplicate the file object and the underlying file pointer and file

22019

descriptor. The new object will have the given file descriptor.

22020

Otherwise the resulting object behaves as if it were newly opened.</description>

22021

22022

22023

22024

22025

<description>Return the standard file object that the posixfile object is based

22026

on. This is sometimes necessary for functions that insist on a

22027

standard file object.</description>

22028

22029

</element>

22030

22031

</group>

22032

22033

<description>Unix

22034

An interface to provide resource usage information on

22035

the current process.

22036

This module provides basic mechanisms for measuring and controlling

22037

system resources utilized by a program.

22038

Symbolic constants are used to specify particular system resources and

22039

to request usage information about either the current process or its

22040

children.

22041

A single exception is defined for errors:

22042

{error}

22043

The functions described below may raise this error if the underlying

22044

system call failures unexpectedly.

22045

</description>

22046

22047

<description>Resources usage can be limited using the setrlimit() function

22048

described below. Each resource is controlled by a pair of limits: a

22049

soft limit and a hard limit. The soft limit is the current limit, and

22050

may be lowered or raised by a process over time. The soft limit can

22051

never exceed the hard limit. The hard limit can be lowered to any

22052

value greater than the soft limit, but not raised. (Only processes with

22053

the effective UID of the super-user can raise a hard limit.)

22054

The specific resources that can be limited are system dependent. They

22055

are described in the getrlimit{2} man page. The resources

22056

listed below are supported when the underlying operating system

22057

supports them; resources which cannot be checked or controlled by the

22058

operating system are not defined in this module for those platforms.

22059

</description>

22060

22061

<description>Returns a tuple (soft, hard) with the current

22062

soft and hard limits of resource. Raises ValueError if

22063

an invalid resource is specified, or error if the

22064

underyling system call fails unexpectedly.</description>

22065

22066

22067

22068

22069

<description>Sets new limits of consumption of resource. The limits

22070

argument must be a tuple (soft, hard) of two

22071

integers describing the new limits. A value of -1 can be used to

22072

specify the maximum possible upper limit.

22073

Raises ValueError if an invalid resource is specified,

22074

if the new soft limit exceeds the hard limit, or if a process tries

22075

to raise its hard limit (unless the process has an effective UID of

22076

super-user). Can also raise error if the underyling

22077

system call fails.</description>

22078

22079

22080

22081

</group>

22082

22083

<description>These functions are used to retrieve resource usage information:

22084

</description>

22085

22086

<description>This function returns an object that describes the resources

22087

consumed by either the current process or its children, as specified

22088

by the who parameter. The who parameter should be

22089

specified using one of the RUSAGE_* constants described

22090

below.

22091

The fields of the return value each describe how a particular system

22092

resource has been used, e.g. amount of time spent running is user mode

22093

or number of times the process was swapped out of main memory. Some

22094

values are dependent on the clock tick internal, e.g. the amount of

22095

memory the process is using.

22096

For backward compatibility, the return value is also accessible as

22097

a tuple of 16 elements.

22098

The fields ru_utime and ru_stime of the return value

22099

are floating point values representing the amount of time spent

22100

executing in user mode and the amount of time spent executing in system

22101

mode, respectively. The remaining values are integers. Consult the

22102

getrusage{2} man page for detailed information about these

22103

values. A brief summary is presented here:

22104

{r|l|l}{code}{Index}{Field}{Resource}

22105

0{ru_utime}{time in user mode (float)}

22106

1{ru_stime}{time in system mode (float)}

22107

2{ru_maxrss}{maximum resident set size}

22108

3{ru_ixrss}{shared memory size}

22109

4{ru_idrss}{unshared memory size}

22110

5{ru_isrss}{unshared stack size}

22111

6{ru_minflt}{page faults not requiring I/O}

22112

7{ru_majflt}{page faults requiring I/O}

22113

8{ru_nswap}{number of swap outs}

22114

9{ru_inblock}{block input operations}

22115

10{ru_oublock}{block output operations}

22116

11{ru_msgsnd}{messages sent}

22117

12{ru_msgrcv}{messages received}

22118

13{ru_nsignals}{signals received}

22119

14{ru_nvcsw}{voluntary context switches}

22120

15{ru_nivcsw}{involuntary context switches}

22121

This function will raise a ValueError if an invalid

22122

who parameter is specified. It may also raise

22123

error exception in unusual circumstances.

22124

Changed in version 2.3: Added access to values as attributes of the

22125

returned object</description>

22126

22127

22128

22129

22130

<description>Returns the number of bytes in a system page. (This need not be the

22131

same as the hardware page size.) This function is useful for

22132

determining the number of bytes of memory a process is using. The

22133

third element of the tuple returned by getrusage() describes

22134

memory usage in pages; multiplying by page size produces number of

22135

bytes.</description>

22136

22137

</element>

22138

22139

</group>

22140

</group>

22141

22142

<description>UNIX

22143

Interface to Sun's NIS (Yellow Pages) library.

22144

The nis module gives a thin wrapper around the NIS library, useful

22145

for central administration of several hosts.

22146

Because NIS exists only on systems, this module is

22147

only available for .

22148

The nis module defines the following functions:

22149

</description>

22150

22151

<description>Return the match for key in map mapname, or raise an

22152

error (nis.error) if there is none.

22153

Both should be strings, key is 8-bit clean.

22154

Return value is an arbitrary array of bytes (may contain NULL

22155

and other joys).

22156

Note that mapname is first checked if it is an alias to another

22157

name.</description>

22158

22159

22160

22161

22162

<description>Return a dictionary mapping key to value such that

22163

match(key, mapname)==value.

22164

Note that both keys and values of the dictionary are arbitrary

22165

arrays of bytes.

22166

Note that mapname is first checked if it is an alias to another

22167

name.</description>

22168

22169

22170

22171

22172

<description>Return a list of all valid maps.</description>

22173

22174

</element>

22175

22176

</group>

22177

22178

<description>Unix

22179

An interface to the library routines.

22180

This module provides an interface to the syslog library

22181

routines. Refer to the manual pages for a detailed description

22182

of the syslog facility.

22183

The module defines the following functions:

22184

</description>

22185

22186

<description>Send the string message to the system logger. A trailing

22187

newline is added if necessary. Each message is tagged with a priority

22188

composed of a facility and a level. The optional

22189

priority argument, which defaults to LOG_INFO,

22190

determines the message priority. If the facility is not encoded in

22191

priority using logical-or (LOG_INFO | LOG_USER), the

22192

value given in the openlog() call is used.</description>

22193

22194

22195

22196

22197

<description>Logging options other than the defaults can be set by explicitly

22198

opening the log file with openlog() prior to calling

22199

syslog(). The defaults are (usually) ident =

22200

'syslog', logopt = 0, facility =

22201

LOG_USER. The ident argument is a string which is

22202

prepended to every message. The optional logopt argument is a

22203

bit field - see below for possible values to combine. The optional

22204

facility argument sets the default facility for messages which

22205

do not have a facility explicitly encoded.</description>

22206

22207

22208

22209

22210

<description>Close the log file.</description>

22211

22212

</element>

22213

22214

22215

<description>Set the priority mask to maskpri and return the

22216

previous mask value. Calls to syslog() with a priority

22217

level not set in maskpri are ignored. The default is to log all

22218

priorities. The function LOG_MASK(pri) calculates the

22219

mask for the individual priority pri. The function

22220

LOG_UPTO(pri) calculates the mask for all priorities up

22221

to and including pri.</description>

22222

22223

22224

22225

</group>

22226

22227

<description>Unix

22228

Utility functions for running external commands.

22229

The commands module contains wrapper functions for

22230

os.popen() which take a system command as a string and

22231

return any output generated by the command and, optionally, the exit

22232

status.

22233

The commands module defines the following functions:

22234

</description>

22235

22236

<description>Execute the string cmd in a shell with os.popen() and

22237

return a 2-tuple (status, output). cmd is

22238

actually run as { cmd ; } 2>1, so that the returned

22239

output will contain output or error messages. A trailing newline is

22240

stripped from the output. The exit status for the command can be

22241

interpreted according to the rules for the C function

22242

wait().</description>

22243

22244

22245

22246

22247

<description>Like getstatusoutput(), except the exit status is ignored

22248

and the return value is a string containing the command's output.</description>

22249

22250

22251

22252

22253

<description>Return the output of ls -ld file as a string. This

22254

function uses the getoutput() function, and properly

22255

escapes backslashes and dollar signs in the argument.</description>

22256

22257

22258

22259

</group>

22260

</group>

22261

22262

22263

</group>

22264

</group>

22265

22266

22267

<description>Profiler Introduction

22268

A profiler is a program that describes the run time performance

22269

of a program, providing a variety of statistics. This documentation

22270

describes the profiler functionality provided in the modules

22271

profile and pstats. This profiler provides

22272

deterministic profiling of any Python programs. It also

22273

provides a series of report generation tools to allow users to rapidly

22274

examine the results of a profile operation.

22275

</description>

22276

22277

<description>This function takes a single argument that has can be passed to the

22278

exec statement, and an optional file name. In all cases this

22279

routine attempts to exec its first argument, and gather profiling

22280

statistics from the execution. If no file name is present, then this

22281

function automatically prints a simple profiling report, sorted by the

22282

standard name string (file/line/function-name) that is presented in

22283

each line. The following is a typical output from such a call:

22284

main()

22285

2706 function calls (2004 primitive calls) in 4.504 CPU seconds

22286

Ordered by: standard name

22287

ncalls tottime percall cumtime percall filename:lineno(function)

22288

2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)

22289

43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)

22290

...

22291

The first line indicates that this profile was generated by the call:

22292

profile.run('main()'), and hence the exec'ed string is

22293

'main()'. The second line indicates that 2706 calls were

22294

monitored. Of those calls, 2004 were primitive. We define

22295

primitive to mean that the call was not induced via recursion.

22296

The next line: Ordered by: name, indicates that

22297

the text string in the far right column was used to sort the output.

22298

The column headings include:

22299

[ncalls ]

22300

for the number of calls,

22301

[tottime ]

22302

for the total time spent in the given function (and excluding time

22303

made in calls to sub-functions),

22304

[percall ]

22305

is the quotient of tottime divided by ncalls

22306

[cumtime ]

22307

is the total time spent in this and all subfunctions (from invocation

22308

till exit). This figure is accurate even for recursive

22309

functions.

22310

[percall ]

22311

is the quotient of cumtime divided by primitive calls

22312

[filename:lineno(function) ]

22313

provides the respective data of each function

22314

When there are two numbers in the first column (for example,

22315

43/3), then the latter is the number of primitive calls, and

22316

the former is the actual number of calls. Note that when the function

22317

does not recurse, these two values are the same, and only the single

22318

figure is printed.</description>

22319

22320

22321

22322

22323

<description>This class constructor creates an instance of a ``statistics object''

22324

from a filename (or set of filenames). Stats objects are

22325

manipulated by methods, in order to print useful reports.

22326

The file selected by the above constructor must have been created by

22327

the corresponding version of profile. To be specific, there is

22328

no file compatibility guaranteed with future versions of this

22329

profiler, and there is no compatibility with files produced by other

22330

profilers (such as the old system profiler).

22331

If several files are provided, all the statistics for identical

22332

functions will be coalesced, so that an overall view of several

22333

processes can be considered in a single report. If additional files

22334

need to be combined with data in an existing Stats object, the

22335

add() method can be used.</description>

22336

22337

22338

22339

22340

<description>Stats objects have the following methods:

22341

</description>

22342

22343

<description>This method for the Stats class removes all leading path

22344

information from file names. It is very useful in reducing the size

22345

of the printout to fit within (close to) 80 columns. This method

22346

modifies the object, and the stripped information is lost. After

22347

performing a strip operation, the object is considered to have its

22348

entries in a ``random'' order, as it was just after object

22349

initialization and loading. If strip_dirs() causes two

22350

function names to be indistinguishable (they are on the same

22351

line of the same filename, and have the same function name), then the

22352

statistics for these two entries are accumulated into a single entry.</description>

22353

22354

</element>

22355

22356

22357

<description>This method of the Stats class accumulates additional

22358

profiling information into the current profiling object. Its

22359

arguments should refer to filenames created by the corresponding

22360

version of profile.run(). Statistics for identically named

22361

(re: file, line, name) functions are automatically accumulated into

22362

single function statistics.</description>

22363

22364

22365

22366

22367

<description>Save the data loaded into the Stats object to a file named

22368

filename. The file is created if it does not exist, and is

22369

overwritten if it already exists. This is equivalent to the method of

22370

the same name on the profile.Profile class.

22371

New in version 2.3</description>

22372

22373

22374

22375

22376

<description>This method modifies the Stats object by sorting it according

22377

to the supplied criteria. The argument is typically a string

22378

identifying the basis of a sort (example: 'time' or

22379

'name').

22380

When more than one key is provided, then additional keys are used as

22381

secondary criteria when there is equality in all keys selected

22382

before them. For example, sort_stats('name', 'file') will sort

22383

all the entries according to their function name, and resolve all ties

22384

(identical function names) by sorting by file name.

22385

Abbreviations can be used for any key names, as long as the

22386

abbreviation is unambiguous. The following are the keys currently

22387

defined:

22388

{l|l}{code}{Valid Arg}{Meaning}

22389

'calls'{call count}

22390

'cumulative'{cumulative time}

22391

'file'{file name}

22392

'module'{file name}

22393

'pcalls'{primitive call count}

22394

'line'{line number}

22395

'name'{function name}

22396

'nfl'{name/file/line}

22397

'stdname'{standard name}

22398

'time'{internal time}

22399

Note that all sorts on statistics are in descending order (placing

22400

most time consuming items first), where as name, file, and line number

22401

searches are in ascending order (alphabetical). The subtle

22402

distinction between 'nfl' and 'stdname' is that the

22403

standard name is a sort of the name as printed, which means that the

22404

embedded line numbers get compared in an odd way. For example, lines

22405

3, 20, and 40 would (if the file names were the same) appear in the

22406

string order 20, 3 and 40. In contrast, 'nfl' does a numeric

22407

compare of the line numbers. In fact, sort_stats('nfl') is the

22408

same as sort_stats('name', 'file', 'line').

22409

For compatibility with the old profiler, the numeric arguments

22410

-1, 0, 1, and 2 are permitted. They are

22411

interpreted as 'stdname', 'calls', 'time', and

22412

'cumulative' respectively. If this old style format (numeric)

22413

is used, only one sort key (the numeric key) will be used, and

22414

additional arguments will be silently ignored.</description>

22415

22416

22417

22418

22419

<description>This method for the Stats class reverses the ordering of the basic

22420

list within the object. This method is provided primarily for

22421

compatibility with the old profiler. Its utility is questionable

22422

now that ascending vs descending order is properly selected based on

22423

the sort key of choice.</description>

22424

22425

</element>

22426

22427

22428

<description>This method for the Stats class prints out a report as described

22429

in the profile.run() definition.

22430

The order of the printing is based on the last sort_stats()

22431

operation done on the object (subject to caveats in add() and

22432

strip_dirs()).

22433

The arguments provided (if any) can be used to limit the list down to

22434

the significant entries. Initially, the list is taken to be the

22435

complete set of profiled functions. Each restriction is either an

22436

integer (to select a count of lines), or a decimal fraction between

22437

0.0 and 1.0 inclusive (to select a percentage of lines), or a regular

22438

expression (to pattern match the standard name that is printed; as of

22439

Python 1.5b1, this uses the Perl-style regular expression syntax

22440

defined by the re module). If several restrictions are

22441

provided, then they are applied sequentially. For example:

22442

print_stats(.1, 'foo:')

22443

would first limit the printing to first 10% of list, and then only

22444

print functions that were part of filename .*foo:. In

22445

contrast, the command:

22446

print_stats('foo:', .1)

22447

would limit the list to all functions having file names .*foo:,

22448

and then proceed to only print the first 10% of them.</description>

22449

22450

22451

22452

22453

<description>This method for the Stats class prints a list of all functions

22454

that called each function in the profiled database. The ordering is

22455

identical to that provided by print_stats(), and the definition

22456

of the restricting argument is also identical. For convenience, a

22457

number is shown in parentheses after each caller to show how many

22458

times this specific call was made. A second non-parenthesized number

22459

is the cumulative time spent in the function at the right.</description>

22460

22461

22462

22463

22464

<description>This method for the Stats class prints a list of all function

22465

that were called by the indicated function. Aside from this reversal

22466

of direction of calls (re: called vs was called by), the arguments and

22467

ordering are identical to the print_callers() method.</description>

22468

22469

22470

22471

22472

<description>1.5.1{This is not needed in modern versions of

22473

Python.

22474

This was once necessary, when Python would print any unused expression

22475

result that was not None. The method is still defined for

22476

backward compatibility.}</description>

22477

22478

</element>

22479

22480

</group>

22481

</group>

22482

22483

<description>High performance logging profiler, mostly written in C.

22484

New in version 2.2

22485

This module provides a nicer interface to the _hotshot C module.

22486

Hotshot is a replacement for the existing profile module. As it's

22487

written mostly in C, it should result in a much smaller performance impact

22488

than the existing profile module.

22489

</description>

22490

22491

<description>The profiler object. The argument logfile is the name of a log

22492

file to use for logged profile data. The argument lineevents

22493

specifies whether to generate events for every source line, or just on

22494

function call/return. It defaults to 0 (only log function

22495

call/return). The argument linetimings specifies whether to

22496

record timing information. It defaults to 1 (store timing

22497

information).</description>

22498

22499

22500

22501

22502

<description>Profile objects have the following methods:

22503

</description>

22504

22505

<description>Add an arbitrary labelled value to the profile output.</description>

22506

22507

22508

22509

22510

<description>Close the logfile and terminate the profiler.</description>

22511

22512

</element>

22513

22514

22515

<description>Return the file descriptor of the profiler's log file.</description>

22516

22517

</element>

22518

22519

22520

<description>Profile an exec-compatible string in the script environment.

22521

The globals from the __main__ module are used as

22522

both the globals and locals for the script.</description>

22523

22524

22525

22526

22527

<description>Profile a single call of a callable.

22528

Additional positional and keyword arguments may be passed

22529

along; the result of the call is returned, and exceptions are

22530

allowed to propogate cleanly, while ensuring that profiling is

22531

disabled on the way out.</description>

22532

22533

22534

22535

22536

<description>Evaluate an exec-compatible string in a specific environment.

22537

The string is compiled before profiling begins.</description>

22538

22539

22540

22541

22542

<description>Start the profiler.</description>

22543

22544

</element>

22545

22546

22547

<description>Stop the profiler.</description>

22548

22549

</element>

22550

22551

</group>

22552

22553

<description>Statistical analysis for Hotshot

22554

New in version 2.2

22555

This module loads hotshot profiling data into the standard pstats

22556

Stats objects.

22557

</description>

22558

22559

<description>Load hotshot data from filename. Returns an instance

22560

of the pstats.Stats class.</description>

22561

22562

22563

22564

</group>

22565

22566

</group>

22567

</group>

22568

22569

<description>Measure the execution time of small code snippets.

22570

New in version 2.3

22571

</description>

22572

22573

<description>Class for timing execution speed of small code snippets.

22574

The constructor takes a statement to be timed, an additional statement

22575

used for setup, and a timer function. Both statements default to

22576

'pass'; the timer function is platform-dependent (see the

22577

module doc string). The statements may contain newlines, as long as

22578

they don't contain multi-line string literals.

22579

To measure the execution time of the first statement, use the

22580

timeit() method. The repeat() method is a

22581

convenience to call timeit() multiple times and return a list

22582

of results.</description>

22583

22584

<properties><property default="'pass'" kind="parameter" name="stmt" required="1"/><property default="'pass'" kind="parameter" name="setup"/><property default="<timer function>" kind="parameter" name="timer"/></properties></element>

22585

22586

22587

<description>Helper to print a traceback from the timed code.

22588

Typical use:

22589

t = Timer(...) # outside the try/except

22590

try:

22591

t.timeit(...) # or t.repeat(...)

22592

except:

22593

t.print_exc()

22594

The advantage over the standard traceback is that source lines in the

22595

compiled template will be displayed.

22596

The optional file argument directs where the traceback is sent;

22597

it defaults to sys.stderr.</description>

22598

22599

22600

22601

22602

<description>Call timeit() a few times.

22603

This is a convenience function that calls the timeit()

22604

repeatedly, returning a list of results. The first argument specifies

22605

how many times to call timeit(). The second argument

22606

specifies the number argument for timeit().

22607

It's tempting to calculate mean and standard deviation from the result

22608

vector and report these. However, this is not very useful. In a typical

22609

case, the lowest value gives a lower bound for how fast your machine can run

22610

the given code snippet; higher values in the result vector are typically not

22611

caused by variability in Python's speed, but by other processes interfering

22612

with your timing accuracy. So the min() of the result is

22613

probably the only number you should be interested in. After that, you

22614

should look at the entire vector and apply common sense rather than

22615

statistics.

22616

</description>

22617

22618

22619

22620

22621

<description>Time number executions of the main statement.

22622

This executes the setup statement once, and then

22623

returns the time it takes to execute the main statement a number of

22624

times, measured in seconds as a float. The argument is the number of

22625

times through the loop, defaulting to one million. The main

22626

statement, the setup statement and the timer function to be used are

22627

passed to the constructor.</description>

22628

22629

22630

22631

22632

<description>When called as a program from the command line, the following form is used:

22633

python timeit.py [-n N] [-r N] [-s S] [-t] [-c] [-h] [statement ...]

22634

where the following options are understood:

22635

[-n N/number=N] how many times to execute 'statement'

22636

[-r N/repeat=N] how many times to repeat the timer (default 3)

22637

[-s S/setup=S] statement to be executed once initially (default

22638

'pass')

22639

[-t/time] use time.time()

22640

(default on all platforms but Windows)

22641

[-c/clock] use time.clock() (default on Windows)

22642

[-v/verbose] print raw timing results; repeat for more digits

22643

precision

22644

[-h/help] print a short usage message and exit

22645

A multi-line statement may be given by specifying each line as a

22646

separate statement argument; indented lines are possible by enclosing

22647

an argument in quotes and using leading spaces. Multiple

22648

-s options are treated similarly.

22649

If -n is not given, a suitable number of loops is

22650

calculated by trying successive powers of 10 until the total time is

22651

at least 0.2 seconds.

22652

The default timer function is platform dependent. On Windows,

22653

time.clock() has microsecond granularity but

22654

time.time()'s granularity is 1/60th of a second; on ,

22655

time.clock() has 1/100th of a second granularity and

22656

time.time() is much more precise. On either platform, the

22657

default timer functions measure wall clock time, not the CPU time.

22658

This means that other processes running on the same computer may

22659

interfere with the timing. The best thing to do when accurate timing

22660

is necessary is to repeat the timing a few times and use the best

22661

time. The -r option is good for this; the default of 3

22662

repetitions is probably enough in most cases. On , you can use

22663

time.clock() to measure CPU time.

22664

There is a certain baseline overhead associated with executing a

22665

pass statement. The code here doesn't try to hide it, but you

22666

should be aware of it. The baseline overhead can be measured by

22667

invoking the program without arguments.

22668

The baseline overhead differs between Python versions! Also, to

22669

fairly compare older Python versions to Python 2.3, you may want to

22670

use Python's -O option for the older versions to avoid

22671

timing SET_LINENO instructions.

22672

</description>

22673

</group>

22674

22675

</group>

22676

</group>

22677

</group>

22678

22679

22680

<description>Easy-to-use controller for Web browsers.

22681

The webbrowser module provides a very high-level interface to

22682

allow displaying Web-based documents to users. The controller objects

22683

are easy to use and are platform-independent. Under most

22684

circumstances, simply calling the open() function from this

22685

module will do the right thing.

22686

Under , graphical browsers are preferred under X11, but text-mode

22687

browsers will be used if graphical browsers are not available or an X11

22688

display isn't available. If text-mode browsers are used, the calling

22689

process will block until the user exits the browser.

22690

Under , if the environment variable BROWSER exists, it

22691

is interpreted to override the platform default list of browsers, as a

22692

colon-separated list of browsers to try in order. When the value of

22693

a list part contains the string , then it is interpreted as

22694

a literal browser command line to be used with the argument URL

22695

substituted for the ; if the part does not contain

22696

, it is simply interpreted as the name of the browser to

22697

launch.

22698

For non- platforms, or when X11 browsers are available on

22699

, the controlling process will not wait for the user to finish

22700

with the browser, but allow the browser to maintain its own window on

22701

the display.

22702

The following exception is defined:

22703

{Error}

22704

Exception raised when a browser control error occurs.

22705

The following functions are defined:

22706

</description>

22707

22708

<description>Display url using the default browser. If new is true,

22709

a new browser window is opened if possible. If autoraise is

22710

true, the window is raised if possible (note that under many window

22711

managers this will occur regardless of the setting of this variable).</description>

22712

22713

22714

22715

22716

<description>Open url in a new window of the default browser, if possible,

22717

otherwise, open url in the only browser window.</description>

22718

22719

22720

22721

22722

<description>Return a controller object for the browser type name. If

22723

name is empty, return a controller for a default browser

22724

appropriate to the caller's environment.</description>

22725

22726

22727

22728

22729

<description>Register the browser type name. Once a browser type is

22730

registered, the get() function can return a controller

22731

for that browser type. If instance is not provided, or is

22732

None, constructor will be called without parameters to

22733

create an instance when needed. If instance is provided,

22734

constructor will never be called, and may be None.

22735

This entry point is only useful if you plan to either set the

22736

BROWSER variable or call get with a nonempty

22737

argument matching the name of a handler you declare.</description>

22738

22739

22740

22741

22742

<description>Browser controllers provide two methods which parallel two of the

22743

module-level convenience functions:

22744

</description>

22745

22746

<description>Display url using the browser handled by this controller. If

22747

new is true, a new browser window is opened if possible.</description>

22748

22749

22750

22751

22752

<description>Open url in a new window of the browser handled by this

22753

controller, if possible, otherwise, open url in the only

22754

browser window.</description>

22755

22756

22757

22758

</group>

22759

</group>

22760

22761

<description>Common Gateway Interface support, used to interpret

22762

forms in server-side scripts.

22763

</description>

22764

22765

<description>cgi-intro

22766

A CGI script is invoked by an HTTP server, usually to process user

22767

input submitted through an HTML <FORM> or <ISINDEX> element.

22768

Most often, CGI scripts live in the server's special cgi-bin

22769

directory. The HTTP server places all sorts of information about the

22770

request (such as the client's hostname, the requested URL, the query

22771

string, and lots of other goodies) in the script's shell environment,

22772

executes the script, and sends the script's output back to the client.

22773

The script's input is connected to the client too, and sometimes the

22774

form data is read this way; at other times the form data is passed via

22775

the ``query string'' part of the URL. This module is intended

22776

to take care of the different cases and provide a simpler interface to

22777

the Python script. It also provides a number of utilities that help

22778

in debugging scripts, and the latest addition is support for file

22779

uploads from a form (if your browser supports it --- Grail 0.3 and

22780

Netscape 2.0 do).

22781

The output of a CGI script should consist of two sections, separated

22782

by a blank line. The first section contains a number of headers,

22783

telling the client what kind of data is following. Python code to

22784

generate a minimal header section looks like this:

22785

print "Content-Type: text/html" # HTML is following

22786

print # blank line, end of headers

22787

The second section is usually HTML, which allows the client software

22788

to display nicely formatted text with header, in-line images, etc.

22789

Here's Python code that prints a simple piece of HTML:

22790

print "<TITLE>CGI script output</TITLE>"

22791

print "<H1>This is my first CGI script</H1>"

22792

print "Hello, world!"

22793

</description>

22794

</group>

22795

22796

<description>Using the cgi module

22797

Begin by writing import cgi. Do not use from cgi import

22798

* --- the module defines all sorts of names for its own use or for

22799

backward compatibility that you don't want in your namespace.

22800

When you write a new script, consider adding the line:

22801

import cgitb; cgitb.enable()

22802

This activates a special exception handler that will display detailed

22803

reports in the Web browser if any errors occur. If you'd rather not

22804

show the guts of your program to users of your script, you can have

22805

the reports saved to files instead, with a line like this:

22806

import cgitb; cgitb.enable(display=0, logdir="/tmp")

22807

It's very helpful to use this feature during script development.

22808

The reports produced by cgitb provide information that

22809

can save you a lot of time in tracking down bugs. You can always

22810

remove the cgitb line later when you have tested your script

22811

and are confident that it works correctly.

22812

To get at submitted form data,

22813

it's best to use the FieldStorage class. The other classes

22814

defined in this module are provided mostly for backward compatibility.

22815

Instantiate it exactly once, without arguments. This reads the form

22816

contents from standard input or the environment (depending on the

22817

value of various environment variables set according to the CGI

22818

standard). Since it may consume standard input, it should be

22819

instantiated only once.

22820

The FieldStorage instance can be indexed like a Python

22821

dictionary, and also supports the standard dictionary methods

22822

has_key() and keys(). The built-in len()

22823

is also supported. Form fields containing empty strings are ignored

22824

and do not appear in the dictionary; to keep such values, provide

22825

a true value for the optional keep_blank_values keyword

22826

parameter when creating the FieldStorage instance.

22827

For instance, the following code (which assumes that the Content-Type header and blank line have already been

22828

printed) checks that the fields name and addr are both

22829

set to a non-empty string:

22830

form = cgi.FieldStorage()

22831

if not (form.has_key("name") and form.has_key("addr")):

22832

print "<H1>Error</H1>"

22833

print "Please fill in the name and addr fields."

22834

return

22835

print "<p>name:", form["name"].value

22836

print "<p>addr:", form["addr"].value

22837

...further form processing here...

22838

Here the fields, accessed through form[key], are

22839

themselves instances of FieldStorage (or

22840

MiniFieldStorage, depending on the form encoding).

22841

The value attribute of the instance yields the string value

22842

of the field. The getvalue() method returns this string value

22843

directly; it also accepts an optional second argument as a default to

22844

return if the requested key is not present.

22845

If the submitted form data contains more than one field with the same

22846

name, the object retrieved by form[key] is not a

22847

FieldStorage or MiniFieldStorage

22848

instance but a list of such instances. Similarly, in this situation,

22849

form.getvalue(key) would return a list of strings.

22850

If you expect this possibility

22851

(when your HTML form contains multiple fields with the same name), use

22852

the isinstance() built-in function to determine whether you

22853

have a single instance or a list of instances. For example, this

22854

code concatenates any number of username fields, separated by

22855

commas:

22856

value = form.getvalue("username", "")

22857

if isinstance(value, list):

22858

# Multiple username fields specified

22859

usernames = ",".join(value)

22860

else:

22861

# Single or no username field specified

22862

usernames = value

22863

If a field represents an uploaded file, accessing the value via the

22864

value attribute or the getvalue() method reads the

22865

entire file in memory as a string. This may not be what you want.

22866

You can test for an uploaded file by testing either the filename

22867

attribute or the file attribute. You can then read the data at

22868

leisure from the file attribute:

22869

fileitem = form["userfile"]

22870

if fileitem.file:

22871

# It's an uploaded file; count lines

22872

linecount = 0

22873

while 1:

22874

line = fileitem.file.readline()

22875

if not line: break

22876

linecount = linecount + 1

22877

The file upload draft standard entertains the possibility of uploading

22878

multiple files from one field (using a recursive

22879

multipart/* encoding). When this occurs, the item will be

22880

a dictionary-like FieldStorage item. This can be determined

22881

by testing its type attribute, which should be

22882

multipart/form-data (or perhaps another MIME type matching

22883

multipart/*). In this case, it can be iterated over

22884

recursively just like the top-level form object.

22885

When a form is submitted in the ``old'' format (as the query string or

22886

as a single data part of type

22887

application/x-www-form-urlencoded), the items will actually

22888

be instances of the class MiniFieldStorage. In this case, the

22889

list, file, and filename attributes are

22890

always None.

22891

</description>

22892

</group>

22893

22894

<description>New in version 2.2 % XXX: Is this true ? The previous section explains how to read CGI form data using the

22895

FieldStorage class. This section describes a higher level

22896

interface which was added to this class to allow one to do it in a

22897

more readable and intuitive way. The interface doesn't make the

22898

techniques described in previous sections obsolete --- they are still

22899

useful to process file uploads efficiently, for example.

22900

The interface consists of two simple methods. Using the methods

22901

you can process form data in a generic way, without the need to worry

22902

whether only one or more values were posted under one name.

22903

In the previous section, you learned to write following code anytime

22904

you expected a user to post more than one value under one name:

22905

item = form.getvalue("item")

22906

if isinstance(item, list):

22907

# The user is requesting more than one item.

22908

else:

22909

# The user is requesting only one item.

22910

This situation is common for example when a form contains a group of

22911

multiple checkboxes with the same name:

22912

22913

22914

In most situations, however, there's only one form control with a

22915

particular name in a form and then you expect and need only one value

22916

associated with this name. So you write a script containing for

22917

example this code:

22918

user = form.getvalue("user").toupper()

22919

The problem with the code is that you should never expect that a

22920

client will provide valid input to your scripts. For example, if a

22921

curious user appends another user=foo pair to the query string,

22922

then the script would crash, because in this situation the

22923

getvalue("user") method call returns a list instead of a

22924

string. Calling the toupper() method on a list is not valid

22925

(since lists do not have a method of this name) and results in an

22926

AttributeError exception.

22927

Therefore, the appropriate way to read form data values was to always

22928

use the code which checks whether the obtained value is a single value

22929

or a list of values. That's annoying and leads to less readable

22930

scripts.

22931

A more convenient approach is to use the methods getfirst()

22932

and getlist() provided by this higher level interface.

22933

</description>

22934

22935

<description>Thin method always returns only one value associated with form field

22936

name. The method returns only the first value in case that

22937

more values were posted under such name. Please note that the order

22938

in which the values are received may vary from browser to browser

22939

and should not be counted on.Note that some recent

22940

versions of the HTML specification do state what order the

22941

field values should be supplied in, but knowing whether a

22942

request was received from a conforming browser, or even from a

22943

browser at all, is tedious and error-prone. If no such form

22944

field or value exists then the method returns the value specified by

22945

the optional parameter default. This parameter defaults to

22946

None if not specified.</description>

22947

22948

22949

22950

22951

<description>This method always returns a list of values associated with form

22952

field name. The method returns an empty list if no such form

22953

field or value exists for name. It returns a list consisting

22954

of one item if only one such value exists.</description>

22955

22956

22957

22958

</group>

22959

22960

<description>These classes, present in earlier versions of the cgi module,

22961

are still supported for backward compatibility. New applications

22962

should use the FieldStorage class.

22963

SvFormContentDict stores single value form content as

22964

dictionary; it assumes each field name occurs in the form only once.

22965

FormContentDict stores multiple value form content as a

22966

dictionary (the form items are lists of values). Useful if your form

22967

contains multiple fields with the same name.

22968

Other classes (FormContent, InterpFormContentDict) are

22969

present for backwards compatibility with really old applications only.

22970

If you still use these and would be inconvenienced when they

22971

disappeared from a next version of this module, drop me a note.

22972

</description>

22973

</group>

22974

22975

<description>Functions in cgi module

22976

These are useful if you want more control, or if you want to employ

22977

some of the algorithms implemented in this module in other

22978

circumstances.

22979

</description>

22980

22981

<description>Parse a query in the environment or from a file (the file defaults

22982

to sys.stdin). The keep_blank_values and

22983

strict_parsing parameters are passed to parse_qs()

22984

unchanged.</description>

22985

22986

22987

22988

22989

<description>Parse a query string given as a string argument (data of type application/x-www-form-urlencoded). Data are

22990

returned as a dictionary. The dictionary keys are the unique query

22991

variable names and the values are lists of values for each name.

22992

The optional argument keep_blank_values is

22993

a flag indicating whether blank values in

22994

URL encoded queries should be treated as blank strings. A true value indicates that blanks should be retained as blank strings. The default false value indicates that

22995

blank values are to be ignored and treated as if they were

22996

not included.

22997

The optional argument strict_parsing is a flag indicating what

22998

to do with parsing errors. If false (the default), errors

22999

are silently ignored. If true, errors raise a ValueError

23000

exception.

23001

Use the urllib.urlencode() function to convert

23002

such dictionaries into query strings.</description>

23003

23004

23005

23006

23007

<description>Parse a query string given as a string argument (data of type application/x-www-form-urlencoded). Data are

23008

returned as a list of name, value pairs.

23009

The optional argument keep_blank_values is

23010

a flag indicating whether blank values in

23011

URL encoded queries should be treated as blank strings. A true value indicates that blanks should be retained as blank strings. The default false value indicates that

23012

blank values are to be ignored and treated as if they were

23013

not included.

23014

The optional argument strict_parsing is a flag indicating what

23015

to do with parsing errors. If false (the default), errors

23016

are silently ignored. If true, errors raise a ValueError

23017

exception.

23018

Use the urllib.urlencode() function to convert

23019

such lists of pairs into query strings.</description>

23020

23021

23022

23023

23024

<description>Parse input of type multipart/form-data (for file uploads). Arguments are fp for the input file and

23025

pdict for a dictionary containing other parameters in

23026

the Content-Type header.

23027

Returns a dictionary just like parse_qs() keys are the

23028

field names, each value is a list of values for that field. This is

23029

easy to use but not much good if you are expecting megabytes to be

23030

uploaded --- in that case, use the FieldStorage class instead

23031

which is much more flexible.

23032

Note that this does not parse nested multipart parts --- use

23033

FieldStorage for that.</description>

23034

23035

23036

23037

23038

<description>Parse a MIME header (such as Content-Type) into a main

23039

value and a dictionary of parameters.</description>

23040

23041

23042

23043

23044

<description>Robust test CGI script, usable as main program.

23045

Writes minimal HTTP headers and formats all information provided to

23046

the script in HTML form.</description>

23047

23048

</element>

23049

23050

23051

<description>Format the shell environment in HTML.</description>

23052

23053

</element>

23054

23055

23056

<description>Format a form in HTML.</description>

23057

23058

23059

23060

23061

<description>Format the current directory in HTML.</description>

23062

23063

</element>

23064

23065

23066

<description>Print a list of useful (used by CGI) environment variables in

23067

HTML.</description>

23068

23069

</element>

23070

23071

23072

<description>Convert the characters

23073

&, < and > in string s to

23074

HTML-safe sequences. Use this if you need to display text that might

23075

contain such characters in HTML. If the optional flag quote is

23076

true, the double-quote character (") is also translated;

23077

this helps for inclusion in an HTML attribute value, as in <A

23078

HREF="...">. If the value to be quoted might include single- or

23079

double-quote characters, or both, consider using the

23080

quoteattr() function in the xml.sax.saxutils

23081

module instead.</description>

23082

23083

23084

23085

</group>

23086

23087

<description>There's one important rule: if you invoke an external program (via the

23088

os.system() or os.popen() functions. or others

23089

with similar functionality), make very sure you don't pass arbitrary

23090

strings received from the client to the shell. This is a well-known

23091

security hole whereby clever hackers anywhere on the Web can exploit a

23092

gullible CGI script to invoke arbitrary shell commands. Even parts of

23093

the URL or field names cannot be trusted, since the request doesn't

23094

have to come from your form!

23095

To be on the safe side, if you must pass a string gotten from a form

23096

to a shell command, you should make sure the string contains only

23097

alphanumeric characters, dashes, underscores, and periods.

23098

</description>

23099

</group>

23100

23101

<description>Read the documentation for your HTTP server and check with your local

23102

system administrator to find the directory where CGI scripts should be

23103

installed; usually this is in a directory cgi-bin in the server tree.

23104

Make sure that your script is readable and executable by ``others''; the

23105

file mode should be 0755 octal (use chmod 0755

23106

filename). Make sure that the first line of the script contains

23107

! starting in column 1 followed by the pathname of the Python

23108

interpreter, for instance:

23109

#!/usr/local/bin/python

23110

Make sure the Python interpreter exists and is executable by ``others''.

23111

Make sure that any files your script needs to read or write are

23112

readable or writable, respectively, by ``others'' --- their mode

23113

should be 0644 for readable and 0666 for writable. This

23114

is because, for security reasons, the HTTP server executes your script

23115

as user ``nobody'', without any special privileges. It can only read

23116

(write, execute) files that everybody can read (write, execute). The

23117

current directory at execution time is also different (it is usually

23118

the server's cgi-bin directory) and the set of environment variables

23119

is also different from what you get when you log in. In particular, don't

23120

count on the shell's search path for executables (PATH) or

23121

the Python module search path (PYTHONPATH) to be set to

23122

anything interesting.

23123

If you need to load modules from a directory which is not on Python's

23124

default module search path, you can change the path in your script,

23125

before importing other modules. For example:

23126

import sys

23127

sys.path.insert(0, "/usr/home/joe/lib/python")

23128

sys.path.insert(0, "/usr/local/lib/python")

23129

(This way, the directory inserted last will be searched first!)

23130

Instructions for non- systems will vary; check your HTTP server's

23131

documentation (it will usually have a section on CGI scripts).

23132

</description>

23133

</group>

23134

23135

<description>Unfortunately, a CGI script will generally not run when you try it

23136

from the command line, and a script that works perfectly from the

23137

command line may fail mysteriously when run from the server. There's

23138

one reason why you should still test your script from the command

23139

line: if it contains a syntax error, the Python interpreter won't

23140

execute it at all, and the HTTP server will most likely send a cryptic

23141

error to the client.

23142

Assuming your script has no syntax errors, yet it does not work, you

23143

have no choice but to read the next section.

23144

</description>

23145

</group>

23146

23147

<description>First of all, check for trivial installation errors --- reading the

23148

section above on installing your CGI script carefully can save you a

23149

lot of time. If you wonder whether you have understood the

23150

installation procedure correctly, try installing a copy of this module

23151

file (cgi.py) as a CGI script. When invoked as a script, the file

23152

will dump its environment and the contents of the form in HTML form.

23153

Give it the right mode etc, and send it a request. If it's installed

23154

in the standard cgi-bin directory, it should be possible to send it a

23155

request by entering a URL into your browser of the form:

23156

http://yourhostname/cgi-bin/cgi.py?name=Joe+Blow&addr=At+Home

23157

If this gives an error of type 404, the server cannot find the script

23158

-- perhaps you need to install it in a different directory. If it

23159

gives another error, there's an installation problem that

23160

you should fix before trying to go any further. If you get a nicely

23161

formatted listing of the environment and form content (in this

23162

example, the fields should be listed as ``addr'' with value ``At Home''

23163

and ``name'' with value ``Joe Blow''), the cgi.py script has been

23164

installed correctly. If you follow the same procedure for your own

23165

script, you should now be able to debug it.

23166

The next step could be to call the cgi module's

23167

test() function from your script: replace its main code

23168

with the single statement

23169

cgi.test()

23170

This should produce the same results as those gotten from installing

23171

the cgi.py file itself.

23172

When an ordinary Python script raises an unhandled exception (for

23173

whatever reason: of a typo in a module name, a file that can't be

23174

opened, etc.), the Python interpreter prints a nice traceback and

23175

exits. While the Python interpreter will still do this when your CGI

23176

script raises an exception, most likely the traceback will end up in

23177

one of the HTTP server's log files, or be discarded altogether.

23178

Fortunately, once you have managed to get your script to execute

23179

some code, you can easily send tracebacks to the Web browser

23180

using the cgitb module. If you haven't done so already,

23181

just add the line:

23182

import cgitb; cgitb.enable()

23183

to the top of your script. Then try running it again; when a

23184

problem occurs, you should see a detailed report that will

23185

likely make apparent the cause of the crash.

23186

If you suspect that there may be a problem in importing the

23187

cgitb module, you can use an even more robust approach

23188

(which only uses built-in modules):

23189

import sys

23190

sys.stderr = sys.stdout

23191

print "Content-Type: text/plain"

23192

print

23193

...your code here...

23194

This relies on the Python interpreter to print the traceback. The

23195

content type of the output is set to plain text, which disables all

23196

HTML processing. If your script works, the raw HTML will be displayed

23197

by your client. If it raises an exception, most likely after the

23198

first two lines have been printed, a traceback will be displayed.

23199

Because no HTML interpretation is going on, the traceback will be

23200

readable.

23201

</description>

23202

</group>

23203

23204

</group>

23205

</group>

23206

23207

<description>Configurable traceback handler for CGI scripts.

23208

New in version 2.2

23209

</description>

23210

23211

<description>This function causes the cgitb module to take over the

23212

interpreter's default handling for exceptions by setting the

23213

value of sys.excepthook.

23214

(in module sys){excepthook()}

23215

The optional argument display defaults to 1 and can be set

23216

to 0 to suppress sending the traceback to the browser.

23217

If the argument logdir is present, the traceback reports are

23218

written to files. The value of logdir should be a directory

23219

where these files will be placed.

23220

The optional argument context is the number of lines of

23221

context to display around the current line of source code in the

23222

traceback; this defaults to 5.

23223

If the optional argument format is "html", the output is

23224

formatted as HTML. Any other value forces plain text output. The default

23225

value is "html".</description>

23226

23227

23228

23229

23230

<description>This function handles an exception using the default settings

23231

(that is, show a report in the browser, but don't log to a file).

23232

This can be used when you've caught an exception and want to

23233

report it using cgitb. The optional info argument

23234

should be a 3-tuple containing an exception type, exception

23235

value, and traceback object, exactly like the tuple returned by

23236

sys.exc_info(). If the info argument

23237

is not supplied, the current exception is obtained from

23238

sys.exc_info().</description>

23239

23240

23241

23242

</group>

23243

23244

<description>Open an arbitrary network resource by URL (requires sockets).

23245

</description>

23246

23247

<description>Open a network object denoted by a URL for reading. If the URL does

23248

not have a scheme identifier, or if it has file: as its scheme

23249

identifier, this opens a local file (without universal newlines);

23250

otherwise it opens a socket to a server somewhere on the network. If

23251

the connection cannot be made, or if the server returns an error code,

23252

the IOError exception is raised. If all went well, a

23253

file-like object is returned. This supports the following methods:

23254

read(), readline(), readlines(), fileno(),

23255

close(), info() and geturl(). It also has

23256

proper support for the iterator protocol.

23257

Except for the info() and geturl() methods,

23258

these methods have the same interface as for

23259

file objects --- see section bltin-file-objects in this

23260

manual. (It is not a built-in file object, however, so it can't be

23261

used at those few places where a true built-in file object is

23262

required.)

23263

The info() method returns an instance of the class

23264

mimetools.Message containing meta-information associated

23265

with the URL. When the method is HTTP, these headers are those

23266

returned by the server at the head of the retrieved HTML page

23267

(including Content-Length and Content-Type). When the method is FTP,

23268

a Content-Length header will be present if (as is now usual) the

23269

server passed back a file length in response to the FTP retrieval

23270

request. A Content-Type header will be present if the MIME type can

23271

be guessed. When the method is local-file, returned headers will include

23272

a Date representing the file's last-modified time, a Content-Length

23273

giving file size, and a Content-Type containing a guess at the file's

23274

type. See also the description of the

23275

mimetoolsmimetools module.

23276

The geturl() method returns the real URL of the page. In

23277

some cases, the HTTP server redirects a client to another URL. The

23278

urlopen() function handles this transparently, but in some

23279

cases the caller needs to know which URL the client was redirected

23280

to. The geturl() method can be used to get at this

23281

redirected URL.

23282

If the url uses the http: scheme identifier, the optional

23283

data argument may be given to specify a POST request

23284

(normally the request type is GET). The data argument

23285

must be in standard application/x-www-form-urlencoded format;

23286

see the urlencode() function below.

23287

The urlopen() function works transparently with proxies

23288

which do not require authentication. In a or Windows

23289

environment, set the http_proxy, ftp_proxy or

23290

gopher_proxy environment variables to a URL that identifies

23291

the proxy server before starting the Python interpreter. For example

23292

(the % is the command prompt):

23293

% http_proxy="http://www.someproxy.com:3128"

23294

% export http_proxy

23295

% python

23296

...

23297

In a Windows environment, if no proxy environment variables are set,

23298

proxy settings are obtained from the registry's Internet Settings

23299

section.

23300

In a Macintosh environment, urlopen() will retrieve proxy

23301

information from Internet</description>

23302

23303

23304

23305

23306

<description>Copy a network object denoted by a URL to a local file, if necessary.

23307

If the URL points to a local file, or a valid cached copy of the

23308

object exists, the object is not copied. Return a tuple

23309

(filename, headers) where filename is the

23310

local file name under which the object can be found, and headers

23311

is whatever the info() method of the object returned by

23312

urlopen() returned (for a remote object, possibly cached).

23313

Exceptions are the same as for urlopen().

23314

The second argument, if present, specifies the file location to copy

23315

to (if absent, the location will be a tempfile with a generated name).

23316

The third argument, if present, is a hook function that will be called

23317

once on establishment of the network connection and once after each

23318

block read thereafter. The hook will be passed three arguments; a

23319

count of blocks transferred so far, a block size in bytes, and the

23320

total size of the file. The third argument may be -1 on older

23321

FTP servers which do not return a file size in response to a retrieval

23322

request.

23323

If the url uses the http: scheme identifier, the optional

23324

data argument may be given to specify a POST request

23325

(normally the request type is GET). The data argument

23326

must in standard application/x-www-form-urlencoded format;

23327

see the urlencode() function below.</description>

23328

23329

23330

23331

23332

<description>Clear the cache that may have been built up by previous calls to

23333

urlretrieve().</description>

23334

23335

</element>

23336

23337

23338

<description>Replace special characters in string using the escape.

23339

Letters, digits, and the characters _.- are never quoted.

23340

The optional safe parameter specifies additional characters

23341

that should not be quoted --- its default value is '/'.

23342

Example: quote('//') yields '/%7econnolly/'.</description>

23343

23344

23345

23346

23347

<description>Like quote(), but also replaces spaces by plus signs, as

23348

required for quoting HTML form values. Plus signs in the original

23349

string are escaped unless they are included in safe. It also

23350

does not have safe default to '/'.</description>

23351

23352

23353

23354

23355

<description>Replace escapes by their single-character equivalent.

23356

Example: unquote('/%7Econnolly/') yields '//'.</description>

23357

23358

23359

23360

23361

<description>Like unquote(), but also replaces plus signs by spaces, as

23362

required for unquoting HTML form values.</description>

23363

23364

23365

23366

23367

<description>Convert a mapping object or a sequence of two-element tuples to a

23368

``url-encoded'' string, suitable to pass to

23369

urlopen() above as the optional data argument. This

23370

is useful to pass a dictionary of form fields to a POST

23371

request. The resulting string is a series of

23372

key=value pairs separated by &

23373

characters, where both key and value are quoted using

23374

quote_plus() above. If the optional parameter doseq is

23375

present and evaluates to true, individual key=value pairs

23376

are generated for each element of the sequence.

23377

When a sequence of two-element tuples is used as the query argument,

23378

the first element of each tuple is a key and the second is a value. The

23379

order of parameters in the encoded string will match the order of parameter

23380

tuples in the sequence.

23381

The cgi module provides the functions

23382

parse_qs() and parse_qsl() which are used to

23383

parse query strings into Python data structures.</description>

23384

23385

23386

23387

23388

<description>Convert the pathname path from the local syntax for a path to

23389

the form used in the path component of a URL. This does not produce a

23390

complete URL. The return value will already be quoted using the

23391

quote() function.</description>

23392

23393

23394

23395

23396

<description>Convert the path component path from an encoded URL to the local

23397

syntax for a path. This does not accept a complete URL. This

23398

function uses unquote() to decode path.</description>

23399

23400

23401

23402

23403

<description>Base class for opening and reading URLs. Unless you need to support

23404

opening objects using schemes other than http:, ftp:,

23405

gopher: or file:, you probably want to use

23406

FancyURLopener.

23407

By default, the URLopener class sends a

23408

User-Agent header of urllib/VVV, where

23409

VVV is the urllib version number. Applications can

23410

define their own User-Agent header by subclassing

23411

URLopener or FancyURLopener and setting the instance

23412

attribute version to an appropriate string value before the

23413

open() method is called.

23414

The optional proxies parameter should be a dictionary mapping

23415

scheme names to proxy URLs, where an empty dictionary turns proxies

23416

off completely. Its default value is None, in which case

23417

environmental proxy settings will be used if present, as discussed in

23418

the definition of urlopen(), above.

23419

Additional keyword parameters, collected in x509, are used for

23420

authentication with the https: scheme. The keywords

23421

key_file and cert_file are supported; both are needed to

23422

actually retrieve a resource at an https: URL.</description>

23423

23424

23425

23426

23427

<description>FancyURLopener subclasses URLopener providing default

23428

handling for the following HTTP response codes: 301, 302, 303, 307 and

23429

401. For the 30x response codes listed above, the

23430

Location header is used to fetch the actual URL. For 401

23431

response codes (authentication required), basic HTTP authentication is

23432

performed. For the 30x response codes, recursion is bounded by the

23433

value of the maxtries attribute, which defaults to 10.

23434

According to the letter of 2616, 301 and 302 responses to

23435

POST requests must not be automatically redirected without

23436

confirmation by the user. In reality, browsers do allow automatic

23437

redirection of these responses, changing the POST to a GET, and

23438

urllib reproduces this behaviour.

23439

The parameters to the constructor are the same as those for

23440

URLopener.

23441

When performing basic authentication, a

23442

FancyURLopener instance calls its

23443

prompt_user_passwd() method. The default implementation asks

23444

the users for the required information on the controlling terminal. A

23445

subclass may override this method to support more appropriate behavior

23446

if needed.</description>

23447

23448

23449

23450

23451

<description>URLopener and FancyURLopener objects have the

23452

following attributes.

23453

</description>

23454

23455

<description>Open fullurl using the appropriate protocol. This method sets

23456

up cache and proxy information, then calls the appropriate open method with

23457

its input arguments. If the scheme is not recognized,

23458

open_unknown() is called. The data argument

23459

has the same meaning as the data argument of urlopen().</description>

23460

23461

23462

23463

23464

<description>Overridable interface to open unknown URL types.</description>

23465

23466

23467

23468

23469

<description>Retrieves the contents of url and places it in filename. The

23470

return value is a tuple consisting of a local filename and either a

23471

mimetools.Message object containing the response headers (for remote

23472

URLs) or None (for local URLs). The caller must then open and read the

23473

contents of filename. If filename is not given and the URL

23474

refers to a local file, the input filename is returned. If the URL is

23475

non-local and filename is not given, the filename is the output of

23476

tempfile.mktemp() with a suffix that matches the suffix of the last

23477

path component of the input URL. If reporthook is given, it must be

23478

a function accepting three numeric parameters. It will be called after each

23479

chunk of data is read from the network. reporthook is ignored for

23480

local URLs.

23481

If the url uses the http: scheme identifier, the optional

23482

data argument may be given to specify a POST request

23483

(normally the request type is GET). The data argument

23484

must in standard application/x-www-form-urlencoded format;

23485

see the urlencode() function below.</description>

23486

23487

23488

23489

23490

<description>Return information needed to authenticate the user at the given host

23491

in the specified security realm. The return value should be a tuple,

23492

(user, password), which can be used for basic

23493

authentication.

23494

The implementation prompts for this information on the terminal; an

23495

application should override this method to use an appropriate

23496

interaction model in the local environment.</description>

23497

23498

23499

23500

</group>

23501

23502

</group>

23503

</group>

23504

23505

<description>An extensible library for opening URLs using a variety of protocols

23506

The urllib2 module defines functions and classes which help

23507

in opening URLs (mostly HTTP) in a complex world --- basic and digest

23508

authentication, redirections and more.

23509

The urllib2 module defines the following functions:

23510

</description>

23511

23512

<description>Open the URL url, which can be either a string or a Request

23513

object (currently the code checks that it really is a Request

23514

instance, or an instance of a subclass of Request).

23515

data should be a string, which specifies additional data to

23516

send to the server. In HTTP requests, which are the only ones that

23517

support data, it should be a buffer in the format of

23518

application/x-www-form-urlencoded, for example one returned

23519

from urllib.urlencode().

23520

This function returns a file-like object with two additional methods:

23521

geturl() --- return the URL of the resource retrieved

23522

info() --- return the meta-information of the page, as

23523

a dictionary-like object

23524

Raises URLError on errors.</description>

23525

23526

23527

23528

23529

<description>Install an OpenerDirector instance as the default opener.

23530

The code does not check for a real OpenerDirector, and any

23531

class with the appropriate interface will work.</description>

23532

23533

23534

23535

23536

<description>Return an OpenerDirector instance, which chains the

23537

handlers in the order given. handlers can be either instances

23538

of BaseHandler, or subclasses of BaseHandler (in

23539

which case it must be possible to call the constructor without

23540

any parameters). Instances of the following classes will be in

23541

front of the handlers, unless the handlers contain

23542

them, instances of them or subclasses of them:

23543

ProxyHandler, UnknownHandler, HTTPHandler,

23544

HTTPDefaultErrorHandler, HTTPRedirectHandler,

23545

FTPHandler, FileHandler, HTTPErrorProcessor.

23546

If the Python installation has SSL support (socket.ssl()

23547

exists), HTTPSHandler will also be added.

23548

Beginning in Python 2.3, a BaseHandler subclass may also

23549

change its handler_order member variable to modify its

23550

position in the handlers list. Besides ProxyHandler, which has

23551

handler_order of 100, all handlers currently have it

23552

set to 500.</description>

23553

23554

23555

23556

23557

<description>This class is an abstraction of a URL request.

23558

url should be a string which is a valid URL. For a description

23559

of data see the add_data() description.

23560

headers should be a dictionary, and will be treated as if

23561

add_header() was called with each key and value as arguments.</description>

23562

23563

23564

23565

23566

<description>The OpenerDirector class opens URLs via BaseHandlers

23567

chained together. It manages the chaining of handlers, and recovery

23568

from errors.</description>

23569

23570

</element>

23571

23572

23573

<description>This is the base class for all registered handlers --- and handles only

23574

the simple mechanics of registration.</description>

23575

23576

</element>

23577

23578

23579

<description>A class which defines a default handler for HTTP error responses; all

23580

responses are turned into HTTPError exceptions.</description>

23581

23582

</element>

23583

23584

23585

<description>A class to handle redirections.</description>

23586

23587

</element>

23588

23589

23590

<description>Cause requests to go through a proxy.

23591

If proxies is given, it must be a dictionary mapping

23592

protocol names to URLs of proxies.

23593

The default is to read the list of proxies from the environment

23594

variables protocol_proxy.</description>

23595

23596

23597

23598

23599

<description>Keep a database of (realm, uri) -> (user, password)

23600

mappings.</description>

23601

23602

</element>

23603

23604

23605

<description>Keep a database of (realm, uri) -> (user, password) mappings.

23606

A realm of None is considered a catch-all realm, which is searched

23607

if no other realm fits.</description>

23608

23609

</element>

23610

23611

23612

<description>This is a mixin class that helps with HTTP authentication, both

23613

to the remote host and to a proxy.

23614

password_mgr, if given, should be something that is compatible

23615

with HTTPPasswordMgr; refer to section~http-password-mgr

23616

for information on the interface that must be supported.</description>

23617

23618

23619

23620

23621

<description>Handle authentication with the remote host.

23622

password_mgr, if given, should be something that is compatible

23623

with HTTPPasswordMgr; refer to section~http-password-mgr

23624

for information on the interface that must be supported.</description>

23625

23626

23627

23628

23629

<description>Handle authentication with the proxy.

23630

password_mgr, if given, should be something that is compatible

23631

with HTTPPasswordMgr; refer to section~http-password-mgr

23632

for information on the interface that must be supported.</description>

23633

23634

23635

23636

23637

<description>This is a mixin class that helps with HTTP authentication, both

23638

to the remote host and to a proxy.

23639

password_mgr, if given, should be something that is compatible

23640

with HTTPPasswordMgr; refer to section~http-password-mgr

23641

for information on the interface that must be supported.</description>

23642

23643

23644

23645

23646

<description>Handle authentication with the remote host.

23647

password_mgr, if given, should be something that is compatible

23648

with HTTPPasswordMgr; refer to section~http-password-mgr

23649

for information on the interface that must be supported.</description>

23650

23651

23652

23653

23654

<description>Handle authentication with the proxy.

23655

password_mgr, if given, should be something that is compatible

23656

with HTTPPasswordMgr; refer to section~http-password-mgr

23657

for information on the interface that must be supported.</description>

23658

23659

23660

23661

23662

<description>A class to handle opening of HTTP URLs.</description>

23663

23664

</element>

23665

23666

23667

<description>A class to handle opening of HTTPS URLs.</description>

23668

23669

</element>

23670

23671

23672

<description>Open local files.</description>

23673

23674

</element>

23675

23676

23677

23678

23679

</element>

23680

23681

23682

<description>Open FTP URLs, keeping a cache of open FTP connections to minimize

23683

delays.</description>

23684

23685

</element>

23686

23687

23688

<description>Open gopher URLs.</description>

23689

23690

</element>

23691

23692

23693

<description>A catch-all class to handle unknown URLs.</description>

23694

23695

</element>

23696

23697

23698

<description>The following methods describe all of Request's public interface,

23699

and so all must be overridden in subclasses.

23700

</description>

23701

23702

<description>Set the Request data to data. This is ignored

23703

by all handlers except HTTP handlers --- and there it should be an

23704

application/x-www-form-encoded buffer, and will change the

23705

request to be POST rather than GET.</description>

23706

23707

23708

23709

23710

<description>Return a string indicating the HTTP request method. This is only

23711

meaningful for HTTP requests, and currently always takes one of the

23712

values ("GET", "POST").</description>

23713

23714

</element>

23715

23716

23717

<description>Return whether the instance has a non-None data.</description>

23718

23719

</element>

23720

23721

23722

<description>Return the instance's data.</description>

23723

23724

</element>

23725

23726

23727

<description>Add another header to the request. Headers are currently ignored by

23728

all handlers except HTTP handlers, where they are added to the list

23729

of headers sent to the server. Note that there cannot be more than

23730

one header with the same name, and later calls will overwrite

23731

previous calls in case the key collides. Currently, this is

23732

no loss of HTTP functionality, since all headers which have meaning

23733

when used more than once have a (header-specific) way of gaining the

23734

same functionality using only one header.</description>

23735

23736

23737

23738

23739

<description>Add a header that will not be added to a redirected request.</description>

23740

23741

23742

23743

23744

<description>Return whether the instance has the named header (checks both regular

23745

and unredirected).</description>

23746

23747

23748

23749

23750

<description>Return the URL given in the constructor.</description>

23751

23752

</element>

23753

23754

23755

<description>Return the type of the URL --- also known as the scheme.</description>

23756

23757

</element>

23758

23759

23760

<description>Return the host to which a connection will be made.</description>

23761

23762

</element>

23763

23764

23765

<description>Return the selector --- the part of the URL that is sent to

23766

the server.</description>

23767

23768

</element>

23769

23770

23771

<description>Prepare the request by connecting to a proxy server. The host

23772

and type will replace those of the instance, and the instance's

23773

selector will be the original URL given in the constructor.</description>

23774

23775

23776

23777

</group>

23778

23779

<description>OpenerDirector instances have the following methods:

23780

</description>

23781

23782

<description>handler should be an instance of BaseHandler. The

23783

following methods are searched, and added to the possible chains.

23784

protocol_open() ---

23785

signal that the handler knows how to open protocol URLs.

23786

protocol_error_type() ---

23787

signal that the handler knows how to handle type errors from

23788

protocol.

23789

protocol_request() ---

23790

signal that the handler knows how to pre-process protocol

23791

requests.

23792

protocol_response() ---

23793

signal that the handler knows how to post-process protocol

23794

responses.

23795

</description>

23796

23797

23798

23799

23800

<description>Explicitly break cycles, and delete all the handlers.

23801

Because the OpenerDirector needs to know the registered handlers,

23802

and a handler needs to know who the OpenerDirector who called

23803

it is, there is a reference cycle. Even though recent versions of Python

23804

have cycle-collection, it is sometimes preferable to explicitly break

23805

the cycles.</description>

23806

23807

</element>

23808

23809

23810

<description>Open the given url (which can be a request object or a string),

23811

optionally passing the given data.

23812

Arguments, return values and exceptions raised are the same as those

23813

of urlopen() (which simply calls the open() method

23814

on the default installed OpenerDirector).</description>

23815

23816

23817

23818

23819

<description>Handle an error in a given protocol. This will call the registered

23820

error handlers for the given protocol with the given arguments (which

23821

are protocol specific). The HTTP protocol is a special case which

23822

uses the HTTP response code to determine the specific error handler;

23823

refer to the http_error_*() methods of the handler classes.

23824

Return values and exceptions raised are the same as those

23825

of urlopen().</description>

23826

23827

23828

23829

</group>

23830

23831

<description>BaseHandler objects provide a couple of methods that are

23832

directly useful, and others that are meant to be used by derived

23833

classes. These are intended for direct use:

23834

</description>

23835

23836

<description>Add a director as parent.</description>

23837

23838

23839

23840

23841

<description>Remove any parents.</description>

23842

23843

</element>

23844

23845

23846

<description>This method is not defined in BaseHandler, but

23847

subclasses should define it if they want to catch all URLs.

23848

This method, if implemented, will be called by the parent

23849

OpenerDirector. It should return a file-like object as

23850

described in the return value of the open() of

23851

OpenerDirector, or None. It should raise

23852

URLError, unless a truly exceptional thing happens (for

23853

example, MemoryError should not be mapped to

23854

URLError).

23855

This method will be called before any protocol-specific open method.</description>

23856

23857

23858

23859

23860

<description>This method is not defined in BaseHandler, but

23861

subclasses should define it if they want to catch all URLs with no

23862

specific registered handler to open it.

23863

This method, if implemented, will be called by the parent OpenerDirector. Return values should be the same as for default_open().</description>

23864

23865

23866

23867

23868

<description>This method is not defined in BaseHandler, but

23869

subclasses should override it if they intend to provide a catch-all

23870

for otherwise unhandled HTTP errors. It will be called automatically

23871

by the OpenerDirector getting the error, and should not

23872

normally be called in other circumstances.

23873

req will be a Request object, fp will be a

23874

file-like object with the HTTP error body, code will be the

23875

three-digit code of the error, msg will be the user-visible

23876

explanation of the code and hdrs will be a mapping object with

23877

the headers of the error.

23878

Return values and exceptions raised should be the same as those

23879

of urlopen().</description>

23880

23881

23882

23883

23884

</group>

23885

23886

<description>Some HTTP redirections require action from this module's client

23887

code. If this is the case, HTTPError is raised. See

23888

2616 for details of the precise meanings of the various

23889

redirection codes.

23890

</description>

23891

23892

<description>Return a Request or None in response to a redirect.

23893

This is called by the default implementations of the

23894

http_error_30*() methods when a redirection is received

23895

from the server. If a redirection should take place, return a new

23896

Request to allow http_error_30*() to perform the

23897

redirect. Otherwise, raise HTTPError if no other

23898

Handler should try to handle this URL, or return None

23899

if you can't but another Handler might.

23900

The default implementation of this method does not strictly

23901

follow 2616, which says that 301 and 302 responses to POST

23902

requests must not be automatically redirected without confirmation by

23903

the user. In reality, browsers do allow automatic redirection of

23904

these responses, changing the POST to a GET, and the default

23905

implementation reproduces this behavior.

23906

</description>

23907

23908

23909

23910

23911

<description>Redirect to the Location: URL. This method is called by

23912

the parent OpenerDirector when getting an HTTP

23913

`moved permanently' response.</description>

23914

23915

23916

23917

23918

<description>The same as http_error_301(), but called for the

23919

`found' response.</description>

23920

23921

23922

23923

23924

<description>The same as http_error_301(), but called for the

23925

`see other' response.</description>

23926

23927

23928

23929

23930

<description>The same as http_error_301(), but called for the

23931

`temporary redirect' response.</description>

23932

23933

23934

23935

</group>

23936

23937

<description>[ProxyHandler]{protocol_open}{request}

23938

The ProxyHandler will have a method

23939

protocol_open() for every protocol which has a

23940

proxy in the proxies dictionary given in the constructor. The

23941

method will modify requests to go through the proxy, by calling

23942

request.set_proxy(), and call the next handler in the chain to

23943

actually execute the protocol.

23944

</description>

23945

</group>

23946

23947

<description>These methods are available on HTTPPasswordMgr and

23948

HTTPPasswordMgrWithDefaultRealm objects.

23949

</description>

23950

23951

<description>uri can be either a single URI, or a sequene of URIs. realm,

23952

user and passwd must be strings. This causes

23953

(user, passwd) to be used as authentication tokens

23954

when authentication for realm and a super-URI of any of the

23955

given URIs is given.</description>

23956

23957

23958

23959

23960

<description>Get user/password for given realm and URI, if any. This method will

23961

return (None, None) if there is no matching user/password.

23962

For HTTPPasswordMgrWithDefaultRealm objects, the realm

23963

None will be searched if the given realm has no matching

23964

user/password.</description>

23965

23966

23967

23968

</group>

23969

23970

23971

<description>Handle an authentication request by getting a user/password pair, and

23972

re-trying the request. authreq should be the name of the header

23973

where the information about the realm is included in the request,

23974

host is the host to authenticate to, req should be the

23975

(failed) Request object, and headers should be the error

23976

headers.</description>

23977

23978

23979

23980

</group>

23981

23982

23983

<description>Retry the request with authentication information, if available.</description>

23984

23985

23986

23987

</group>

23988

23989

23990

<description>Retry the request with authentication information, if available.</description>

23991

23992

23993

23994

</group>

23995

23996

23997

<description>authreq should be the name of the header where the information about

23998

the realm is included in the request, host should be the host to

23999

authenticate to, req should be the (failed) Request

24000

object, and headers should be the error headers.</description>

24001

24002

24003

24004

</group>

24005

24006

24007

<description>Retry the request with authentication information, if available.</description>

24008

24009

24010

24011

</group>

24012

24013

24014

<description>Retry the request with authentication information, if available.</description>

24015

24016

24017

24018

</group>

24019

24020

24021

<description>Send an HTTP request, which can be either GET or POST, depending on

24022

req.has_data().</description>

24023

24024

24025

24026

</group>

24027

24028

24029

<description>Send an HTTPS request, which can be either GET or POST, depending on

24030

req.has_data().</description>

24031

24032

24033

24034

</group>

24035

24036

24037

<description>Open the file locally, if there is no host name, or

24038

the host name is 'localhost'. Change the

24039

protocol to ftp otherwise, and retry opening

24040

it using parent.</description>

24041

24042

24043

24044

</group>

24045

24046

24047

<description>Open the FTP file indicated by req.

24048

The login is always done with empty username and password.</description>

24049

24050

24051

24052

</group>

24053

24054

<description>CacheFTPHandler objects are FTPHandler objects with

24055

the following additional methods:

24056

</description>

24057

24058

<description>Set timeout of connections to t seconds.</description>

24059

24060

24061

24062

24063

<description>Set maximum number of cached connections to m.</description>

24064

24065

24066

24067

</group>

24068

24069

24070

<description>Open the gopher resource indicated by req.</description>

24071

24072

24073

24074

</group>

24075

24076

24077

<description>Raise a URLError exception.</description>

24078

24079

</element>

24080

24081

</group>

24082

24083

24084

<description>Process HTTP error responses.

24085

For 200 error codes, the response object is returned immediately.

24086

For non-200 error codes, this simply passes the job on to the

24087

protocol_error_code() handler methods, via

24088

OpenerDirector.error(). Eventually,

24089

urllib2.HTTPDefaultErrorHandler will raise an

24090

HTTPError if no other handler handles the error.</description>

24091

24092

</element>

24093

24094

</group>

24095

24096

</group>

24097

</group>

24098

24099

<description>HTTP and HTTPS protocol client (requires sockets).

24100

</description>

24101

24102

<description>An HTTPConnection instance represents one transaction with an HTTP

24103

server. It should be instantiated passing it a host and optional port number.

24104

If no port number is passed, the port is extracted from the host string if it

24105

has the form host:port, else the default HTTP port (80) is

24106

used. For example, the following calls all create instances that connect to

24107

the server at the same host and port:

24108

>>> h1 = httplib.HTTPConnection('www.cwi.nl')

24109

>>> h2 = httplib.HTTPConnection('www.cwi.nl:80')

24110

>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)

24111

New in version 2.0</description>

24112

24113

24114

24115

24116

<description>A subclass of HTTPConnection that uses SSL for communication with

24117

secure servers. Default port is 443.

24118

key_file is

24119

the name of a PEM formatted file that contains your private

24120

key. cert_file is a PEM formatted certificate chain file.

24121

This does not do any certificate verification!

24122

New in version 2.0</description>

24123

24124

24125

24126

24127

<description>Class whose instances are returned upon successful connection. Not

24128

instantiated directly by user.

24129

New in version 2.0</description>

24130

24131

24132

24133

24134

<description>HTTPConnection instances have the following methods:

24135

</description>

24136

24137

<description>This will send a request to the server using the HTTP request method

24138

method and the selector url. If the body argument is

24139

present, it should be a string of data to send after the headers are finished.

24140

The header Content-Length is automatically set to the correct value.

24141

The headers argument should be a mapping of extra HTTP headers to send

24142

with the request.</description>

24143

24144

24145

24146

24147

<description>Should be called after a request is sent to get the response from the server.

24148

Returns an HTTPResponse instance.</description>

24149

24150

</element>

24151

24152

24153

<description>Set the debugging level (the amount of debugging output printed).

24154

The default debug level is 0, meaning no debugging output is

24155

printed.</description>

24156

24157

24158

24159

24160

<description>Connect to the server specified when the object was created.</description>

24161

24162

</element>

24163

24164

24165

<description>Close the connection to the server.</description>

24166

24167

</element>

24168

24169

24170

<description>Send data to the server. This should be used directly only after the

24171

endheaders() method has been called and before

24172

getreply() has been called.</description>

24173

24174

24175

24176

24177

<description>This should be the first call after the connection to the server has

24178

been made. It sends a line to the server consisting of the

24179

request string, the selector string, and the HTTP version

24180

(HTTP/1.1). To disable automatic sending of Host: or

24181

Accept-Encoding: headers (for example to accept additional

24182

content encodings), specify skip_host or skip_accept_encoding

24183

with non-False values.

24184

Changed in version 2.4: skip_accept_encoding argument added</description>

24185

24186

24187

24188

24189

<description>Send an 822-style header to the server. It sends a line to the

24190

server consisting of the header, a colon and a space, and the first

24191

argument. If more arguments are given, continuation lines are sent,

24192

each consisting of a tab and an argument.</description>

24193

24194

24195

24196

24197

<description>Send a blank line to the server, signalling the end of the headers.</description>

24198

24199

</element>

24200

24201

</group>

24202

24203

<description>HTTPResponse instances have the following methods and attributes:

24204

</description>

24205

24206

<description>Reads and returns the response body, or up to the next amt bytes.</description>

24207

24208

24209

24210

24211

<description>Get the contents of the header name, or default if there is no

24212

matching header.</description>

24213

24214

24215

24216

</group>

24217

24218

</group>

24219

</group>

24220

24221

<description>FTP protocol client (requires sockets).

24222

</description>

24223

24224

<description>Return a new instance of the FTP class. When

24225

host is given, the method call connect(host) is

24226

made. When user is given, additionally the method call

24227

login(user, passwd, acct) is made (where

24228

passwd and acct default to the empty string when not given).</description>

24229

24230

24231

24232

24233

<description>Several methods are available in two flavors: one for handling text

24234

files and another for binary files. These are named for the command

24235

which is used followed by lines for the text version or

24236

binary for the binary version.

24237

FTP instances have the following methods:

24238

</description>

24239

24240

<description>Set the instance's debugging level. This controls the amount of

24241

debugging output printed. The default, 0, produces no

24242

debugging output. A value of 1 produces a moderate amount of

24243

debugging output, generally a single line per request. A value of

24244

2 or higher produces the maximum amount of debugging output,

24245

logging each line sent and received on the control connection.</description>

24246

24247

24248

24249

24250

<description>Connect to the given host and port. The default port number is 21, as

24251

specified by the FTP protocol specification. It is rarely needed to

24252

specify a different port number. This function should be called only

24253

once for each instance; it should not be called at all if a host was

24254

given when the instance was created. All other methods can only be

24255

used after a connection has been made.</description>

24256

24257

24258

24259

24260

<description>Return the welcome message sent by the server in reply to the initial

24261

connection. (This message sometimes contains disclaimers or help

24262

information that may be relevant to the user.)</description>

24263

24264

</element>

24265

24266

24267

<description>Log in as the given user. The passwd and acct

24268

parameters are optional and default to the empty string. If no

24269

user is specified, it defaults to 'anonymous'. If

24270

user is 'anonymous', the default passwd is

24271

'anonymous@'. This function should be called only

24272

once for each instance, after a connection has been established; it

24273

should not be called at all if a host and user were given when the

24274

instance was created. Most FTP commands are only allowed after the

24275

client has logged in.</description>

24276

24277

24278

24279

24280

<description>Abort a file transfer that is in progress. Using this does not always

24281

work, but it's worth a try.</description>

24282

24283

</element>

24284

24285

24286

<description>Send a simple command string to the server and return the response

24287

string.</description>

24288

24289

24290

24291

24292

<description>Send a simple command string to the server and handle the response.

24293

Return nothing if a response code in the range 200--299 is received.

24294

Raise an exception otherwise.</description>

24295

24296

24297

24298

24299

<description>Retrieve a file in binary transfer mode. command should be an

24300

appropriate RETR command: 'RETR filename'.

24301

The callback function is called for each block of data received,

24302

with a single string argument giving the data block.

24303

The optional maxblocksize argument specifies the maximum chunk size to

24304

read on the low-level socket object created to do the actual transfer

24305

(which will also be the largest size of the data blocks passed to

24306

callback). A reasonable default is chosen. rest means the

24307

same thing as in the transfercmd() method.</description>

24308

24309

24310

24311

24312

<description>Retrieve a file or directory listing in ASCII transfer mode.

24313

command should be an appropriate RETR command (see

24314

retrbinary()) or a LIST command (usually just the string

24315

'LIST'). The callback function is called for each line,

24316

with the trailing CRLF stripped. The default callback prints

24317

the line to sys.stdout.</description>

24318

24319

24320

24321

24322

<description>Enable ``passive'' mode if boolean is true, other disable

24323

passive mode. (In Python 2.0 and before, passive mode was off by

24324

default; in Python 2.1 and later, it is on by default.)</description>

24325

24326

24327

24328

24329

<description>Store a file in binary transfer mode. command should be an

24330

appropriate STOR command: "STOR filename".

24331

file is an open file object which is read until using its

24332

read() method in blocks of size blocksize to provide the

24333

data to be stored. The blocksize argument defaults to 8192.

24334

Changed in version 2.1: default for blocksize added</description>

24335

24336

24337

24338

24339

<description>Store a file in ASCII transfer mode. command should be an

24340

appropriate STOR command (see storbinary()). Lines are

24341

read until from the open file object file using its

24342

readline() method to provide the data to be stored.</description>

24343

24344

24345

24346

24347

<description>Initiate a transfer over the data connection. If the transfer is

24348

active, send a EPRT or PORT command and the transfer command specified

24349

by cmd, and accept the connection. If the server is passive,

24350

send a EPSV or PASV command, connect to it, and start the transfer

24351

command. Either way, return the socket for the connection.

24352

If optional rest is given, a REST command is

24353

sent to the server, passing rest as an argument. rest is

24354

usually a byte offset into the requested file, telling the server to

24355

restart sending the file's bytes at the requested offset, skipping

24356

over the initial bytes. Note however that RFC

24357

959 requires only that rest be a string containing characters

24358

in the printable range from ASCII code 33 to ASCII code 126. The

24359

transfercmd() method, therefore, converts

24360

rest to a string, but no check is

24361

performed on the string's contents. If the server does

24362

not recognize the REST command, an

24363

error_reply exception will be raised. If this happens,

24364

simply call transfercmd() without a rest argument.</description>

24365

24366

24367

24368

24369

<description>Like transfercmd(), but returns a tuple of the data

24370

connection and the expected size of the data. If the expected size

24371

could not be computed, None will be returned as the expected

24372

size. cmd and rest means the same thing as in

24373

transfercmd().</description>

24374

24375

24376

24377

24378

<description>Return a list of files as returned by the NLST command. The

24379

optional argument is a directory to list (default is the current

24380

server directory). Multiple arguments can be used to pass

24381

non-standard options to the NLST command.</description>

24382

24383

24384

24385

24386

<description>Produce a directory listing as returned by the LIST command,

24387

printing it to standard output. The optional argument is a

24388

directory to list (default is the current server directory). Multiple

24389

arguments can be used to pass non-standard options to the LIST

24390

command. If the last argument is a function, it is used as a

24391

callback function as for retrlines(); the default

24392

prints to sys.stdout. This method returns None.</description>

24393

24394

24395

24396

24397

<description>Rename file fromname on the server to toname.</description>

24398

24399

24400

24401

24402

<description>Remove the file named filename from the server. If successful,

24403

returns the text of the response, otherwise raises

24404

error_perm on permission errors or

24405

error_reply on other errors.</description>

24406

24407

24408

24409

24410

<description>Set the current directory on the server.</description>

24411

24412

24413

24414

24415

<description>Create a new directory on the server.</description>

24416

24417

24418

24419

24420

<description>Return the pathname of the current directory on the server.</description>

24421

24422

</element>

24423

24424

24425

<description>Remove the directory named dirname on the server.</description>

24426

24427

24428

24429

24430

<description>Request the size of the file named filename on the server. On

24431

success, the size of the file is returned as an integer, otherwise

24432

None is returned. Note that the SIZE command is not standardized, but is supported by many common server implementations.</description>

24433

24434

24435

24436

24437

<description>Send a QUIT command to the server and close the connection.

24438

This is the ``polite'' way to close a connection, but it may raise an

24439

exception of the server reponds with an error to the

24440

QUIT command. This implies a call to the close()

24441

method which renders the FTP instance useless for subsequent

24442

calls (see below).</description>

24443

24444

</element>

24445

24446

24447

<description>Close the connection unilaterally. This should not be applied to an

24448

already closed connection such as after a successful call to

24449

quit(). After this call the FTP instance should not

24450

be used any more (after a call to close() or

24451

quit() you cannot reopen the connection by issuing another

24452

login() method).</description>

24453

24454

</element>

24455

24456

</group>

24457

</group>

24458

24459

<description>Gopher protocol client (requires sockets).

24460

This module provides a minimal implementation of client side of the

24461

Gopher protocol. It is used by the module urllib to

24462

handle URLs that use the Gopher protocol.

24463

The module defines the following functions:

24464

</description>

24465

24466

<description>Send a selector string to the gopher server at host and

24467

port (default 70). Returns an open file object from

24468

which the returned document can be read.</description>

24469

24470

24471

24472

24473

<description>Send a selector string and a query string to a gopher

24474

server at host and port (default 70). Returns an

24475

open file object from which the returned document can be read.</description>

24476

24477

24478

24479

</group>

24480

24481

<description>POP3 protocol client (requires sockets).

24482

%By Andrew T. Csillag

24483

%Even though I put it into LaTeX, I cannot really claim that I wrote

24484

%it since I just stole most of it from the poplib.py source code and

24485

%the imaplib ``chapter''.

24486

%Revised by ESR, January 2000

24487

This module defines a class, POP3, which encapsulates a

24488

connection to a POP3 server and implements the protocol as defined in

24489

1725. The POP3 class supports both the minimal and

24490

optional command sets. Additionally, this module provides a class

24491

POP3_SSL, which provides support for connecting to POP3

24492

servers that use SSL as an underlying protocol layer.

24493

Note that POP3, though widely supported, is obsolescent. The

24494

implementation quality of POP3 servers varies widely, and too many are

24495

quite poor. If your mailserver supports IMAP, you would be better off

24496

using the imaplib.IMAP4 class, as IMAP

24497

servers tend to be better implemented.

24498

A single class is provided by the poplib module:

24499

</description>

24500

24501

<description>This class implements the actual POP3 protocol. The connection is

24502

created when the instance is initialized.

24503

If port is omitted, the standard POP3 port (110) is used.</description>

24504

24505

24506

24507

24508

<description>This is a subclass of POP3 that connects to the server over an

24509

SSL encrypted socket. If port is not specified, 995, the

24510

standard POP3-over-SSL port is used. keyfile and certfile

24511

are also optional - they can contain a PEM formatted private key and

24512

certificate chain file for the SSL connection.

24513

New in version 2.4</description>

24514

24515

24516

24517

24518

<description>All POP3 commands are represented by methods of the same name,

24519

in lower-case; most return the response text sent by the server.

24520

An POP3 instance has the following methods:

24521

</description>

24522

24523

<description>Set the instance's debugging level. This controls the amount of

24524

debugging output printed. The default, 0, produces no

24525

debugging output. A value of 1 produces a moderate amount of

24526

debugging output, generally a single line per request. A value of

24527

2 or higher produces the maximum amount of debugging output,

24528

logging each line sent and received on the control connection.</description>

24529

24530

24531

24532

24533

<description>Returns the greeting string sent by the POP3 server.</description>

24534

24535

</element>

24536

24537

24538

<description>Send user command, response should indicate that a password is required.</description>

24539

24540

24541

24542

24543

<description>Send password, response includes message count and mailbox size.

24544

Note: the mailbox on the server is locked until quit() is

24545

called.</description>

24546

24547

24548

24549

24550

<description>Use the more secure APOP authentication to log into the POP3 server.</description>

24551

24552

24553

24554

24555

<description>Use RPOP authentication (similar to UNIX r-commands) to log into POP3 server.</description>

24556

24557

24558

24559

24560

<description>Get mailbox status. The result is a tuple of 2 integers:

24561

(message count, mailbox size).</description>

24562

24563

</element>

24564

24565

24566

<description>Request message list, result is in the form

24567

(response, ['mesg_num octets', ...]). If which is

24568

set, it is the message to list.</description>

24569

24570

24571

24572

24573

<description>Retrieve whole message number which, and set its seen flag.

24574

Result is in form (response, ['line', ...], octets).</description>

24575

24576

24577

24578

24579

<description>Flag message number which for deletion. On most servers

24580

deletions are not actually performed until QUIT (the major exception is

24581

Eudora QPOP, which deliberately violates the RFCs by doing pending

24582

deletes on any disconnect).</description>

24583

24584

24585

24586

24587

<description>Remove any deletion marks for the mailbox.</description>

24588

24589

</element>

24590

24591

24592

<description>Do nothing. Might be used as a keep-alive.</description>

24593

24594

</element>

24595

24596

24597

<description>Signoff: commit changes, unlock mailbox, drop connection.</description>

24598

24599

</element>

24600

24601

24602

<description>Retrieves the message header plus howmuch lines of the message

24603

after the header of message number which. Result is in form

24604

(response, ['line', ...], octets).

24605

The POP3 TOP command this method uses, unlike the RETR command,

24606

doesn't set the message's seen flag; unfortunately, TOP is poorly

24607

specified in the RFCs and is frequently broken in off-brand servers.

24608

Test this method by hand against the POP3 servers you will use before

24609

trusting it.</description>

24610

24611

24612

24613

24614

<description>Return message digest (unique id) list.

24615

If which is specified, result contains the unique id for that

24616

message in the form 'response mesgnum uid,

24617

otherwise result is list (response, ['mesgnum uid', ...],

24618

octets).</description>

24619

24620

24621

24622

</group>

24623

24624

</group>

24625

</group>

24626

24627

<description>IMAP4 protocol client (requires sockets).

24628

% Based on HTML documentation by Piers Lauder <piers@communitysolutions.com.au>;

24629

% converted by Fred L. Drake, Jr. <fdrake@acm.org>.

24630

% Revised by ESR, January 2000.

24631

% Changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002 % Changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>, November 2002 This module defines three classes, IMAP4, IMAP4_SSL and IMAP4_stream, which encapsulate a

24632

connection to an IMAP4 server and implement a large subset of the

24633

IMAP4rev1 client protocol as defined in 2060. It is backward

24634

compatible with IMAP4 (1730) servers, but note that the

24635

STATUS command is not supported in IMAP4.

24636

Three classes are provided by the imaplib module, IMAP4 is the base class:

24637

</description>

24638

24639

<description>This class implements the actual IMAP4 protocol. The connection is

24640

created and protocol version (IMAP4 or IMAP4rev1) is determined when

24641

the instance is initialized.

24642

If host is not specified, '' (the local host) is used.

24643

If port is omitted, the standard IMAP4 port (143) is used.</description>

24644

24645

24646

24647

24648

<description>This is a subclass derived from IMAP4 that connects over an SSL encrypted socket (to use this class you need a socket module that was compiled with SSL support).

24649

If host is not specified, '' (the local host) is used.

24650

If port is omitted, the standard IMAP4-over-SSL port (993) is used.

24651

keyfile and certfile are also optional - they can contain a PEM formatted

24652

private key and certificate chain file for the SSL connection.</description>

24653

24654

24655

24656

24657

<description>This is a subclass derived from IMAP4 that connects

24658

to the stdin/stdout file descriptors created by passing command to os.popen2().

24659

New in version 2.3</description>

24660

24661

24662

24663

24664

<description>Converts an IMAP4 INTERNALDATE string to Coordinated Universal

24665

Time. Returns a time module tuple.</description>

24666

24667

24668

24669

24670

<description>Converts an integer into a string representation using characters

24671

from the set [A .. P].</description>

24672

24673

24674

24675

24676

<description>Converts an IMAP4 FLAGS response to a tuple of individual

24677

flags.</description>

24678

24679

24680

24681

24682

<description>Converts a time module tuple to an IMAP4

24683

INTERNALDATE representation. Returns a string in the form:

24684

"DD-Mmm-YYYY HH:MM:SS +HHMM" (including double-quotes).</description>

24685

24686

24687

24688

24689

<description>All IMAP4rev1 commands are represented by methods of the same name,

24690

either upper-case or lower-case.

24691

All arguments to commands are converted to strings, except for

24692

AUTHENTICATE, and the last argument to APPEND which is

24693

passed as an IMAP4 literal. If necessary (the string contains IMAP4

24694

protocol-sensitive characters and isn't enclosed with either

24695

parentheses or double quotes) each string is quoted. However, the

24696

password argument to the LOGIN command is always quoted.

24697

If you want to avoid having an argument string quoted

24698

(eg: the flags argument to STORE) then enclose the string in

24699

parentheses (eg: r'(\Deleted)').

24700

Each command returns a tuple: (type, [data,

24701

...]) where type is usually 'OK' or 'NO',

24702

and data is either the text from the command response, or

24703

mandated results from the command. Each data

24704

is either a string, or a tuple. If a tuple, then the first part

24705

is the header of the response, and the second part contains

24706

the data (ie: 'literal' value).

24707

An IMAP4 instance has the following methods:

24708

</description>

24709

24710

<description>Append message to named mailbox.</description>

24711

24712

24713

24714

24715

<description>Authenticate command --- requires response processing. This is

24716

currently unimplemented, and raises an exception.</description>

24717

24718

24719

24720

24721

<description>Checkpoint mailbox on server.</description>

24722

24723

</element>

24724

24725

24726

<description>Close currently selected mailbox. Deleted messages are removed from

24727

writable mailbox. This is the recommended command before

24728

LOGOUT.</description>

24729

24730

</element>

24731

24732

24733

<description>Copy message_set messages onto end of new_mailbox.</description>

24734

24735

24736

24737

24738

<description>Create new mailbox named mailbox.</description>

24739

24740

24741

24742

24743

<description>Delete old mailbox named mailbox.</description>

24744

24745

24746

24747

24748

<description>Permanently remove deleted items from selected mailbox. Generates an

24749

EXPUNGE response for each deleted message. Returned data

24750

contains a list of EXPUNGE message numbers in order

24751

received.</description>

24752

24753

</element>

24754

24755

24756

<description>Fetch (parts of) messages. message_parts should be

24757

a string of message part names enclosed within parentheses,

24758

eg: "(UID BODY[TEXT])". Returned data are tuples

24759

of message part envelope and data.</description>

24760

24761

24762

24763

24764

<description>Get the ACLs for mailbox.

24765

The method is non-standard, but is supported by the Cyrus server.</description>

24766

24767

24768

24769

24770

<description>Get the quota root's resource usage and limits.

24771

This method is part of the IMAP4 QUOTA extension defined in rfc2087.

24772

New in version 2.3</description>

24773

24774

24775

24776

24777

<description>Get the list of quota roots for the named mailbox.

24778

This method is part of the IMAP4 QUOTA extension defined in rfc2087.

24779

New in version 2.3</description>

24780

24781

24782

24783

24784

<description>List mailbox names in directory matching

24785

pattern. directory defaults to the top-level mail

24786

folder, and pattern defaults to match anything. Returned data

24787

contains a list of LIST responses.</description>

24788

24789

24790

24791

24792

<description>Identify the client using a plaintext password.

24793

The password will be quoted.</description>

24794

24795

24796

24797

24798

<description>Force use of CRAM-MD5 authentication when identifying the client to protect the password.

24799

Will only work if the server CAPABILITY response includes the phrase AUTH=CRAM-MD5.

24800

New in version 2.3</description>

24801

24802

24803

24804

24805

<description>Shutdown connection to server. Returns server BYE response.</description>

24806

24807

</element>

24808

24809

24810

<description>List subscribed mailbox names in directory matching pattern.

24811

directory defaults to the top level directory and

24812

pattern defaults to match any mailbox.

24813

Returned data are tuples of message part envelope and data.</description>

24814

24815

24816

24817

24818

<description>Send NOOP to server.</description>

24819

24820

</element>

24821

24822

24823

<description>Opens socket to port at host.

24824

The connection objects established by this method

24825

will be used in the read, readline, send, and shutdown methods.

24826

You may override this method.</description>

24827

24828

24829

24830

24831

<description>Fetch truncated part of a message.

24832

Returned data is a tuple of message part envelope and data.</description>

24833

24834

24835

24836

24837

<description>Assume authentication as user.

24838

Allows an authorised administrator to proxy into any user's mailbox.

24839

New in version 2.3</description>

24840

24841

24842

24843

24844

<description>Reads size bytes from the remote server.

24845

You may override this method.</description>

24846

24847

24848

24849

24850

<description>Reads one line from the remote server.

24851

You may override this method.</description>

24852

24853

</element>

24854

24855

24856

<description>Prompt server for an update. Returned data is None if no new

24857

messages, else value of RECENT response.</description>

24858

24859

</element>

24860

24861

24862

<description>Rename mailbox named oldmailbox to newmailbox.</description>

24863

24864

24865

24866

24867

<description>Return data for response code if received, or

24868

None. Returns the given code, instead of the usual type.</description>

24869

24870

24871

24872

24873

<description>Search mailbox for matching messages. Returned data contains a space

24874

separated list of matching message numbers. charset may be

24875

None, in which case no CHARSET will be specified in the

24876

request to the server. The IMAP protocol requires that at least one

24877

criterion be specified; an exception will be raised when the server

24878

returns an error.

24879

Example:

24880

# M is a connected IMAP4 instance...

24881

msgnums = M.search(None, 'FROM', '"LDJ"')

24882

# or:

24883

msgnums = M.search(None, '(FROM "LDJ")')

24884

</description>

24885

24886

24887

24888

24889

<description>Select a mailbox. Returned data is the count of messages in

24890

mailbox (EXISTS response). The default mailbox

24891

is 'INBOX'. If the readonly flag is set, modifications

24892

to the mailbox are not allowed.</description>

24893

24894

24895

24896

24897

<description>Sends data to the remote server.

24898

You may override this method.</description>

24899

24900

24901

24902

24903

<description>Set an ACL for mailbox.

24904

The method is non-standard, but is supported by the Cyrus server.</description>

24905

24906

24907

24908

24909

<description>Set the quota root's resource limits.

24910

This method is part of the IMAP4 QUOTA extension defined in rfc2087.

24911

New in version 2.3</description>

24912

24913

24914

24915

24916

<description>Close connection established in open.

24917

You may override this method.</description>

24918

24919

</element>

24920

24921

24922

<description>Returns socket instance used to connect to server.</description>

24923

24924

</element>

24925

24926

24927

<description>The sort command is a variant of search with sorting semantics for

24928

the results. Returned data contains a space

24929

separated list of matching message numbers.

24930

Sort has two arguments before the search_criterion

24931

argument(s); a parenthesized list of sort_criteria, and the searching charset.

24932

Note that unlike search, the searching charset argument is mandatory.

24933

There is also a uid sort command which corresponds to sort the way

24934

that uid search corresponds to search.

24935

The sort command first searches the mailbox for messages that

24936

match the given searching criteria using the charset argument for

24937

the interpretation of strings in the searching criteria. It then

24938

returns the numbers of matching messages.

24939

This is an IMAP4rev1 extension command.</description>

24940

24941

24942

24943

24944

<description>Request named status conditions for mailbox.</description>

24945

24946

24947

24948

24949

<description>Alters flag dispositions for messages in mailbox.</description>

24950

24951

24952

24953

24954

<description>Subscribe to new mailbox.</description>

24955

24956

24957

24958

24959

<description>The thread command is a variant of search with threading semantics for

24960

the results. Returned data contains a space

24961

separated list of thread members.

24962

Thread members consist of zero or more messages numbers, delimited by spaces,

24963

indicating successive parent and child.

24964

Thread has two arguments before the search_criterion

24965

argument(s); a threading_algorithm, and the searching charset.

24966

Note that unlike search, the searching charset argument is mandatory.

24967

There is also a uid thread command which corresponds to thread the way

24968

that uid search corresponds to search.

24969

The thread command first searches the mailbox for messages that

24970

match the given searching criteria using the charset argument for

24971

the interpretation of strings in the searching criteria. It thren

24972

returns the matching messages threaded according to the specified

24973

threading algorithm.

24974

This is an IMAP4rev1 extension command. New in version 2.4</description>

24975

24976

24977

24978

24979

<description>Execute command args with messages identified by UID, rather than

24980

message number. Returns response appropriate to command. At least

24981

one argument must be supplied; if none are provided, the server will

24982

return an error and an exception will be raised.</description>

24983

24984

24985

24986

24987

<description>Unsubscribe from old mailbox.</description>

24988

24989

24990

24991

24992

<description>Allow simple extension commands notified by server in

24993

CAPABILITY response.</description>

24994

24995

24996

24997

24998

<description>Returns SSLObject instance used for the secure connection with the server.</description>

24999

25000

</element>

25001

25002

</group>

25003

25004

</group>

25005

</group>

25006

25007

<description>NNTP protocol client (requires sockets).

25008

</description>

25009

25010

<description>Return a new instance of the NNTP class, representing a

25011

connection to the NNTP server running on host host, listening at

25012

port port. The default port is 119. If the optional

25013

user and password are provided, or if suitable credentials are present in ~/.netrc,

25014

the AUTHINFO USER and AUTHINFO PASS commands are used to

25015

identify and authenticate the user to the server. If the optional

25016

flag readermode is true, then a mode reader command is

25017

sent before authentication is performed. Reader mode is sometimes

25018

necessary if you are connecting to an NNTP server on the local machine

25019

and intend to call reader-specific commands, such as group. If

25020

you get unexpected NNTPPermanentErrors, you might need to set

25021

readermode. readermode defaults to None.</description>

25022

25023

25024

25025

25026

<description>Derived from the standard exception Exception, this is the base

25027

class for all exceptions raised by the nntplib module.</description>

25028

25029

</element>

25030

25031

25032

<description>Exception raised when an unexpected reply is received from the

25033

server. For backwards compatibility, the exception error_reply

25034

is equivalent to this class.</description>

25035

25036

</element>

25037

25038

25039

<description>Exception raised when an error code in the range 400--499 is

25040

received. For backwards compatibility, the exception

25041

error_temp is equivalent to this class.</description>

25042

25043

</element>

25044

25045

25046

<description>Exception raised when an error code in the range 500--599 is

25047

received. For backwards compatibility, the exception

25048

error_perm is equivalent to this class.</description>

25049

25050

</element>

25051

25052

25053

<description>Exception raised when a reply is received from the server that does

25054

not begin with a digit in the range 1--5. For backwards

25055

compatibility, the exception error_proto is equivalent to this

25056

class.</description>

25057

25058

</element>

25059

25060

25061

<description>Exception raised when there is some error in the response data. For

25062

backwards compatibility, the exception error_data is

25063

equivalent to this class.</description>

25064

25065

</element>

25066

25067

25068

<description>NNTP instances have the following methods. The response that is

25069

returned as the first item in the return tuple of almost all methods

25070

is the server's response: a string beginning with a three-digit code.

25071

If the server's response indicates an error, the method raises one of

25072

the above exceptions.

25073

</description>

25074

25075

<description>Return the welcome message sent by the server in reply to the initial

25076

connection. (This message sometimes contains disclaimers or help

25077

information that may be relevant to the user.)</description>

25078

25079

</element>

25080

25081

25082

<description>Set the instance's debugging level. This controls the amount of

25083

debugging output printed. The default, 0, produces no debugging

25084

output. A value of 1 produces a moderate amount of debugging

25085

output, generally a single line per request or response. A value of

25086

2 or higher produces the maximum amount of debugging output,

25087

logging each line sent and received on the connection (including

25088

message text).</description>

25089

25090

25091

25092

25093

<description>Send a NEWGROUPS command. The date argument should be a

25094

string of the form 'yymmdd' indicating the

25095

date, and time should be a string of the form

25096

'hhmmss' indicating the time. Return a pair

25097

(response, groups) where groups is a list of

25098

group names that are new since the given date and time.

25099

If the file parameter is supplied, then the output of the NEWGROUPS command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start

25100

calling write() on it to store the lines of the command output.

25101

If file is supplied, then the returned list is an empty list.</description>

25102

25103

25104

25105

25106

<description>Send a NEWNEWS command. Here, group is a group name or

25107

'*', and date and time have the same meaning as for

25108

newgroups(). Return a pair (response,

25109

articles) where articles is a list of article ids.

25110

If the file parameter is supplied, then the output of the NEWNEWS command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start

25111

calling write() on it to store the lines of the command output.

25112

If file is supplied, then the returned list is an empty list.</description>

25113

25114

25115

25116

25117

<description>Send a LIST command. Return a pair (response,

25118

list) where list is a list of tuples. Each tuple has the

25119

form (group, last, first, flag), where

25120

group is a group name, last and first are the last

25121

and first article numbers (as strings), and flag is

25122

'y' if posting is allowed, 'n' if not, and 'm' if

25123

the newsgroup is moderated. (Note the ordering: last,

25124

first.)

25125

If the file parameter is supplied, then the output of the LIST command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start

25126

calling write() on it to store the lines of the command output.

25127

If file is supplied, then the returned list is an empty list.</description>

25128

25129

25130

25131

25132

<description>Send a GROUP command, where name is the group name.

25133

Return a tuple (response, count, first,

25134

last, name) where count is the (estimated) number

25135

of articles in the group, first is the first article number in

25136

the group, last is the last article number in the group, and

25137

name is the group name. The numbers are returned as strings.</description>

25138

25139

25140

25141

25142

<description>Send a HELP command. Return a pair (response,

25143

list) where list is a list of help strings.

25144

If the file parameter is supplied, then the output of the HELP command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start

25145

calling write() on it to store the lines of the command output.

25146

If file is supplied, then the returned list is an empty list.</description>

25147

25148

25149

25150

25151

<description>Send a STAT command, where id is the message id (enclosed

25152

in < and >) or an article number (as a string).

25153

Return a triple (response, number, id) where

25154

number is the article number (as a string) and id is the

25155

article id (enclosed in < and >).</description>

25156

25157

25158

25159

25160

<description>Send a NEXT command. Return as for stat().</description>

25161

25162

</element>

25163

25164

25165

<description>Send a LAST command. Return as for stat().</description>

25166

25167

</element>

25168

25169

25170

<description>Send a HEAD command, where id has the same meaning as for

25171

stat(). Return a tuple

25172

(response, number, id, list)

25173

where the first three are the same as for stat(),

25174

and list is a list of the article's headers (an uninterpreted

25175

list of lines, without trailing newlines).</description>

25176

25177

25178

25179

25180

<description>Send a BODY command, where id has the same meaning as for

25181

stat(). If the file parameter is supplied, then

25182

the body is stored in a file. If file is a string, then

25183

the method will open a file object with that name, write to it then close it.

25184

If file is a file object, then it will start calling

25185

write() on it to store the lines of the body.

25186

Return as for head(). If file is supplied, then

25187

the returned list is an empty list.</description>

25188

25189

25190

25191

25192

<description>Send an ARTICLE command, where id has the same meaning as

25193

for stat(). Return as for head().</description>

25194

25195

25196

25197

25198

<description>Send a SLAVE command. Return the server's response.</description>

25199

25200

</element>

25201

25202

25203

<description>Send an XHDR command. This command is not defined in the RFC

25204

but is a common extension. The header argument is a header

25205

keyword, e.g. 'subject'. The string argument should have

25206

the form 'first-last' where first and

25207

last are the first and last article numbers to search. Return a

25208

pair (response, list), where list is a list of

25209

pairs (id, text), where id is an article id

25210

(as a string) and text is the text of the requested header for

25211

that article.

25212

If the file parameter is supplied, then the output of the XHDR command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start

25213

calling write() on it to store the lines of the command output.

25214

If file is supplied, then the returned list is an empty list.</description>

25215

25216

25217

25218

25219

<description>Post an article using the POST command. The file

25220

argument is an open file object which is read until EOF using its

25221

readline() method. It should be a well-formed news article,

25222

including the required headers. The post() method

25223

automatically escapes lines beginning with ..</description>

25224

25225

25226

25227

25228

<description>Send an IHAVE command. If the response is not an error, treat

25229

file exactly as for the post() method.</description>

25230

25231

25232

25233

25234

<description>Return a triple (response, date, time),

25235

containing the current date and time in a form suitable for the

25236

newnews() and newgroups() methods.

25237

This is an optional NNTP extension, and may not be supported by all

25238

servers.</description>

25239

25240

</element>

25241

25242

25243

<description>Process an XGTITLE command, returning a pair (response,

25244

list), where list is a list of tuples containing

25245

(name, title).

25246

% XXX huh? Should that be name, description?

25247

If the file parameter is supplied, then the output of the XGTITLE command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start

25248

calling write() on it to store the lines of the command output.

25249

If file is supplied, then the returned list is an empty list.

25250

This is an optional NNTP extension, and may not be supported by all

25251

servers.</description>

25252

25253

25254

25255

25256

<description>Return a pair (resp, list). list is a list

25257

of tuples, one for each article in the range delimited by the start

25258

and end article numbers. Each tuple is of the form

25259

(article number, subject, poster, date,

25260

id, references, size, lines).

25261

If the file parameter is supplied, then the output of the XOVER command is stored in a file. If file is a string, then the method will open a file object with that name, write to it then close it. If file is a file object, then it will start

25262

calling write() on it to store the lines of the command output.

25263

If file is supplied, then the returned list is an empty list.

25264

This is an optional NNTP extension, and may not be supported by all

25265

servers.</description>

25266

25267

25268

25269

25270

<description>Return a pair (resp, path), where path is the

25271

directory path to the article with message ID id. This is an

25272

optional NNTP extension, and may not be supported by all servers.</description>

25273

25274

25275

25276

25277

<description>Send a QUIT command and close the connection. Once this method

25278

has been called, no other methods of the NNTP object should be called.</description>

25279

25280

</element>

25281

25282

</group>

25283

</group>

25284

25285

<description>SMTP protocol client (requires sockets).

25286

</description>

25287

25288

<description>A SMTP instance encapsulates an SMTP connection. It has

25289

methods that support a full repertoire of SMTP and ESMTP

25290

operations. If the optional host and port parameters are given, the

25291

SMTP connect() method is called with those parameters during

25292

initialization. An SMTPConnectError is raised if the

25293

specified host doesn't respond correctly.

25294

For normal use, you should only require the initialization/connect,

25295

sendmail(), and quit() methods. An example is

25296

included below.</description>

25297

25298

25299

25300

25301

<description>An SMTP instance has the following methods:

25302

</description>

25303

25304

<description>Set the debug output level. A true value for level results in

25305

debug messages for connection and for all messages sent to and

25306

received from the server.</description>

25307

25308

25309

25310

25311

<description>Connect to a host on a given port. The defaults are to connect to the

25312

local host at the standard SMTP port (25).

25313

If the hostname ends with a colon (:) followed by a

25314

number, that suffix will be stripped off and the number interpreted as

25315

the port number to use.

25316

This method is automatically invoked by the constructor if a

25317

host is specified during instantiation.</description>

25318

25319

25320

25321

25322

<description>Send a command cmd to the server. The optional argument

25323

argstring is simply concatenated to the command, separated by a

25324

space.

25325

This returns a 2-tuple composed of a numeric response code and the

25326

actual response line (multiline responses are joined into one long

25327

line.)

25328

In normal operation it should not be necessary to call this method

25329

explicitly. It is used to implement other methods and may be useful

25330

for testing private extensions.

25331

If the connection to the server is lost while waiting for the reply,

25332

SMTPServerDisconnected will be raised.</description>

25333

25334

25335

25336

25337

<description>Identify yourself to the SMTP server using HELO. The hostname

25338

argument defaults to the fully qualified domain name of the local

25339

host.

25340

In normal operation it should not be necessary to call this method

25341

explicitly. It will be implicitly called by the sendmail()

25342

when necessary.</description>

25343

25344

25345

25346

25347

<description>Identify yourself to an ESMTP server using EHLO. The hostname

25348

argument defaults to the fully qualified domain name of the local

25349

host. Examine the response for ESMTP option and store them for use by

25350

has_extn().

25351

Unless you wish to use has_extn() before sending

25352

mail, it should not be necessary to call this method explicitly. It

25353

will be implicitly called by sendmail() when necessary.</description>

25354

25355

25356

25357

25358

<description>Return 1 if name is in the set of SMTP service extensions

25359

returned by the server, 0 otherwise. Case is ignored.</description>

25360

25361

25362

25363

25364

<description>Check the validity of an address on this server using SMTP VRFY.

25365

Returns a tuple consisting of code 250 and a full 822 address

25366

(including human name) if the user address is valid. Otherwise returns

25367

an SMTP error code of 400 or greater and an error string.

25368

Many sites disable SMTP VRFY in order to foil spammers.</description>

25369

25370

25371

25372

25373

<description>Log in on an SMTP server that requires authentication.

25374

The arguments are the username and the password to authenticate with.

25375

If there has been no previous EHLO or HELO command this

25376

session, this method tries ESMTP EHLO first.

25377

This method will return normally if the authentication was successful,

25378

or may raise the following exceptions:

25379

[SMTPHeloError]

25380

The server didn't reply properly to the HELO greeting.

25381

[SMTPAuthenticationError]

25382

The server didn't accept the username/password combination.

25383

[SMTPError]

25384

No suitable authentication method was found.

25385

</description>

25386

25387

25388

25389

25390

<description>Put the SMTP connection in TLS (Transport Layer Security) mode. All

25391

SMTP commands that follow will be encrypted. You should then call

25392

ehlo() again.

25393

If keyfile and certfile are provided, these are passed to

25394

the socket module's ssl() function.</description>

25395

25396

25397

25398

25399

<description>Send mail. The required arguments are an 822 from-address

25400

string, a list of 822 to-address strings, and a message string.

25401

The caller may pass a list of ESMTP options (such as 8bitmime)

25402

to be used in MAIL FROM commands as mail_options. ESMTP

25403

options (such as DSN commands) that should be used with all

25404

RCPT commands can be passed as rcpt_options. (If you

25405

need to use different ESMTP options to different recipients you have

25406

to use the low-level methods such as mail, rcpt and

25407

data to send the message.)

25408

The from_addr and to_addrs parameters are

25409

used to construct the message envelope used by the transport agents.

25410

The SMTP does not modify the message headers in any way.

25411

If there has been no previous EHLO or HELO command this

25412

session, this method tries ESMTP EHLO first. If the server does

25413

ESMTP, message size and each of the specified options will be passed

25414

to it (if the option is in the feature set the server advertises). If

25415

EHLO fails, HELO will be tried and ESMTP options

25416

suppressed.

25417

This method will return normally if the mail is accepted for at least

25418

one recipient. Otherwise it will throw an exception. That is, if this

25419

method does not throw an exception, then someone should get your mail.

25420

If this method does not throw an exception, it returns a dictionary,

25421

with one entry for each recipient that was refused. Each entry

25422

contains a tuple of the SMTP error code and the accompanying error

25423

message sent by the server.

25424

This method may raise the following exceptions:

25425

[SMTPRecipientsRefused]

25426

All recipients were refused. Nobody got the mail. The

25427

recipients attribute of the exception object is a dictionary

25428

with information about the refused recipients (like the one returned

25429

when at least one recipient was accepted).

25430

[SMTPHeloError]

25431

The server didn't reply properly to the HELO greeting.

25432

[SMTPSenderRefused]

25433

The server didn't accept the from_addr.

25434

[SMTPDataError]

25435

The server replied with an unexpected error code (other than a refusal

25436

of a recipient).

25437

Unless otherwise noted, the connection will be open even after

25438

an exception is raised.</description>

25439

25440

25441

25442

25443

<description>Terminate the SMTP session and close the connection.</description>

25444

25445

</element>

25446

25447

</group>

25448

25449

</group>

25450

</group>

25451

25452

<description>Telnet client class.

25453

</description>

25454

25455

<description>Telnet represents a connection to a Telnet server. The

25456

instance is initially not connected by default; the open()

25457

method must be used to establish a connection. Alternatively, the

25458

host name and optional port number can be passed to the constructor,

25459

to, in which case the connection to the server will be established

25460

before the constructor returns.

25461

Do not reopen an already connected instance.

25462

This class has many read_*() methods. Note that some of them raise EOFError when the end of the connection is read,

25463

because they can return an empty string for other reasons. See the

25464

individual descriptions below.</description>

25465

25466

25467

25468

25469

<description>Telnet instances have the following methods:

25470

</description>

25471

25472

<description>Read until a given string, expected, is encountered or until

25473

timeout seconds have passed.

25474

When no match is found, return whatever is available instead,

25475

possibly the empty string. Raise EOFError if the connection

25476

is closed and no cooked data is available.</description>

25477

25478

25479

25480

25481

<description>Read all data until ; block until connection closed.</description>

25482

25483

</element>

25484

25485

25486

<description>Read at least one byte of cooked data unless is hit.

25487

Return '' if is hit. Block if no data is immediately

25488

available.</description>

25489

25490

</element>

25491

25492

25493

<description>Read everything that can be without blocking in I/O (eager).

25494

Raise EOFError if connection closed and no cooked data

25495

available. Return '' if no cooked data available otherwise.

25496

Do not block unless in the midst of an IAC sequence.</description>

25497

25498

</element>

25499

25500

25501

<description>Read readily available data.

25502

Raise EOFError if connection closed and no cooked data

25503

available. Return '' if no cooked data available otherwise.

25504

Do not block unless in the midst of an IAC sequence.</description>

25505

25506

</element>

25507

25508

25509

<description>Process and return data already in the queues (lazy).

25510

Raise EOFError if connection closed and no data available.

25511

Return '' if no cooked data available otherwise. Do not block

25512

unless in the midst of an IAC sequence.</description>

25513

25514

</element>

25515

25516

25517

<description>Return any data available in the cooked queue (very lazy).

25518

Raise EOFError if connection closed and no data available.

25519

Return '' if no cooked data available otherwise. This method

25520

never blocks.</description>

25521

25522

</element>

25523

25524

25525

<description>Return the data collected between a SB/SE pair (suboption begin/end).

25526

The callback should access these data when it was invoked with a

25527

SE command. This method never blocks.

25528

New in version 2.3</description>

25529

25530

</element>

25531

25532

25533

<description>Connect to a host.

25534

The optional second argument is the port number, which

25535

defaults to the standard Telnet port (23).

25536

Do not try to reopen an already connected instance.</description>

25537

25538

25539

25540

25541

<description>Print a debug message when the debug level is > 0.

25542

If extra arguments are present, they are substituted in the

25543

message using the standard string formatting operator.</description>

25544

25545

25546

25547

25548

<description>Set the debug level. The higher the value of debuglevel, the

25549

more debug output you get (on sys.stdout).</description>

25550

25551

25552

25553

25554

<description>Close the connection.</description>

25555

25556

</element>

25557

25558

25559

<description>Return the socket object used internally.</description>

25560

25561

</element>

25562

25563

25564

<description>Return the file descriptor of the socket object used internally.</description>

25565

25566

</element>

25567

25568

25569

<description>Write a string to the socket, doubling any IAC characters.

25570

This can block if the connection is blocked. May raise

25571

socket.error if the connection is closed.</description>

25572

25573

25574

25575

25576

<description>Interaction function, emulates a very dumb Telnet client.</description>

25577

25578

</element>

25579

25580

25581

<description>Multithreaded version of interact().</description>

25582

25583

</element>

25584

25585

25586

<description>Read until one from a list of a regular expressions matches.

25587

The first argument is a list of regular expressions, either

25588

compiled (re.RegexObject instances) or uncompiled (strings).

25589

The optional second argument is a timeout, in seconds; the default

25590

is to block indefinitely.

25591

Return a tuple of three items: the index in the list of the

25592

first regular expression that matches; the match object

25593

returned; and the text read up till and including the match.

25594

If end of file is found and no text was read, raise

25595

EOFError. Otherwise, when nothing matches, return

25596

(-1, None, text) where text is the text received so

25597

far (may be the empty string if a timeout happened).

25598

If a regular expression ends with a greedy match (such as .*)

25599

or if more than one expression can match the same input, the

25600

results are indeterministic, and may depend on the I/O timing.</description>

25601

25602

25603

25604

25605

<description>Each time a telnet option is read on the input flow, this

25606

callback (if set) is called with the following parameters :

25607

callback(telnet socket, command (DO/DONT/WILL/WONT), option). No other

25608

action is done afterwards by telnetlib.</description>

25609

25610

25611

25612

</group>

25613

25614

</group>

25615

</group>

25616

25617

<description>Parse URLs into components.

25618

</description>

25619

25620

<description>Parse a URL into 6 components, returning a 6-tuple: (addressing

25621

scheme, network location, path, parameters, query, fragment

25622

identifier). This corresponds to the general structure of a URL:

25623

scheme://netloc/path;parameters?query#fragment.

25624

Each tuple item is a string, possibly empty.

25625

The components are not broken up in smaller parts (e.g. the network

25626

location is a single string), and % escapes are not expanded.

25627

The delimiters as shown above are not part of the tuple items,

25628

except for a leading slash in the path component, which is

25629

retained if present.

25630

Example:

25631

urlparse('http://www.cwi.nl:80/%7Eguido/Python.html')

25632

yields the tuple

25633

('http', 'www.cwi.nl:80', '/%7Eguido/Python.html', '', '', '')

25634

If the default_scheme argument is specified, it gives the

25635

default addressing scheme, to be used only if the URL string does not

25636

specify one. The default value for this argument is the empty string.

25637

If the allow_fragments argument is zero, fragment identifiers

25638

are not allowed, even if the URL's addressing scheme normally does

25639

support them. The default value for this argument is 1.</description>

25640

25641

25642

25643

25644

<description>Construct a URL string from a tuple as returned by urlparse().

25645

This may result in a slightly different, but equivalent URL, if the

25646

URL that was parsed originally had redundant delimiters, e.g. a ? with

25647

an empty query (the draft states that these are equivalent).</description>

25648

25649

25650

25651

25652

<description>This is similar to urlparse(), but does not split the

25653

params from the URL. This should generally be used instead of

25654

urlparse() if the more recent URL syntax allowing

25655

parameters to be applied to each segment of the path portion of

25656

the URL (see 2396). A separate function is needed to separate

25657

the path segments and parameters. This function returns a 5-tuple:

25658

(addressing scheme, network location, path, query, fragment

25659

identifier).

25660

New in version 2.2</description>

25661

25662

25663

25664

25665

<description>Combine the elements of a tuple as returned by urlsplit()

25666

into a complete URL as a string.

25667

New in version 2.2</description>

25668

25669

25670

25671

25672

<description>Construct a full (``absolute'') URL by combining a ``base URL''

25673

(base) with a ``relative URL'' (url). Informally, this

25674

uses components of the base URL, in particular the addressing scheme,

25675

the network location and (part of) the path, to provide missing

25676

components in the relative URL.

25677

Example:

25678

urljoin('http://www.cwi.nl/%7Eguido/Python.html', 'FAQ.html')

25679

yields the string

25680

'http://www.cwi.nl/%7Eguido/FAQ.html'

25681

The allow_fragments argument has the same meaning as for

25682

urlparse().</description>

25683

25684

25685

25686

25687

<description>If url contains a fragment identifier, returns a modified

25688

version of url with no fragment identifier, and the fragment

25689

identifier as a separate string. If there is no fragment identifier

25690

in url, returns url unmodified and an empty string.</description>

25691

25692

25693

25694

</group>

25695

25696

<description>A framework for network servers.

25697

The SocketServer module simplifies the task of writing network

25698

servers.

25699

There are four basic server classes: TCPServer uses the

25700

Internet TCP protocol, which provides for continuous streams of data

25701

between the client and server. UDPServer uses datagrams, which

25702

are discrete packets of information that may arrive out of order or be

25703

lost while in transit. The more infrequently used

25704

UnixStreamServer and UnixDatagramServer classes are

25705

similar, but use domain sockets; they're not available on

25706

non- platforms. For more details on network programming, consult

25707

a book such as W. Richard Steven's UNIX Network Programming

25708

or Ralph Davis's Win32 Network Programming.

25709

These four classes process requests synchronously; each request

25710

must be completed before the next request can be started. This isn't

25711

suitable if each request takes a long time to complete, because it

25712

requires a lot of computation, or because it returns a lot of data

25713

which the client is slow to process. The solution is to create a

25714

separate process or thread to handle each request; the

25715

ForkingMixIn and ThreadingMixIn mix-in classes can be

25716

used to support asynchronous behaviour.

25717

Creating a server requires several steps. First, you must create a

25718

request handler class by subclassing the BaseRequestHandler

25719

class and overriding its handle() method; this method will

25720

process incoming requests. Second, you must instantiate one of the

25721

server classes, passing it the server's address and the request

25722

handler class. Finally, call the handle_request() or

25723

serve_forever() method of the server object to process one or

25724

many requests.

25725

When inheriting from ThreadingMixIn for threaded connection

25726

behavior, you should explicitly declare how you want your threads

25727

to behave on an abrupt shutdown. The ThreadingMixIn class

25728

defines an attribute daemon_threads, which indicates whether

25729

or not the server should wait for thread termination. You should

25730

set the flag explicitly if you would like threads to behave

25731

autonomously; the default is False, meaning that Python

25732

will not exit until all threads created by ThreadingMixIn have

25733

exited.

25734

Server classes have the same external methods and attributes, no

25735

matter what network protocol they use:

25736

</description>

25737

25738

<description>Return an integer file descriptor for the socket on which the server

25739

is listening. This function is most commonly passed to

25740

select.select(), to allow monitoring multiple servers in the

25741

same process.</description>

25742

25743

</element>

25744

25745

25746

<description>Process a single request. This function calls the following methods

25747

in order: get_request(), verify_request(), and

25748

process_request(). If the user-provided handle()

25749

method of the handler class raises an exception, the server's

25750

handle_error() method will be called.</description>

25751

25752

</element>

25753

25754

25755

<description>Handle an infinite number of requests. This simply calls

25756

handle_request() inside an infinite loop.</description>

25757

25758

</element>

25759

25760

25761

<description>Actually processes the request by instantiating

25762

RequestHandlerClass and calling its handle() method.</description>

25763

25764

</element>

25765

25766

25767

<description>Must accept a request from the socket, and return a 2-tuple containing

25768

the new socket object to be used to communicate with the

25769

client, and the client's address.</description>

25770

25771

</element>

25772

25773

25774

<description>This function is called if the RequestHandlerClass's

25775

handle() method raises an exception. The default action is

25776

to print the traceback to standard output and continue handling

25777

further requests.</description>

25778

25779

25780

25781

25782

<description>Calls finish_request() to create an instance of the

25783

RequestHandlerClass. If desired, this function can create a

25784

new process or thread to handle the request; the ForkingMixIn

25785

and ThreadingMixIn classes do this.</description>

25786

25787

25788

25789

25790

<description>Called by the server's constructor to activate the server.

25791

May be overridden.</description>

25792

25793

</element>

25794

25795

25796

<description>Called by the server's constructor to bind the socket to the desired

25797

address. May be overridden.</description>

25798

25799

</element>

25800

25801

25802

<description>Must return a Boolean value; if the value is true, the request will be

25803

processed, and if it's false, the request will be denied.

25804

This function can be overridden to implement access controls for a server.

25805

The default implementation always return true.</description>

25806

25807

25808

25809

25810

<description>Called after the handle() method to perform any clean-up

25811

actions required. The default implementation does nothing. If

25812

setup() or handle() raise an exception, this

25813

function will not be called.</description>

25814

25815

</element>

25816

25817

25818

<description>This function must do all the work required to service a request.

25819

Several instance attributes are available to it; the request is

25820

available as self.request; the client address as

25821

self.client_address; and the server instance as

25822

self.server, in case it needs access to per-server

25823

information.

25824

The type of self.request is different for datagram or stream

25825

services. For stream services, self.request is a socket

25826

object; for datagram services, self.request is a string.

25827

However, this can be hidden by using the mix-in request handler

25828

classes

25829

StreamRequestHandler or DatagramRequestHandler, which

25830

override the setup() and finish() methods, and

25831

provides self.rfile and self.wfile attributes.

25832

self.rfile and self.wfile can be read or written,

25833

respectively, to get the request data or return data to the client.</description>

25834

25835

</element>

25836

25837

25838

<description>Called before the handle() method to perform any

25839

initialization actions required. The default implementation does

25840

nothing.</description>

25841

25842

</element>

25843

25844

</group>

25845

25846

<description>Basic HTTP server (base class for

25847

SimpleHTTPServer and CGIHTTPServer).

25848

</description>

25849

25850

<description>This class builds on the TCPServer class by

25851

storing the server address as instance

25852

variables named server_name and server_port. The

25853

server is accessible by the handler, typically through the handler's

25854

server instance variable.</description>

25855

25856

25857

25858

25859

<description>This class is used

25860

to handle the HTTP requests that arrive at the server. By itself,

25861

it cannot respond to any actual HTTP requests; it must be subclassed

25862

to handle each request method (e.g. GET or POST).

25863

BaseHTTPRequestHandler provides a number of class and instance

25864

variables, and methods for use by subclasses.

25865

The handler will parse the request and the headers, then call a

25866

method specific to the request type. The method name is constructed

25867

from the request. For example, for the request method SPAM, the

25868

do_SPAM() method will be called with no arguments. All of

25869

the relevant information is stored in instance variables of the

25870

handler. Subclasses should not need to override or extend the

25871

__init__() method.</description>

25872

25873

25874

25875

25876

<description>Calls handle_one_request() once (or, if persistent connections

25877

are enabled, multiple times) to handle incoming HTTP requests.

25878

You should never need to override it; instead, implement appropriate

25879

do_*() methods.</description>

25880

25881

</element>

25882

25883

25884

<description>This method will parse and dispatch

25885

the request to the appropriate do_*() method. You should

25886

never need to override it.</description>

25887

25888

</element>

25889

25890

25891

<description>Sends and logs a complete error reply to the client. The numeric

25892

code specifies the HTTP error code, with message as

25893

optional, more specific text. A complete set of headers is sent,

25894

followed by text composed using the error_message_format

25895

class variable.</description>

25896

25897

25898

25899

25900

<description>Sends a response header and logs the accepted request. The HTTP

25901

response line is sent, followed by Server and Date

25902

headers. The values for these two headers are picked up from the

25903

version_string() and date_time_string() methods,

25904

respectively.</description>

25905

25906

25907

25908

25909

<description>Writes a specific MIME header to the output stream. keyword

25910

should specify the header keyword, with value specifying

25911

its value.</description>

25912

25913

25914

25915

25916

<description>Sends a blank line, indicating the end of the MIME headers in

25917

the response.</description>

25918

25919

</element>

25920

25921

25922

<description>Logs an accepted (successful) request. code should specify

25923

the numeric HTTP code associated with the response. If a size of

25924

the response is available, then it should be passed as the

25925

size parameter.</description>

25926

25927

25928

25929

25930

<description>Logs an error when a request cannot be fulfilled. By default,

25931

it passes the message to log_message(), so it takes the

25932

same arguments (format and additional values).</description>

25933

25934

25935

25936

25937

<description>Logs an arbitrary message to sys.stderr. This is typically

25938

overridden to create custom error logging mechanisms. The

25939

format argument is a standard printf-style format string,

25940

where the additional arguments to log_message() are applied

25941

as inputs to the formatting. The client address and current date

25942

and time are prefixed to every message logged.</description>

25943

25944

25945

25946

25947

<description>Returns the server software's version string. This is a combination

25948

of the server_version and sys_version class variables.</description>

25949

25950

</element>

25951

25952

25953

<description>Returns the current date and time, formatted for a message header.</description>

25954

25955

</element>

25956

25957

25958

<description>Returns the current date and time, formatted for logging.</description>

25959

25960

</element>

25961

25962

25963

<description>Returns the client address, formatted for logging. A name lookup

25964

is performed on the client's IP address.</description>

25965

25966

</element>

25967

25968

</group>

25969

25970

<description>This module provides a basic request handler for HTTP

25971

servers.

25972

The SimpleHTTPServer module defines a request-handler class,

25973

interface compatible with BaseHTTPServer.BaseHTTPRequestHandler

25974

which serves files only from a base directory.

25975

The SimpleHTTPServer module defines the following class:

25976

</description>

25977

25978

<description>This class is used, to serve files from current directory and below,

25979

directly mapping the directory structure to HTTP requests.

25980

A lot of the work is done by the base class

25981

BaseHTTPServer.BaseHTTPRequestHandler, such as parsing the

25982

request. This class implements the do_GET() and

25983

do_HEAD() functions.</description>

25984

25985

25986

25987

25988

<description>This method serves the 'HEAD' request type: it sends the

25989

headers it would send for the equivalent GET request. See the

25990

do_GET() method for more complete explanation of the possible

25991

headers.</description>

25992

25993

</element>

25994

25995

25996

<description>The request is mapped to a local file by interpreting the request as

25997

a path relative to the current working directory.

25998

If the request was mapped to a directory, a 403 respond is output,

25999

followed by the explanation 'Directory listing not supported'.

26000

Any IOError exception in opening the requested file, is mapped

26001

to a 404, 'File not found' error. Otherwise, the content

26002

type is guessed using the extensions_map variable.

26003

A 'Content-type:' with the guessed content type is output, and

26004

then a blank line, signifying end of headers, and then the contents of

26005

the file. The file is always opened in binary mode.

26006

For example usage, see the implementation of the test()

26007

function.</description>

26008

26009

</element>

26010

26011

</group>

26012

26013

<description>This module provides a request handler for HTTP servers

26014

which can run CGI scripts.

26015

The CGIHTTPServer module defines a request-handler class,

26016

interface compatible with

26017

BaseHTTPServer.BaseHTTPRequestHandler and inherits behavior

26018

from SimpleHTTPServer.SimpleHTTPRequestHandler but can also

26019

run CGI scripts.

26020

This module can run CGI scripts on and Windows systems;

26021

on Mac OS it will only be able to run Python scripts within the same

26022

process as itself.

26023

The CGIHTTPServer module defines the following class:

26024

</description>

26025

26026

<description>This class is used to serve either files or output of CGI scripts from the current directory and below. Note that mapping HTTP hierarchic

26027

structure to local directory structure is exactly as in

26028

SimpleHTTPServer.SimpleHTTPRequestHandler.

26029

The class will however, run the CGI script, instead of serving it as a

26030

file, if it guesses it to be a CGI script. Only directory-based CGI

26031

are used --- the other common server configuration is to treat special

26032

extensions as denoting CGI scripts.

26033

The do_GET() and do_HEAD() functions are

26034

modified to run CGI scripts and serve the output, instead of serving

26035

files, if the request leads to somewhere below the

26036

cgi_directories path.</description>

26037

26038

26039

26040

26041

<description>This method serves the 'POST' request type, only allowed for

26042

CGI scripts. Error 501, "Can only POST to CGI scripts", is output

26043

when trying to POST to a non-CGI url.</description>

26044

26045

</element>

26046

26047

</group>

26048

26049

<description>Support for HTTP state management (cookies).

26050

The Cookie module defines classes for abstracting the concept of cookies, an HTTP state management mechanism. It supports both simple

26051

string-only cookies, and provides an abstraction for having any serializable

26052

data-type as cookie value.

26053

The module formerly strictly applied the parsing rules described in

26054

the 2109 and 2068 specifications. It has since been discovered

26055

that MSIE 3.0x doesn't follow the character rules outlined in those

26056

specs. As a result, the parsing rules used are a bit less strict.

26057

{CookieError}

26058

Exception failing because of 2109 invalidity: incorrect

26059

attributes, incorrect Set-Cookie header, etc.

26060

</description>

26061

26062

<description>This class is a dictionary-like object whose keys are strings and

26063

whose values are Morsel instances. Note that upon setting a key to

26064

a value, the value is first converted to a Morsel containing

26065

the key and the value.

26066

If input is given, it is passed to the load() method.</description>

26067

26068

26069

26070

26071

<description>This class derives from BaseCookie and overrides

26072

value_decode() and value_encode() to be the identity

26073

and str() respectively.</description>

26074

26075

26076

26077

26078

<description>This class derives from BaseCookie and overrides

26079

value_decode() and value_encode() to be the

26080

pickle.loads() and pickle.dumps().

26081

2.3{Reading pickled values from untrusted

26082

cookie data is a huge security hole, as pickle strings can be crafted

26083

to cause arbitrary code to execute on your server. It is supported

26084

for backwards compatibility only, and may eventually go away.}</description>

26085

26086

26087

26088

26089

<description>This class derives from BaseCookie. It overrides

26090

value_decode() to be pickle.loads() if it is a

26091

valid pickle, and otherwise the value itself. It overrides

26092

value_encode() to be pickle.dumps() unless it is a

26093

string, in which case it returns the value itself.

26094

2.3{The same security warning from SerialCookie

26095

applies here.}</description>

26096

26097

26098

26099

26100

26101

<description>Return a decoded value from a string representation. Return value can

26102

be any type. This method does nothing in BaseCookie --- it exists

26103

so it can be overridden.</description>

26104

26105

26106

26107

26108

<description>Return an encoded value. val can be any type, but return value

26109

must be a string. This method does nothing in BaseCookie --- it exists

26110

so it can be overridden

26111

In general, it should be the case that value_encode() and value_decode() are inverses on the range of value_decode.</description>

26112

26113

26114

26115

26116

<description>Return a string representation suitable to be sent as HTTP headers.

26117

attrs and header are sent to each Morsel's

26118

output() method. sep is used to join the headers

26119

together, and is by default a newline.</description>

26120

26121

26122

26123

26124

<description>Return an embeddable JavaScript snippet, which, if run on a browser which

26125

supports JavaScript, will act the same as if the HTTP headers was sent.

26126

The meaning for attrs is the same as in output().</description>

26127

26128

26129

26130

26131

<description>If rawdata is a string, parse it as an HTTP_COOKIE and add

26132

the values found there as Morsels. If it is a dictionary, it

26133

is equivalent to:

26134

for k, v in rawdata.items():

26135

cookie[k] = v

26136

</description>

26137

26138

26139

26140

</group>

26141

26142

26143

<description>Abstract a key/value pair, which has some 2109 attributes.

26144

Morsels are dictionary-like objects, whose set of keys is constant ---

26145

the valid 2109 attributes, which are

26146

expires

26147

path

26148

comment

26149

domain

26150

max-age

26151

secure

26152

version

26153

The keys are case-insensitive.</description>

26154

26155

</element>

26156

26157

26158

<description>Set the key, value and coded_value members.</description>

26159

26160

26161

26162

26163

<description>Whether K is a member of the set of keys of a Morsel.</description>

26164

26165

26166

26167

26168

<description>Return a string representation of the Morsel, suitable

26169

to be sent as an HTTP header. By default, all the attributes are included,

26170

unless attrs is given, in which case it should be a list of attributes

26171

to use. header is by default "Set-Cookie:".</description>

26172

26173

26174

26175

26176

<description>Return an embeddable JavaScript snippet, which, if run on a browser which

26177

supports JavaScript, will act the same as if the HTTP header was sent.

26178

The meaning for attrs is the same as in output().</description>

26179

26180

26181

26182

26183

<description>Return a string representing the Morsel, without any surrounding HTTP

26184

or JavaScript.

26185

The meaning for attrs is the same as in output().</description>

26186

26187

26188

26189

</group>

26190

26191

</group>

26192

</group>

26193

26194

<description>XML-RPC client access.

26195

% Not everyting is documented yet. It might be good to describe % Marshaller, Unmarshaller, getparser, dumps, loads, and Transport.

26196

New in version 2.2

26197

XML-RPC is a Remote Procedure Call method that uses XML passed via

26198

HTTP as a transport. With it, a client can call methods with

26199

parameters on a remote server (the server is named by a URI) and get back

26200

structured data. This module supports writing XML-RPC client code; it

26201

handles all the details of translating between conformable Python

26202

objects and XML on the wire.

26203

</description>

26204

26205

<description>A ServerProxy instance is an object that manages communication

26206

with a remote XML-RPC server. The required first argument is a URI

26207

(Uniform Resource Indicator), and will normally be the URL of the

26208

server. The optional second argument is a transport factory instance;

26209

by default it is an internal SafeTransport instance for https:

26210

URLs and an internal HTTP Transport instance otherwise. The

26211

optional third argument is an encoding, by default UTF-8. The optional

26212

fourth argument is a debugging flag. If allow_none is true, the Python constant None will be translated into XML; the

26213

default behaviour is for None to raise a TypeError.

26214

This is a commonly-used extension to the XML-RPC specification, but isn't

26215

supported by all clients and servers; see

26216

http://ontosys.com/xml-rpc/extensions.html for a description. Both the HTTP and HTTPS transports support the URL syntax extension for

26217

HTTP Basic Authentication: http://user:pass@host:port/path. The user:pass portion will be base64-encoded as an HTTP `Authorization'

26218

header, and sent to the remote server as part of the connection process

26219

when invoking an XML-RPC method. You only need to use this if the

26220

remote server requires a Basic Authentication user and password.

26221

The returned instance is a proxy object with methods that can be used

26222

to invoke corresponding RPC calls on the remote server. If the remote

26223

server supports the introspection API, the proxy can also be used to query

26224

the remote server for the methods it supports (service discovery) and

26225

fetch other server-associated metadata.

26226

ServerProxy instance methods take Python basic types and objects as arguments and return Python basic types and classes. Types that are

26227

conformable (e.g. that can be marshalled through XML), include the

26228

following (and except where noted, they are unmarshalled as the same

26229

Python type):

26230

{l|l}{constant}{Name}{Meaning}

26231

boolean{The True and False constants}

26232

integers{Pass in directly}

26233

floating-point numbers{Pass in directly}

26234

strings{Pass in directly}

26235

arrays{Any Python sequence type containing conformable

26236

elements. Arrays are returned as lists}

26237

structures{A Python dictionary. Keys must be strings,

26238

values may be any conformable type.}

26239

dates{in seconds since the epoch; pass in an instance of the

26240

DateTime wrapper class}

26241

binary data{pass in an instance of the Binary

26242

wrapper class}

26243

This is the full set of data types supported by XML-RPC. Method calls

26244

may also raise a special Fault instance, used to signal

26245

XML-RPC server errors, or ProtocolError used to signal an

26246

error in the HTTP/HTTPS transport layer. Note that even though starting

26247

with Python 2.2 you can subclass builtin types, the xmlrpclib module

26248

currently does not marshal instances of such subclasses.

26249

When passing strings, characters special to XML such as <,

26250

>, and & will be automatically escaped. However, it's

26251

the caller's responsibility to ensure that the string is free of

26252

characters that aren't allowed in XML, such as the control characters

26253

with ASCII values between 0 and 31; failing to do this will result in

26254

an XML-RPC request that isn't well-formed XML. If you have to pass

26255

arbitrary strings via XML-RPC, use the Binary wrapper class

26256

described below.

26257

Server is retained as an alias for ServerProxy for backwards

26258

compatibility. New code should use ServerProxy.</description>

26259

26260

26261

26262

26263

<description>A ServerProxy instance has a method corresponding to

26264

each remote procedure call accepted by the XML-RPC server. Calling

26265

the method performs an RPC, dispatched by both name and argument

26266

signature (e.g. the same method name can be overloaded with multiple

26267

argument signatures). The RPC finishes by returning a value, which

26268

may be either returned data in a conformant type or a Fault or

26269

ProtocolError object indicating an error.

26270

Servers that support the XML introspection API support some common

26271

methods grouped under the reserved system member:

26272

</description>

26273

26274

<description>This method returns a list of strings, one for each (non-system)

26275

method supported by the XML-RPC server.</description>

26276

26277

</element>

26278

26279

26280

<description>This method takes one parameter, the name of a method implemented by

26281

the XML-RPC server.It returns an array of possible signatures for this

26282

method. A signature is an array of types. The first of these types is

26283

the return type of the method, the rest are parameters.

26284

Because multiple signatures (ie. overloading) is permitted, this method

26285

returns a list of signatures rather than a singleton.

26286

Signatures themselves are restricted to the top level parameters

26287

expected by a method. For instance if a method expects one array of

26288

structs as a parameter, and it returns a string, its signature is

26289

simply "string, array". If it expects three integers and returns a

26290

string, its signature is "string, int, int, int".

26291

If no signature is defined for the method, a non-array value is

26292

returned. In Python this means that the type of the returned value will be something other that list.</description>

26293

26294

26295

26296

26297

<description>This method takes one parameter, the name of a method implemented by

26298

the XML-RPC server. It returns a documentation string describing the

26299

use of that method. If no such string is available, an empty string is

26300

returned. The documentation string may contain HTML markup.</description>

26301

26302

26303

26304

</group>

26305

26306

<description>This class may be initialized from any Python value; the instance

26307

returned depends only on its truth value. It supports various Python

26308

operators through __cmp__(), __repr__(),

26309

__int__(), and __nonzero__() methods, all

26310

implemented in the obvious ways.

26311

It also has the following method, supported mainly for internal use by

26312

the unmarshalling code:

26313

</description>

26314

26315

<description>Write the XML-RPC encoding of this Boolean item to the out stream object.</description>

26316

26317

26318

26319

</group>

26320

26321

<description>This class may initialized from date in seconds since the epoch, a

26322

time tuple, or an ISO 8601 time/date string. It has the following

26323

methods, supported mainly for internal use by the

26324

marshalling/unmarshalling code:

26325

</description>

26326

26327

<description>Accept a string as the instance's new time value.</description>

26328

26329

26330

26331

26332

<description>Write the XML-RPC encoding of this DateTime item to the out stream object.</description>

26333

26334

26335

26336

</group>

26337

26338

<description>This class may initialized from string data (which may include NULs).

26339

The primary acess to the content of a Binary object is

26340

provided by an attribute:

26341

[Binary]{data}

26342

The binary data encapsulated by the Binary instance. The data

26343

is provided as an 8-bit string.

26344

Binary objects have the following methods, supported mainly

26345

for internal use by the marshalling/unmarshalling code:

26346

</description>

26347

26348

<description>Accept a base64 string and decode it as the instance's new data.</description>

26349

26350

26351

26352

26353

<description>Write the XML-RPC base 64 encoding of this binary item to the out

26354

stream object.</description>

26355

26356

26357

26358

</group>

26359

26360

<description>A Fault object encapsulates the content of an XML-RPC fault tag.

26361

Fault objects have the following members:

26362

{faultCode}

26363

A string indicating the fault type.

26364

{faultString}

26365

A string containing a diagnostic message associated with the fault.

26366

</description>

26367

</group>

26368

26369

<description>A ProtocolError object describes a protocol error in the

26370

underlying transport layer (such as a 404 `not found' error if the

26371

server named by the URI does not exist). It has the following

26372

members:

26373

{url}

26374

The URI or URL that triggered the error.

26375

{errcode}

26376

The error code.

26377

{errmsg}

26378

The error message or diagnostic string.

26379

{headers}

26380

A string containing the headers of the HTTP/HTTPS request that

26381

triggered the error.

26382

</description>

26383

</group>

26384

26385

<description>New in version 2.4

26386

In http://www.xmlrpc.com/discuss/msgReader8, an approach

26387

is presented to encapsulate multiple calls to a remote server into

26388

a single request.

26389

</description>

26390

26391

<description>Create an object used to boxcar method calls. server is the

26392

eventual target of the call. Calls can be made to the result object,

26393

but they will immediately return None, and only store the

26394

call name and parameters in the MultiCall object. Calling

26395

the object itself causes all stored calls to be transmitted as

26396

a single system.multicall request. The result of this call

26397

is a generator; iterating over this generator yields the individual

26398

results.</description>

26399

26400

26401

26402

</group>

26403

26404

26405

<description>Convert any Python value to one of the XML-RPC Boolean constants,

26406

True or False.</description>

26407

26408

26409

26410

26411

<description>Trivially convert any Python string to a Binary object.</description>

26412

26413

26414

26415

26416

<description>Convert params into an XML-RPC request.

26417

or into a response if methodresponse is true.

26418

params can be either a tuple of arguments or an instance of the Fault exception class. If methodresponse is true,

26419

only a single value can be returned, meaning that params must be of length 1.

26420

encoding, if supplied, is the encoding to use in the generated

26421

XML; the default is UTF-8. Python's None value cannot be

26422

used in standard XML-RPC; to allow using it via an extension, provide a true value for allow_none.</description>

26423

26424

26425

26426

26427

<description>Convert an XML-RPC request or response into Python objects, a

26428

(params, methodname). params is a tuple of argument; methodname

26429

is a string, or None if no method name is present in the packet.

26430

If the XML-RPC packet represents a fault condition, this

26431

function will raise a Fault exception.</description>

26432

26433

26434

26435

</group>

26436

26437

</group>

26438

</group>

26439

26440

<description>Basic XML-RPC server implementation.

26441

The SimpleXMLRPCServer module provides a basic server

26442

framework for XML-RPC servers written in Python. Servers can either

26443

be free standing, using SimpleXMLRPCServer, or embedded in a

26444

CGI environment, using CGIXMLRPCRequestHandler.

26445

</description>

26446

26447

<description>Create a new server instance. The requestHandler parameter

26448

should be a factory for request handler instances; it defaults to

26449

SimpleXMLRPCRequestHandler. The addr and

26450

requestHandler parameters are passed to the

26451

SocketServer.TCPServer constructor. If

26452

logRequests is true (the default), requests will be logged;

26453

setting this parameter to false will turn off logging. This class

26454

provides methods for registration of functions that can be called by

26455

the XML-RPC protocol.</description>

26456

26457

26458

26459

26460

<description>Create a new instance to handle XML-RPC requests in a CGI

26461

environment. New in version 2.3</description>

26462

26463

</element>

26464

26465

26466

<description>Create a new request handler instance. This request handler

26467

supports POST requests and modifies logging so that the

26468

logRequests parameter to the SimpleXMLRPCServer

26469

constructor parameter is honored.</description>

26470

26471

</element>

26472

26473

26474

<description>The SimpleXMLRPCServer class is based on

26475

SocketServer.TCPServer and provides a means of creating

26476

simple, stand alone XML-RPC servers.

26477

</description>

26478

26479

<description>Register a function that can respond to XML-RPC requests. If

26480

name is given, it will be the method name associated with

26481

function, otherwise function.__name__ will be

26482

used. name can be either a normal or Unicode string, and may

26483

contain characters not legal in Python identifiers, including the

26484

period character.</description>

26485

26486

26487

26488

26489

<description>Register an object which is used to expose method names which have

26490

not been registered using register_function(). If

26491

instance contains a _dispatch() method, it is called

26492

with the requested method name and the parameters from the request;

26493

the return value is returned to the client as the result. If

26494

instance does not have a _dispatch() method, it is

26495

searched for an attribute matching the name of the requested method;

26496

if the requested method name contains periods, each component of the

26497

method name is searched for individually, with the effect that a

26498

simple hierarchical search is performed. The value found from this

26499

search is then called with the parameters from the request, and the

26500

return value is passed back to the client.</description>

26501

26502

26503

26504

26505

<description>Registers the XML-RPC introspection functions system.listMethods,

26506

system.methodHelp and system.methodSignature. New in version 2.3</description>

26507

26508

</element>

26509

26510

26511

<description>Registers the XML-RPC multicall function system.multicall.</description>

26512

26513

</element>

26514

26515

</group>

26516

26517

<description>The CGIXMLRPCRequestHandler class can be used to handle XML-RPC requests sent to Python CGI scripts.

26518

</description>

26519

26520

<description>Register a function that can respond to XML-RPC requests. If name is given, it will be the method name associated with function, otherwise function.__name__ will be used. name

26521

can be either a normal or Unicode string, and may contain characters not legal in Python identifiers, including the period

26522

character.</description>

26523

26524

26525

26526

26527

<description>Register an object which is used to expose method names which have not been registered using register_function(). If instance contains a _dispatch() method, it is called with the requested method name and the parameters from the request; the return value is returned to the client as the result.

26528

If instance does not have a _dispatch() method, it is searched for an attribute matching the name of the requested method; if the requested method name contains periods, each component of the method name is searched for individually, with the effect that a simple hierarchical search is performed. The value found from this search is then called with the parameters from the request, and the return value is passed back to the client.</description>

26529

26530

26531

26532

26533

<description>Register the XML-RPC introspection functions system.listMethods, system.methodHelp and system.methodSignature.</description>

26534

26535

</element>

26536

26537

26538

<description>Register the XML-RPC multicall function system.multicall.</description>

26539

26540

</element>

26541

26542

26543

<description>Handle a XML-RPC request. If request_text is given, it should be the POST data provided by the HTTP server, otherwise the contents of stdin will be used.</description>

26544

26545

26546

26547

</group>

26548

</group>

26549

26550

<description>Self-documenting XML-RPC server implementation.

26551

New in version 2.3

26552

The DocXMLRPCServer module extends the classes found in

26553

SimpleXMLRPCServer to serve HTML documentation in response to

26554

HTTP GET requests. Servers can either be free standing, using

26555

DocXMLRPCServer, or embedded in a CGI environment, using

26556

DocCGIXMLRPCRequestHandler.

26557

</description>

26558

26559

<description>Create a new server instance. All parameters have the same meaning as

26560

for SimpleXMLRPCServer.SimpleXMLRPCServer;

26561

requestHandler defaults to DocXMLRPCRequestHandler.</description>

26562

26563

26564

26565

26566

<description>Create a new instance to handle XML-RPC requests in a CGI environment.</description>

26567

26568

</element>

26569

26570

26571

<description>Create a new request handler instance. This request handler supports

26572

XML-RPC POST requests, documentation GET requests, and modifies

26573

logging so that the logRequests parameter to the

26574

DocXMLRPCServer constructor parameter is honored.</description>

26575

26576

</element>

26577

26578

26579

<description>The DocXMLRPCServer class is derived from

26580

SimpleXMLRPCServer.SimpleXMLRPCServer and provides a means of

26581

creating self-documenting, stand alone XML-RPC servers. HTTP POST

26582

requests are handled as XML-RPC method calls. HTTP GET requests are

26583

handled by generating pydoc-style HTML documentation. This allows a

26584

server to provide its own web-based documentation.

26585

</description>

26586

26587

<description>Set the title used in the generated HTML documentation. This title

26588

will be used inside the HTML "title" element.</description>

26589

26590

26591

26592

26593

<description>Set the name used in the generated HTML documentation. This name will

26594

appear at the top of the generated documentation inside a "h1"

26595

element.</description>

26596

26597

26598

26599

26600

<description>Set the description used in the generated HTML documentation. This

26601

description will appear as a paragraph, below the server name, in the

26602

documentation.</description>

26603

26604

26605

26606

</group>

26607

26608

<description>The DocCGIXMLRPCRequestHandler class is derived from

26609

SimpleXMLRPCServer.CGIXMLRPCRequestHandler and provides a means

26610

of creating self-documenting, XML-RPC CGI scripts. HTTP POST requests

26611

are handled as XML-RPC method calls. HTTP GET requests are handled by

26612

generating pydoc-style HTML documentation. This allows a server to

26613

provide its own web-based documentation.

26614

</description>

26615

26616

<description>Set the title used in the generated HTML documentation. This title

26617

will be used inside the HTML "title" element.</description>

26618

26619

26620

26621

26622

<description>Set the name used in the generated HTML documentation. This name will

26623

appear at the top of the generated documentation inside a "h1"

26624

element.</description>

26625

26626

26627

26628

26629

<description>Set the description used in the generated HTML documentation. This

26630

description will appear as a paragraph, below the server name, in the

26631

documentation.</description>

26632

26633

26634

26635

</group>

26636

</group>

26637

26638

<description>A base class for developing asynchronous socket handling services.

26639

% Heavily adapted from original documentation by Sam Rushing.

26640

This module provides the basic infrastructure for writing asynchronous socket service clients and servers.

26641

There are only two ways to have a program on a single processor do ``more than one thing at a time.'' Multi-threaded programming is the simplest and most popular way to do it, but there is another very different technique, that lets you have nearly all the advantages of multi-threading, without actually using multiple threads. It's really only practical if your program is largely I/O bound. If your program is processor bound, then pre-emptive scheduled threads are probably what you really need. Network servers are rarely processor bound, however.

26642

If your operating system supports the select() system call in its I/O library (and nearly all do), then you can use it to juggle multiple communication channels at once; doing other work while your I/O is taking place in the ``background.'' Although this strategy can seem strange and complex, especially at first, it is in many ways easier to understand and control than multi-threaded programming. The asyncore module solves many of the difficult problems for you, making the task of building sophisticated high-performance network servers and clients a snap. For ``conversational'' applications

26643

and protocols the companion asynchat module is invaluable.

26644

The basic idea behind both modules is to create one or more network

26645

channels, instances of class asyncore.dispatcher and

26646

asynchat.async_chat. Creating the channels adds them to a global

26647

map, used by the loop() function if you do not provide it

26648

with your own map.

26649

Once the initial channel(s) is(are) created, calling the loop()

26650

function activates channel service, which continues until the last

26651

channel (including any that have been added to the map during asynchronous

26652

service) is closed.

26653

</description>

26654

26655

<description>Enter a polling loop that only terminates after all open channels

26656

have been closed. All arguments are optional. The timeout

26657

argument sets the timeout parameter for the appropriate

26658

select() or poll() call, measured in seconds;

26659

the default is 30 seconds. The use_poll parameter, if true,

26660

indicates that poll() should be used in preference to

26661

select() (the default is False). The map parameter

26662

is a dictionary whose items are the channels to watch. As channels

26663

are closed they are deleted from their map. If map is

26664

omitted, a global map is used (this map is updated by the default

26665

class __init__()

26666

-- make sure you extend, rather than override, __init__()

26667

if you want to retain this behavior).

26668

Channels (instances of asyncore.dispatcher, asynchat.async_chat

26669

and subclasses thereof) can freely be mixed in the map.</description>

26670

26671

26672

26673

26674

<description>The dispatcher class is a thin wrapper around a low-level socket object.

26675

To make it more useful, it has a few methods for event-handling which are called

26676

from the asynchronous loop. Otherwise, it can be treated as a normal non-blocking socket object.

26677

Two class attributes can be modified, to improve performance,

26678

or possibly even to conserve memory.

26679

{ac_in_buffer_size}

26680

The asynchronous input buffer size (default 4096).

26681

{ac_out_buffer_size}

26682

The asynchronous output buffer size (default 4096).

26683

The firing of low-level events at certain times or in certain connection

26684

states tells the asynchronous loop that certain higher-level events have

26685

taken place. For example, if we have asked for a socket to connect to

26686

another host, we know that the connection has been made when the socket

26687

becomes writable for the first time (at this point you know that you may

26688

write to it with the expectation of success). The implied higher-level

26689

events are:

26690

{l|l}{code}{Event}{Description}

26691

handle_connect(){Implied by the first write event}

26692

handle_close(){Implied by a read event with no data available}

26693

handle_accept(){Implied by a read event on a listening socket}

26694

During asynchronous processing, each mapped channel's readable()

26695

and writable() methods are used to determine whether the channel's

26696

socket should be added to the list of channels select()ed or

26697

poll()ed for read and write events.</description>

26698

26699

</element>

26700

26701

26702

<description>Called when the asynchronous loop detects that a read()

26703

call on the channel's socket will succeed.</description>

26704

26705

</element>

26706

26707

26708

<description>Called when the asynchronous loop detects that a writable socket

26709

can be written. Often this method will implement the necessary buffering for performance. For example:

26710

def handle_write(self):

26711

sent = self.send(self.buffer)

26712

self.buffer = self.buffer[sent:]

26713

</description>

26714

26715

</element>

26716

26717

26718

<description>Called when there is out of band (OOB) data for a socket connection. This will almost never happen, as OOB is tenuously supported and rarely used.</description>

26719

26720

</element>

26721

26722

26723

<description>Called when the active opener's socket actually makes a connection.

26724

Might send a ``welcome'' banner, or initiate a protocol

26725

negotiation with the remote endpoint, for example.</description>

26726

26727

</element>

26728

26729

26730

<description>Called when the socket is closed.</description>

26731

26732

</element>

26733

26734

26735

<description>Called when an exception is raised and not otherwise handled. The default

26736

version prints a condensed traceback.</description>

26737

26738

</element>

26739

26740

26741

<description>Called on listening channels (passive openers) when a connection can be established with a new remote endpoint that

26742

has issued a connect() call for the local endpoint.</description>

26743

26744

</element>

26745

26746

26747

<description>Called each time around the asynchronous loop to determine whether a

26748

channel's socket should be added to the list on which read events can

26749

occur. The default method simply returns True, indicating that by default, all channels will be interested in

26750

read events.</description>

26751

26752

</element>

26753

26754

26755

<description>Called each time around the asynchronous loop to determine whether a

26756

channel's socket should be added to the list on which write events can

26757

occur. The default method simply returns True, indicating that by default, all channels will be interested in

26758

write events.</description>

26759

26760

</element>

26761

26762

26763

<description>This is identical to the creation of a normal socket, and will use the same options for creation. Refer to the

26764

socket documentation for information on creating

26765

sockets.</description>

26766

26767

26768

26769

26770

<description>As with the normal socket object, address is a tuple with the first element the host to connect to, and the second the port number.</description>

26771

26772

26773

26774

26775

<description>Send data to the remote end-point of the socket.</description>

26776

26777

26778

26779

26780

<description>Read at most buffer_size bytes from the socket's remote end-point.

26781

An empty string implies that the channel has been closed from the other

26782

end.</description>

26783

26784

26785

26786

26787

<description>Listen for connections made to the socket. The backlog

26788

argument specifies the maximum number of queued connections

26789

and should be at least 1; the maximum value is

26790

system-dependent (usually 5).</description>

26791

26792

26793

26794

26795

<description>Bind the socket to address. The socket must not already

26796

be bound. (The format of address depends on the address

26797

family --- see above.)</description>

26798

26799

26800

26801

26802

<description>Accept a connection. The socket must be bound to an address

26803

and listening for connections. The return value is a pair

26804

(conn, address) where conn is a

26805

new socket object usable to send and receive data on

26806

the connection, and address is the address bound to the

26807

socket on the other end of the connection.</description>

26808

26809

</element>

26810

26811

26812

<description>Close the socket. All future operations on the socket object

26813

will fail. The remote end-point will receive no more data (after

26814

queued data is flushed). Sockets are automatically closed

26815

when they are garbage-collected.</description>

26816

26817

</element>

26818

26819

26820

</group>

26821

</group>

26822

26823

<description>Support for asynchronous command/response protocols.

26824

This module builds on the asyncore infrastructure,

26825

simplifying asynchronous clients and servers and making it easier to

26826

handle protocols whose elements are terminated by arbitrary strings, or

26827

are of variable length. asynchat defines the abstract class

26828

async_chat that you subclass, providing implementations of the

26829

collect_incoming_data() and found_terminator()

26830

methods. It uses the same asynchronous loop as asyncore, and

26831

the two types of channel, asyncore.dispatcher and

26832

asynchat.async_chat, can freely be mixed in the channel map.

26833

Typically an asyncore.dispatcher server channel generates new

26834

asynchat.async_chat channel objects as it receives incoming

26835

connection requests. </description>

26836

26837

<description>This class is an abstract subclass of asyncore.dispatcher. To make

26838

practical use of the code you must subclass async_chat, providing

26839

meaningful collect_incoming_data() and found_terminator()

26840

methods. The asyncore.dispatcher methods can be

26841

used, although not all make sense in a message/response context. Like asyncore.dispatcher, async_chat defines a set of events

26842

that are generated by an analysis of socket conditions after a

26843

select() call. Once the polling loop has been started the

26844

async_chat object's methods are called by the event-processing

26845

framework with no action on the part of the programmer.

26846

Unlike asyncore.dispatcher, async_chat allows you to define

26847

a first-in-first-out queue (fifo) of producers. A producer need have

26848

only one method, more(), which should return data to be transmitted

26849

on the channel. The producer indicates exhaustion (i.e. that it contains

26850

no more data) by having its more() method return the empty string. At

26851

this point the async_chat object removes the producer from the fifo

26852

and starts using the next producer, if any. When the producer fifo is empty

26853

the handle_write() method does nothing. You use the channel object's

26854

set_terminator() method to describe how to recognize the end

26855

of, or an important breakpoint in, an incoming transmission from the

26856

remote endpoint.

26857

To build a functioning async_chat subclass your input methods collect_incoming_data() and

26858

found_terminator() must handle the data that the channel receives

26859

asynchronously. The methods are described below.</description>

26860

26861

</element>

26862

26863

26864

<description>Pushes a None on to the producer fifo. When this producer is

26865

popped off the fifo it causes the channel to be closed.</description>

26866

26867

</element>

26868

26869

26870

<description>Called with data holding an arbitrary amount of received data.

26871

The default method, which must be overridden, raises a NotImplementedError exception.</description>

26872

26873

26874

26875

26876

<description>In emergencies this method will discard any data held in the input and/or

26877

output buffers and the producer fifo.</description>

26878

26879

</element>

26880

26881

26882

<description>Called when the incoming data stream matches the termination condition

26883

set by set_terminator. The default method, which must be overridden,

26884

raises a NotImplementedError exception. The buffered input data should

26885

be available via an instance attribute.</description>

26886

26887

</element>

26888

26889

26890

<description>Returns the current terminator for the channel.</description>

26891

26892

</element>

26893

26894

26895

<description>Called when the channel is closed. The default method silently closes

26896

the channel's socket.</description>

26897

26898

</element>

26899

26900

26901

<description>Called when a read event fires on the channel's socket in the

26902

asynchronous loop. The default method checks for the termination

26903

condition established by set_terminator(), which can be either

26904

the appearance of a particular string in the input stream or the receipt

26905

of a particular number of characters. When the terminator is found,

26906

handle_read calls the found_terminator() method after

26907

calling collect_incoming_data() with any data preceding the

26908

terminating condition.</description>

26909

26910

</element>

26911

26912

26913

<description>Called when the application may write data to the channel. The default method calls the initiate_send() method, which in turn

26914

will call refill_buffer() to collect data from the producer

26915

fifo associated with the channel.</description>

26916

26917

</element>

26918

26919

26920

<description>Creates a simple_producer object (see below) containing the data and

26921

pushes it on to the channel's producer_fifo to ensure its

26922

transmission. This is all you need to do to have the channel write

26923

the data out to the network, although it is possible to use your

26924

own producers in more complex schemes to implement encryption and

26925

chunking, for example.</description>

26926

26927

26928

26929

26930

<description>Takes a producer object and adds it to the producer fifo associated with

26931

the channel. When all currently-pushed producers have been exhausted

26932

the channel will consume this producer's data by calling its

26933

more() method and send the data to the remote endpoint.</description>

26934

26935

26936

26937

26938

<description>Should return True for the channel to be included in the set of

26939

channels tested by the select() loop for readability.</description>

26940

26941

</element>

26942

26943

26944

<description>Refills the output buffer by calling the more() method of the

26945

producer at the head of the fifo. If it is exhausted then the

26946

producer is popped off the fifo and the next producer is activated.

26947

If the current producer is, or becomes, None then the channel

26948

is closed.</description>

26949

26950

</element>

26951

26952

26953

<description>Sets the terminating condition to be recognised on the channel. term

26954

may be any of three types of value, corresponding to three different ways

26955

to handle incoming protocol data.

26956

{l|l}{}{term}{Description}

26957

string{Will call found_terminator() when the

26958

string is found in the input stream}

26959

integer{Will call found_terminator() when the

26960

indicated number of characters have been received}

26961

None{The channel continues to collect data forever}

26962

Note that any data following the terminator will be available for reading by

26963

the channel after found_terminator() is called.</description>

26964

26965

26966

26967

26968

<description>Should return True as long as items remain on the producer fifo,

26969

or the channel is connected and the channel's output buffer is non-empty.</description>

26970

26971

</element>

26972

26973

26974

26975

<description>A simple_producer takes a chunk of data and an optional buffer size.

26976

Repeated calls to its more() method yield successive chunks of the

26977

data no larger than buffer_size.</description>

26978

26979

26980

26981

26982

<description>Produces the next chunk of information from the producer, or returns the empty string.</description>

26983

26984

</element>

26985

26986

26987

<description>Each channel maintains a fifo holding data which has been pushed by the

26988

application but not yet popped for writing to the channel.

26989

A fifo is a list used to hold data and/or producers until they are required.

26990

If the list argument is provided then it should contain producers or

26991

data items to be written to the channel.</description>

26992

26993

26994

26995

26996

<description>Returns True iff the fifo is empty.</description>

26997

26998

</element>

26999

27000

27001

<description>Returns the least-recently push()ed item from the fifo.</description>

27002

27003

</element>

27004

27005

27006

<description>Adds the given data (which may be a string or a producer object) to the

27007

producer fifo.</description>

27008

27009

27010

27011

27012

<description>If the fifo is not empty, returns True, first(), deleting the popped

27013

item. Returns False, None for an empty fifo.</description>

27014

27015

</element>

27016

27017

27018

<description>Returns True if string haystack ends with any non-empty

27019

prefix of string needle.</description>

27020

27021

27022

27023

</group>

27024

27025

</group>

27026

</group>

27027

</group>

27028

27029

27030

<description>Generic output formatter and device interface.

27031

This module supports two interface definitions, each with multiple

27032

implementations. The formatter interface is used by the

27033

HTMLParser class of the htmllib module, and the

27034

writer interface is required by the formatter interface.

27035

(class in htmllib){HTMLParser}

27036

Formatter objects transform an abstract flow of formatting events into

27037

specific output events on writer objects. Formatters manage several

27038

stack structures to allow various properties of a writer object to be

27039

changed and restored; writers need not be able to handle relative

27040

changes nor any sort of ``change back'' operation. Specific writer

27041

properties which may be controlled via formatter objects are

27042

horizontal alignment, font, and left margin indentations. A mechanism

27043

is provided which supports providing arbitrary, non-exclusive style

27044

settings to a writer as well. Additional interfaces facilitate

27045

formatting events which are not reversible, such as paragraph

27046

separation.

27047

Writer objects encapsulate device interfaces. Abstract devices, such

27048

as file formats, are supported as well as physical devices. The

27049

provided implementations all work with abstract devices. The

27050

interface makes available mechanisms for setting the properties which

27051

formatter objects manage and inserting data into the output.

27052

</description>

27053

27054

<description>Interfaces to create formatters are dependent on the specific

27055

formatter class being instantiated. The interfaces described below

27056

are the required interfaces which all formatters must support once

27057

initialized.

27058

One data element is defined at the module level:

27059

{AS_IS}

27060

Value which can be used in the font specification passed to the

27061

push_font() method described below, or as the new value to any

27062

other push_property() method. Pushing the AS_IS

27063

value allows the corresponding pop_property() method to

27064

be called without having to track whether the property was changed.

27065

The following attributes are defined for formatter instance objects:

27066

[formatter]{writer}

27067

The writer instance with which the formatter interacts.

27068

</description>

27069

27070

<description>Close any open paragraphs and insert at least blanklines

27071

before the next paragraph.</description>

27072

27073

27074

27075

27076

<description>Add a hard line break if one does not already exist. This does not

27077

break the logical paragraph.</description>

27078

27079

</element>

27080

27081

27082

<description>Insert a horizontal rule in the output. A hard break is inserted if

27083

there is data in the current paragraph, but the logical paragraph is

27084

not broken. The arguments and keywords are passed on to the writer's

27085

send_line_break() method.</description>

27086

27087

27088

27089

27090

<description>Provide data which should be formatted with collapsed whitespace.

27091

Whitespace from preceding and successive calls to

27092

add_flowing_data() is considered as well when the whitespace

27093

collapse is performed. The data which is passed to this method is

27094

expected to be word-wrapped by the output device. Note that any

27095

word-wrapping still must be performed by the writer object due to the

27096

need to rely on device and font information.</description>

27097

27098

27099

27100

27101

<description>Provide data which should be passed to the writer unchanged.

27102

Whitespace, including newline and tab characters, are considered legal

27103

in the value of data.</description>

27104

27105

27106

27107

27108

<description>Insert a label which should be placed to the left of the current left

27109

margin. This should be used for constructing bulleted or numbered

27110

lists. If the format value is a string, it is interpreted as a

27111

format specification for counter, which should be an integer.

27112

The result of this formatting becomes the value of the label; if

27113

format is not a string it is used as the label value directly.

27114

The label value is passed as the only argument to the writer's

27115

send_label_data() method. Interpretation of non-string label

27116

values is dependent on the associated writer.

27117

Format specifications are strings which, in combination with a counter

27118

value, are used to compute label values. Each character in the format

27119

string is copied to the label value, with some characters recognized

27120

to indicate a transform on the counter value. Specifically, the

27121

character 1 represents the counter value formatter as an

27122

Arabic number, the characters A and a

27123

represent alphabetic representations of the counter value in upper and

27124

lower case, respectively, and I and i

27125

represent the counter value in Roman numerals, in upper and lower

27126

case. Note that the alphabetic and roman transforms require that the

27127

counter value be greater than zero.</description>

27128

27129

27130

27131

27132

<description>Send any pending whitespace buffered from a previous call to

27133

add_flowing_data() to the associated writer object. This

27134

should be called before any direct manipulation of the writer object.</description>

27135

27136

</element>

27137

27138

27139

<description>Push a new alignment setting onto the alignment stack. This may be

27140

AS_IS if no change is desired. If the alignment value is

27141

changed from the previous setting, the writer's new_alignment()

27142

method is called with the align value.</description>

27143

27144

27145

27146

27147

<description>Restore the previous alignment.</description>

27148

27149

</element>

27150

27151

27152

<description>Change some or all font properties of the writer object. Properties

27153

which are not set to AS_IS are set to the values passed in

27154

while others are maintained at their current settings. The writer's

27155

new_font() method is called with the fully resolved font

27156

specification.</description>

27157

27158

27159

27160

27161

<description>Restore the previous font.</description>

27162

27163

</element>

27164

27165

27166

<description>Increase the number of left margin indentations by one, associating

27167

the logical tag margin with the new indentation. The initial

27168

margin level is 0. Changed values of the logical tag must be

27169

true values; false values other than AS_IS are not

27170

sufficient to change the margin.</description>

27171

27172

27173

27174

27175

<description>Restore the previous margin.</description>

27176

27177

</element>

27178

27179

27180

<description>Push any number of arbitrary style specifications. All styles are

27181

pushed onto the styles stack in order. A tuple representing the

27182

entire stack, including AS_IS values, is passed to the

27183

writer's new_styles() method.</description>

27184

27185

27186

27187

27188

<description>Pop the last n style specifications passed to

27189

push_style(). A tuple representing the revised stack,

27190

including AS_IS values, is passed to the writer's

27191

new_styles() method.</description>

27192

27193

27194

27195

27196

<description>Set the spacing style for the writer.</description>

27197

27198

27199

27200

27201

<description>Inform the formatter that data has been added to the current paragraph

27202

out-of-band. This should be used when the writer has been manipulated

27203

directly. The optional flag argument can be set to false if

27204

the writer manipulations produced a hard line break at the end of the

27205

output.</description>

27206

27207

27208

27209

</group>

27210

27211

<description>Two implementations of formatter objects are provided by this module.

27212

Most applications may use one of these classes without modification or

27213

subclassing.

27214

</description>

27215

27216

<description>A formatter which does nothing. If writer is omitted, a

27217

NullWriter instance is created. No methods of the writer are

27218

called by NullFormatter instances. Implementations should

27219

inherit from this class if implementing a writer interface but don't

27220

need to inherit any implementation.</description>

27221

27222

27223

27224

27225

<description>The standard formatter. This implementation has demonstrated wide

27226

applicability to many writers, and may be used directly in most

27227

circumstances. It has been used to implement a full-featured

27228

World Wide Web browser.</description>

27229

27230

27231

27232

</group>

27233

27234

<description>Interfaces to create writers are dependent on the specific writer

27235

class being instantiated. The interfaces described below are the

27236

required interfaces which all writers must support once initialized.

27237

Note that while most applications can use the

27238

AbstractFormatter class as a formatter, the writer must

27239

typically be provided by the application.

27240

</description>

27241

27242

<description>Flush any buffered output or device control events.</description>

27243

27244

</element>

27245

27246

27247

<description>Set the alignment style. The align value can be any object,

27248

but by convention is a string or None, where None

27249

indicates that the writer's ``preferred'' alignment should be used.

27250

Conventional align values are 'left', 'center',

27251

'right', and 'justify'.</description>

27252

27253

27254

27255

27256

<description>Set the font style. The value of font will be None,

27257

indicating that the device's default font should be used, or a tuple

27258

of the form (size, italic, bold,

27259

teletype). Size will be a string indicating the size of

27260

font that should be used; specific strings and their interpretation

27261

must be defined by the application. The italic, bold, and

27262

teletype values are Boolean values specifying which of those

27263

font attributes should be used.</description>

27264

27265

27266

27267

27268

<description>Set the margin level to the integer level and the logical tag

27269

to margin. Interpretation of the logical tag is at the

27270

writer's discretion; the only restriction on the value of the logical

27271

tag is that it not be a false value for non-zero values of

27272

level.</description>

27273

27274

27275

27276

27277

<description>Set the spacing style to spacing.</description>

27278

27279

27280

27281

27282

<description>Set additional styles. The styles value is a tuple of

27283

arbitrary values; the value AS_IS should be ignored. The

27284

styles tuple may be interpreted either as a set or as a stack

27285

depending on the requirements of the application and writer

27286

implementation.</description>

27287

27288

27289

27290

27291

<description>Break the current line.</description>

27292

27293

</element>

27294

27295

27296

<description>Produce a paragraph separation of at least blankline blank

27297

lines, or the equivalent. The blankline value will be an

27298

integer. Note that the implementation will receive a call to

27299

send_line_break() before this call if a line break is needed; this method should not include ending the last line of the paragraph.

27300

It is only responsible for vertical spacing between paragraphs.</description>

27301

27302

27303

27304

27305

<description>Display a horizontal rule on the output device. The arguments to this

27306

method are entirely application- and writer-specific, and should be

27307

interpreted with care. The method implementation may assume that a

27308

line break has already been issued via send_line_break().</description>

27309

27310

27311

27312

27313

<description>Output character data which may be word-wrapped and re-flowed as

27314

needed. Within any sequence of calls to this method, the writer may

27315

assume that spans of multiple whitespace characters have been

27316

collapsed to single space characters.</description>

27317

27318

27319

27320

27321

<description>Output character data which has already been formatted

27322

for display. Generally, this should be interpreted to mean that line

27323

breaks indicated by newline characters should be preserved and no new

27324

line breaks should be introduced. The data may contain embedded

27325

newline and tab characters, unlike data provided to the

27326

send_formatted_data() interface.</description>

27327

27328

27329

27330

27331

<description>Set data to the left of the current left margin, if possible.

27332

The value of data is not restricted; treatment of non-string

27333

values is entirely application- and writer-dependent. This method

27334

will only be called at the beginning of a line.</description>

27335

27336

27337

27338

</group>

27339

27340

<description>Three implementations of the writer object interface are provided as

27341

examples by this module. Most applications will need to derive new

27342

writer classes from the NullWriter class.

27343

</description>

27344

27345

<description>A writer which only provides the interface definition; no actions are

27346

taken on any methods. This should be the base class for all writers

27347

which do not need to inherit any implementation methods.</description>

27348

27349

</element>

27350

27351

27352

<description>A writer which can be used in debugging formatters, but not much

27353

else. Each method simply announces itself by printing its name and

27354

arguments on standard output.</description>

27355

27356

</element>

27357

27358

27359

<description>Simple writer class which writes output on the file object passed in

27360

as file or, if file is omitted, on standard output. The

27361

output is simply word-wrapped to the number of columns specified by

27362

maxcol. This class is suitable for reflowing a sequence of

27363

paragraphs.</description>

27364

27365

27366

27367

</group>

27368

</group>

27369

27370

<description>Package supporting the parsing, manipulating, and

27371

generating email messages, including MIME documents.

27372

New in version 2.2

27373

The email package is a library for managing email messages,

27374

including MIME and other 2822-based message documents. It

27375

subsumes most of the functionality in several older standard modules

27376

such as rfc822, mimetools,

27377

multifile, and other non-standard packages such as

27378

mimecntl. It is specifically not designed to do any

27379

sending of email messages to SMTP (2821) servers; that is the

27380

function of the smtplib module. The email

27381

package attempts to be as RFC-compliant as possible, supporting in

27382

addition to 2822, such MIME-related RFCs as

27383

2045-2047, and 2231.

27384

The primary distinguishing feature of the email package is

27385

that it splits the parsing and generating of email messages from the

27386

internal object model representation of email. Applications

27387

using the email package deal primarily with objects; you can

27388

add sub-objects to messages, remove sub-objects from messages,

27389

completely re-arrange the contents, etc. There is a separate parser

27390

and a separate generator which handles the transformation from flat

27391

text to the object model, and then back to flat text again. There

27392

are also handy subclasses for some common MIME object types, and a few

27393

miscellaneous utilities that help with such common tasks as extracting

27394

and parsing message field values, creating RFC-compliant dates, etc.

27395

The following sections describe the functionality of the

27396

email package. The ordering follows a progression that

27397

should be common in applications: an email message is read as flat

27398

text from a file or other source, the text is parsed to produce the

27399

object structure of the email message, this structure is manipulated,

27400

and finally rendered back into flat text.

27401

It is perfectly feasible to create the object structure out of whole

27402

cloth --- i.e. completely from scratch. From there, a similar

27403

progression can be taken as above.

27404

Also included are detailed specifications of all the classes and

27405

modules that the email package provides, the exception

27406

classes you might encounter while using the email package,

27407

some auxiliary utilities, and a few examples. For users of the older

27408

mimelib package, or previous versions of the email

27409

package, a section on differences and porting is provided.

27410

smtplib{SMTP protocol client}

27411

</description>

27412

27413

<description>emailmessage

27414

</description>

27415

</group>

27416

27417

<description>emailparser

27418

</description>

27419

</group>

27420

27421

<description>emailgenerator

27422

</description>

27423

</group>

27424

27425

<description>emailmimebase

27426

</description>

27427

</group>

27428

27429

<description>emailheaders

27430

</description>

27431

</group>

27432

27433

<description>emailcharsets

27434

</description>

27435

</group>

27436

27437

<description>emailencoders

27438

</description>

27439

</group>

27440

27441

<description>emailexc

27442

</description>

27443

</group>

27444

27445

<description>emailutil

27446

</description>

27447

</group>

27448

27449

<description>emailiter

27450

</description>

27451

</group>

27452

27453

<description>Version 1 of the email package was bundled with Python

27454

releases up to Python 2.2.1. Version 2 was developed for the Python

27455

2.3 release, and backported to Python 2.2.2. It was also available as

27456

a separate distutils based package. email version 2 is

27457

almost entirely backward compatible with version 1, with the

27458

following differences:

27459

The email.Header and email.Charset modules

27460

have been added.

27461

The pickle format for Message instances has changed.

27462

Since this was never (and still isn't) formally defined, this

27463

isn't considered a backward incompatibility. However if your

27464

application pickles and unpickles Message instances, be

27465

aware that in email version 2, Message

27466

instances now have private variables _charset and

27467

_default_type.

27468

Several methods in the Message class have been

27469

deprecated, or their signatures changed. Also, many new methods

27470

have been added. See the documentation for the Message

27471

class for details. The changes should be completely backward

27472

compatible.

27473

The object structure has changed in the face of

27474

message/rfc822 content types. In email

27475

version 1, such a type would be represented by a scalar payload,

27476

i.e. the container message's is_multipart() returned

27477

false, get_payload() was not a list object, but a single

27478

Message instance.

27479

This structure was inconsistent with the rest of the package, so

27480

the object representation for message/rfc822 content

27481

types was changed. In email version 2, the container

27482

does return True from is_multipart(), and

27483

get_payload() returns a list containing a single

27484

Message item.

27485

Note that this is one place that backward compatibility could

27486

not be completely maintained. However, if you're already

27487

testing the return type of get_payload(), you should be

27488

fine. You just need to make sure your code doesn't do a

27489

set_payload() with a Message instance on a

27490

container with a content type of message/rfc822.

27491

The Parser constructor's strict argument was

27492

added, and its parse() and parsestr() methods

27493

grew a headersonly argument. The strict flag was

27494

also added to functions email.message_from_file()

27495

and email.message_from_string().

27496

Generator.__call__() is deprecated; use

27497

Generator.flatten() instead. The Generator

27498

class has also grown the clone() method.

27499

The DecodedGenerator class in the

27500

email.Generator module was added.

27501

The intermediate base classes MIMENonMultipart and

27502

MIMEMultipart have been added, and interposed in the

27503

class hierarchy for most of the other MIME-related derived

27504

classes.

27505

The _encoder argument to the MIMEText constructor

27506

has been deprecated. Encoding now happens implicitly based

27507

on the _charset argument.

27508

The following functions in the email.Utils module have

27509

been deprecated: dump_address_pairs(),

27510

decode(), and encode(). The following

27511

functions have been added to the module:

27512

make_msgid(), decode_rfc2231(),

27513

encode_rfc2231(), and decode_params().

27514

The non-public function email.Iterators._structure()

27515

was added.

27516

</description>

27517

</group>

27518

27519

<description>The email package was originally prototyped as a separate

27520

library called

27521

mimelib{http://mimelib.sf.net/}.

27522

Changes have been made so that

27523

method names are more consistent, and some methods or modules have

27524

either been added or removed. The semantics of some of the methods

27525

have also changed. For the most part, any functionality available in

27526

mimelib is still available in the email package,

27527

albeit often in a different way. Backward compatibility between

27528

the mimelib package and the email package was not a

27529

priority.

27530

Here is a brief description of the differences between the

27531

mimelib and the email packages, along with hints on

27532

how to port your applications.

27533

Of course, the most visible difference between the two packages is

27534

that the package name has been changed to email. In

27535

addition, the top-level package has the following differences:

27536

messageFromString() has been renamed to

27537

message_from_string().

27538

messageFromFile() has been renamed to

27539

message_from_file().

27540

The Message class has the following differences:

27541

The method asString() was renamed to as_string().

27542

The method ismultipart() was renamed to

27543

is_multipart().

27544

The get_payload() method has grown a decode

27545

optional argument.

27546

The method getall() was renamed to get_all().

27547

The method addheader() was renamed to add_header().

27548

The method gettype() was renamed to get_type().

27549

The methodgetmaintype() was renamed to

27550

get_main_type().

27551

The method getsubtype() was renamed to

27552

get_subtype().

27553

The method getparams() was renamed to

27554

get_params().

27555

Also, whereas getparams() returned a list of strings,

27556

get_params() returns a list of 2-tuples, effectively

27557

the key/value pairs of the parameters, split on the =

27558

sign.

27559

The method getparam() was renamed to get_param().

27560

The method getcharsets() was renamed to

27561

get_charsets().

27562

The method getfilename() was renamed to

27563

get_filename().

27564

The method getboundary() was renamed to

27565

get_boundary().

27566

The method setboundary() was renamed to

27567

set_boundary().

27568

The method getdecodedpayload() was removed. To get

27569

similar functionality, pass the value 1 to the decode flag

27570

of the {get_payload()} method.

27571

The method getpayloadastext() was removed. Similar

27572

functionality

27573

is supported by the DecodedGenerator class in the

27574

email.Generator module.

27575

The method getbodyastext() was removed. You can get

27576

similar functionality by creating an iterator with

27577

typed_subpart_iterator() in the

27578

email.Iterators module.

27579

The Parser class has no differences in its public interface.

27580

It does have some additional smarts to recognize

27581

message/delivery-status type messages, which it represents as

27582

a Message instance containing separate Message

27583

subparts for each header block in the delivery status

27584

notificationDelivery Status Notifications (DSN) are defined

27585

in 1894..

27586

The Generator class has no differences in its public

27587

interface. There is a new class in the email.Generator

27588

module though, called DecodedGenerator which provides most of

27589

the functionality previously available in the

27590

Message.getpayloadastext() method.

27591

The following modules and classes have been changed:

27592

The MIMEBase class constructor arguments _major

27593

and _minor have changed to _maintype and

27594

_subtype respectively.

27595

The Image class/module has been renamed to

27596

MIMEImage. The _minor argument has been renamed to

27597

_subtype.

27598

The Text class/module has been renamed to

27599

MIMEText. The _minor argument has been renamed to

27600

_subtype.

27601

The MessageRFC822 class/module has been renamed to

27602

MIMEMessage. Note that an earlier version of

27603

mimelib called this class/module RFC822, but

27604

that clashed with the Python standard library module

27605

rfc822 on some case-insensitive file systems.

27606

Also, the MIMEMessage class now represents any kind of

27607

MIME message with main type message. It takes an

27608

optional argument _subtype which is used to set the MIME

27609

subtype. _subtype defaults to rfc822.

27610

mimelib provided some utility functions in its

27611

address and date modules. All of these functions

27612

have been moved to the email.Utils module.

27613

The MsgReader class/module has been removed. Its functionality

27614

is most closely supported in the body_line_iterator()

27615

function in the email.Iterators module.

27616

</description>

27617

</group>

27618

27619

</group>

27620

</group>

27621

27622

<description>Mailcap file handling.

27623

Mailcap files are used to configure how MIME-aware applications such

27624

as mail readers and Web browsers react to files with different MIME

27625

types. (The name ``mailcap'' is derived from the phrase ``mail

27626

capability''.) For example, a mailcap file might contain a line like

27627

video/mpeg; xmpeg . Then, if the user encounters an email

27628

message or Web document with the MIME type video/mpeg,

27629

will be replaced by a filename (usually one belonging to a

27630

temporary file) and the xmpeg program can be automatically

27631

started to view the file.

27632

The mailcap format is documented in 1524, ``A User Agent

27633

Configuration Mechanism For Multimedia Mail Format Information,'' but

27634

is not an Internet standard. However, mailcap files are supported on

27635

most systems.

27636

</description>

27637

27638

<description>Return a 2-tuple; the first element is a string containing the command

27639

line to be executed

27640

(which can be passed to os.system()), and the second element is

27641

the mailcap entry for a given MIME type. If no matching MIME

27642

type can be found, (None, None) is returned.

27643

key is the name of the field desired, which represents the type

27644

of activity to be performed; the default value is 'view', since in the most common case you simply want to view the body of the MIME-typed

27645

data. Other possible values might be 'compose' and 'edit', if you

27646

wanted to create a new body of the given MIME type or alter the

27647

existing body data. See 1524 for a complete list of these

27648

fields.

27649

filename is the filename to be substituted for in the

27650

command line; the default value is

27651

'/dev/null' which is almost certainly not what you want, so

27652

usually you'll override it by specifying a filename.

27653

plist can be a list containing named parameters; the default

27654

value is simply an empty list. Each entry in the list must be a

27655

string containing the parameter name, an equals sign (=),

27656

and the parameter's value. Mailcap entries can contain named parameters like %{foo}, which will be replaced by the

27657

value of the parameter named 'foo'. For example, if the command line

27658

showpartial %{id}{number}{total}

27659

was in a mailcap file, and plist was set to ['id=1',

27660

'number=2', 'total=3'], the resulting command line would be 'showpartial 1 2 3'. In a mailcap file, the ``test'' field can optionally be specified to

27661

test some external condition (such as the machine architecture, or the

27662

window system in use) to determine whether or not the mailcap line

27663

applies. findmatch() will automatically check such

27664

conditions and skip the entry if the check fails.</description>

27665

27666

27667

27668

27669

<description>Returns a dictionary mapping MIME types to a list of mailcap file

27670

entries. This dictionary must be passed to the findmatch()

27671

function. An entry is stored as a list of dictionaries, but it

27672

shouldn't be necessary to know the details of this representation.

27673

The information is derived from all of the mailcap files found on the

27674

system. Settings in the user's mailcap file /.mailcap

27675

will override settings in the system mailcap files

27676

/etc/mailcap, /usr/etc/mailcap, and

27677

/usr/local/etc/mailcap.</description>

27678

27679

</element>

27680

27681

</group>

27682

27683

<description>Read various mailbox formats.

27684

This module defines a number of classes that allow easy and uniform

27685

access to mail messages in a () mailbox.

27686

</description>

27687

27688

<description>Access to a classic -style mailbox, where all messages are

27689

contained in a single file and separated by From (a.k.a. From_) lines. The file object fp points to the

27690

mailbox file. The optional factory parameter is a callable that

27691

should create new message objects. factory is called with one

27692

argument, fp by the next() method of the mailbox

27693

object. The default is the rfc822.Message class (see the

27694

rfc822 module -- and the note below).

27695

For maximum portability, messages in a -style mailbox are

27696

separated by any line that begins exactly with the string 'From

27697

' (note the trailing space) if preceded by exactly two newlines.

27698

Because of the wide-range of variations in practice, nothing else on

27699

the From_ line should be considered. However, the current

27700

implementation doesn't check for the leading two newlines. This is

27701

usually fine for most applications.

27702

The UnixMailbox class implements a more strict version of

27703

From_ line checking, using a regular expression that usually correctly

27704

matched From_ delimiters. It considers delimiter line to be separated

27705

by From name time lines. For maximum portability,

27706

use the PortableUnixMailbox class instead. This class is

27707

identical to UnixMailbox except that individual messages are

27708

separated by only From lines.

27709

For more information, see

27710

Configuring

27711

Netscape Mail on : Why the Content-Length Format is Bad.</description>

27712

27713

27714

27715

27716

<description>A less-strict version of UnixMailbox, which considers only the

27717

From at the beginning of the line separating messages. The

27718

``name time'' portion of the From line is ignored, to

27719

protect against some variations that are observed in practice. This

27720

works since lines in the message which begin with 'From ' are

27721

quoted by mail handling software at delivery-time.</description>

27722

27723

27724

27725

27726

<description>Access an MMDF-style mailbox, where all messages are contained

27727

in a single file and separated by lines consisting of 4 control-A

27728

characters. The file object fp points to the mailbox file.

27729

Optional factory is as with the UnixMailbox class.</description>

27730

27731

27732

27733

27734

<description>Access an MH mailbox, a directory with each message in a separate

27735

file with a numeric name.

27736

The name of the mailbox directory is passed in dirname.

27737

factory is as with the UnixMailbox class.</description>

27738

27739

27740

27741

27742

<description>Access a Qmail mail directory. All new and current mail for the

27743

mailbox specified by dirname is made available.

27744

factory is as with the UnixMailbox class.</description>

27745

27746

27747

27748

27749

<description>Access a Babyl mailbox, which is similar to an MMDF mailbox. In

27750

Babyl format, each message has two sets of headers, the

27751

original headers and the visible headers. The original

27752

headers appear before a line containing only '*** EOOH ***'

27753

(End-Of-Original-Headers) and the visible headers appear after the

27754

EOOH line. Babyl-compliant mail readers will show you only the

27755

visible headers, and BabylMailbox objects will return messages

27756

containing only the visible headers. You'll have to do your own

27757

parsing of the mailbox file to get at the original headers. Mail

27758

messages start with the EOOH line and end with a line containing only

27759

'037014'. factory is as with the

27760

UnixMailbox class.</description>

27761

27762

27763

27764

27765

<description>All implementations of mailbox objects are iterable objects, and

27766

have one externally visible method. This method is used by iterators

27767

created from mailbox objects and may also be used directly.

27768

</description>

27769

27770

<description>Return the next message in the mailbox, created with the optional

27771

factory argument passed into the mailbox object's constructor.

27772

By default this is an rfc822.Message

27773

object (see the rfc822 module). Depending on the mailbox

27774

implementation the fp attribute of this object may be a true

27775

file object or a class instance simulating a file object, taking care

27776

of things like message boundaries if multiple mail messages are

27777

contained in a single file, etc. If no more messages are available,

27778

this method returns None.</description>

27779

27780

</element>

27781

27782

</group>

27783

</group>

27784

27785

<description>% LaTeX'ized from the comments in the module by Skip Montanaro

27786

% <skip@mojam.com>.

27787

Manipulate MH mailboxes from Python.

27788

The mhlib module provides a Python interface to MH folders and

27789

their contents.

27790

The module contains three basic classes, MH, which represents a

27791

particular collection of folders, Folder, which represents a single

27792

folder, and Message, which represents a single message.

27793

</description>

27794

27795

<description>MH represents a collection of MH folders.</description>

27796

27797

27798

27799

27800

<description>The Folder class represents a single folder and its messages.</description>

27801

27802

27803

27804

27805

<description>Message objects represent individual messages in a folder. The

27806

Message class is derived from mimetools.Message.</description>

27807

27808

27809

27810

27811

<description>MH instances have the following methods:

27812

</description>

27813

27814

<description>Print an error message -- can be overridden.</description>

27815

27816

27817

27818

27819

<description>Return a profile entry (None if not set).</description>

27820

27821

27822

27823

27824

<description>Return the mailbox pathname.</description>

27825

27826

</element>

27827

27828

27829

<description>Return the current folder name.</description>

27830

27831

</element>

27832

27833

27834

<description>Set the current folder name.</description>

27835

27836

27837

27838

27839

<description>Return a list of top-level folders.</description>

27840

27841

</element>

27842

27843

27844

<description>Return a list of all folders.</description>

27845

27846

</element>

27847

27848

27849

<description>Return a list of direct subfolders of the given folder.</description>

27850

27851

27852

27853

27854

<description>Return a list of all subfolders of the given folder.</description>

27855

27856

27857

27858

27859

<description>Create a new folder.</description>

27860

27861

27862

27863

27864

<description>Delete a folder -- must have no subfolders.</description>

27865

27866

27867

27868

27869

<description>Return a new open folder object.</description>

27870

27871

27872

27873

</group>

27874

27875

<description>Folder instances represent open folders and have the following

27876

methods:

27877

</description>

27878

27879

<description>Print an error message -- can be overridden.</description>

27880

27881

27882

27883

27884

<description>Return the folder's full pathname.</description>

27885

27886

</element>

27887

27888

27889

<description>Return the full pathname of the folder's sequences file.</description>

27890

27891

</element>

27892

27893

27894

<description>Return the full pathname of message n of the folder.</description>

27895

27896

27897

27898

27899

<description>Return a list of messages in the folder (as numbers).</description>

27900

27901

</element>

27902

27903

27904

<description>Return the current message number.</description>

27905

27906

</element>

27907

27908

27909

<description>Set the current message number to n.</description>

27910

27911

27912

27913

27914

<description>Parse msgs syntax into list of messages.</description>

27915

27916

27917

27918

27919

<description>Get last message, or 0 if no messages are in the folder.</description>

27920

27921

</element>

27922

27923

27924

<description>Set last message (internal use only).</description>

27925

27926

27927

27928

27929

<description>Return dictionary of sequences in folder. The sequence names are used as keys, and the values are the lists of message numbers in the

27930

sequences.</description>

27931

27932

</element>

27933

27934

27935

<description>Return dictionary of sequences in folder {name: list}.</description>

27936

27937

27938

27939

27940

<description>Remove messages in list from folder.</description>

27941

27942

27943

27944

27945

<description>Move messages in list to other folder.</description>

27946

27947

27948

27949

27950

<description>Move one message to a given destination in another folder.</description>

27951

27952

27953

27954

27955

<description>Copy one message to a given destination in another folder.</description>

27956

27957

27958

27959

</group>

27960

27961

<description>The Message class adds one method to those of

27962

mimetools.Message:

27963

</description>

27964

27965

<description>Return a new open message object (costs a file descriptor).</description>

27966

27967

27968

27969

</group>

27970

</group>

27971

27972

<description>Tools for parsing MIME-style message bodies.

27973

2.3{The email package should be used in

27974

preference to the mimetools module. This

27975

module is present only to maintain backward

27976

compatibility.}

27977

This module defines a subclass of the

27978

rfc822rfc822 module's

27979

Message class and a number of utility functions that are

27980

useful for the manipulation for MIME multipart or encoded message.

27981

It defines the following items:

27982

</description>

27983

27984

<description>Return a new instance of the Message class. This is a

27985

subclass of the rfc822.Message class, with some additional

27986

methods (see below). The seekable argument has the same meaning

27987

as for rfc822.Message.</description>

27988

27989

27990

27991

27992

<description>Return a unique string that has a high likelihood of being usable as a

27993

part boundary. The string has the form

27994

'hostipaddr.uid.pid.timestamp.random'.</description>

27995

27996

</element>

27997

27998

27999

<description>Read data encoded using the allowed MIME encoding from open file

28000

object input and write the decoded data to open file object

28001

output. Valid values for encoding include

28002

'base64', 'quoted-printable', 'uuencode',

28003

'x-uuencode', 'uue', 'x-uue', '7bit', and '8bit'. Decoding messages encoded in '7bit' or '8bit'

28004

has no effect. The input is simply copied to the output.</description>

28005

28006

28007

28008

28009

<description>Read data from open file object input and write it encoded using

28010

the allowed MIME encoding to open file object output.

28011

Valid values for encoding are the same as for decode().</description>

28012

28013

28014

28015

28016

<description>Read lines from open file input until and write them to

28017

open file output.</description>

28018

28019

28020

28021

28022

<description>Read blocks until from open file input and write them to

28023

open file output. The block size is currently fixed at 8192.</description>

28024

28025

28026

28027

28028

<description>The Message class defines the following methods in

28029

addition to the rfc822.Message methods:

28030

</description>

28031

28032

<description>Return the parameter list of the Content-Type header.

28033

This is a list of strings. For parameters of the form

28034

key=value, key is converted to lower case but

28035

value is not. For example, if the message contains the header

28036

Content-type: text/html; spam=1; Spam=2; Spam then

28037

getplist() will return the Python list ['spam=1',

28038

'spam=2', 'Spam'].</description>

28039

28040

</element>

28041

28042

28043

<description>Return the value of the first parameter (as returned by

28044

getplist()) of the form name=value for the

28045

given name. If value is surrounded by quotes of the form

28046

`<...>' or `"..."', these are removed.</description>

28047

28048

28049

28050

28051

<description>Return the encoding specified in the

28052

Content-Transfer-Encoding message header. If no such

28053

header exists, return '7bit'. The encoding is converted to

28054

lower case.</description>

28055

28056

</element>

28057

28058

28059

<description>Return the message type (of the form type/subtype)

28060

as specified in the Content-Type header. If no such

28061

header exists, return 'text/plain'. The type is converted to

28062

lower case.</description>

28063

28064

</element>

28065

28066

28067

<description>Return the main type as specified in the Content-Type

28068

header. If no such header exists, return 'text'. The main

28069

type is converted to lower case.</description>

28070

28071

</element>

28072

28073

28074

<description>Return the subtype as specified in the Content-Type

28075

header. If no such header exists, return 'plain'. The subtype

28076

is converted to lower case.</description>

28077

28078

</element>

28079

28080

</group>

28081

</group>

28082

28083

<description>Mapping of filename extensions to MIME types.

28084

The mimetypes module converts between a filename or URL and

28085

the MIME type associated with the filename extension. Conversions are

28086

provided from filename to MIME type and from MIME type to filename

28087

extension; encodings are not supported for the latter conversion.

28088

The module provides one class and a number of convenience functions.

28089

The functions are the normal interface to this module, but some

28090

applications may be interested in the class as well.

28091

The functions described below provide the primary interface for this

28092

module. If the module has not been initialized, they will call

28093

init() if they rely on the information init()

28094

sets up.

28095

</description>

28096

28097

<description>Guess the type of a file based on its filename or URL, given by

28098

filename. The return value is a tuple (type,

28099

encoding) where type is None if the type can't be

28100

guessed (missing or unknown suffix) or a string of the form

28101

'type/subtype', usable for a MIME

28102

content-type header.

28103

encoding is None for no encoding or the name of the

28104

program used to encode (e.g. compress or gzip).

28105

The encoding is suitable for use as a Content-Encoding

28106

header, not as a Content-Transfer-Encoding header.

28107

The mappings are table driven. Encoding suffixes are case sensitive;

28108

type suffixes are first tried case sensitively, then case

28109

insensitively.

28110

Optional strict is a flag specifying whether the list of known

28111

MIME types is limited to only the official types registered

28112

with IANA{http://www.isi.edu/in-notes/iana/assignments/media-types}

28113

are recognized. When strict is true (the default), only the

28114

IANA types are supported; when strict is false, some additional

28115

non-standard but commonly used MIME types are also recognized.</description>

28116

28117

28118

28119

28120

<description>Guess the extensions for a file based on its MIME type, given by

28121

type.

28122

The return value is a list of strings giving all possible filename extensions,

28123

including the leading dot (.). The extensions are not guaranteed

28124

to have been associated with any particular data stream, but would be mapped

28125

to the MIME type type by guess_type().

28126

Optional strict has the same meaning as with the

28127

guess_type() function.</description>

28128

28129

28130

28131

28132

<description>Guess the extension for a file based on its MIME type, given by

28133

type.

28134

The return value is a string giving a filename extension, including the

28135

leading dot (.). The extension is not guaranteed to have been

28136

associated with any particular data stream, but would be mapped to the MIME type type by guess_type(). If no extension can

28137

be guessed for type, None is returned.

28138

Optional strict has the same meaning as with the

28139

guess_type() function.</description>

28140

28141

28142

28143

28144

<description>Initialize the internal data structures. If given, files must

28145

be a sequence of file names which should be used to augment the

28146

default type map. If omitted, the file names to use are taken from

28147

knownfiles. Each file named in files or

28148

knownfiles takes precedence over those named before it.

28149

Calling init() repeatedly is allowed.</description>

28150

28151

28152

28153

28154

<description>Load the type map given in the file filename, if it exists. The type map is returned as a dictionary mapping filename extensions,

28155

including the leading dot (.), to strings of the form

28156

'type/subtype'. If the file filename does

28157

not exist or cannot be read, None is returned.</description>

28158

28159

28160

28161

28162

<description>Add a mapping from the mimetype type to the extension ext.

28163

When the extension is already known, the new type will replace the old

28164

one. When the type is already known the extension will be added

28165

to the list of known extensions.

28166

When strict is the mapping will added to the official

28167

MIME types, otherwise to the non-standard ones.</description>

28168

28169

28170

28171

28172

<description>This class represents a MIME-types database. By default, it

28173

provides access to the same database as the rest of this module.

28174

The initial database is a copy of that provided by the module, and

28175

may be extended by loading additional mime.types-style files

28176

into the database using the read() or readfp()

28177

methods. The mapping dictionaries may also be cleared before

28178

loading additional data if the default data is not desired.

28179

The optional filenames parameter can be used to cause

28180

additional files to be loaded ``on top'' of the default database.

28181

New in version 2.2</description>

28182

28183

28184

28185

28186

<description>MimeTypes instances provide an interface which is very like

28187

that of the mimetypes module.

28188

{suffix_map}

28189

Dictionary mapping suffixes to suffixes. This is used to allow

28190

recognition of encoded files for which the encoding and the type are

28191

indicated by the same extension. For example, the .tgz

28192

extension is mapped to .tar.gz to allow the encoding and type

28193

to be recognized separately. This is initially a copy of the global

28194

suffix_map defined in the module.

28195

{encodings_map}

28196

Dictionary mapping filename extensions to encoding types. This is

28197

initially a copy of the global encodings_map defined in the

28198

module.

28199

{types_map}

28200

Dictionary mapping filename extensions to MIME types. This is

28201

initially a copy of the global types_map defined in the

28202

module.

28203

{common_types}

28204

Dictionary mapping filename extensions to non-standard, but commonly

28205

found MIME types. This is initially a copy of the global

28206

common_types defined in the module.

28207

</description>

28208

28209

<description>Similar to the guess_extension() function, using the

28210

tables stored as part of the object.</description>

28211

28212

28213

28214

28215

<description>Similar to the guess_type() function, using the tables

28216

stored as part of the object.</description>

28217

28218

28219

28220

28221

<description>Load MIME information from a file named path. This uses

28222

readfp() to parse the file.</description>

28223

28224

28225

28226

28227

<description>Load MIME type information from an open file. The file must have

28228

the format of the standard mime.types files.</description>

28229

28230

28231

28232

</group>

28233

</group>

28234

28235

<description>Generic MIME file writer.

28236

2.3{The email package should be used in

28237

preference to the MimeWriter module. This

28238

module is present only to maintain backward

28239

compatibility.}

28240

This module defines the class MimeWriter. The

28241

MimeWriter class implements a basic formatter for creating

28242

MIME multi-part files. It doesn't seek around the output file nor

28243

does it use large amounts of buffer space. You must write the parts

28244

out in the order that they should occur in the final

28245

file. MimeWriter does buffer the headers you add, allowing you to rearrange their order.

28246

</description>

28247

28248

<description>Return a new instance of the MimeWriter class. The only

28249

argument passed, fp, is a file object to be used for

28250

writing. Note that a StringIO object could also be used.</description>

28251

28252

28253

28254

28255

<description>MimeWriter instances have the following methods:

28256

</description>

28257

28258

<description>Add a header line to the MIME message. The key is the name of

28259

the header, where the value obviously provides the value of the

28260

header. The optional argument prefix determines where the header is inserted; 0 means append at the end, 1 is insert at

28261

the start. The default is to append.</description>

28262

28263

28264

28265

28266

<description>Causes all headers accumulated so far to be written out (and

28267

forgotten). This is useful if you don't need a body part at all,

28268

e.g. a subpart of type message/rfc822 that's (mis)used

28269

to store some header-like information.</description>

28270

28271

</element>

28272

28273

28274

<description>Returns a file-like object which can be used to write to the

28275

body of the message. The content-type is set to the provided

28276

ctype, and the optional parameter plist provides

28277

additional parameters for the content-type declaration. prefix

28278

functions as in addheader() except that the default is to

28279

insert at the start.</description>

28280

28281

28282

28283

28284

<description>Returns a file-like object which can be used to write to the

28285

body of the message. Additionally, this method initializes the

28286

multi-part code, where subtype provides the multipart subtype,

28287

boundary may provide a user-defined boundary specification, and

28288

plist provides optional parameters for the subtype.

28289

prefix functions as in startbody(). Subparts should be

28290

created using nextpart().</description>

28291

28292

28293

28294

28295

<description>Returns a new instance of MimeWriter which represents an

28296

individual part in a multipart message. This may be used to write the part as well as used for creating recursively complex multipart

28297

messages. The message must first be initialized with

28298

startmultipartbody() before using nextpart().</description>

28299

28300

</element>

28301

28302

28303

<description>This is used to designate the last part of a multipart message, and

28304

should always be used when writing multipart messages.</description>

28305

28306

</element>

28307

28308

</group>

28309

</group>

28310

28311

<description>Mimification and unmimification of mail messages.

28312

2.3{The email package should be used in

28313

preference to the mimify module. This

28314

module is present only to maintain backward

28315

compatibility.}

28316

The mimify module defines two functions to convert mail messages to

28317

and from MIME format. The mail message can be either a simple message

28318

or a so-called multipart message. Each part is treated separately.

28319

Mimifying (a part of) a message entails encoding the message as

28320

quoted-printable if it contains any characters that cannot be

28321

represented using 7-bit . Unmimifying (a part of) a message

28322

entails undoing the quoted-printable encoding. Mimify and unmimify

28323

are especially useful when a message has to be edited before being

28324

sent. Typical use would be:

28325

unmimify message

28326

edit message

28327

mimify message

28328

send message

28329

The modules defines the following user-callable functions and

28330

user-settable variables:

28331

</description>

28332

28333

<description>Copy the message in infile to outfile, converting parts to

28334

quoted-printable and adding MIME mail headers when necessary.

28335

infile and outfile can be file objects (actually, any

28336

object that has a readline() method (for infile) or a

28337

write() method (for outfile)) or strings naming the files.

28338

If infile and outfile are both strings, they may have the

28339

same value.</description>

28340

28341

28342

28343

28344

<description>Copy the message in infile to outfile, decoding all

28345

quoted-printable parts. infile and outfile can be file

28346

objects (actually, any object that has a readline() method (for

28347

infile) or a write() method (for outfile)) or strings

28348

naming the files. If infile and outfile are both strings,

28349

they may have the same value.

28350

If the decode_base64 argument is provided and tests true, any

28351

parts that are coded in the base64 encoding are decoded as well.</description>

28352

28353

28354

28355

28356

<description>Return a decoded version of the encoded header line in line.

28357

This only supports the ISO 8859-1 charset (Latin-1).</description>

28358

28359

28360

28361

28362

<description>Return a MIME-encoded version of the header line in line.</description>

28363

28364

28365

28366

</group>

28367

28368

<description>Support for reading files which contain distinct

28369

parts, such as some MIME data.

28370

The MultiFile object enables you to treat sections of a text

28371

file as file-like input objects, with '' being returned by

28372

readline() when a given delimiter pattern is encountered. The

28373

defaults of this class are designed to make it useful for parsing

28374

MIME multipart messages, but by subclassing it and overriding methods it can be easily adapted for more general use.

28375

</description>

28376

28377

<description>Create a multi-file. You must instantiate this class with an input

28378

object argument for the MultiFile instance to get lines from,

28379

such as a file object returned by open().

28380

MultiFile only ever looks at the input object's

28381

readline(), seek() and tell() methods, and

28382

the latter two are only needed if you want random access to the

28383

individual MIME parts. To use MultiFile on a non-seekable

28384

stream object, set the optional seekable argument to false; this

28385

will prevent using the input object's seek() and

28386

tell() methods.</description>

28387

28388

28389

28390

28391

<description>A MultiFile instance has the following methods:

28392

</description>

28393

28394

<description>Read a line. If the line is data (not a section-divider or end-marker

28395

or real EOF) return it. If the line matches the most-recently-stacked

28396

boundary, return '' and set self.last to 1 or 0 according as

28397

the match is or is not an end-marker. If the line matches any other

28398

stacked boundary, raise an error. On encountering end-of-file on the

28399

underlying stream object, the method raises Error unless

28400

all boundaries have been popped.</description>

28401

28402

28403

28404

28405

<description>Return all lines remaining in this part as a list of strings.</description>

28406

28407

28408

28409

28410

<description>Read all lines, up to the next section. Return them as a single

28411

(multiline) string. Note that this doesn't take a size argument!</description>

28412

28413

</element>

28414

28415

28416

<description>Seek. Seek indices are relative to the start of the current section.

28417

The pos and whence arguments are interpreted as for a file

28418

seek.</description>

28419

28420

28421

28422

28423

<description>Return the file position relative to the start of the current section.</description>

28424

28425

</element>

28426

28427

28428

<description>Skip lines to the next section (that is, read lines until a

28429

section-divider or end-marker has been consumed). Return true if

28430

there is such a section, false if an end-marker is seen. Re-enable

28431

the most-recently-pushed boundary.</description>

28432

28433

</element>

28434

28435

28436

<description>Return true if str is data and false if it might be a section

28437

boundary. As written, it tests for a prefix other than '--' at

28438

start of line (which all MIME boundaries have) but it is declared so

28439

it can be overridden in derived classes.

28440

Note that this test is used intended as a fast guard for the real

28441

boundary tests; if it always returns false it will merely slow

28442

processing, not cause it to fail.</description>

28443

28444

28445

28446

28447

<description>Push a boundary string. When an appropriately decorated version of

28448

this boundary is found as an input line, it will be interpreted as a

28449

section-divider or end-marker. All subsequent

28450

reads will return the empty string to indicate end-of-file, until a

28451

call to pop() removes the boundary a or next() call

28452

reenables it.

28453

It is possible to push more than one boundary. Encountering the

28454

most-recently-pushed boundary will return EOF; encountering any other

28455

boundary will raise an error.</description>

28456

28457

28458

28459

28460

<description>Pop a section boundary. This boundary will no longer be interpreted

28461

as EOF.</description>

28462

28463

</element>

28464

28465

28466

<description>Turn a boundary into a section-divider line. By default, this

28467

method prepends '--' (which MIME section boundaries have) but

28468

it is declared so it can be overridden in derived classes. This

28469

method need not append LF or CR-LF, as comparison with the result

28470

ignores trailing whitespace.</description>

28471

28472

28473

28474

28475

<description>Turn a boundary string into an end-marker line. By default, this

28476

method prepends '--' and appends '--' (like a

28477

MIME-multipart end-of-message marker) but it is declared so it can be

28478

overridden in derived classes. This method need not append LF or

28479

CR-LF, as comparison with the result ignores trailing whitespace.</description>

28480

28481

28482

28483

</group>

28484

28485

</group>

28486

</group>

28487

28488

<description>Parse 2822 style mail messages.

28489

2.3{The email package should be used in

28490

preference to the rfc822 module. This

28491

module is present only to maintain backward

28492

compatibility.}

28493

This module defines a class, Message, which represents an

28494

``email message'' as defined by the Internet standard

28495

2822.This module originally conformed to 822,

28496

hence the name. Since then, 2822 has been released as an

28497

update to 822. This module should be considered

28498

2822-conformant, especially in cases where the

28499

syntax or semantics have changed since 822. Such messages

28500

consist of a collection of message headers, and a message body. This

28501

module also defines a helper class

28502

AddressList for parsing 2822 addresses. Please refer to

28503

the RFC for information on the specific syntax of 2822 messages.

28504

The mailboxmailbox module provides classes to read mailboxes produced by various end-user mail programs.

28505

</description>

28506

28507

<description>A Message instance is instantiated with an input object as

28508

parameter. Message relies only on the input object having a

28509

readline() method; in particular, ordinary file objects

28510

qualify. Instantiation reads headers from the input object up to a

28511

delimiter line (normally a blank line) and stores them in the

28512

instance. The message body, following the headers, is not consumed.

28513

This class can work with any input object that supports a

28514

readline() method. If the input object has seek and tell

28515

capability, the rewindbody() method will work; also, illegal

28516

lines will be pushed back onto the input stream. If the input object

28517

lacks seek but has an unread() method that can push back a

28518

line of input, Message will use that to push back illegal

28519

lines. Thus this class can be used to parse messages coming from a

28520

buffered stream.

28521

The optional seekable argument is provided as a workaround for

28522

certain stdio libraries in which tell() discards buffered

28523

data before discovering that the lseek() system call

28524

doesn't work. For maximum portability, you should set the seekable

28525

argument to zero to prevent that initial tell() when passing

28526

in an unseekable object such as a file object created from a socket

28527

object.

28528

Input lines as read from the file may either be terminated by CR-LF or

28529

by a single linefeed; a terminating CR-LF is replaced by a single

28530

linefeed before the line is stored.

28531

All header matching is done independent of upper or lower case;

28532

e.g. m['From'], m['from'] and

28533

m['FROM'] all yield the same result.</description>

28534

28535

28536

28537

28538

<description>You may instantiate the AddressList helper class using a single

28539

string parameter, a comma-separated list of 2822 addresses to be

28540

parsed. (The parameter None yields an empty list.)</description>

28541

28542

28543

28544

28545

<description>Return a new string with backslashes in str replaced by two

28546

backslashes and double quotes replaced by backslash-double quote.</description>

28547

28548

28549

28550

28551

<description>Return a new string which is an unquoted version of str.

28552

If str ends and begins with double quotes, they are stripped

28553

off. Likewise if str ends and begins with angle brackets, they

28554

are stripped off.</description>

28555

28556

28557

28558

28559

<description>Parse address, which should be the value of some

28560

address-containing field such as To or Cc,

28561

into its constituent ``realname'' and ``email address'' parts.

28562

Returns a tuple of that information, unless the parse fails, in which

28563

case a 2-tuple (None, None) is returned.</description>

28564

28565

28566

28567

28568

<description>The inverse of parseaddr(), this takes a 2-tuple of the form

28569

(realname, email_address) and returns the string

28570

value suitable for a To or Cc header. If

28571

the first element of pair is false, then the second element is

28572

returned unmodified.</description>

28573

28574

28575

28576

28577

<description>Attempts to parse a date according to the rules in 2822.

28578

however, some mailers don't follow that format as specified, so

28579

parsedate() tries to guess correctly in such cases. date is a string containing an 2822 date, such as 'Mon, 20 Nov 1995 19:12:08 -0500'. If it succeeds in parsing

28580

the date, parsedate() returns a 9-tuple that can be passed

28581

directly to time.mktime(); otherwise None will be

28582

returned. Note that fields 6, 7, and 8 of the result tuple are not

28583

usable.</description>

28584

28585

28586

28587

28588

<description>Performs the same function as parsedate(), but returns

28589

either None or a 10-tuple; the first 9 elements make up a tuple

28590

that can be passed directly to time.mktime(), and the tenth

28591

is the offset of the date's timezone from UTC (which is the official

28592

term for Greenwich Mean Time). (Note that the sign of the timezone

28593

offset is the opposite of the sign of the time.timezone

28594

variable for the same timezone; the latter variable follows the

28595

standard while this module follows 2822.) If the input

28596

string has no timezone, the last element of the tuple returned is

28597

None. Note that fields 6, 7, and 8 of the result tuple are not

28598

usable.</description>

28599

28600

28601

28602

28603

<description>Turn a 10-tuple as returned by parsedate_tz() into a UTC

28604

timestamp. If the timezone item in the tuple is None, assume

28605

local time. Minor deficiency: this first interprets the first 8

28606

elements as a local time and then compensates for the timezone

28607

difference; this may yield a slight error around daylight savings time

28608

switch dates. Not enough to worry about for common use.</description>

28609

28610

28611

28612

28613

<description>A Message instance has the following methods:

28614

</description>

28615

28616

<description>Seek to the start of the message body. This only works if the file

28617

object is seekable.</description>

28618

28619

</element>

28620

28621

28622

<description>Returns a line's canonicalized fieldname (the dictionary key that will

28623

be used to index it) if the line is a legal 2822 header; otherwise

28624

returns None (implying that parsing should stop here and the

28625

line be pushed back on the input stream). It is sometimes useful to

28626

override this method in a subclass.</description>

28627

28628

28629

28630

28631

<description>Return true if the given line is a delimiter on which Message should

28632

stop. The delimiter line is consumed, and the file object's read

28633

location positioned immediately after it. By default this method just

28634

checks that the line is blank, but you can override it in a subclass.</description>

28635

28636

28637

28638

28639

<description>Return True if the given line should be ignored entirely, just skipped.

28640

By default this is a stub that always returns False, but you can

28641

override it in a subclass.</description>

28642

28643

28644

28645

28646

<description>Return a list of lines consisting of all headers matching

28647

name, if any. Each physical line, whether it is a continuation

28648

line or not, is a separate list item. Return the empty list if no

28649

header matches name.</description>

28650

28651

28652

28653

28654

<description>Return a list of lines comprising the first header matching

28655

name, and its continuation line(s), if any. Return

28656

None if there is no header matching name.</description>

28657

28658

28659

28660

28661

<description>Return a single string consisting of the text after the colon in the

28662

first header matching name. This includes leading whitespace,

28663

the trailing linefeed, and internal linefeeds and whitespace if there

28664

any continuation line(s) were present. Return None if there is

28665

no header matching name.</description>

28666

28667

28668

28669

28670

<description>Like getrawheader(name), but strip leading and trailing

28671

whitespace. Internal whitespace is not stripped. The optional

28672

default argument can be used to specify a different default to

28673

be returned when there is no header matching name.</description>

28674

28675

28676

28677

28678

<description>An alias for getheader(), to make the interface more compatible with regular dictionaries.</description>

28679

28680

28681

28682

28683

<description>Return a pair (full name, email address) parsed

28684

from the string returned by getheader(name). If no

28685

header matching name exists, return (None, None);

28686

otherwise both the full name and the address are (possibly empty)

28687

strings.

28688

Example: If m's first From header contains the

28689

string 'jack@cwi.nl (Jack Jansen)', then

28690

m.getaddr('From') will yield the pair

28691

('Jack Jansen', 'jack@cwi.nl').

28692

If the header contained

28693

'Jack Jansen <jack@cwi.nl>' instead, it would yield the

28694

exact same result.</description>

28695

28696

28697

28698

28699

<description>This is similar to getaddr(list), but parses a header

28700

containing a list of email addresses (e.g. To header) and

28701

returns a list of (full name, email address) pairs

28702

(even if there was only one address in the header). If there is no

28703

header matching name, return an empty list.

28704

If multiple headers exist that match the named header (e.g. if there

28705

are several Cc headers), all are parsed for addresses.

28706

Any continuation lines the named headers contain are also parsed.</description>

28707

28708

28709

28710

28711

<description>Retrieve a header using getheader() and parse it into a 9-tuple

28712

compatible with time.mktime(); note that fields 6, 7, and 8 are not usable. If there is no header matching

28713

name, or it is unparsable, return None.

28714

Date parsing appears to be a black art, and not all mailers adhere to

28715

the standard. While it has been tested and found correct on a large

28716

collection of email from many sources, it is still possible that this

28717

function may occasionally yield an incorrect result.</description>

28718

28719

28720

28721

28722

<description>Retrieve a header using getheader() and parse it into a

28723

10-tuple; the first 9 elements will make a tuple compatible with

28724

time.mktime(), and the 10th is a number giving the offset

28725

of the date's timezone from UTC. Note that fields 6, 7, and 8 are not usable. Similarly to getdate(), if

28726

there is no header matching name, or it is unparsable, return

28727

None.</description>

28728

28729

28730

28731

</group>

28732

28733

<description>An AddressList instance has the following methods:

28734

</description>

28735

28736

<description>Return the number of addresses in the address list.</description>

28737

28738

</element>

28739

28740

28741

<description>Return a canonicalized string representation of the address list.

28742

Addresses are rendered in "name" <host@domain> form, comma-separated.</description>

28743

28744

</element>

28745

28746

28747

<description>Return a new AddressList instance that contains all addresses

28748

in both AddressList operands, with duplicates removed (set

28749

union).</description>

28750

28751

28752

28753

28754

<description>In-place version of __add__(); turns this AddressList

28755

instance into the union of itself and the right-hand instance,

28756

alist.</description>

28757

28758

28759

28760

28761

<description>Return a new AddressList instance that contains every address

28762

in the left-hand AddressList operand that is not present in

28763

the right-hand address operand (set difference).</description>

28764

28765

28766

28767

28768

<description>In-place version of __sub__(), removing addresses in this

28769

list which are also in alist.</description>

28770

28771

28772

28773

</group>

28774

</group>

28775

28776

<description>Encode and decode files using the MIME base64 data.

28777

</description>

28778

28779

<description>Decode the contents of the input file and write the resulting

28780

binary data to the output file.

28781

input and output must either be file objects or objects that

28782

mimic the file object interface. input will be read until

28783

input.read() returns an empty string.</description>

28784

28785

28786

28787

28788

<description>Decode the string s, which must contain one or more lines of

28789

base64 encoded data, and return a string containing the resulting

28790

binary data.</description>

28791

28792

28793

28794

28795

<description>Encode the contents of the input file and write the resulting

28796

base64 encoded data to the output file.

28797

input and output must either be file objects or objects that

28798

mimic the file object interface. input will be read until

28799

input.read() returns an empty string. encode()

28800

returns the encoded data plus a trailing newline character

28801

('\n').</description>

28802

28803

28804

28805

28806

<description>Encode the string s, which can contain arbitrary binary data,

28807

and return a string containing one or more lines of

28808

base64-encoded data. encodestring() returns a

28809

string containing one or more lines of base64-encoded data

28810

always including an extra trailing newline ('\n').</description>

28811

28812

28813

28814

</group>

28815

28816

<description>Tools for converting between binary and various

28817

-encoded binary representations.

28818

The binascii module contains a number of methods to convert

28819

between binary and various -encoded binary

28820

representations. Normally, you will not use these functions directly

28821

but use wrapper modules like uuuu or

28822

binhexbinhex instead, this module solely

28823

exists because bit-manipulation of large amounts of data is slow in

28824

Python.

28825

The binascii module defines the following functions:

28826

</description>

28827

28828

<description>Convert a single line of uuencoded data back to binary and return the

28829

binary data. Lines normally contain 45 (binary) bytes, except for the

28830

last line. Line data may be followed by whitespace.</description>

28831

28832

28833

28834

28835

<description>Convert binary data to a line of ASCII characters, the return value

28836

is the converted line, including a newline char. The length of

28837

data should be at most 45.</description>

28838

28839

28840

28841

28842

<description>Convert a block of base64 data back to binary and return the

28843

binary data. More than one line may be passed at a time.</description>

28844

28845

28846

28847

28848

<description>Convert binary data to a line of ASCII characters in base64 coding.

28849

The return value is the converted line, including a newline char.

28850

The length of data should be at most 57 to adhere to the base64

28851

standard.</description>

28852

28853

28854

28855

28856

<description>Convert a block of quoted-printable data back to binary and return the

28857

binary data. More than one line may be passed at a time.

28858

If the optional argument header is present and true, underscores

28859

will be decoded as spaces.</description>

28860

28861

28862

28863

28864

<description>Convert binary data to a line(s) of ASCII characters in

28865

quoted-printable encoding. The return value is the converted line(s).

28866

If the optional argument quotetabs is present and true, all tabs

28867

and spaces will be encoded. If the optional argument header is

28868

present and true, spaces will be encoded as underscores per RFC1522.

28869

If the optional argument header is present and false, newline

28870

characters will be encoded as well, otherwise linefeed conversion might

28871

corrupt the binary data stream.</description>

28872

28873

28874

28875

28876

<description>Convert binhex4 formatted ASCII data to binary, without doing

28877

RLE-decompression. The string should contain a complete number of

28878

binary bytes, or (in case of the last portion of the binhex4 data)

28879

have the remaining bits zero.</description>

28880

28881

28882

28883

28884

<description>Perform RLE-decompression on the data, as per the binhex4

28885

standard. The algorithm uses 0x90 after a byte as a repeat

28886

indicator, followed by a count. A count of 0 specifies a byte

28887

value of 0x90. The routine returns the decompressed data,

28888

unless data input data ends in an orphaned repeat indicator, in which

28889

case the Incomplete exception is raised.</description>

28890

28891

28892

28893

28894

<description>Perform binhex4 style RLE-compression on data and return the

28895

result.</description>

28896

28897

28898

28899

28900

<description>Perform hexbin4 binary-to-ASCII translation and return the

28901

resulting string. The argument should already be RLE-coded, and have a

28902

length divisible by 3 (except possibly the last fragment).</description>

28903

28904

28905

28906

28907

<description>Compute the binhex4 crc value of data, starting with an initial

28908

crc and returning the result.</description>

28909

28910

28911

28912

28913

<description>Compute CRC-32, the 32-bit checksum of data, starting with an initial

28914

crc. This is consistent with the ZIP file checksum. Since the

28915

algorithm is designed for use as a checksum algorithm, it is not

28916

suitable for use as a general hash algorithm. Use as follows:

28917

print binascii.crc32("hello world")

28918

# Or, in two pieces:

28919

crc = binascii.crc32("hello")

28920

crc = binascii.crc32(" world", crc)

28921

print crc

28922

</description>

28923

28924

28925

28926

28927

<description>hexlify{data}

28928

Return the hexadecimal representation of the binary data. Every

28929

byte of data is converted into the corresponding 2-digit hex

28930

representation. The resulting string is therefore twice as long as

28931

the length of data.</description>

28932

28933

28934

28935

28936

<description>unhexlify{hexstr}

28937

Return the binary data represented by the hexadecimal string

28938

hexstr. This function is the inverse of b2a_hex().

28939

hexstr must contain an even number of hexadecimal digits (which

28940

can be upper or lower case), otherwise a TypeError is

28941

raised.</description>

28942

28943

28944

28945

</group>

28946

28947

<description>Encode and decode files in binhex4 format.

28948

This module encodes and decodes files in binhex4 format, a format

28949

allowing representation of Macintosh files in . On the Macintosh,

28950

both forks of a file and the finder information are encoded (or

28951

decoded), on other platforms only the data fork is handled.

28952

The binhex module defines the following functions:

28953

</description>

28954

28955

<description>Convert a binary file with filename input to binhex file

28956

output. The output parameter can either be a filename or a

28957

file-like object (any object supporting a write() and

28958

close() method).</description>

28959

28960

28961

28962

28963

<description>Decode a binhex file input. input may be a filename or a

28964

file-like object supporting read() and close() methods.

28965

The resulting file is written to a file named output, unless the

28966

argument is omitted in which case the output filename is read from the

28967

binhex file.</description>

28968

28969

28970

28971

28972

</group>

28973

</group>

28974

28975

<description>Encode and decode files using the MIME

28976

quoted-printable encoding.

28977

This module performs quoted-printable transport encoding and decoding,

28978

as defined in 1521: ``MIME (Multipurpose Internet Mail

28979

Extensions) Part One: Mechanisms for Specifying and Describing the

28980

Format of Internet Message Bodies''. The quoted-printable encoding is

28981

designed for data where there are relatively few nonprintable

28982

characters; the base64 encoding scheme available via the

28983

base64 module is more compact if there are many such

28984

characters, as when sending a graphics file.

28985

</description>

28986

28987

<description>Decode the contents of the input file and write the resulting

28988

decoded binary data to the output file.

28989

input and output must either be file objects or objects that

28990

mimic the file object interface. input will be read until

28991

input.readline() returns an empty string.

28992

If the optional argument header is present and true, underscore

28993

will be decoded as space. This is used to decode

28994

``Q''-encoded headers as described in 1522: ``MIME (Multipurpose Internet Mail Extensions)

28995

Part Two: Message Header Extensions for Non-ASCII Text''.</description>

28996

28997

28998

28999

29000

<description>Encode the contents of the input file and write the resulting

29001

quoted-printable data to the output file.

29002

input and output must either be file objects or objects that

29003

mimic the file object interface. input will be read until

29004

input.readline() returns an empty string.

29005

quotetabs is a flag which controls whether to encode embedded

29006

spaces and tabs; when true it encodes such embedded whitespace, and

29007

when false it leaves them unencoded. Note that spaces and tabs

29008

appearing at the end of lines are always encoded, as per 1521.</description>

29009

29010

29011

29012

29013

<description>Like decode(), except that it accepts a source string and

29014

returns the corresponding decoded string.</description>

29015

29016

29017

29018

29019

<description>Like encode(), except that it accepts a source string and

29020

returns the corresponding encoded string. quotetabs is optional

29021

(defaulting to 0), and is passed straight through to

29022

encode().</description>

29023

29024

29025

29026

</group>

29027

29028

<description>Encode and decode files in uuencode format.

29029

This module encodes and decodes files in uuencode format, allowing

29030

arbitrary binary data to be transferred over ASCII-only connections.

29031

Wherever a file argument is expected, the methods accept a file-like

29032

object. For backwards compatibility, a string containing a pathname

29033

is also accepted, and the corresponding file will be opened for

29034

reading and writing; the pathname '-' is understood to mean the

29035

standard input or output. However, this interface is deprecated; it's

29036

better for the caller to open the file itself, and be sure that, when

29037

required, the mode is 'rb' or 'wb' on Windows.

29038

This code was contributed by Lance Ellinghouse, and modified by Jack

29039

Jansen.

29040

</description>

29041

29042

<description>Uuencode file in_file into file out_file. The uuencoded

29043

file will have the header specifying name and mode as

29044

the defaults for the results of decoding the file. The default

29045

defaults are taken from in_file, or '-' and 0666

29046

respectively.</description>

29047

29048

29049

29050

29051

<description>This call decodes uuencoded file in_file placing the result on

29052

file out_file. If out_file is a pathname, mode is

29053

used to set the permission bits if the file must be

29054

created. Defaults for out_file and mode are taken from

29055

the uuencode header. However, if the file specified in the header

29056

already exists, a uu.Error is raised.</description>

29057

29058

29059

29060

</group>

29061

29062

<description>Encoders and decoders for the External Data

29063

Representation (XDR).

29064

</description>

29065

29066

<description>Packer is the class for packing data into XDR representation.

29067

The Packer class is instantiated with no arguments.</description>

29068

29069

</element>

29070

29071

29072

<description>Unpacker is the complementary class which unpacks XDR data

29073

values from a string buffer. The input buffer is given as

29074

data.</description>

29075

29076

29077

29078

29079

<description>Packer instances have the following methods:

29080

</description>

29081

29082

<description>Returns the current pack buffer as a string.</description>

29083

29084

</element>

29085

29086

29087

<description>Resets the pack buffer to the empty string.</description>

29088

29089

</element>

29090

29091

29092

<description>Packs the single-precision floating point number value.</description>

29093

29094

29095

29096

29097

<description>Packs the double-precision floating point number value.</description>

29098

29099

29100

29101

29102

<description>Packs a fixed length string, s. n is the length of the

29103

string but it is not packed into the data buffer. The string

29104

is padded with null bytes if necessary to guaranteed 4 byte alignment.</description>

29105

29106

29107

29108

29109

<description>Packs a fixed length opaque data stream, similarly to

29110

pack_fstring().</description>

29111

29112

29113

29114

29115

<description>Packs a variable length string, s. The length of the string is

29116

first packed as an unsigned integer, then the string data is packed

29117

with pack_fstring().</description>

29118

29119

29120

29121

29122

<description>Packs a variable length opaque data string, similarly to

29123

pack_string().</description>

29124

29125

29126

29127

29128

<description>Packs a variable length byte stream, similarly to pack_string().</description>

29129

29130

29131

29132

29133

<description>Packs a list of homogeneous items. This method is useful for

29134

lists with an indeterminate size; i.e. the size is not available until

29135

the entire list has been walked. For each item in the list, an

29136

unsigned integer 1 is packed first, followed by the data value

29137

from the list. pack_item is the function that is called to pack

29138

the individual item. At the end of the list, an unsigned integer

29139

0 is packed.

29140

For example, to pack a list of integers, the code might appear like

29141

this:

29142

import xdrlib

29143

p = xdrlib.Packer()

29144

p.pack_list([1, 2, 3], p.pack_int)

29145

</description>

29146

29147

29148

29149

29150

<description>Packs a fixed length list (array) of homogeneous items. n

29151

is the length of the list; it is not packed into the buffer,

29152

but a ValueError exception is raised if

29153

len(array) is not equal to n. As above,

29154

pack_item is the function used to pack each element.</description>

29155

29156

29157

29158

29159

<description>Packs a variable length list of homogeneous items. First, the

29160

length of the list is packed as an unsigned integer, then each element

29161

is packed as in pack_farray() above.</description>

29162

29163

29164

29165

</group>

29166

29167

<description>The Unpacker class offers the following methods:

29168

</description>

29169

29170

<description>Resets the string buffer with the given data.</description>

29171

29172

29173

29174

29175

<description>Returns the current unpack position in the data buffer.</description>

29176

29177

</element>

29178

29179

29180

<description>Sets the data buffer unpack position to position. You should be

29181

careful about using get_position() and set_position().</description>

29182

29183

29184

29185

29186

<description>Returns the current unpack data buffer as a string.</description>

29187

29188

</element>

29189

29190

29191

<description>Indicates unpack completion. Raises an Error exception

29192

if all of the data has not been unpacked.</description>

29193

29194

</element>

29195

29196

29197

<description>Unpacks a single-precision floating point number.</description>

29198

29199

</element>

29200

29201

29202

<description>Unpacks a double-precision floating point number, similarly to

29203

unpack_float().</description>

29204

29205

</element>

29206

29207

29208

<description>Unpacks and returns a fixed length string. n is the number of

29209

characters expected. Padding with null bytes to guaranteed 4 byte

29210

alignment is assumed.</description>

29211

29212

29213

29214

29215

<description>Unpacks and returns a fixed length opaque data stream, similarly to

29216

unpack_fstring().</description>

29217

29218

29219

29220

29221

<description>Unpacks and returns a variable length string. The length of the

29222

string is first unpacked as an unsigned integer, then the string data

29223

is unpacked with unpack_fstring().</description>

29224

29225

</element>

29226

29227

29228

<description>Unpacks and returns a variable length opaque data string, similarly to

29229

unpack_string().</description>

29230

29231

</element>

29232

29233

29234

<description>Unpacks and returns a variable length byte stream, similarly to

29235

unpack_string().</description>

29236

29237

</element>

29238

29239

29240

<description>Unpacks and returns a list of homogeneous items. The list is unpacked

29241

one element at a time

29242

by first unpacking an unsigned integer flag. If the flag is 1,

29243

then the item is unpacked and appended to the list. A flag of

29244

0 indicates the end of the list. unpack_item is the

29245

function that is called to unpack the items.</description>

29246

29247

29248

29249

29250

<description>Unpacks and returns (as a list) a fixed length array of homogeneous

29251

items. n is number of list elements to expect in the buffer.

29252

As above, unpack_item is the function used to unpack each element.</description>

29253

29254

29255

29256

29257

<description>Unpacks and returns a variable length list of homogeneous items.

29258

First, the length of the list is unpacked as an unsigned integer, then

29259

each element is unpacked as in unpack_farray() above.</description>

29260

29261

29262

29263

</group>

29264

29265

</group>

29266

</group>

29267

29268

<description>% Note the needed for ... ;-(

29269

Loading of .netrc files.

29270

New in version 1.5.2

29271

The netrc class parses and encapsulates the netrc file format

29272

used by the ftp program and other FTP clients.

29273

</description>

29274

29275

<description>A netrc instance or subclass instance encapsulates data from a netrc file. The initialization argument, if present, specifies the

29276

file to parse. If no argument is given, the file .netrc in the

29277

user's home directory will be read. Parse errors will raise

29278

NetrcParseError with diagnostic information including the

29279

file name, line number, and terminating token.</description>

29280

29281

29282

29283

29284

<description>A netrc instance has the following methods:

29285

</description>

29286

29287

<description>Return a 3-tuple (login, account, password)

29288

of authenticators for host. If the netrc file did not

29289

contain an entry for the given host, return the tuple associated with

29290

the `default' entry. If neither matching host nor default entry is

29291

available, return None.</description>

29292

29293

29294

29295

29296

<description>Dump the class data as a string in the format of a netrc file.

29297

(This discards comments and may reorder the entries.)</description>

29298

29299

</element>

29300

29301

</group>

29302

</group>

29303

29304

<description>Loads a robots.txt file and

29305

answers questions about fetchability of other URLs.

29306

</description>

29307

29308

<description>This class provides a set of methods to read, parse and answer questions

29309

about a single robots.txt file.

29310

{set_url}{url}

29311

Sets the URL referring to a robots.txt file.</description>

29312

29313

</element>

29314

29315

29316

<description>Reads the robots.txt URL and feeds it to the parser.</description>

29317

29318

</element>

29319

29320

29321

<description>Parses the lines argument.</description>

29322

29323

29324

29325

29326

<description>Returns True if the useragent is allowed to fetch the url

29327

according to the rules contained in the parsed robots.txt file.</description>

29328

29329

29330

29331

29332

<description>Returns the time the robots.txt file was last fetched. This is

29333

useful for long-running web spiders that need to check for new

29334

robots.txt files periodically.</description>

29335

29336

</element>

29337

29338

29339

<description>Sets the time the robots.txt file was last fetched to the current

29340

time.</description>

29341

29342

</element>

29343

29344

</group>

29345

29346

<description>Write and read tabular data to and from delimited files.

29347

New in version 2.3

29348

</description>

29349

29350

<description>The csv module defines the following functions:

29351

</description>

29352

29353

<description>Return a reader object which will iterate over lines in the given

29354

{}csvfile. csvfile can be any object which supports the

29355

iterator protocol and returns a string each time its next

29356

method is called. If csvfile is a file object, it must be opened with

29357

the 'b' flag on platforms where that makes a difference. An optional

29358

{}dialect parameter can be given

29359

which is used to define a set of parameters specific to a particular CSV

29360

dialect. It may be an instance of a subclass of the Dialect

29361

class or one of the strings returned by the list_dialects

29362

function. The other optional {}fmtparam keyword arguments can be

29363

given to override individual formatting parameters in the current

29364

dialect. For more information about the dialect and formatting

29365

parameters, see section~csv-fmt-params, ``Dialects and Formatting

29366

Parameters'' for details of these parameters.

29367

All data read are returned as strings. No automatic data type

29368

conversion is performed.</description>

29369

29370

29371

29372

29373

<description>Return a writer object responsible for converting the user's data into

29374

delimited strings on the given file-like object. csvfile can be any

29375

object with a write method. If csvfile is a file object,

29376

it must be opened with the 'b' flag on platforms where that makes a

29377

difference. An optional

29378

{}dialect parameter can be given which is used to define a set of

29379

parameters specific to a particular CSV dialect. It may be an instance

29380

of a subclass of the Dialect class or one of the strings

29381

returned by the list_dialects function. The other optional

29382

{}fmtparam keyword arguments can be given to override individual

29383

formatting parameters in the current dialect. For more information

29384

about the dialect and formatting parameters, see

29385

section~csv-fmt-params, ``Dialects and Formatting Parameters'' for

29386

details of these parameters. To make it as easy as possible to

29387

interface with modules which implement the DB API, the value

29388

None is written as the empty string. While this isn't a

29389

reversible transformation, it makes it easier to dump SQL NULL data values

29390

to CSV files without preprocessing the data returned from a

29391

cursor.fetch*() call. All other non-string data are stringified

29392

with str() before being written.</description>

29393

29394

29395

29396

29397

<description>Associate dialect with name. dialect must be a subclass

29398

of csv.Dialect. name must be a string or Unicode object.</description>

29399

29400

29401

29402

29403

<description>Delete the dialect associated with name from the dialect registry. An

29404

Error is raised if name is not a registered dialect

29405

name.</description>

29406

29407

29408

29409

29410

<description>Return the dialect associated with name. An Error is

29411

raised if name is not a registered dialect name.</description>

29412

29413

29414

29415

29416

<description>Return the names of all registered dialects.</description>

29417

29418

</element>

29419

29420

29421

<description>Create an object which operates like a regular reader but maps the

29422

information read into a dict whose keys are given by the optional

29423

{} fieldnames

29424

parameter. If the fieldnames parameter is omitted, the values in

29425

the first row of the csvfile will be used as the fieldnames.

29426

If the row read has fewer fields than the fieldnames sequence,

29427

the value of restval will be used as the default value. If the row

29428

read has more fields than the fieldnames sequence, the remaining data is

29429

added as a sequence keyed by the value of restkey. If the row read

29430

has fewer fields than the fieldnames sequence, the remaining keys take the

29431

value of the optional restval parameter. All other parameters are

29432

interpreted as for reader objects.</description>

29433

29434

29435

29436

29437

<description>Create an object which operates like a regular writer but maps dictionaries

29438

onto output rows. The fieldnames parameter identifies the order in

29439

which values in the dictionary passed to the writerow() method are

29440

written to the csvfile. The optional restval parameter

29441

specifies the value to be written if the dictionary is missing a key in

29442

fieldnames. If the dictionary passed to the writerow()

29443

method contains a key not found in fieldnames, the optional

29444

extrasaction parameter indicates what action to take. If it is set

29445

to 'raise' a ValueError is raised. If it is set to

29446

'ignore', extra values in the dictionary are ignored. All other

29447

parameters are interpreted as for writer objects.

29448

Note that unlike the DictReader class, the fieldnames

29449

parameter of the DictWriter is not optional. Since Python's

29450

dict objects are not ordered, there is not enough information

29451

available to deduce the order in which the row should be written to the

29452

csvfile.</description>

29453

29454

29455

29456

29457

<description>The Sniffer class is used to deduce the format of a CSV file.</description>

29458

29459

</element>

29460

29461

29462

<description>Analyze the given sample and return a Dialect subclass

29463

reflecting the parameters found. If the optional delimiters parameter

29464

is given, it is interpreted as a string containing possible valid delimiter

29465

characters.</description>

29466

29467

29468

29469

29470

<description>Analyze the sample text (presumed to be in CSV format) and return

29471

True if the first row appears to be a series of column

29472

headers.</description>

29473

29474

29475

29476

</group>

29477

29478

<description>To make it easier to specify the format of input and output records,

29479

specific formatting parameters are grouped together into dialects. A

29480

dialect is a subclass of the Dialect class having a set of specific

29481

methods and a single validate() method. When creating reader

29482

or writer objects, the programmer can specify a string or a subclass

29483

of the Dialect class as the dialect parameter. In addition to, or

29484

instead of, the dialect parameter, the programmer can also specify

29485

individual formatting parameters, which have the same names as the

29486

attributes defined below for the Dialect class.

29487

Dialects support the following attributes:

29488

[Dialect]{delimiter}

29489

A one-character string used to separate fields. It defaults to ','.

29490

[Dialect]{doublequote}

29491

Controls how instances of quotechar appearing inside a field should be

29492

themselves be quoted. When True, the character is doubledd.

29493

When False, the escapechar must be a one-character string

29494

which is used as a prefix to the quotechar. It defaults to

29495

True.

29496

[Dialect]{escapechar}

29497

A one-character string used to escape the delimiter if quoting

29498

is set to QUOTE_NONE. It defaults to None.

29499

[Dialect]{lineterminator}

29500

The string used to terminate lines in the CSV file. It defaults to

29501

'\r\n'.

29502

[Dialect]{quotechar}

29503

A one-character string used to quote elements containing the delimiter

29504

or which start with the quotechar. It defaults to '"'.

29505

[Dialect]{quoting}

29506

Controls when quotes should be generated by the writer. It can take on any

29507

of the QUOTE_* constants (see section~csv-contents)

29508

and defaults to QUOTE_MINIMAL. [Dialect]{skipinitialspace}

29509

When True, whitespace immediately following the delimiter

29510

is ignored. The default is False.

29511

</description>

29512

</group>

29513

29514

<description>Reader objects (DictReader instances and objects returned by

29515

the reader() function) have the following public methods:

29516

[csv reader]{next}{}

29517

Return the next row of the reader's iterable object as a list, parsed

29518

according to the current dialect.

29519

</description>

29520

</group>

29521

29522

<description>Writer objects (DictWriter instances and objects returned by

29523

the writer() function) have the following public methods:

29524

[csv writer]{writerow}{row}

29525

Write the row parameter to the writer's file object, formatted

29526

according to the current dialect.

29527

[csv writer]{writerows}{rows}

29528

Write all the rows parameters to the writer's file object, formatted

29529

according to the current dialect.

29530

</description>

29531

</group>

29532

29533

</group>

29534

</group>

29535

</group>

29536

29537

29538

<description>A simple parser that can handle HTML and XHTML.

29539

This module defines a class HTMLParser which serves as the

29540

basis for parsing text files formatted in HTML</description>

29541

29542

<description>The HTMLParser class is instantiated without arguments.

29543

An HTMLParser instance is fed HTML data and calls handler functions

29544

when tags begin and end. The HTMLParser class is meant to be

29545

overridden by the user to provide a desired behavior.

29546

Unlike the parser in htmllib, this parser does not check

29547

that end tags match start tags or call the end-tag handler for

29548

elements which are closed implicitly by closing an outer element.</description>

29549

29550

</element>

29551

29552

29553

<description>Reset the instance. Loses all unprocessed data. This is called

29554

implicitly at instantiation time.</description>

29555

29556

</element>

29557

29558

29559

<description>Feed some text to the parser. It is processed insofar as it consists

29560

of complete elements; incomplete data is buffered until more data is

29561

fed or close() is called.</description>

29562

29563

29564

29565

29566

<description>Force processing of all buffered data as if it were followed by an

29567

end-of-file mark. This method may be redefined by a derived class to

29568

define additional processing at the end of the input, but the

29569

redefined version should always call the HTMLParser base class

29570

method close().</description>

29571

29572

</element>

29573

29574

29575

<description>Return current line number and offset.</description>

29576

29577

</element>

29578

29579

29580

<description>Return the text of the most recently opened start tag. This should

29581

not normally be needed for structured processing, but may be useful in

29582

dealing with HTML ``as deployed'' or for re-generating input with

29583

minimal changes (whitespace between attributes can be preserved,

29584

etc.).</description>

29585

29586

</element>

29587

29588

29589

<description>This method is called to handle the start of a tag. It is intended to

29590

be overridden by a derived class; the base class implementation does

29591

nothing. The tag argument is the name of the tag converted to

29592

lower case. The attrs argument is a list of (name,

29593

value) pairs containing the attributes found inside the tag's

29594

<> brackets. The name will be translated to lower case

29595

and double quotes and backslashes in the value have been

29596

interpreted. For instance, for the tag <A

29597

HREF="http://www.cwi.nl/">, this method would be called as

29598

handle_starttag('a', [('href', 'http://www.cwi.nl/')]).</description>

29599

29600

29601

29602

29603

<description>Similar to handle_starttag(), but called when the parser

29604

encounters an XHTML-style empty tag (<a .../>). This method

29605

may be overridden by subclasses which require this particular lexical

29606

information; the default implementation simple calls

29607

handle_starttag() and handle_endtag().</description>

29608

29609

29610

29611

29612

<description>This method is called to handle the end tag of an element. It is

29613

intended to be overridden by a derived class; the base class

29614

implementation does nothing. The tag argument is the name of

29615

the tag converted to lower case.</description>

29616

29617

29618

29619

29620

<description>This method is called to process arbitrary data. It is intended to be

29621

overridden by a derived class; the base class implementation does

29622

nothing.</description>

29623

29624

29625

29626

29627

<description>This method is called to

29628

process a character reference of the form #ref;. It

29629

is intended to be overridden by a derived class; the base class

29630

implementation does nothing.</description>

29631

29632

29633

29634

29635

<description>This method is called to process a general entity reference of the

29636

form &name; where name is an general entity

29637

reference. It is intended to be overridden by a derived class; the

29638

base class implementation does nothing.</description>

29639

29640

29641

29642

29643

<description>This method is called when a comment is encountered. The

29644

comment argument is a string containing the text between the

29645

{-}{-} and {-}{-} delimiters, but not the delimiters

29646

themselves. For example, the comment <!{-}{-}text{-}{-}> will

29647

cause this method to be called with the argument 'text'. It is

29648

intended to be overridden by a derived class; the base class

29649

implementation does nothing.</description>

29650

29651

29652

29653

29654

<description>Method called when an SGML declaration is read by the parser. The

29655

decl parameter will be the entire contents of the declaration

29656

inside the <!...> markup.It is intended to be overridden

29657

by a derived class; the base class implementation does nothing.</description>

29658

29659

29660

29661

29662

<description>Method called when a processing instruction is encountered. The

29663

data parameter will contain the entire processing instruction.

29664

For example, for the processing instruction <?proc color='red'>,

29665

this method would be called as handle_pi("proc color='red'"). It

29666

is intended to be overridden by a derived class; the base class

29667

implementation does nothing.

29668

The HTMLParser class uses the SGML syntactic rules for

29669

processing instruction. An XHTML processing instruction using the

29670

trailing ? will cause the ? to be included in

29671

data.</description>

29672

29673

29674

29675

29676

</group>

29677

</group>

29678

29679

<description>Only as much of an SGML parser as needed to parse HTML.

29680

</description>

29681

29682

<description>The SGMLParser class is instantiated without arguments.

29683

The parser is hardcoded to recognize the following

29684

constructs:

29685

Opening and closing tags of the form

29686

<tag attr="value" ...> and

29687

</tag>, respectively.

29688

Numeric character references of the form #name;.

29689

Entity references of the form &name;.

29690

SGML comments of the form . Note that

29691

spaces, tabs, and newlines are allowed between the trailing

29692

> and the immediately preceding --.

29693

</description>

29694

29695

</element>

29696

29697

29698

<description>Reset the instance. Loses all unprocessed data. This is called

29699

implicitly at instantiation time.</description>

29700

29701

</element>

29702

29703

29704

<description>Stop processing tags. Treat all following input as literal input

29705

(CDATA). (This is only provided so the HTML tag

29706

<PLAINTEXT> can be implemented.)</description>

29707

29708

</element>

29709

29710

29711

<description>Enter literal mode (CDATA mode).</description>

29712

29713

</element>

29714

29715

29716

<description>Feed some text to the parser. It is processed insofar as it consists

29717

of complete elements; incomplete data is buffered until more data is

29718

fed or close() is called.</description>

29719

29720

29721

29722

29723

<description>Force processing of all buffered data as if it were followed by an

29724

end-of-file mark. This method may be redefined by a derived class to

29725

define additional processing at the end of the input, but the

29726

redefined version should always call close().</description>

29727

29728

</element>

29729

29730

29731

<description>Return the text of the most recently opened start tag. This should

29732

not normally be needed for structured processing, but may be useful in

29733

dealing with HTML ``as deployed'' or for re-generating input with

29734

minimal changes (whitespace between attributes can be preserved,

29735

etc.).</description>

29736

29737

</element>

29738

29739

29740

<description>This method is called to handle start tags for which either a

29741

start_tag() or do_tag() method has been

29742

defined. The tag argument is the name of the tag converted to

29743

lower case, and the method argument is the bound method which

29744

should be used to support semantic interpretation of the start tag.

29745

The attributes argument is a list of (name,

29746

value) pairs containing the attributes found inside the tag's

29747

<> brackets. The name has been translated to lower case

29748

and double quotes and backslashes in the value have been interpreted.

29749

For instance, for the tag <A HREF="http://www.cwi.nl/">, this

29750

method would be called as unknown_starttag('a', [('href',

29751

'http://www.cwi.nl/')]). The base implementation simply calls

29752

method with attributes as the only argument.</description>

29753

29754

29755

29756

29757

<description>This method is called to handle endtags for which an

29758

end_tag() method has been defined. The

29759

tag argument is the name of the tag converted to lower case, and

29760

the method argument is the bound method which should be used to

29761

support semantic interpretation of the end tag. If no

29762

end_tag() method is defined for the closing element,

29763

this handler is not called. The base implementation simply calls

29764

method.</description>

29765

29766

29767

29768

29769

<description>This method is called to process arbitrary data. It is intended to be

29770

overridden by a derived class; the base class implementation does

29771

nothing.</description>

29772

29773

29774

29775

29776

<description>This method is called to process a character reference of the form

29777

#ref;. In the base implementation, ref must

29778

be a decimal number in the

29779

range 0-255. It translates the character to ASCII and calls the

29780

method handle_data() with the character as argument. If

29781

ref is invalid or out of range, the method

29782

unknown_charref(ref) is called to handle the error. A

29783

subclass must override this method to provide support for named

29784

character entities.</description>

29785

29786

29787

29788

29789

<description>This method is called to process a general entity reference of the

29790

form &ref; where ref is an general entity

29791

reference. It looks for ref in the instance (or class)

29792

variable entitydefs which should be a mapping from entity

29793

names to corresponding translations. If a translation is found, it

29794

calls the method handle_data() with the translation;

29795

otherwise, it calls the method unknown_entityref(ref).

29796

The default entitydefs defines translations for

29797

;, , ;, ;, and

29798

;.</description>

29799

29800

29801

29802

29803

<description>This method is called when a comment is encountered. The

29804

comment argument is a string containing the text between the

29805

delimiters, but not the delimiters

29806

themselves. For example, the comment  will

29807

cause this method to be called with the argument 'text'. The

29808

default method does nothing.</description>

29809

29810

29811

29812

29813

<description>Method called when an SGML declaration is read by the parser. In

29814

practice, the DOCTYPE declaration is the only thing observed in

29815

HTML, but the parser does not discriminate among different (or broken)

29816

declarations. Internal subsets in a DOCTYPE declaration are

29817

not supported. The data parameter will be the entire contents

29818

of the declaration inside the <!...> markup. The

29819

default implementation does nothing.</description>

29820

29821

29822

29823

29824

<description>This method is called when an end tag is found which does not

29825

correspond to any open element.</description>

29826

29827

29828

29829

29830

<description>This method is called to process an unknown start tag. It is intended

29831

to be overridden by a derived class; the base class implementation

29832

does nothing.</description>

29833

29834

29835

29836

29837

<description>This method is called to process an unknown end tag. It is intended

29838

to be overridden by a derived class; the base class implementation

29839

does nothing.</description>

29840

29841

29842

29843

29844

<description>This method is called to process unresolvable numeric character

29845

references. Refer to handle_charref() to determine what is

29846

handled by default. It is intended to be overridden by a derived

29847

class; the base class implementation does nothing.</description>

29848

29849

29850

29851

29852

<description>This method is called to process an unknown entity reference. It is

29853

intended to be overridden by a derived class; the base class

29854

implementation does nothing.</description>

29855

29856

29857

29858

</group>

29859

29860

<description>A parser for HTML documents.

29861

</description>

29862

29863

<description>This is the basic HTML parser class. It supports all entity names

29864

required by the XHTML 1.0 Recommendation (http://www.w3.org/TR/xhtml1). It also defines handlers for all HTML 2.0 and many HTML 3.0 and 3.2 elements.</description>

29865

29866

29867

29868

29869

<description>In addition to tag methods, the HTMLParser class provides some

29870

additional methods and instance variables for use within tag methods.

29871

{formatter}

29872

This is the formatter instance associated with the parser.

29873

{nofill}

29874

Boolean flag which should be true when whitespace should not be

29875

collapsed, or false when it should be. In general, this should only

29876

be true when character data is to be treated as ``preformatted'' text,

29877

as within a <PRE> element. The default value is false. This

29878

affects the operation of handle_data() and save_end().

29879

</description>

29880

29881

<description>This method is called at the start of an anchor region. The arguments

29882

correspond to the attributes of the <A> tag with the same

29883

names. The default implementation maintains a list of hyperlinks

29884

(defined by the HREF attribute for <A> tags) within the

29885

document. The list of hyperlinks is available as the data attribute

29886

anchorlist.</description>

29887

29888

29889

29890

29891

<description>This method is called at the end of an anchor region. The default

29892

implementation adds a textual footnote marker using an index into the

29893

list of hyperlinks created by anchor_bgn().</description>

29894

29895

</element>

29896

29897

29898

<description>This method is called to handle images. The default implementation

29899

simply passes the alt value to the handle_data()

29900

method.</description>

29901

29902

29903

29904

29905

<description>Begins saving character data in a buffer instead of sending it to the

29906

formatter object. Retrieve the stored data via save_end().

29907

Use of the save_bgn() / save_end() pair may not be

29908

nested.</description>

29909

29910

</element>

29911

29912

29913

<description>Ends buffering character data and returns all data saved since the

29914

preceding call to save_bgn(). If the nofill flag is

29915

false, whitespace is collapsed to single spaces. A call to this

29916

method without a preceding call to save_bgn() will raise a

29917

TypeError exception.</description>

29918

29919

</element>

29920

29921

</group>

29922

</group>

29923

29924

<description>% Markup notes:

29925

%

29926

% Many of the attributes of the XMLParser objects are callbacks.

29927

% Since signature information must be presented, these are described

29928

% using the methoddesc environment. Since they are attributes which

29929

% are set by client code, in-text references to these attributes

29930

% should be marked using the macro and should not include the

29931

% parentheses used when marking functions and methods.

29932

An interface to the Expat non-validating XML parser.

29933

New in version 2.0

29934

The xml.parsers.expat module is a Python interface to the

29935

Expat</description>

29936

29937

<description>Returns an explanatory string for a given error number errno.</description>

29938

29939

29940

29941

29942

<description>Creates and returns a new xmlparser object. encoding, if specified, must be a string naming the encoding used by the XML data. Expat doesn't support as many encodings as

29943

Python does, and its repertoire of encodings can't be extended; it

29944

supports UTF-8, UTF-16, ISO-8859-1 (Latin1), and ASCII. If

29945

encoding is given it will override the implicit or explicit

29946

encoding of the document.

29947

Expat can optionally do XML namespace processing for you, enabled by

29948

providing a value for namespace_separator. The value must be a

29949

one-character string; a ValueError will be raised if the

29950

string has an illegal length (None is considered the same as

29951

omission). When namespace processing is enabled, element type names

29952

and attribute names that belong to a namespace will be expanded. The

29953

element name passed to the element handlers

29954

StartElementHandler and EndElementHandler

29955

will be the concatenation of the namespace URI, the namespace

29956

separator character, and the local part of the name. If the namespace

29957

separator is a zero byte (chr(0)) then the namespace URI and

29958

the local part will be concatenated without any separator.

29959

For example, if namespace_separator is set to a space character

29960

( ) and the following document is parsed:

29961

<?xml version="1.0"?>

29962

<root xmlns = "http://default-namespace.org/"

29963

xmlns:py = "http://www.python.org/ns/">

29964

<py:elem1 />

29965

29966

</root>

29967

StartElementHandler will receive the following strings

29968

for each element:

29969

http://default-namespace.org/ root

29970

http://www.python.org/ns/ elem1

29971

elem2

29972

</description>

29973

29974

29975

29976

29977

<description>xmlparser objects have the following methods:

29978

</description>

29979

29980

<description>Parses the contents of the string data, calling the appropriate

29981

handler functions to process the parsed data. isfinal must be

29982

true on the final call to this method. data can be the empty

29983

string at any time.</description>

29984

29985

29986

29987

29988

<description>Parse XML data reading from the object file. file only

29989

needs to provide the read(nbytes) method, returning the

29990

empty string when there's no more data.</description>

29991

29992

29993

29994

29995

<description>Sets the base to be used for resolving relative URIs in system

29996

identifiers in declarations. Resolving relative identifiers is left

29997

to the application: this value will be passed through as the

29998

base argument to the ExternalEntityRefHandler,

29999

NotationDeclHandler, and

30000

UnparsedEntityDeclHandler functions.</description>

30001

30002

30003

30004

30005

<description>Returns a string containing the base set by a previous call to

30006

SetBase(), or None if SetBase() hasn't been called.</description>

30007

30008

</element>

30009

30010

30011

<description>Returns the input data that generated the current event as a string.

30012

The data is in the encoding of the entity which contains the text.

30013

When called while an event handler is not active, the return value is

30014

None.

30015

New in version 2.1</description>

30016

30017

</element>

30018

30019

30020

<description>Create a ``child'' parser which can be used to parse an external

30021

parsed entity referred to by content parsed by the parent parser. The

30022

context parameter should be the string passed to the

30023

ExternalEntityRefHandler() handler function, described below.

30024

The child parser is created with the ordered_attributes,

30025

returns_unicode and specified_attributes set to the

30026

values of this parser.</description>

30027

30028

30029

30030

30031

<description>Called when the XML declaration is parsed. The XML declaration is the

30032

(optional) declaration of the applicable version of the XML

30033

recommendation, the encoding of the document text, and an optional

30034

``standalone'' declaration. version and encoding will be

30035

strings of the type dictated by the returns_unicode

30036

attribute, and standalone will be 1 if the document is

30037

declared standalone, 0 if it is declared not to be standalone,

30038

or -1 if the standalone clause was omitted.

30039

This is only available with Expat version 1.95.0 or newer.

30040

New in version 2.1</description>

30041

30042

30043

30044

30045

<description>Called when Expat begins parsing the document type declaration

30046

(<!DOCTYPE ...). The doctypeName is provided exactly

30047

as presented. The systemId and publicId parameters give

30048

the system and public identifiers if specified, or None if

30049

omitted. has_internal_subset will be true if the document

30050

contains and internal document declaration subset.

30051

This requires Expat version 1.2 or newer.</description>

30052

30053

30054

30055

30056

<description>Called when Expat is done parsing the document type delaration.

30057

This requires Expat version 1.2 or newer.</description>

30058

30059

</element>

30060

30061

30062

<description>Called once for each element type declaration. name is the name

30063

of the element type, and model is a representation of the

30064

content model.</description>

30065

30066

30067

30068

30069

<description>Called for each declared attribute for an element type. If an

30070

attribute list declaration declares three attributes, this handler is

30071

called three times, once for each attribute. elname is the name

30072

of the element to which the declaration applies and attname is

30073

the name of the attribute declared. The attribute type is a string

30074

passed as type; the possible values are 'CDATA',

30075

'ID', 'IDREF', ...

30076

default gives the default value for the attribute used when the

30077

attribute is not specified by the document instance, or None if

30078

there is no default value ( values). If the attribute

30079

is required to be given in the document instance, required will

30080

be true.

30081

This requires Expat version 1.95.0 or newer.</description>

30082

30083

30084

30085

30086

<description>Called for the start of every element. name is a string

30087

containing the element name, and attributes is a dictionary

30088

mapping attribute names to their values.</description>

30089

30090

30091

30092

30093

<description>Called for the end of every element.</description>

30094

30095

30096

30097

30098

<description>Called for every processing instruction.</description>

30099

30100

30101

30102

30103

<description>Called for character data. This will be called for normal character

30104

data, CDATA marked content, and ignorable whitespace. Applications

30105

which must distinguish these cases can use the

30106

StartCdataSectionHandler, EndCdataSectionHandler,

30107

and ElementDeclHandler callbacks to collect the required

30108

information.</description>

30109

30110

30111

30112

30113

<description>Called for unparsed (NDATA) entity declarations. This is only present

30114

for version 1.2 of the Expat library; for more recent versions, use

30115

EntityDeclHandler instead. (The underlying function in the

30116

Expat library has been declared obsolete.)</description>

30117

30118

30119

30120

30121

<description>Called for all entity declarations. For parameter and internal

30122

entities, value will be a string giving the declared contents

30123

of the entity; this will be None for external entities. The

30124

notationName parameter will be None for parsed entities,

30125

and the name of the notation for unparsed entities.

30126

is_parameter_entity will be true if the entity is a paremeter

30127

entity or false for general entities (most applications only need to

30128

be concerned with general entities).

30129

This is only available starting with version 1.95.0 of the Expat

30130

library.

30131

New in version 2.1</description>

30132

30133

30134

30135

30136

<description>Called for notation declarations. notationName, base, and

30137

systemId, and publicId are strings if given. If the

30138

public identifier is omitted, publicId will be None.</description>

30139

30140

30141

30142

30143

<description>Called when an element contains a namespace declaration. Namespace

30144

declarations are processed before the StartElementHandler is

30145

called for the element on which declarations are placed.</description>

30146

30147

30148

30149

30150

<description>Called when the closing tag is reached for an element that contained a namespace declaration. This is called once for each

30151

namespace declaration on the element in the reverse of the order for

30152

which the StartNamespaceDeclHandler was called to indicate

30153

the start of each namespace declaration's scope. Calls to this

30154

handler are made after the corresponding EndElementHandler

30155

for the end of the element.</description>

30156

30157

30158

30159

30160

<description>Called for comments. data is the text of the comment, excluding

30161

the leading `'.</description>

30162

30163

30164

30165

30166

<description>Called at the start of a CDATA section. This and

30167

StartCdataSectionHandler are needed to be able to identify

30168

the syntactical start and end for CDATA sections.</description>

30169

30170

</element>

30171

30172

30173

<description>Called at the end of a CDATA section.</description>

30174

30175

</element>

30176

30177

30178

<description>Called for any characters in the XML document for

30179

which no applicable handler has been specified. This means

30180

characters that are part of a construct which could be reported, but

30181

for which no handler has been supplied.</description>

30182

30183

30184

30185

30186

<description>This is the same as the DefaultHandler, but doesn't inhibit expansion of internal entities.

30187

The entity reference will not be passed to the default handler.</description>

30188

30189

30190

30191

30192

<description>Called if the

30193

XML document hasn't been declared as being a standalone document.

30194

This happens when there is an external subset or a reference to a

30195

parameter entity, but the XML declaration does not set standalone to

30196

yes in an XML declaration. If this handler returns 0,

30197

then the parser will throw an XML_ERROR_NOT_STANDALONE

30198

error. If this handler is not set, no exception is raised by the

30199

parser for this condition.</description>

30200

30201

</element>

30202

30203

30204

<description>Called for references to external entities. base is the current

30205

base, as set by a previous call to SetBase(). The public and

30206

system identifiers, systemId and publicId, are strings if

30207

given; if the public identifier is not given, publicId will be

30208

None. The context value is opaque and should only be

30209

used as described below.

30210

For external entities to be parsed, this handler must be implemented.

30211

It is responsible for creating the sub-parser using

30212

ExternalEntityParserCreate(context), initializing it with

30213

the appropriate callbacks, and parsing the entity. This handler

30214

should return an integer; if it returns 0, the parser will

30215

throw an XML_ERROR_EXTERNAL_ENTITY_HANDLING error,

30216

otherwise parsing will continue.

30217

If this handler is not provided, external entities are reported by the

30218

DefaultHandler callback, if provided.</description>

30219

30220

30221

30222

</group>

30223

30224

<description>ExpatError exceptions have a number of interesting

30225

attributes:

30226

[ExpatError]{code}

30227

Expat's internal error number for the specific error. This will

30228

match one of the constants defined in the errors object from

30229

this module.

30230

New in version 2.1

30231

[ExpatError]{lineno}

30232

Line number on which the error was detected. The first line is

30233

numbered 1.

30234

New in version 2.1

30235

[ExpatError]{offset}

30236

Character offset into the line where the error occurred. The first

30237

column is numbered 0.

30238

New in version 2.1

30239

</description>

30240

</group>

30241

30242

<description>The following program defines three handlers that just print out their

30243

arguments.

30244

import xml.parsers.expat

30245

# 3 handler functions

30246

def start_element(name, attrs):

30247

print 'Start element:', name, attrs

30248

def end_element(name):

30249

print 'End element:', name

30250

def char_data(data):

30251

print 'Character data:', repr(data)

30252

p = xml.parsers.expat.ParserCreate()

30253

p.StartElementHandler = start_element

30254

p.EndElementHandler = end_element

30255

p.CharacterDataHandler = char_data

30256

p.Parse("""<?xml version="1.0"?>

30257

30258

30259

</parent>""", 1)

30260

The output from this program is:

30261

Start element: parent {'id': 'top'}

30262

Start element: child1 {'name': 'paul'}

30263

Character data: 'Text goes here'

30264

End element: child1

30265

Character data: ''

30266

Start element: child2 {'name': 'fred'}

30267

Character data: 'More text'

30268

End element: child2

30269

Character data: ''

30270

End element: parent

30271

</description>

30272

</group>

30273

30274

<description>Content modules are described using nested tuples. Each tuple

30275

contains four values: the type, the quantifier, the name, and a tuple

30276

of children. Children are simply additional content module

30277

descriptions.

30278

The values of the first two fields are constants defined in the

30279

model object of the xml.parsers.expat module. These

30280

constants can be collected in two groups: the model type group and the

30281

quantifier group.

30282

The constants in the model type group are:

30283

{XML_CTYPE_ANY}

30284

The element named by the model name was declared to have a content

30285

model of ANY.

30286

{XML_CTYPE_CHOICE}

30287

The named element allows a choice from a number of options; this is

30288

used for content models such as (A | B | C).

30289

{XML_CTYPE_EMPTY}

30290

Elements which are declared to be EMPTY have this model type.

30291

{XML_CTYPE_MIXED}

30292

{XML_CTYPE_NAME}

30293

{XML_CTYPE_SEQ}

30294

Models which represent a series of models which follow one after the

30295

other are indicated with this model type. This is used for models

30296

such as (A, B, C).

30297

The constants in the quantifier group are:

30298

{XML_CQUANT_NONE}

30299

No modifier is given, so it can appear exactly once, as for A.

30300

{XML_CQUANT_OPT}

30301

The model is optional: it can appear once or not at all, as for

30302

A?.

30303

{XML_CQUANT_PLUS}

30304

The model must occur one or more times (like A+).

30305

{XML_CQUANT_REP}

30306

The model must occur zero or more times, as for A*.

30307

</description>

30308

</group>

30309

30310

</group>

30311

</group>

30312

30313

<description>Document Object Model API for Python.

30314

New in version 2.0

30315

The Document Object Model, or ``DOM,'' is a cross-language API from

30316

the World Wide Web Consortium (W3C) for accessing and modifying XML

30317

documents. A DOM implementation presents an XML document as a tree

30318

structure, or allows client code to build such a structure from

30319

scratch. It then gives access to the structure through a set of

30320

objects which provided well-known interfaces.

30321

The DOM is extremely useful for random-access applications. SAX only

30322

allows you a view of one bit of the document at a time. If you are

30323

looking at one SAX element, you have no access to another. If you are

30324

looking at a text node, you have no access to a containing element.

30325

When you write a SAX application, you need to keep track of your

30326

program's position in the document somewhere in your own code. SAX

30327

does not do it for you. Also, if you need to look ahead in the XML

30328

document, you are just out of luck.

30329

Some applications are simply impossible in an event driven model with

30330

no access to a tree. Of course you could build some sort of tree

30331

yourself in SAX events, but the DOM allows you to avoid writing that

30332

code. The DOM is a standard tree representation for XML data.

30333

%What if your needs are somewhere between SAX and the DOM? Perhaps

30334

%you cannot afford to load the entire tree in memory but you find the

30335

%SAX model somewhat cumbersome and low-level. There is also a module

30336

%called xml.dom.pulldom that allows you to build trees of only the

30337

%parts of a document that you need structured access to. It also has

30338

%features that allow you to find your way around the DOM.

30339

% See http://www.prescod.net/python/pulldom

30340

The Document Object Model is being defined by the W3C in stages, or

30341

``levels'' in their terminology. The Python mapping of the API is

30342

substantially based on the DOM Level~2 recommendation. The mapping of

30343

the Level~3 specification, currently only available in draft form, is

30344

being developed by the Python XML Special Interest

30345

Group{http://www.python.org/sigs/xml-sig/} as part of the

30346

PyXML package{http://pyxml.sourceforge.net/}. Refer to the

30347

documentation bundled with that package for information on the current

30348

state of DOM Level~3 support.

30349

DOM applications typically start by parsing some XML into a DOM. How

30350

this is accomplished is not covered at all by DOM Level~1, and Level~2

30351

provides only limited improvements: There is a

30352

DOMImplementation object class which provides access to

30353

Document creation methods, but no way to access an XML

30354

reader/parser/Document builder in an implementation-independent way.

30355

There is also no well-defined way to access these methods without an

30356

existing Document object. In Python, each DOM implementation

30357

will provide a function getDOMImplementation(). DOM Level~3

30358

adds a Load/Store specification, which defines an interface to the

30359

reader, but this is not yet available in the Python standard library.

30360

Once you have a DOM document object, you can access the parts of your

30361

XML document through its properties and methods. These properties are

30362

defined in the DOM specification; this portion of the reference manual

30363

describes the interpretation of the specification in Python.

30364

The specification provided by the W3C defines the DOM API for Java,

30365

ECMAScript, and OMG IDL. The Python mapping defined here is based in

30366

large part on the IDL version of the specification, but strict

30367

compliance is not required (though implementations are free to support

30368

the strict mapping from IDL). See section dom-conformance,

30369

``Conformance,'' for a detailed discussion of mapping requirements.

30370